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.
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.
Using the API access token provided by your Account Manager, you can start building your integration.
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:
State | Description |
---|---|
in_progress |
Any application created, but missing information in required fields. |
in_review |
Any application that is complete, but has not been approved or rejected. Applications in review cannot be updated or changed. |
on_hold |
Any application that is held from approval or rejection by a member of the Bambora Onboarding Team. |
approved |
Any complete application that is approved to begin processing. |
rejected |
Any complete application that fails to meet approval criteria. |
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.
in_progress
to approved
.in_progress
to rejected
.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:
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:
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}
When you make an HTTP request to the API, headers are required for both authentication, and the API version.
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
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.
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 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.
Flow | Description |
---|---|
SEPA-EUR | Single Euro Payments in Europe. |
BACS-GBP | Bankers Automated Clearing Service and Payment Schemes Limited in the United Kingdom. |
ACH-USD | Automated Clearing House in the United States of America. |
EFT-CAD | Electronic Funds Transfer in Canada. |
Used for processing payment transactions including credit cards. Accounts using a card payments flow are locked to the specified region.
Flow | Description |
---|---|
PSP-CAD | Payment Service Providers in Canada. |
PSP-USD | Payment Service Providers in the United States of America. |
A flow for any Merchant Account held with another acquirer, the gateway flow allows transactions like the card payments flow.
Flow | Description |
---|---|
GW-CDN | Gateway Services in Canada. |
GW-USA | Gateway Services in the United States of America. |
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.
As we run through all of the parts of an integration call, we'll be referring to the PSP-CAD Card payments flow.
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.
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 Conditionsversion
andname
from the first API call. All date and time variables are IS-8601 formatYYYY-MM-DDThh:mm:ssTZD
. For full dates that have no specific time, set the time to zeros.
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.
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": ""
}
}'
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"
}'
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.