Using The SDK

To take a test drive of our SDK in our sandbox environment, please go here: https://www.basecommerce.com/developers/ to register for a demo account. In order to use the SDK in the production environment, you will need to have an active Merchant Account with Base Commerce.


Before diving into the SDK here is an overview of the Base Commerce platform as well as some notes on submitting development tickets.


  • Overview of BaseLink
    • Partner Portal ( https://partner.basecommercesandbox.com and https://partner.basecommerce.com )
      • Partner Portal is for our partners on the Base Commerce gateway.  A username(email), password, and SMS pin number is required for each login. When logged into partner portal, all the merchants listed under your partner are available for viewing. The partner portal has reporting functions that can be for their entire portfolio or refined to one merchant. Partners have the ability to submit new merchant applications and view application statuses through the partner portal. Partner users with the role Masquerade enabled, have the ability to log into their merchant’s virtual terminal. This allows further reporting refined to that specific merchant and allows the partner to provide customer support as they can see everything the merchant sees.  The partner does not have the ability to edit their merchants configuring or add processing services. Partners can also add/delete partner users here.
      • In sandbox partners can create multiple sandbox merchants to help their testing. This is done by clicking the "New Sandbox Merchant" button on the merchant tab.
      • From an SDK standpoint, the partner can get their partner level SDK credentials from the developer tab. Partner SDK credentials can only be used to submit merchant applications. To process transactions you will need to use merchant SDK credentials.
    • Merchant Portal ( https://my.basecommercesandbox.com and https://my.basecommerce.com )
      • Merchant Portal is the virtual terminal for merchants. A username(email) and password is required for each login. The Merchant portal allows merchants to create new transactions, save customer information in their encrypted vault, and schedule recurring payments. The merchant portal provides reporting such as CC and ACH transaction data, CC and ACH batch information, ACH funding, Chargebacks, and ACH statements. The merchant portal gives the merchant the ability to customize their account such as receipts and custom transaction fields. Merchant users enabled as administrator have the ability to edit and create additional merchant logins.  The merchant does not have the ability to view or edit their account configuring. If they need something changed or updated, their agent(partner) or an authorized contact should Base Commerce operations.
      • If you are a user under multiple merchants, when you go to login a drop down on the login screen will give you the options of which merchant you would like to login under.
      • From an SDK standpoint, the merchant SDK credentials will be used to add vault records and process transactions. Merchant SDK credentials can not be used to submit merchant applications.
  • Merchant Applications via SDK
    • If you plan on submitting merchant applications via the SDK you will want to work with your RM/Account Manager to go through a merchant application and see what will apply to your business model. There is a lot of conditional logic and various pricing fields that are different depending on the merchant's business. Merchant applications submitted via the SDK can be viewed in the partner portal to confirm all fields are set correctly. Once you believe you have everything set how you would like it, your RM/Account Manager will need to approve everything looks good in sandbox before moving to submit live applications in production. Doing this will ensure the fastest turn around time when in production by minimizing delays/application pending by having the most accurate data as possible.
  • Development tickets ( https://basesdksupport.com )
    • A signed partner or merchant agreement is required to receive development support.
    • Development tickets are solely meant for SDK development questions. If your question(s) do not relate to using the SDK, you might be asked to forward your question to your RM/Account Manager or another department to answer, which will then increase your overall response time.
    • Always submit a ticket first, even if you would like to have a conference call, someone from the development team is not always available to join a conference call immediately. A ticket created with the preemptive questions added to it could be answered sooner, and an agenda of topics/questions will be required as a prerequisite to a call. Also with tickets being created everything is recorded and can be referenced at a later time.
    • New tickets should be created for different questions for ease of referencing later.
    • If you have questions or requests to enable any features or change any account management type of items ( thresholds, name change, add users, etc…), for both sandbox and/or production, these should go through your RM/Account Manager or requests@basecommerce.com not the development ticketing system.
    • Development tickets have a 24-48 business hour response time. Development questions go to this URL which requires an email and password but gives a view of all your open and old tickets: https://basesdksupport.com
    • Please let us know once the ticket has been answered/fulfilled. On average if you go 5 business days without responding to us it will get put into a pending closure status then after 2 more days the ticket will be automatically closed.



Regardless of which programming language you are using, the architecture of the SDK is the same. All code examples throughout this document (and throughout all of the Base Commerce Technical Documentation) are in JAVA. To retrieve your SDK credentials, go to https://my.basecommercesandbox.com (https://my.basecommerce.com for production) under the Development tab.


Please note, that there are several more examples in the merchant portal, under the developer tab, at the bottom in the code snippets section. This has examples in all languages.


Each request to the Base Commerce Platform begins by initializing the BaseCommerceClient object with your username, password, and transaction key. 

BaseCommerceClient o_client = new BaseCommerceClient( “username”, ”password”, ”key”); 

Ping Pong

The main focus of this feature is to have a fast check for both your credentials, and general connection to the Base Commerce Servers. 

BaseCommerceClient o_client = new BaseCommerceClient( "username", "password", "key" );
        
// Set to true if you are testing the connection to the sandbox environment, otherwise do not set
o_client.setSandbox(true);
        
try {
            
    System.out.println( o_client.sendPing() );
            
} catch ( BaseCommerceClientException ve_exception ) {
            
    switch ( ve_exception.getMessage() ) {
		case "Invalid Credentials.":
        	// Handle here
            break;
        case "Invalid url or host is offline.":
        	// Handle here
            break;
	}
            
}

What To Expect

  • If success, the method will return true
  • If failed due to wrong credentials
    • Will throw / raise an exception saying "Invalid Credentials."
      • in Obj-C this is handled by the handle403Response BaseCommerceClientDelegate method
  • If failed due to connectivity issues
    • Will throw / raise an exception saying "Invalid url or host is offline."
      • in Obj-C this is handled by the handle404Response BaseCommerceClientDelegate method

Last Session ID

Every request made through the SDK is given a unique Session ID. This Session ID should be stored after every request while testing and passed in with any Development Support Tickets you open when running into issues. The Session ID will enable our Development Support Team to quickly identify your connection and what went wrong. For more information about SDKs for Credit Card Processing, please visit: Credit Card Processing.

BaseCommerceClient o_client = new BaseCommerceClient( XS_USERNAME, XS_PASSWORD, XS_KEY );
 
// Make any request with the client, for this example we will grab the Session ID after calling deleteBankAccount
BankAccount o_bank_account = o_client.deleteBankAccount( "e604b169820e45b79bc87a357be848b7ebb25229a7c741386595d155209acc63" );

// We are ignoring what was returned via the BankAccount as its state does not effect receiving a Session ID

String s_session_id = o_client.getLastSessionID();
 
// Save or print out this Session ID with each request so you have it when you run into issues

System.out.println( "Session ID : " + s_session_id );

Processing Transactions

Bank Card Transactions

Bank Account Transactions