Step 3: Develop your integration

We'll now go through the process of performing and validating an online payment transaction through Checkout, Custom Checkout with Payment APIs or Batch Payments API.

Checkout users

For checkout users, see steps below. Click the links to find specific instructions.

• Step 1: Create a checkout link . 

• Step 2: Configure the checkout form . 

• Step 3: Set up redirect rules .  

• Step 4: Embed it on your website, platform or email .

Custom Checkout with Payment API users or Batch Payment API users

For users of Custom Checkout with Payment API or Batch Payment API, see requirements and steps below:

cURL

We use the command-line tool cURL for HTTP request examples, allowing API requests without a web application, similar to using command prompts in Windows or Terminal in Apple. For more information, click here .

Postman

For fans of the HTTP Client Postman , we offer a comprehensive collection of requests and an environment . The collection uses the pre and post request scripts to set authentication headers and record transaction IDs. Before you run any queries, you'll need to update the environment with your Merchant ID and API access passcodes.

API specs

Our APIs are the RESTful interface to our payment gateway. It allows you to 

• Accept and analyze credit card payments.

• Process multiple payments in one batch request.

• Create a payment profile to record customer details for future transactions

• Generate reports for credit card and bank transfer payments.

• Create customized onboarding processes for software vendor partners and large direct merchants. 

• Create credit card tokens to reduce the scope of your PCI compliance.

Only two languages are accepted, English and French.

You can either interact with the API directly or through an SDK (a library of helper functions to simplify your integration with the SDK).

1. Payment API Specs (Payment, Profiles, Reports, & Recurring Payments) 

2. Batch Payment API Specs

3. Batch Payment Report API Specs  

4. Onboarding API Specs

With your Merchant ID in hand and your passcodes set, you're ready to combine them into the required Authorization header. You can use our encoder to create an authorization header here .

Tokenize the credit card

To process credit card transactions online, you must be in compliance with standards set out by the Payment Card Industry (PCI). Tokenizing credit card details is the most effective way to reduce the scope of your PCI compliance by removing the interaction between your server and your customer's card details.

Embed our Custom Checkout JavaScript library in your checkout page to validate card inputs and tokenize all card data. Custom Checkout's input fields can be customized to fit the payment form on your web site. Follow the steps in this link on how to set-up Custom Checkout. See example image of our Custom Checkout form:

You can also access our server-based tokenization endpoint to get the token. However, it is strongly recommended to use our Custom Checkout solution instead of directly accessing the tokenization endpoint because sensitive card data is never exposed to your server, providing an extra layer of security protection against data breaches.

Example request:

curl --location 'https://api.na.bambora.com/scripts/tokenization/tokens' \
--header 'Content-Type: application/json' \
--data '{
"number":"4030000010001234",
"expiry_month":"06",
"expiry_year":"28",
"cvd":"123"
}'

Response: 200 OK

{
"token": " c140-15f0cc51-ff4b-47ee-826f-b0eb26bfbc84",
"code": 1,
"version": 1,
"message": ""
}

It is important to note that you will always receive a token, even if the request data is wrong or the card is invalid. To validate the tokenized card with the cardholder’s issuing bank, you will have to create a payment using the token by either passing it to the  Payment API to process a one-time payment immediately or pass it to the Payment Profile API to save the card data for future payments.

Create a Payment Profile

Once you have a single-use token with payment details, you can use it to store the credit card details as a Payment Profile (multi-use token) for future payments. You can also store your bank account information in the Payment Profile.

Example request:

curl --location 'https://api.na.bambora.com/v1/profiles' \
--header 'Authorization: Passcode {{passcode_encoded}}' \
--header 'Content-Type: application/json' \
{
"token":{ 
"name":"John Doe",
"code":"{{tokenizedCC}}",
},
"billing": {
"name": "John Doe",
"address_line1": "2659 Douglas St",
"address_line2": "",
"city": "victoria",
"province": "bc",
"country": "ca",
"postal_code": "V8T4M3",
"phone_number": "25013312345",
"email_address": "jon@example.com"
},
"bank_account": { 
"bank_account_holder": "Bill Smith", 
"account_number": "12345689", 
"bank_account_type": "Canadian Bank", 
"institution_number": "128", 
"branch_number": "12774" 
}, 
"validate": "true", 
"comment": "new client profile", 
"customer_code": "profile1" 
}

Response: 200 OK

{
"code": 1,
"message": "Operation Successful",
"customer_code": "profile1",
"validation": {
"id": "10000357",
"approved": "1",
"message_id": "1",
"message": "Approved",
"auth_code": "TEST",
"trans_date": "2025-03-04T08:58:30",
"order_number": "",
"type": "PA",
"amount": 0.0,
"cvd_id": "1"
}
}

You can see the list of our Payment Profile response codes here .

Take a one-time payment

With a single-use or multi-use token, you can charge the card. The sample below displays a transaction for $100 using a Payment Profile.

Example request:

curl --location 'https://api.na.bambora.com/v1/payments' \
--header 'Authorization: Passcode {{passcode_encoded}}' \
--header 'Content-Type: application/json' \


{
"order_number":"{{currentOrderNumber}}",
"amount": 100.00,
"payment_method":"payment_profile",
"payment_profile": { 
"customer_code": "{{profileId}}", 
"card_id": "{{cardId}}",
"complete": true
}
}

Response: 200 OK

{
"id": "10000358",
"authorizing_merchant_id": 387130000,
"approved": "1",
"message_id": "1",
"message": "Approved",
"auth_code": "TEST",
"created": "2025-03-04T09:04:06",
"order_number": "10000182",
"type": "P",
"payment_method": "CC",
"risk_score": 0.0,
"amount": 100.00,
"custom": {
"ref1": "",
"ref2": "",
"ref3": "",
"ref4": "",
"ref5": ""
},
"card": {
"card_type": "VI",
"last_four": "1234",
"card_bin": "403000",
"address_match": 1,
"postal_result": 1,
"avs_result": "1",
"cvd_result": "5",
"avs": {
"id": "Y",
"message": "Street address and Postal/ZIP match.",
"processed": true
}
},
"links": [
{
"rel": "void",
"href": "https://api.na.bambora.com/v1/payments/10000358/void",
"method": "POST"
},
{
"rel": "return",
"href": "https://api.na.bambora.com/v1/payments/10000358/returns",
"method": "POST"
}
]
}

If your transaction was not approved, check the HTTP response code along with the message in the object. You'll only receive one of two codes from our payment gateway emulator: 1 for approved, 7 for declined.

You can see the full list of the Payment Response codes here .

Take a recurring payment

When handling recurring or installment payments, refer to the Credential-on-File transaction guide . Here's how the process works:

1. The cardholder gives explicit permission for the merchant to securely save their payment information, including the card number and expiration date.

2. With this authorization, the merchant is allowed to use these saved details for future transactions with the cardholder.

3. The merchant is responsible for implementing the logic and schedule for executing the recurring payments.

By following these steps, you ensure compliance and functionality when managing stored payment credentials for repeated transactions.

Example request:

curl --location 'https://api.na.bambora.com/v1/payments' \
--header 'Authorization: {{your_encoded_payment_profile_passcode}}'\
--header 'Content-Type: application/json' \


{
"amount": 100.00,
"payment_method":"payment_profile",
"payment_profile": { 
"customer_code": "{{profileId}}", 
"card_id": "{{cardId}}",
"complete": true
},
"card_on_file": {
"type": "first_recurring"
},
"custom":{
"ref1": "January gym membership" 
}
}

Response: 200 OK

{
"id": "10000359",
"authorizing_merchant_id": 387130000,
"approved": "1",
"message_id": "1",
"message": "Approved",
"auth_code": "TEST",
"created": "2025-03-06T03:38:53",
"order_number": "10000359",
"type": "P",
"payment_method": "CC",
"risk_score": 0.0,
"amount": 100.00,
"custom": {
"ref1": "January gym membership",
"ref2": "",
"ref3": "",
"ref4": "",
"ref5": ""
},
"card": {
"card_type": "VI",
"last_four": "1234",
"card_bin": "403000",
"address_match": 1,
"postal_result": 1,
"avs_result": "1",
"cvd_result": "5",
"avs": {
"id": "Y",
"message": "Street address and Postal/ZIP match.",
"processed": true
}
},
"links": [
{
"rel": "void",
"href": "https://api.na.bambora.com/v1/payments/10000359/void",
"method": "POST"
},
{
"rel": "return",
"href": "https://api.na.bambora.com/v1/payments/10000359/returns",
"method": "POST"
}
],
"card_on_file": {
"type": "first_recurring",
"series_id": 392033758
}
}

If you need to support simple recurring payment scenarios, you can use our Recurring Payment API . This API lets you schedule payments to automatically charge your customers daily, weekly, monthly, or annually. However, please be aware that this API is not included in our RESTful specification.

Website requirements

Crafting an effective online checkout process is essential for fostering customer trust and ensuring smooth transactions on an ecommerce site. By integrating key website components, businesses can enhance usability, protect consumer data, and provide transparency, all of which contribute to a reliable and satisfying shopping experience.

These are the website requirements vital for creating a smooth and trustworthy ecommerce checkout experience:

• Business name – typically URL and DBA/legal name should match the merchant application

• Business location

• Business type & products/services sold

• Customer service number & email address (that cardholders could contact)

• Shipping or delivery information (where applicable)

• Refund/cancellation policy

• Currency of the transaction

• Privacy statement or policy

• Terms and conditions

Every business faces the challenge of fraud prevention, and Worldline is here to support you in this crucial task. In this section, you'll discover five impactful strategies designed to safeguard your operations. By taking a proactive stance, you play a crucial role in fostering a secure payment ecosystem for your business and your customers. These tools and insights will empower you to spot potential threats early and respond with confidence. Vigilance is essential in minimizing risks and maintaining the trust of those you serve.

3D Secure 2.0

3D Secure 2.0 (3DS2) is an advanced security protocol that authenticates card-not-present transactions, helping to prevent fraud while minimizing customer friction. This service offers an upgraded experience by streamlining payment verification. By incorporating 3DS2, merchants can enhance transaction security, adding an extra layer of protection for both their business and their customers.

For more details, please see our 3DS2 Guide .

Address Verification Services (AVS)

The Address Verification System (AVS) is a valuable tool for reducing fraud in card-not-present transactions. This free service compares the billing address submitted during a purchase with the address information on file with the card issuer. AVS provides merchants with a result that indicates the level of match, helping them assess the risk of each transaction. It's important to note that not all cards will have complete data available, and AVS results are generated after the transaction is processed. Merchants can then decide if a refund is necessary for high-risk transactions, adding an extra layer of security to protect their business.

Please see our list of AVS Response codes here .

Card Verification Value (CVV)

The Card Verification Value (CVV) is an integral part of card-not-present transactions, providing an additional security layer to verify a customer's identity. This 3 or 4-digit code, found on the back of most credit and debit cards, ensures that the person making the purchase has physical access to the card. As a result, the use of CVV helps reduce the likelihood of fraudulent transactions and enhances payment security. After processing a transaction, merchants can assess the risk and decide if a refund is necessary for high-risk transactions, boosting protection and confidence in their payment systems.

Please see our list of CVV Response Codes here .

Transaction reversal options

Worldline offers automatic transaction reversal options to enhance your fraud mitigation efforts and provide an additional safeguard, allowing merchants to effectively manage potential fraud risks. If there is a mismatch in the Card Verification Value (CVV) or Address Verification System (AVS) fields, you have the ability to reverse the transaction automatically. Once these options are enabled, any approved transaction with a CVD or AVS mismatch will automatically be voided, and a decline will be issued to the client. 

Please see our help documentation for more details.

Risk Thresholds

Worldline offers Risk Thresholds as a free service to help merchants block potentially high-risk transactions effectively. By utilizing sophisticated monitoring tools like geolocation checks, proxy detection, IP tracking, and Bank Identification Number verification, each transaction is evaluated and assigned a risk score ranging from 0.01 to 100, indicating the likelihood of fraud.

Transactions with risk scores meeting or exceeding the predefined Decline threshold are automatically blocked from processing. If a transaction has a risk score falling between the Warn and Decline thresholds, you'll receive an alert, allowing you to take further action as necessary. To ensure an accurate risk assessment, the customer's IP address should be included when using the API; This is automatically handled when using our hosted Checkout form.

Please reach out to our Customer Care team to enable this service on your account. 

Please see our Risk Thresholds reference here .

Payment notifications

You can register for a callback when one-time payment and recurring payments are processed. The callback URL is set in the Member Area . Click Administration , then Account settings , and then Order settings , under Response Notification .

The parameters posted to the webhook are the same as those returned by the Payment API.

You may find it helpful while testing to use tools that allow you to inspect and debug webhook requests like PutsReq or Webhook.Site .

Search the transaction

Our platform empowers you to generate flexible reports, allowing you to review detailed transaction information by transaction ID and access basic summary order data using specialized search and sort functions.

Get transactions

You can retrieve a previous transaction using this method. All you need is the transaction ID.

Example request:

curl --location 'https://api.na.bambora.com/v1/payments/{{transactionId}}' \
--header 'Authorization: Passcode {{payment_passcode_encoded}}' \
--header 'Content-Type: application/json' \

Response: 200 OK

{
"id": 10000369,
"authorizing_merchant_id": 385310000,
"approved": 1,
"message_id": 1,
"message": "Approved",
"auth_code": "TEST",
"created": "2025-03-06T21:33:18.497215-08:00",
"amount": 120.48,
"order_number": "10000369",
"type": "P",
"comments": "FY2024 Taxes Payment - Rollup 1234-09090-90909-90909",
"batch_number": "0064",
"total_refunds": 0.0,
"total_completions": 0.0,
"payment_method": "CC",
"card": {
"name": "John Doe",
"expiry_month": "02",
"expiry_year": "27",
"card_type": "VI",
"last_four": "0026",
"avs_result": "N",
"cvd_result": "1",
"cavv_result": ""
},
"billing": {
"name": "Test User",
"address_line1": "1755 W. BROADWAY SUITE 105",
"address_line2": "",
"city": "Victoria",
"province": "BC",
"country": "CA",
"postal_code": "J0L1T0",
"phone_number": "1234567890",
"email_address": "tester@test.com",
"phone_country_code": "1",
"phone_type": "m"
},
"shipping": {
"name": "User Testson",
"address_line1": "1234 Testing Street",
"address_line2": "",
"city": "Huntsville",
"province": "AL",
"country": "US",
"postal_code": "36000",
"phone_number": "0987654321",
"email_address": "user@test.com",
"phone_country_code": "1"
},
"custom": {
"ref1": "",
"ref2": "",
"ref3": "",
"ref4": "",
"ref5": ""
},
"adjusted_by": [],
"links": [
{
"rel": "void",
"href": "https://api.na.bambora.com/v1/payments/10000369/void",
"method": "POST"
},
{
"rel": "return",
"href": "https://api.na.bambora.com/v1/payments/10000369/returns",
"method": "POST"
}
],
"device_channel": "02"
}

You can learn more about using our Get Transactions, Search by Specific Criteria and its parameters and the error messages on this page .

You can learn more about using our Get Transactions, Search by Specific Criteria and its parameters and the error messages on this page . You can see the Get Transactions and Search Query Reporting API specification in our Payment API specification document .

Build a web form

Create and host a payment web form to collect bank data needed for ACH/EFT. It is the merchant’s or software vendor’s ownership to build their own web form. See an example image of a web form collecting bank account information:

Once information has been collected on the web form, you can either create, update, or add the bank account information to a Payment Profile through our Profiles API or submit the bank account details in a batch file through the Batch Payments API .

Create a Payment Profile

Create a new payment profile tied to one individual with an assigned bank account and with its billing address. FINTRAC requires merchants to provide the name and address of the beneficiary for each electronic funds transfer (EFT) that they submit for processing $1,000 or more. This is not required on US ACH payments.

You can see our Profiles API specification by going to our Payment API Specifications --> Operations --> Profiles --> Create Profile.

Example request (Canadian bank account - EFT):

curl --location 'https://api.na.bambora.com/v1/profiles' \
--header 'Authorization: Passcode {{profile_passcode_encoded}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"bank_account": {
"bank_account_holder": "Scottie Smith",
"account_number": "12345689",
"bank_account_type": "Canadian Bank",
"institution_number": "128",
"branch_number": "12773"
},
"billing": {
"name": "Scottie Smith",
"address_line1": "2659 Douglas St",
"address_line2": "",
"city": "victoria",
"province": "bc",
"country": "ca",
"postal_code": "V8T4M3",
"phone_number": "25013312345",
"email_address": "scottie.smith@fakeemail.com"
},
"comment": "new bank profile",
"customer_code": "Bank2 profile"
}'

Response: 200 OK

{
"code": 1,
"message": "Operation Successful",
"customer_code": "Bank2profile"
}

Upload the batch file

To process bank transactions (ACH/EFT) online, you will have to use the Batch Payment API. This API allows you to combine multiple transactions into a single API request. Each payment type must be processed with a separate batch request. Within a single bank-to-bank request, you can pay (credit) and collect (debit) funds. The Batch payment API uses the Batch Upload API access passcode.

Example request (Canadian bank account - EFT):

curl --location 'https://api.na.bambora.com/v1/batchpayments' \
--header 'Content-Type: multipart/form-data; boundary=CHEESE' \
--header 'Authorization: {{Batch_Upload_Encoded_Passcode}}' \
--header 'FileType: STD' \
--data '--CHEESE
Content-Disposition: form-data; name="criteria"
Content-Type: application/json


{
"process_now": 1
}
--CHEESE
Content-Disposition: form-data; name="testdata1"; filename="testdata1.csv"
Content-Type: text/plain


E,C,001,99001,09400313371,10000,1000070001,General Motors,,MerchantName,Address1,Address2,City,ON,CA,L5N5Y7
E,C,,,,10000,,,Bank3profile,dynamic descriptor
E,C,002,99002,09400313372,20000,1000070002,Paul Randall,,MerchantName,Address1,Address2,Toronto,ON,CA,M5F8J8
E,C,003,99003,09400313373,30000,1000070003,Alex Anderson,,MerchantName,Address1,Address2,Mississauga,ON,CA,L6K8K9
--CHEESE--
'

Response: 200 OK

{
"code": 1,
"message": "File successfully received",
"batch_id": 10000013,
"process_date": "20250318",
"process_time_zone": "GMT-08:00",
"batch_mode": "test"
}

Query the batch file

Query the status of your batches of bank-to-bank (ACH/EFT) transactions and the status of the individual transactions within those batches by using Batch Reporting API . For credit cards, please use the Reports query in our Payments API.