External Payment Gateway Connector API
To integrate an external payment gateway with Bold Checkout, a developer must create an external payment gateway connector. A connector is an API implemented by a developer that interfaces between the external payment gateway and Bold Checkout. Bold Checkout uses this connector to send payloads to the designated external payment gateway.
A connector must support the following endpoints:
These endpoints are built on the iframe_url
set when registering the gateway with the Create External Payment Gateway endpoint. For example, if your iframe_url
is www.example.com/gateway
, your Retain
endpoint will be www.example.com/gateway/retain
.
A connector also uses actions and events to interact with the iframe
, as shown in the External Payment Gateway Actions and Events reference.
For more information on external payment gateways, refer to the Concepts page. For information on integrating external payment gateways in Checkout, refer to the Integrate an External Payment Gateway guide.
Request headers
The request headers from Bold contain a signature and other metadata in the following format:
Authorization: Signature keyId="api_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) x-bold-date"
X-Bold-Api-Authorization: Signature keyId="api_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) x-bold-date"
Retain
Converts a token received from the Checkout Frontend Create Payment endpoint into a permanent reference used for payment processing.
Retain Request
TYPE: POST
Attributes
Key | Type | Description |
---|---|---|
provider_id | string | An identifier configured when the gateway is provisioned by the external payment gateway. |
token | string | A token generated by the payment gateway to identify the payment. |
customer_data | object | An array of customer data pulled from the order. |
billing_address | object | (Optional) The full billing address from the order. Bold leaves this field empty if the billing address is not set on the order. |
third_party_parameters | array | An array of key-value pairs passed to Bold Checkout via the Create Payment endpoint. |
Example
{
"provider_id": "8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228"
"token": "ABCF-123",
"customer_data":
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
},
"billing_address":
{
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"third_party_parameters":
[
"payment1": "details1",
"payment2": "details2"
]
}
Retain Response
Attributes
Key | Type | Description |
---|---|---|
token | string | A string generated by the payment gateway to identify the retained payment. |
Example
{
"token": "C-123AB"
}
Auth
Authorizes a payment of a specific value.
Auth Request
TYPE: POST
Attributes
Key | Type | Description |
---|---|---|
token | string | A token generated by the payment gateway, returned in the Retain response. |
order_id | integer | The Bold-generated internal order identifier. |
amount | number | The payment amount, represented in cents/base currency units, using ISO-4217 standards. |
currency | string | The currency of the payment, using ISO-4217 standards. |
billing_address | object | (Optional) The full billing address from the order. Bold leaves this field empty if the billing address is not set on the order. |
shipping_address | object | (Optional) The full shipping address from the order. Bold leaves this field empty if the shipping address is not set on the order. |
order_details | object | (Optional) Detailed information about each line item, shipping information, total taxes and the shipping total. Only set if additional_order_details is set to true when registering an external payment gateway. |
Example
{
"token": "C-123BA",
"amount": 10000,
"order_id": 188JS98DUJD7,
"currency": "CAD",
"billing_address": {
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping_address": {
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"order_details": {
"tax_total": 30,
"shipping_total": 5,
"line_items":
[
{
"name": "Oak Cheese Grater",
"description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
"kind": debit,
"quantity": 2,
"unit_amount": 2350,
"unit_tax_amount": 150,
"total_amount": 5000,
"discount_amount": 0,
"product_code": "OAK_GRATER_SM"
}
],
"shipping_address": {
"company": "Bold Commerce",
"country_code_alpha2": "CA",
"country_name": "Canada",
"extended_address": "Suite 200",
"first_name": "John",
"last_name": "Doe",
"locality": "Winnipeg",
"postal_code": "R3Y0L6",
"region": "MB",
"street_address": "50 Fultz Blvd"
}
}
}
Auth Response
Attributes
Key | Type | Description |
---|---|---|
authorization_id | string | A string generated by the payment gateway to identify the authorized payment. |
Example
{
"authorization_id": "123ABC456"
}
Capture
Captures a specific payment amount less than or equal to the authorization amount.
For partial captures, Checkout sends the hold_open
flag to indicate there may be additional captures against the authorization.
Capture Request
TYPE: POST
Attributes
Key | Type | Description |
---|---|---|
authorization_id | string | A string generated by the payment gateway to identify an authorized payment, returned in the Auth response. |
amount | number | The payment amount, represented in cents/base currency units, using ISO-4217 standards. |
hold_open | boolean | Set to true if there are more possible captures to follow against the same authorization. Only set if partial_capture is set to true when registering an external payment gateway. |
fulfillment_data | object | Object passed in via the Create Payment endpoint. Only sent if required by the external payment application. |
The structure of fulfillment_data
is dependent on the external payment gateway. Bold directly passes the data provided by the external payment gateway in this field.
Example
{
"authorization_id": "123ABC456",
"amount" : 5000,
"hold_open": true,
"fulfillment_data":
{
"fulfillment_info": "<fulfillment_info_details>"
}
}
Capture Response
Attributes
Key | Type | Description |
---|---|---|
transaction_id | string | A string generated by the payment gateway to identify the transaction. |
Example
{
"transaction_id": "aj7rif94sd"
}
Void
Cancels the payment authorization before capture. Uses the authorization_id
to cancel the authorization and release the held funds.
Void Request
TYPE: POST
Attributes
Key | Type | Description |
---|---|---|
authorization_id | string | The authorization_id returned in an Auth response. |
Example
{
"authorization_id" : "123ABC456"
}
Void Response
Attributes
None
Example
200
on success
Refund
Refunds a specific amount against a previously successful capture.
Refund Request
TYPE: POST
Attributes
Key | Type | Description |
---|---|---|
amount | number | The payment amount, represented in cents/base currency units, using ISO-4217 standards. |
transaction_id | string | The transaction_id of the payment capture to issue the refund against, returned in the Capture response. |
reason | string | A text description, giving the refund reason. |
refund_data | object | An object containing a list of items refunded by this request. |
Example
{
"amount": 2500,
"transaction_id": "aj7rif94sd",
"reason" : "Product didn't arrive",
"refund_data": {<refund_data>}
}
Refund Response
Attributes
None
Example
200
on success