Credit Card Processing

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. 

The following example is authorizing a credit card for one U.S. dollar:

BankCardTransaction o_bc_transaction = new BankCardTransaction(); 
o_bc_transaction.setCardNumber( "4111111111111111"); 
o_bc_transaction.setCardName( "Test Card"); 
o_bc_transaction.setType( BankCardTransaction.XS_BCT_TYPE_AUTH );

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:

o_bc_transaction = o_client.processBankCardTransaction( o_bc_transaction );

In this example, we want to confirm that the transaction was approved, so we will check the status on the BankCardTransaction object:

if ( o_bc_transaction.isStatus(BankCardTransaction.XS_BCT_STATUS_FAILED) ) { 

       // Transaction failed, look at messages for reasons why 
       System.out.println( o_bc_transaction.getMessages() ); 

} else if ( o_bc_transaction.isStatus(BankCardTransaction.XS_BCT_STATUS_DECLINED) ) { 

       // Transaction declined, look at response code and response message 
       System.out.println( o_bc_transaction.getResponseCode() ); 
       System.out.println( o_bc_transaction.getResponseMessage() ); 

} else if ( o_transaction.isStatus( BankCardTransaction.XO_AUTHORIZED ) { 

       // Transaction was successfully authorized 


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:

American Express Visa Mastercard Discover
378282246310005 4111111111111111 5555555555554444 6011111111111117
371449635398431 4012888888881881 5200828282828210 6011000990139424
378734493671000 4222222222222 5105105105105100  

Adding a Single Credit Card to Sandbox

In the Developer Dashboard on 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
M 111
N 112
P 113
S 114
U 115
Y 116

BankCardTransaction Types

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:

Transaction Type Description
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.

BankCardTransaction Statuses

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:

Transaction Status Description
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.