Menu

Secured Vault

Included in the Base Commerce platform is a secured vault that can be used for storing customer payment information, both credit card and bank account information. We encourage our Partners and Merchants to utilize our PCI Level1 Compliant vault to store any payment information rather than storing this information within your software applications. Protecting consumer data is a critical responsibility of software developers, and data breaches can be extremely costly should they occur. 

The vault works by assigning a unique token to each payment data record that is added to the system. Future transactions can then be processed by utilizing the token instead of the payment details. The scope of each stored record is dictated by the credentials that are used when creating the record. Records that are created using a Merchant username, password, and key will be linked to that Merchant.

Adding Credit Card Vault Records

Credit card vault records are created using the BankCard object in the BaseCommerceSDK and the addBankCard method in the BaseCommerceClient.

BaseCommerceClient o_client = new BaseCommerceClient( "username", "password", "key");
BankCard o_bank_card = new BankCard ();
o_bank_card.setCardExpirationMonth("03");
o_bank_card.setCardExpirationYear("2019");
o_bank_card.setCardNumber( "4111111111111111");
o_bank_card.setCardName("Test Card");

You have the option of either specifying your own Token or having the BaseCommerce platform generate one for you. If you want to specify your own token you can set it using the setToken() method:

o_bank_card.setToken("myToken123");

The last step is to invoke the addBankCard() method on the BaseCommerceClient.

o_bank_card = o_client.addBankCard( o_bank_card );

If you did not specify your own token when creating the BankCard object, you can retrieve the system generated token by invoking the getToken() method on the BankCard object returned by addBankCard(). This is the token that you should stored on your system for future transactions.

o_bank_card.getToken();

Required Credit Card Vault Record Fields

  • Number
  • Expiration Month
  • Expiration Year
  • Name

Optional Credit Card Vault Record Fields

  • Email
  • Token (if one is not passed in to us we will generate one)
  • Custom Fields 1-10
  • Alias
  • Address (required if merchant has AVS required set)


Processing Credit Card Transactions Using A Token

Transactions can be processed using a vault token by setting the token on the BankCardTransaction object using the setToken() method. When a token is present on the BankCardTransaction, payment details will be retrieved from the vault to process the payment.

BankCardTransaction o_bc_transaction = new BankCardTransaction();
o_bc_transaction.setType(BankCardTransaction.XS_BCT_TYPE_SALE);
o_bc_transaction.setAmount(5.25);
o_bc_transaction.setToken("2f2baba358a59cecdc4f5a88ffbd74d355c3c9b2397544d2184339b3c60d2c3e");
BaseCommerceClient o_client = new BaseCommerceClient("username", "password", "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() );
}

Adding Bank Account Vault Records

Bank account vault records are created using the BankAccount object in the BaseCommerceSDK and the addBankAccount method in the BaseCommerceClient:

BaseCommerceClient o_client = new BaseCommerceClient( "username", "password", "key");
BankAccount o_bank_account = new BankAccount ();
o_bank_account.setAccountNumber( "123123123123");
o_bank_account.setRoutingNumber( "111000025");
o_bank_account.setType( BankAccount.XS_BA_TYPE_CHECKING);
o_bank_account.setAccountName("Test Card");

You have the option of either specifying your own Token or having the BaseCommerce platform generate one for you. If you want to specify your own token you can set it using the setToken() method:

o_bank_account.setToken("myToken123");

The last step is to invoke the addBankAccount() method on the BaseCommerceClient:

o_bank_account = o_client.addBankAccount( o_bank_account );

If you did not specify your own token when creating the BankAccount object, you can retrieve the system generated token by invoking the getToken() method on the BankAccount object returned by addBankAccount(). This is the token that you should stored on your system for future transactions.

o_bank_account.getToken();

Required ACH Vault Record Fields

  • Name
  • Account Number
  • Routing Number
  • Type (Checking/Savings)

Optional

  • Email Address
  • Vault Alias
  • Custom Fields 1-10
  • Token (if one is not passed in to us we will generate one)

Processing ACH Transactions Using A Token

Transactions can be processed using a vault token by setting the token on the BankAccountTransaction object using the setToken() method. When a token is present on the BankAccountTransaction, payment details will be retrieved from the vault to process the payment:

BankAccountTransaction o_ach_transaction = new BankAccountTransaction();
o_ach_transaction.setType(BankAccountTransaction.XS_BAT_TYPE_DEBIT);
o_ach_transaction.setMethod(BankAccountTransaction.XS_BAT_METHOD_CCD);
o_ach_transaction.setAmount(5.25);
o_ach_transaction.setToken("7388430d262469efac9563027bb239edbf3c167a4a958ab128a53f9af3b185f7");
BaseCommerceClient o_client = new BaseCommerceClient(XS_USERNAME, XS_PASSWORD, XS_KEY);
o_client.setSandbox(true);
o_ach_transaction = o_client.processBankAccountTransaction(o_ach_transaction);
if (o_ach_transaction.isStatus(BankAccountTransaction.XS_BAT_STATUS_FAILED)) {
    // Transaction failed, look at messages for reasons why
    System.out.println(o_ach_transaction.getMessages());
} else if (o_ach_transaction.isStatus(BankAccountTransaction.XS_BAT_STATUS_CREATED)) {
    // Transaction successful
    System.out.println(o_ach_transaction.getBankAccountTransactionId());
}