Onboarding

This guide is for Partners building an onboarding integration with custom user interface (UI) to upload merchant applications and manage documentation.

If you're interested in a hosted solution for onboarding, contact your Account Manager.

Getting started

To get a custom UI using our Onboarding API, you'll need to construct an environment that integrates our sandbox, and have it approved by our Onboarding Team.

To begin, make sure you're signed up for a partner account. After you're accepted, we'll email you an API access token for our sandbox environment along with a Pricing Package ID.

Your test Pricing Package ID will set the rates for customers that begin processing.

Once you have your account and pricing ID, you'll be ready to start building your environments. To help with your integration you can review our Onboarding API References.

Testing environments

Using the API access token provided by your Account Manager, you can start building your integration.

Sandbox

The sandbox you have access to will be a direct clone of the Production environment, and allows you to test the workflow of Onboarding.

This sandbox is currently limited to Onboarding and does not include test payments.

All API calls to the sandbox are made through the following URL:

https://sandbox-api.na.bambora.com/

If an application is created using the PSP-CAD flow, a request to GET it would look like:

https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/applications/{applicationId}

As an application moves through the Onboarding process, it will be in multiple states:

An application that is rejected cannot be reviewed further, and must be re-submitted as a new application.

To test the transition between states in the sandbox environment, you can enter a magic string in the company_name field on a POST or PUT request.

• TEST_APPROVED - Move the application from in_progress to approved.
• TEST_REJECTED - Move the application from in_progress to rejected.

Integration review

Once you've completed all of your integration testing, contact your Account Manager to begin the review.

Most reviews take no longer than a single business day, and ensure that your integration is:

• Submitting complete and correct forms.
• Correctly displaying or linking to Terms and Conditions.
• Correctly displaying or linking to card processing prices.

Production

After your integration is approved, you'll be provided with a Production API key for your Production environment. Other than your magic string no longer working, the two environments will be identical.

All API calls to production are made through the following URL:

https://api.na.bambora.com/

If an application is created using the PSP-CAD flow, a request to GET it would look like:

https://api.na.bambora.com/v1/boarding/workflows/psp-cad/applications/{applicationId}

API requests

Request headers

When you make an HTTP request to the API, headers are required for both authentication, and the API version.

Authentication

Every request that is made to the Onboarding and Payments API requires an API access token, and can be included in the header:

Authorization: Bearer YOUR_TOKEN_HERE

API version

You can find a list of our Onboarding API versions here. Any new integrations require the most recent version.

Add the version number to the Header of your API request:

X-API-Version: 2016-08-18

If the API is updated, or a new one is introduced, it will appear in the Changelog. If an API is ever deprecated, you'll be notified via email well in advance with assistance in updating.

Select a flow

All endpoints in the Onboarding API are organized based on the functionality being requested. We call these, 'flows'.

All flows support the creation, reading, and updating of applications, as well as requesting Terms and Conditions. Some flows also support creating and reading of documents attached to applications.

Each application can only be associated with a single flow. If a Merchant wants to work through multiple flows to accept multiple currencies, for example, they'll need to submit an application for each flow.

Fund transfer

Fund transfer flow is used for financial transactions between institutions such as banks completing direct deposit, payroll, and batched transactions. Accounts using a fund transfer flow are locked to the specified region.

Card payments

Used for processing payment transactions including credit cards. Accounts using a card payments flow are locked to the specified region.

Gateway

A flow for any Merchant Account held with another acquirer, the gateway flow allows transactions like the card payments flow.

You can find a complete list of flows in our Onboarding API References, with the most recent version of the API specs here, and Terms and Conditions here.

Sample integration calls

As we run through all of the parts of an integration call, we'll be referring to the PSP-CAD Card payments flow.

Terms and Conditions

In your UI, Bambora's Terms and Conditions must be linked to or displayed. Our API requires that you clearly specify the version of the terms, the pricing or rate, as well as the date and time when they are agreed to. This ensures that the merchant is aware of processing fees and their cost. If you require custom Terms and Conditions, you can reach out to your Account Manager to learn more.

Standard Terms and Conditions are acquired through a GET, and can be requested as either a PDF or HTML.

/v1/boarding/workflows/psp-cad/terms/{partner}/{file_type}/version

In the example below, the call is being made for the Terms as HTML. For default Terms, set the partner value to default.

With Terms and Conditions calls, the version and authorization header are optional

To begin the two-step call, execute the following cURL command.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/terms/default/html/version \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE"

A JSON object will be returned.

{
  "version": "o5xq2r8JtnqYUWr1mURrOEZVXyx_fihe",
  "name": "psp-cad/default/html/2017-04-03_21:25:10"
}

Next, extract the version for your second call.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/terms/default/html/version/o5xq2r8JtnqYUWr1mURrOEZVXyx_fihe \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE"

This second API call will return a raw HTML or PDF of the Terms and Conditions.

During the review process of your interface and integration, the Onboarding Team will ensure you're displaying the Terms and Pricing correctly.

Creating an application

When you create an application, you'll need to include the first JSON version, and name call references from the Terms, not the name from the header of the second call.

To create a new application, you'll POST using /v1/boarding/workflows/psp-cad/applications

While there are no required fields to make an HTTP request, fields highlighted by a red asterisk are required to move an application to the in_review state. The sample below has all of the required fields for a PSP-CAD application. In the testing sandbox, this application would be moved to approved.

Execute the following cURL request by adding your version, authorization header, and pricing package ID, and the required application fields.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/applications \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE" \
-d '{
    "pricing_id": "123_YOUR_ID_123",
    "applicant": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1988-03-25T22:00:00.00000Z",
      "phone_number": "222-222-2222",
      "email": "test@example.com",
      "agreement": {
        "name": "psp-cad/default/html/2017-04-03_21:25:10",
        "version": "o5xq2r8JtnqYUWr1mURrOEZVXyx_fihe",
        "timestamp": "2017-03-25T22:04:10.04399Z"
      },
      "address": {
        "address_line1": "123 Main Street",
        "city": "Victoria",
        "country":"CA"
      }
    },
    "business": {
      "company_name": "TEST_APPROVED",
      "annual_sales": 800000.00,
      "merchant_category": "5813",
      "entity_type": "partnership",
      "start_date": "2013-06-01T22:06:00.00000Z",
      "address": {
        "address_line1": "123 Main Street",
        "city": "Victoria",
        "country":"CA"
      },
      "bank_account": {
        "owner_name": "Jane Doe",
        "transit_number": "69877",
        "institution_number": "345",
        "account_number": "3453"
      }
    }
}'

The agreement variables require the Terms and Conditions version and name from the first API call. All date and time variables are IS-8601 format YYYY-MM-DDThh:mm:ssTZD. For full dates that have no specific time, set the time to zeros.

Reading an application

All submitted applications can be fetched through a GET.

/v1/boarding/workflows/psp-cad/applications

The application ID is returned in the initial POST request, and used to retrieve the application. Using the cURL below, you'll add your authorization header, version, and application ID.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/applications/{applicationId} \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE" \

After an application has reached the approved state, the Merchant ID in the response will be used to process payments through your account.

To find out if an application has been approved, use an HTTP GET with the application ID to request the application state.

Updating an application

Any application currently in the in_progress state can be modified and updated using a PUT.

/v1/boarding/workflows/psp-cad/applications/{applicationId}

Using the application ID from the POST return, you'll be able to update information on an application.

If your update to an application is a single variable such as phone_number, like in the cURL below, you can add just that data. Any fields not passed will remain the way they were on creation.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/applications/{applicationId} \
-X PUT \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE" \
-d '{
      "applicant": {
      "phone_number": "222-867-5309"
      }
    }'

To remove a field from a previously submitted application, set the value of the field to an empty string or zero.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-cad/applications/{applicationId} \
-X PUT \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE" \
-d '{
      "applicant": {
      "first_name": "",
      "last_name": ""
      }
    }'

Uploading documentation

If you're using the SEPA-EUR, BACS-GBP, ACH-USD, EFT-CAD, or PSP-USD flows, you can attach a document to an in_progress application. For this example, we'll use the PSP-USD flow.

To upload documents, use POST.

/v1/boarding/workflows/psp-usd/applications/{applicationId}/documents

You'll use POST, GET, and DELETE for documents associated with an application. Execute the following cURL with your version, authorization header, and application ID to add a document.

curl https://sandbox-api.na.bambora.com/v1/boarding/workflows/psp-usd/applications/{applicationId}/documents \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "X-API-Version : SELECTED_VERSION_HERE" \
-d '{
     "name": "bank_statement",
     "type": "pdf",
     "base64": "XXxx_PUT_BASE_64_ENCODED_STRING_OF_DOCUMENT_HERE_xxXX"
    }'

Processing payments

Now that you're ready to begin processing payments, you can learn about integrating with our Payments API. You can also use our Merchant Quickstart Guide to get up and running fast.