Once you have created your client instance, you will then create an object the represents the type of action you wish to perform on the platform (detailed in the following sections). Debit Cards and Credit Cards are both processed the same way through the gateway, both as a BankCard object. Bank Cards are processed on the Base Commerce Platform using the BankCardTransaction object to encapsulate all of the cardholder data, details about the transaction, and the BaseCommercePayClient processBankCardTransaction() method.
Make sure to check the getMessages() on the response if the transaction fails, as it will indicate what the failure reason is.
The following example is authorizing a credit card for one U.S. dollar:
Next, you will invoke the method on the BaseCommerceClient which corresponds to the desired function. This will make the client connect to our platform via SSL and execute your request. Upon completion of the request, the object you passed as a parameter will be updated with the results of the request:
In this example, we want to confirm that the transaction was approved, since it was a transaction of type AUTH not SALE it will comp back in the AUTHORIZED status where as if it was a SALE it would come back as CAPTURED if successful. We will check the status on the BankCardTransaction object then print out the values returned:
This completes the process of authorizing a card and checking the response. In the event you are processing multiple transactions, the same client object can be reused multiple times; however, the BankCardTransaction object should not be reused. When you are done with the client, there is no clean up to do, as all resources are closed and variables are reset (with the exception of the username, password, and key) after each transaction is processed.
In the event that the server is unable to process your request due to invalid credentials (username, password, key), a BaseCommercePayClientException will be thrown, indicating that there is a communication error with the server.
Only the following test cards will return approvals in the SandBox Environment:
Adding a Single Credit Card to Sandbox
In the Developer Dashboard on https://www.my.basecommercesandbox.com under the SDK credentials, there is a text box to enter a credit card number. The number you enter, when processed with, will return a CAPTURED state. This number can also be used for testing if you are using an encrypted card reader since there is no test track data for the test numbers in the above table.
Test Case Scenarios for Approvals / Declines
To simulate real life, you can use any of the aforementioned cards with a valid expiration date. If the date is in the future, the transaction will return an authorization.
- Transactions that have a cent value of 10 cents will decline for insufficient funds
- Transactions that have a cent value of 20 cents will decline for do not honor
- Transactions that have a cent value of 30 cents will decline for lost/stolen
- Transactions that have a cent value of 40 cents will return response code of 0002 partial authorization. If the Merchant is not configured for this, it will decline.
Test Case Scenarios for CVV and AVS Response Codes
|AVS Response Code||Address Line 1||Address Zipcode|
|U||456 Willow Drive||23456|
|R||79 Evergreen Drive||34567|
|E||246 Apple Lane||45678|
|S||19 Redwood Ave||56789|
|Y||123 Maple Ave||12345|
|X||123 Maple Ave||123456789|
|A||123 Maple Ave||67890|
|W||87 Cherry Lane||123456789|
|Z||22 Oak St||12345|
|N||68 Willow Drive||78901|
|CVV Response Code||CVV Value|
Every BankCardTransaction request requires a transaction type be set prior to executing processBankCardTransaction(). The transaction type is set by invoking the setType( ) method on the BankCardTransaction object with one of the following types:
|XS_BCT_TYPE_SALE||This is the most commonly used method for processing. The SALE transaction type instructs the system to obtain an AUTH on the cardholder's card and mark the transaction for settlement to the Merchant's bank account. A successful transaction of the SALE type will result in a status of CAPTURED.|
|XS_BCT_TYPE_AUTH||Requests that the platform obtains an authorization for the specified transaction. This method will only obtain an authorization code and place a hold on the funds on the cardholder's card. Transactions that are only authorized will not automatically settle and be deposited to your bank account. After you have obtained a successful authorization, you should either CAPTURE the transaction if you want it to settle or VOID the transaction if you want to release the hold on the card. A successful transaction of the AUTH type will result in a status of AUTHORIZED.|
|XS_BCT_TYPE_CAPTURE||Instructs the system to mark the specified transaction (based on the BankCardTransactionId) to be settled to the Merchant's bank account. In order to execute a CAPTURE, the transaction must have a transaction status of AUTHORIZED. A successful transaction of the CAPTURE type will result in a status of CAPTURED.|
|XS_BCT_TYPE_VOID||Voids a transaction that has been AUTHORIZED or CAPTURED, releasing the hold on the cardholder's account. Voids can only occur on transactions that have not settled to the Merchant's bank account. A successful transaction of the VOID type will result in a status of VOIDED.|
|XS_BCT_TYPE_REFUND||Refunds the specified amount of a transaction (based on the BankCardTransactionId) that has been SETTLED. The refund amount cannot be greater than the original transaction amount. A successful transaction of the REFUND type will result in a status of CAPTURED.|
|XS_BCT_TYPE_CREDIT||Issues a blind credit (meaning the credit is not tied to a settled transaction) to the card specified. A successful transaction of the CREDIT type will result in a status of CAPTURED. **Credits are disabled by default, so please contact us for assistance.|
Every BankCardTransaction that is processed with valid credentials will have a status that should be checked to determine the results of the transaction. The status can be obtained from a BankCardTransaction object by executing the getStats() or isStatus() methods. The status values are as follows:
|XS_BCT_STATUS_AUTHORIZED||Indicates that an XS_BCT_TYPE_AUTH type transaction has succeeded and an authorization has been obtained, placing a hold on the funds for the specified card. Authorized transactions will not settle to the Merchant's bank account until they are CAPTURED by executing a request with a transaction type of XS_BCT_TYPE_CAPTURE and specifying the BankCardTransactionID of the transaction to capture.|
|XS_BCT_STATUS_CAPTURED||Indicates that the transaction has been successfully captured (either as a result of a XS_BCT_TYPE_SALE or XS_BCT_TYPE_CAPTURE type request). A Captured transaction will be settled to the Merchant's bank account.|
|XS_BCT_STATUS_SETTLED||Indicates that the transaction has been successfully settled as a result of the server merchant settlement tasks (these happen automatically on a daily basis when your batch is closed) and the funds will be deposited into the Merchant's bank account.|
|XS_BCT_STATUS_VOIDED||Indicates the transaction has been voided as a result of a XS_BCT_TYPE_VOID type request and the hold has been released on the cardholder's card.|
|XS_BCT_STATUS_DECLINED||Indicates that the transaction has been declined as a result of an XS_BCT_TYPE_AUTH or XS_BCT_TYPE_SALE type request. The reason for the decline can be found by executing getResponseCode() and getResponseMessage() on the BankCardTransaction object. ** See Response Codes for a list of reasons a card will decline.|
|XS_BCT_STATUS_FAILED||Indicates that the transaction has failed as a result of our platform's integrity checks. See getResponseMessage() on the BankCardTransaction object for the reason why. This status should not appear in production environments and is used as a way to assist the developer if they are missing data or trying to perform a transaction type out of sequence.|
Required Credit Card Transaction Fields
- Expiration Month
- Expiration Year
- Transaction type
- Voids require the original transaction ID
- Capture/refunds require the original transaction ID and the amount
- CVV is required if merchant has AVS required enabled