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. 

Make sure to check the getMessages() on the response if the transaction fails, as it will indicate what the failure reason is.

Here is an example of processing a SALE transaction:

                Address o_address = new Address( Address.XS_ADDRESS_NAME_BILLING );
                o_address.setLine1( "5055 E. Washington Street");
                o_address.setLine2( "Suite 300");
                o_address.setCity( "Phoenix" );
                o_address.setState( "AZ" );
                o_address.setCountry( "US" );
                o_address.setZipcode( "85034" );
                BankCardTransaction o_bc_transaction = new BankCardTransaction();
                o_bc_transaction.setType( BankCardTransaction.XS_BCT_TYPE_SALE );
                o_bc_transaction.setAmount( 5.25 );
                o_bc_transaction.setCardName( "Sample Bank Card Transaction" );
                o_bc_transaction.setCardNumber( "4111111111111111" );
                o_bc_transaction.setCardExpirationMonth( "08" );
                o_bc_transaction.setCardExpirationYear( "2025" );
                o_bc_transaction.setCardCVV2( "111" );
                o_bc_transaction.setBillingAddress( o_address );

                BaseCommerceClient o_client = new BaseCommerceClient( s_username, s_password, s_key );
                o_client.setSandbox( true );
                o_bc_transaction = o_client.processBankCardTransaction( o_bc_transaction );

                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_bc_transaction.isStatus( BankCardTransaction.XS_BCT_STATUS_CAPTURED ) ) {
                    // Transaction successful
                    System.out.println( o_bc_transaction.getTransactionId() );

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, 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:

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
		System.out.println( o_bc_transaction.getTransactionId() ); //Base Commerce Unique custom ID for every BankCardTransaction
		System.out.println( o_bc_transaction.getAuthorizationCode() ); //The authorization code
		System.out.println( o_bc_transaction.getAVSResponseCode() ); //The AVS response code


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 ExpressVisaMastercardDiscover



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 CodeAddress Line 1Address Zipcode
U456 Willow Drive23456
R79 Evergreen Drive34567
E246 Apple Lane45678
S19 Redwood Ave56789
Y123 Maple Ave12345
X123 Maple Ave123456789
A123 Maple Ave67890
W87 Cherry Lane123456789
Z22 Oak St12345
N68 Willow Drive78901
CVV Response CodeCVV Value

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 TypeDescription
XS_BCT_TYPE_SALEThis 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_AUTHRequests 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_CAPTUREInstructs 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_REFUNDRefunds 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_CREDITIssues 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 StatusDescription
XS_BCT_STATUS_AUTHORIZEDIndicates 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_CAPTUREDIndicates 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_SETTLEDIndicates 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_VOIDEDIndicates 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_DECLINEDIndicates 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

  • Number
  • Amount
  • 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