Base Commerce Technical Documentation

Credit Card Processing

Credit Cards are processed on the Base Commerce Platform using the BankCardTransaction object to encapsulate all of the card holder data and details about the transaction and the BaseCommercePayClient processBankCardTransaction() method. This section details the types of transactions that can be preformed on the platform, required and optional parameters, and the statuses you can expect back from each type of request.

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:

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 card holders card and mark the transaction for settlement to the merchants 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 auth code and place a hold on the funds on the cardholders 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 merchants 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 card holders account. Voids can only occur on transactions that have not settled to the merchants 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 can not be greater than the original transaction amount. A successful transaction of the REFUND type will result in a status of REFUNDED.

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, please contact

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:

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 merchants bank account until they are CAPTURED with 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 merchants 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 merchants 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 card holders 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 platforms 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 preform a transaction type out of sequence.

XS_BCT_STATUS_3DSECURE – Indicates that the customer needs to be redirected to the 3D Secure Verification URL as the result of a XS_BCT_TYPE_AUTH or XS_BCT_TYPE_SALE type transaction that had 3D Secure enabled on the request.
** See 3D Secure section for more details

XS_BCT_STATUS_VERIFIED – Indicates that the transaction has completed the 3D Secure verification and will be marked as AUTHORIZED or CAPTURED depending on the transaction type that was specified when the transaction was initiated.
** See 3D Secure section for more details

Auth-Capture

Situations may arise wherein the amount of the transaction that will settle and be charged to the cardholder will be different form the amount originally authorized. The most common example is full service restaurants wherein the original authorization does not include the server tip. The server gets an authorization for the amount of the check, then returns to the POS to add the tip. Herein, the captured and settled amount is greater than the amount that was authorized. Keep in mind that, under card network rules, certain industries can settle an amount greater that the authorization without paying an interchange penalty such as restaurants, hotels and rental cars. If you are not one of these industries and you expect to settle amounts greater than the initial authorization, you may wish to add some amount to the authorization to insure that the captured and settled amount is not greater. There is no interchange penalty for settling an amount that is less than the authorization

Address o_address = new Address( Address.XS_ADDRESS_NAME_BILLING );
o_address.setLine1( "123 Maple Ave" );
o_address.setZipcode( "12345" );

BankCardTransaction o_bc_transaction = new BankCardTransaction();
o_bc_transaction.setBillingAddress( o_address );
o_bc_transaction.setType(BankCardTransaction.XS_BCT_TYPE_AUTH);
o_bc_transaction.setAmount(10.00);
o_bc_transaction.setCardName("Sample Bank Card Transaction");
o_bc_transaction.setCardNumber("4111111111111111");
o_bc_transaction.setCardExpirationMonth("01");
o_bc_transaction.setCardExpirationYear("2020");
o_bc_transaction.setCardCVV2( "111" );
BaseCommerceClient o_client = new BaseCommerceClient( "username", "password", "key" );
o_client.setSandbox(true);
o_bc_transaction = o_client.processBankCardTransaction(o_bc_transaction);
int n_transaction_id = o_bc_transaction.getTransactionId();
System.out.println( o_bc_transaction.getTransactionId() );

o_bc_transaction = new BankCardTransaction();
o_bc_transaction.setTransactionId( n_transaction_id );
o_bc_transaction.setType( BankCardTransaction.XS_BCT_TYPE_CAPTURE );
o_bc_transaction.setAmount( 9.50 );

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.getAuthorizationCode() );
       System.out.println( o_bc_transaction.getTransactionId() );
       System.out.println( o_bc_transaction.getResponseCode() );
       System.out.println( o_bc_transaction.getResponseMessage() );
       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.getTransactionId() );
       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.getAuthorizationCode() );
       System.out.println( o_bc_transaction.getTransactionId() );
       System.out.println( o_bc_transaction.getResponseCode() );
       System.out.println( o_bc_transaction.getResponseMessage() );
}
System.out.println("avs code : " + o_bc_transaction.getAVSResponseCode() );
System.out.println("cvv code : " + o_bc_transaction.getCVVResponseCode() );

Address Verification Services (AVS)

The Address Verification System (AVS) is a system used to verify the address of a person claiming to own a credit card. The system will check the billing address of the credit card provided by the user with the address on file at the credit card company. AVS will automatically be performed on all transactions that have a address included in the BankCardTransaction request. After the transaction has been processed, you can obtain the results of the AVS check by invokeing the getAVSResponse() method which will contain one of the following values:

Code
Summary
Value Description
Visa
Master Card
American Express
Discover
X
Match
Street address and 9-digit ZIP code both match
Y
Match
Street address and 5-digit ZIP code both match
A
Partial Match
Street address matches, but both 5-digit and 9-digit ZIP code do not match
W
Partial Match
Street address does not match, but 9-digit ZIP code matches
Z
Partial Match
Street address does not match, but 5-digit ZIP code matches
N
No Match
Street address, 5-digit ZIP code, and 9-digit ZIP code all do not match
U
System Unavailable
Address information unavailable. Returned if non-US. AVS is not available or if the AVS in a U.S. bank is not functioning properly
R
System Unavailable
Retry - Issuer's System Unavailable or Timed Out.
E
Invalid
AVS data is invalid
S
Not Supported
U.S. issuing bank does not support AVS

Card Verification Value (CVV2, CVC2, CVD, CID)

Card Verification Value (CVV) codes are the three or four-digit codes on the back of the payment card that are used to further authenticate the consumer during a card-not-present transaction. The following are the response messages sent back to you during the authorization process, and can help determine your next action—approval, exception or decline. CVV2 check will automatically be performed on all transactions that have a CVV2 value set using the setCVV2() method on the BankCardTransaction object. After the transaction has been processed, you can obtain the results of the CVV2 check by invokeing the getCVV2ResponseCode() method which will contain one of the following values:

Code
Visa CVV2
MasterCard CVC2
Discover CVD
American Express CID
M
Match
Match
Match
Match
N
No match
No match
No match
No match
P
Not processed
Not processed
Not processed
Not applicable
S
Should have been present
Should have been present
Should have been present
Not applicable
U
Issuer unable to process
Issuer unable to process
Issuer unable to process
Issuer unable to process

3D Secure

Verified by Visa and MasterCard Secure Code enable a Cardholder making an online payment to be authenticated by their issuing bank. Verified by Visa and MasterCard Secure Code allow Cardholders to enroll for free in these programs wherein the cardholder creates a PIN Number that further identifies them as the holder of the card with their bank. Under Visa and MasterCard Operating Regulations, if an online merchant either offers the cardholder the opportunity to enroll or allows the cardholder to authenticate themselves with their PIN, the merchant is absolved from any chargeback liability. This means that if a cardholder charges back (reverses) a payment by claiming that they did not authorize the payment, that payment which has settled to the merchant, cannot be reversed or debited back to reimburse the issuer and cardholder. Verified by Visa and MasterCard Secure Code are ideal solutions for online merchants who experience a high degree of friendly fraud or merchants selling high dollar value goods who may become targets of fraudsters or dishonest consumers. In order to utilize 3D Secure in your application you must enroll in 3D Secure by Need verbiage from Hughes about enrolling in 3d secure…

By default, 3D Secure is disabled on your transactions. To enable it, you will invoke on the BankCardTransaction object the setCheckSecureCode(true) method, and the setVerifyCompleteURL() method with the URL you want us to send a POST request to after the 3D Secure process is complete. Transactions that are processed with this flag will result in a status of XS_BCT_STATUS_3DSECURE indicating that you should redirect the user to the URL that is returned by the BankCardTransaction’s getVerifyURL() method. This will allow the user to complete the online verification process with their financial institution. Once the use has completed the verification process they will be redirected to the URL that you provided in the setVerifyCompleteURL() method. Appended to the URL will be the BankCardTransaction ID of the transaction that was processed, under the key / name : bank_card_transaction_id. You should then invoke a getBankCardTransaction call on the BaseCommerceClient to retrieve the updated status of the transaction to determine weather 3D Secure failed (XS_BCT_STATUS_FAILED), or completed successfully and the transaction was processed; XS_BCT_STATUS_AUTHORIZED for Authorizations, XS_BCT_STATUS_CAPTURED for Sales, or XS_BCT_STATUS_DECLINED if the transaction was declined for other reasons.

Response Codes

Response Code Value
Response Code Message
0000
Approved
0001
Duplicate request (Approved Previously)
0002
Partial amount approved
0003
Duplicate request (Declined Previously)
0004
Reversal not allowed
0005
Return not allowed
0006
Supervisor override required
0007
Modify transaction not allowed
0008
Possible duplicate request
0009
Duplicate Request (Reversed previously)
0010
Inactive terminal (The terminal in the store is inactive )
0011
Device (Terminal) configuration missing
0012
Insufficient privileges
0013
Incremental Auth Not Allowed
0020
Inactive account
0021
Merchant (Account) configuration missing
0022
Processor configuration missing
0023
Merchant already active
0030
Unique ID error
0050
Inactive terminal
0060
Inactive account
0070
Relates to a unique hardware Identifier for that terminal
0080
Duplicate request (Backend)
0090
Reversal not allowed (Backend)
0091
Return not allowed (Backend)
0092
Request format error (Backend)
0093
Encryption failure from host
0910
Time out
0911
System Errort
0912
Error on Host
7000
Record not found
7500
Record not found (Backend)
2001
Refer to Issuer
2002
Suspected Card (Pick UP, Hot-Card)
2003
Honor with Identification
2004
Invalid Amount
2005
Invalid Card
2006
No such Issuer
2007
Invalid Fee
2008
Incorrect PIN
2009
Pin Attempts Exceeded
2010
Key Synchronized Failed from Host
2011
Expired Card
2012
Insufficient Funds
2013
Invalid from Account
2014
Invalid to Account
2015
Withdrawal Limit Exceeded
2016
Withdrawal Frequency Exceeded
2017
Time Limit for Pre-Auth Reached
2018
AVS Failed
2019
Billing Zip Match
2020
CVV2 Verification Failed
2021
Issuer or Switch Imperative
2022
Duplicate Transaction (Same amount / Account)
2023
Balance unavailable for inquiry
2024
Check digit error
2025
Excluded BIN ID for merchant
2026
Do not honor
2027
AVS and CVV2 failed
2028
Invalid date
2029
Invalid service
2030
Host validation error
2031
Activity Limit Exceeded
2032
Cannot complete because of violation
2033
Debit Pin required
2034
Blocked BIN by Issuer/Type
2035
Check service authentication failure
2039
Could Not Retrieve a Valid Card Number for Token
2040
Invalid Card – Mod 10 check failed
2041
Duplicate Card
2042
No Card found for the BIN
7001
Invalid User_ID
7002
Invalid Password
7003
User Locked..Call CSR
7004
Invalid Security Question/Answer
7005
User Already Logged in
7006
Force Password Change
7007
User Inactive..Call CSR
7008
Operator Not Found
7009
Expired Client Password
7010
Invalid Host ID
7011
Client Authentication Failed
7012
Invalid user or password
7013
Multiple users with same email. Enter Login ID
7100
General Login Decline
7110
Invalid Password Length
9000
Validation Error
9100
AVS Required
9101
Postal Code Does Not Match
9102
Street Address Does Not Match
9103
Issuing Bank Does Not Support AVS
9106
AVS System Error
9110
CVV Required
9111
CVV Does Not Match
9112
CVV Not Provided