Search

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 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 and they can only be used by that merchant.

If you would like to utilize the same card information/vault record under multiple merchants you will want to add the vault record under one merchant, get back the token, then add a second card using the second merchant's SDK credentials but set the same token on that vault record before adding it (opposed to letting Base Commerce auto generate a token for you) Then when you are processing transactions using vault records by giving us a token to us, we use the vault record that is under each merchant. Code sample is below.

*Please note, that for VISA cards, a $0.00 authorization will be run on the card before allowing to add the card to the vault due to VISA rules and regulations.

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");

o_address.setLine1("123 test lane");
o_address.setZipcode("12345");
o_address.setCity("looney town");
o_address.setState("az");
o_address.setCountry("us");

o_bank_card.setBillingAddress(o_address);

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. This would be the method you would want to utilize if you want to have the same token value for vault records under different merchants. You can NOT have the same token value for a vault record under the same merchant though:

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 (GUI Merchant Portal only)
Token (if one is not passed in to us we will generate one)
Custom Fields 1-10 (GUI virtual terminal only)
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 (GUI Merchant Portal only)
Vault Alias
Custom Fields 1-10 (GUI virtual terminal only)
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());
}

Adding the same Bank Account vault record information under 2 different merchants.

String s_account_number = "123456789";
String s_routing_number = "011001962";
String s_name = "Test account";

BankAccount o_bank_account = new BankAccount();
o_bank_account.setName( s_name );
o_bank_account.setAccountNumber( s_account_number );
o_bank_account.setRoutingNumber( s_routing_number );
o_bank_account.setType(BankAccount.XS_BA_TYPE_CHECKING);

String s_token = "";

BaseCommerceClient o_client = new BaseCommerceClient(XS_USERNAME, XS_PASSWORD, XS_KEY);
o_client.setSandbox( true );
o_bank_account = o_client.addBankAccount( o_bank_account );

if (o_bank_account.isStatus( BankAccount.XS_BA_STATUS_FAILED ) ) {
    // Bank Account add failed, look at messages for reasons why
    System.out.println( o_bank_account.getMessages() );
} else if ( o_bank_account.isStatus( BankAccount.XS_BA_STATUS_ACTIVE ) ) {
    // Bank Account add Successful and record the token so you can use it later to add the second vault record
    s_token = o_bank_account.getToken();

    //create a second BankAccount to add to the vault
    BankAccount o_bank_account_2 = new BankAccount();
    o_bank_account_2.setName( s_name );
    o_bank_account_2.setAccountNumber( s_account_number );
    o_bank_account_2.setRoutingNumber( s_routing_number );
    o_bank_account_2.setType(BankAccount.XS_BA_TYPE_CHECKING);
    //set token to be same as first one
    o_bank_account_2.setToken( s_token );

    //need to initialize client using the second merchants SDK credentials
    BaseCommerceClient o_client_2 = new BaseCommerceClient(XS_USERNAME_2, XS_PASSWORD_2, XS_KEY_2);
    o_client_2.setSandbox(true);
    o_bank_account_2 = o_client_2.addBankAccount( o_bank_account_2 );

    if (o_bank_account_2.isStatus( BankAccount.XS_BA_STATUS_FAILED ) ) {
        // Bank Account add failed, look at messages for reasons why
        System.out.println( o_bank_account_2.getMessages() );
    } else if ( o_bank_account_2.isStatus( BankAccount.XS_BA_STATUS_ACTIVE ) ) {
        //its active under the second merchant now
    }

}

Now that the vault record is under both merchants, you can process a BankAccountTransaction call using that same token. The transaction will be processed under the merchant whose SDK credentials were used.