Bambora North America REST

Bambora North America REST Fact Sheet

Quick start

New to integrating Bambora North America REST with Spreedly? Here's your 5-minute setup guide:

Retrieve your Bambora North America REST credentials
1. Log into your Bambora dashboard
2. Navigate to administration → account setting → order setting
3. collect API access passcode and merchant id
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add Bambora gateway to Spreedly in sandbox mode

ℹ️
Review this documentation to understand more about how to test transactions.

Adding Bambora North America REST

Required Credentials

merchant_id: Your Bambora merchant identifier (merchant ID)

passcode: Your Bambora passcode used authentication

sub_merchant_id(Optional): Your Bambora sub-merchant identifier (sub merchant ID)

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
  <gateway_type>bambora_na</gateway_type>
  <merchant_id>your_merchant_id</merchant_id>
  <passcode>your_passcode</passcode>
  <sub_merchant_id>your_sub_merchant_id(optional)</sub_merchant_id>
</gateway>'

Response

<gateway>
    <token>1GGR5AAJ038QSVPRTFGAHM8XTV</token>
    <gateway_type>bambora_na</gateway_type>
    <name>Bambora North America REST</name>
    <description nil="true"/>
    <merchant_profile_key nil="true"/>
    <sub_merchant_key nil="true"/>
    <merchant_id>300200374</merchant_id>
    <sub_merchant_id nil="true"/>
    <characteristics>
        <supports_purchase type="boolean">true</supports_purchase>
        <supports_authorize type="boolean">true</supports_authorize>
        <supports_capture type="boolean">true</supports_capture>
        <supports_partial_capture type="boolean">true</supports_partial_capture>
        <supports_credit type="boolean">true</supports_credit>
        <supports_partial_credit type="boolean">false</supports_partial_credit>
        <supports_general_credit type="boolean">false</supports_general_credit>
        <supports_void type="boolean">true</supports_void>
        <supports_adjust type="boolean">false</supports_adjust>
        <supports_verify type="boolean">true</supports_verify>
        <supports_reference_purchase type="boolean">false</supports_reference_purchase>
        <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
        <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
        <supports_store type="boolean">false</supports_store>
        <supports_remove type="boolean">false</supports_remove>
        <supports_fraud_review type="boolean">false</supports_fraud_review>
        <supports_network_tokenization type="boolean">false</supports_network_tokenization>
        <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
        <supports_partial_refund type="boolean">true</supports_partial_refund>
        <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    </characteristics>
    <credentials>
        <credential>
            <name>merchant_id</name>
            <value>merchant_id</value>
        </credential>
        <credential>
            <name>sub_merchant_id</name>
            <value nil="true"/>
        </credential>
    </credentials>
    <gateway_settings>
  </gateway_settings>
    <gateway_specific_fields>
        <gateway_specific_field>billing_phone_country_code</gateway_specific_field>
        <gateway_specific_field>billing_phone_type</gateway_specific_field>
        <gateway_specific_field>shipping_phone_country_code</gateway_specific_field>
        <gateway_specific_field>shipping_email</gateway_specific_field>
        <gateway_specific_field>ship_same_as_ord</gateway_specific_field>
        <gateway_specific_field>device_channel</gateway_specific_field>
        <gateway_specific_field>three_ds_xid</gateway_specific_field>
        <gateway_specific_field>three_ds_enabled</gateway_specific_field>
        <gateway_specific_field>language</gateway_specific_field>
        <gateway_specific_field>ref1</gateway_specific_field>
        <gateway_specific_field>ref2</gateway_specific_field>
        <gateway_specific_field>ref3</gateway_specific_field>
        <gateway_specific_field>ref4</gateway_specific_field>
        <gateway_specific_field>ref5</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
        <payment_method>apple_pay</payment_method>
    </payment_methods>
    <state>retained</state>
    <redacted type="boolean">false</redacted>
    <sandbox type="boolean">true</sandbox>
</gateway>

Purchase (Auth and Capture)

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
  "payment_method_token": "payment_method_token",
  "amount": 1000,
  "currency code": "CAD"
  "retain_on_success": true
  }
}

Additional Notes

Bambora supports card-on-file transaction for purchase transaction only.
For transacting without 3ds use three_ds_enabled GSF as false
Bambora captures 0 amount for voiding the autorization transaction.

Advanced features

3D Secure Global (3DS) authentication

ℹ️
Please review this guide to understand how Spreedly works with 3DS Global.

Stored Credentials

For Bambora, sending stored credential fields can be done using Spreedly’s first class support. For any Authorize or Purchase request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction:

stored_credential_initiator

stored_credential_reason_type

First / credential-on-file setup (CIT)

reason_type	initiator	card_on_file.type (bambora mapped field)
installment	cardholder	first_installment
recurring	cardholder	first_recurring
unscheduled	cardholder	first_unscheduled

Subsequent use

reason_type	initiator	card_on_file.type
installment	merchant	subsequent_installment
installment	cardholder	subsequent_installment
recurring	merchant	subsequent_recurring
recurring	cardholder	subsequent_recurring
unscheduled	merchant	subsequent_unscheduled
unscheduled	cardholder	subsequent_customer_initiated

Gateway Specific Fields

<gateway_specific_fields>
  <bambora_na>
    <gateway_specific_field>billing_phone_country_code</gateway_specific_field>
    <gateway_specific_field>billing_phone_type</gateway_specific_field>
    <gateway_specific_field>shipping_phone_country_code</gateway_specific_field>
    <gateway_specific_field>shipping_email</gateway_specific_field>
    <gateway_specific_field>ship_same_as_ord</gateway_specific_field>
    <gateway_specific_field>device_channel</gateway_specific_field>
    <gateway_specific_field>three_ds_xid</gateway_specific_field>
    <gateway_specific_field>three_ds_enabled</gateway_specific_field>
    <gateway_specific_field>language</gateway_specific_field>
    <gateway_specific_field>ref1</gateway_specific_field>
    <gateway_specific_field>ref2</gateway_specific_field>
    <gateway_specific_field>ref3</gateway_specific_field>
    <gateway_specific_field>ref4</gateway_specific_field>
    <gateway_specific_field>ref5</gateway_specific_field>
  </bambora_na>
</gateway_specific_fields>

Field Name	Type	Required	Use Case (Description)	Example Value
billing_phone_country_code	String	No	Country code for the billing phone number to ensure proper international formatting.	1
billing_phone_type	String	No	Specifies the type of billing phone (e.g., mobile, home, work) for fraud checks or contact classification.	m
shipping_phone_country_code	String	No	Country code for the shipping phone number. Useful for international deliveries.	1
shipping_email	String	No	Email address associated with the shipping details for delivery notifications or verification.	[email protected]
ship_same_as_ord	Boolean	No	If true, billing address is reused as the shipping address to simplify checkout.	TRUE
device_channel	String	No	Indicates the device channel used for the transaction (e.g., browser, app). Often used in fraud/3DS flows.	2
three_ds_xid	String	No	Unique identifier for tracking the 3DS transaction. If not provided, it will be auto-generated.	abc123xyz
three_ds_enabled	Boolean	No	Controls whether 3DS authentication is applied to the transaction.	FALSE
language	String	No	Preferred language for the transaction or user interface.	en
ref1	String	No	Custom reference field mapped to Bambora for internal tracking or metadata.	any value
ref2	String	No	Additional custom reference field for gateway-specific use.	any value
ref3	String	No	Additional custom reference field for gateway-specific use.	any value
ref4	String	No	Additional custom reference field for extended metadata tracking.	any value
ref5	String	No	Additional custom reference field for extended metadata tracking.	any value

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <bambora_na>
    <auth_code>57</auth_code>
    <transaction_type>P | R | VP | VR | PA | PAC</transaction_type>
    <risk_score>0</risk_score>
    <links>links for void/refund</links>
    <details>error details array</details>
    <three_ds_xid>2345678ygf</three_ds_xid>
  </bambora_na>
</gateway_specific_response_fields>

Field Name	Type	Description
auth_code	string	Authorization code returned by the Bambora gateway indicating the result of the transaction.
transaction_type	string (enum)	Type of transaction performed. Possible values: P = Purchase R = Return/Refund VP = Void Purchase VR = Void Return PA = Pre-Authorization PAC = Pre-Authorization Completion
risk_score	integer	Represents the probability (in percentage) that the transaction is fraudulent. For example, a value of 10 indicates a 10% fraud risk.
links	object / string	Contains URLs to perform follow-up actions such as void, refund, or completion of the transaction.
details	array	An array containing error details or additional information related to the transaction.
three_ds_xid	string	Unique identifier used to trace the 3D Secure (3DS) transaction in Bambora. If not provided, Spreedly generates a unique ID.

Additional resources

📘
If you need support with this gateway please contact Support at [email protected].

📘
Bambora Documentation: Worldline NAM Developer Documentation
API Endpoint: https://api.na.bambora.com/v1 (Production)
Test Endpoint: https://api.na.bambora.com/v1 (Test)