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 base_url set when registering the gateway with the Create External Payment Gateway endpoint and the payments subroute. For example, if your base_url is www.example.com/gateway, your Retain endpoint uses the payments subroute and becomes www.example.com/gateway/payments/retain.

A connector also uses actions and events to interact with the iframe, as shown in the External Payment Gateway Actions and Events reference.

note

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) date"
X-Bold-Api-Authorization: Signature keyId="api_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) date"

Retain

Converts a token received from the Checkout Frontend Create Payment endpoint into a permanent reference used for payment processing.

Before calling any of the endpoints for the external payment gateway connector, the storefront tokenizes the payment information for the transaction. Tokenization is the process of replacing sensitive data with randomized data (a nonce) relevant only to the payment gateway.

From the embedded iframe, the storefront calls the external payment gateway to tokenize the customer's payment information.
The external payment gateway connector provides the payment information to the external payment gateway and receives a generated token. The generated token is a nonce, and it can only be used once per transaction.
The connector calls Bold's Create Payment endpoint with the returned token.

Once the external payment gateway provides the tokenized payment information, Bold uses the connector to hold the payment amount for the transaction.

Bold uses the connector's Retain endpoint to either create a customer or vault the payment information through the external payment gateway.
The external payment gateway receives the connector's nonce and returns the tokenized payment data.
The connector sends the tokenized payment data to Bold, and Bold returns a successful Create Payment response to the connector.

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`	`object`	An array of key-value pairs passed to Bold Checkout via the `payment_parameters` field in the Create Payment endpoint. If `third_party_parameters` is empty, its value is an empty array (`[]`).

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": {
    "is_giftcard": "true",
    "customer_segment_id": "ab4329tn23oe315"
  }
}

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.

When the storefront calls the Process Order endpoint, Bold must authenticate the request with the external payment gateway before proceeding.

Bold calls the connector's Auth endpoint with the storefront's information.
The connector communicates with the external payment gateway to authenticate the transaction.
Once the connector sends Bold a successful Auth response, Bold processes the authenticated transaction.
Bold returns the result of Process Order to the storefront.

The "Using automatic capture" section in the diagram represents the "delayed payment capture" setting in your Bold Checkout admin settings. When enabled, Bold does not try to immediately capture an order.

Screenshot of the delayed payment capture setting in the Bold Checkout Admin

Auth Request

TYPE: POST

Attributes

Key	Type	Description
`token`	`string`	A token generated by the payment gateway, returned in the Retain response.
`order_id`	`string`	The public order identifier, generated by Bold.
`bold_order_id`	`integer`	The Bold order identifier, generated by Bold.
`customer_data`	`object`	An object of customer data pulled from the order.
`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.

The order_details object below includes tax and shipping totals. These values are represented in either base currency units (minor units of currency) or currency units (major units of currency with appended minor units). For example, to represent $1.20 USD in base currency units, the value is 120. To represent $1.20 USD in currency units, the value is 1.20.

The order_details object also contains the array line_items. Each line item contains properties populated from the transaction. Currently, the kind field only accepts the value debit.

Example

{
  "token": "C-123BA",
  "amount": 10000,
  "order_id": "woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB",
  "bold_order_id": 255,
  "customer_data": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "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": 4.75,   # currency unit
    "shipping_total": 10.25,   # currency unit
    "line_items": [
      {
        "name": "Oak Cheese Grater",
        "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
        "kind": "debit",
        "quantity": 2,
        "unit_amount": 9500,   # base currency unit
        "unit_tax_amount": 4.75,   # currency unit
        "total_amount": 90.60,   # currency unit
        "discount_amount": 9.15,   # currency unit
        "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, Bold Checkout sends the hold_open flag to indicate there may be additional captures against the authorization.

The storefront calls one of Bold's capture payment endpoints via API.
Bold sends the request to external payment gateway connector's Capture endpoint.
The connector sends the request to the external payment gateway.
The external payment gateway sends its response to the connector, which forwards the response to Bold.
Bold sends the operation response back to the storefront.

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.
`platform_order_id`	`string`	A unique order identifier, assigned by the platform.
`platform_friendly_order_id`	`string`	An order identifier, assigned by the platform. Unique for each store.

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.

The storefront calls Bold's Cancel Order endpoint via API.
Bold sends the request to external payment gateway connector's Void endpoint.
The connector sends the request to the external payment gateway.
The external payment gateway sends its response to the connector, which forwards the response to Bold.
Bold sends the operation response back to the storefront.

Void Request

TYPE: POST

Attributes

Key	Type	Description
`authorization_id`	`string`	The `authorization_id` returned in an Auth response.
`platform_order_id`	`string`	A unique order identifier, assigned by the platform.
`platform_friendly_order_id`	`string`	An order identifier, assigned by the platform. Unique for each store.
`origin_payment_id`	`string`	The original payment's identifier. This field is only sent when using the Capture Specific Payment endpoint, which creates a new transaction from an existing one.

Example

{
  "authorization_id": "123ABC456"
}

Void Response

Attributes

None

Example

200 on success

Refund

Refunds a specific amount against a previously successful capture.

The storefront calls one of Bold's refund endpoints via Checkout Backend API.
Bold sends the request to external payment gateway connector's Refund endpoint.
The connector sends the request to the external payment gateway.
The external payment gateway sends its response to the connector, which forwards the response to Bold.
Bold sends the operation response back to the storefront.

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.
`platform_order_id`	`string`	A unique order identifier, assigned by the platform.
`platform_friendly_order_id`	`string`	An order identifier, assigned by the platform. Unique for each store.
`origin_payment_id`	`string`	The original payment's identifier. This field is only sent when using the Capture Specific Payment endpoint, which creates a new transaction from an existing one.

Example

{
  "amount": 2500,
  "transaction_id": "aj7rif94sd",
  "reason" : "Product didn't arrive",
  "refund_data": {<refund_data>}
}

Refund Response

Attributes

None

Example

200 on success

Request headers​

Retain​

Retain Request​

Attributes​

Example​

Retain Response​

Attributes​

Example​

Auth​

Auth Request​

Attributes​

Example​

Auth Response​

Attributes​

Example​

Capture​

Capture Request​

Attributes​

Example​

Capture Response​

Attributes​

Example​

Void​

Void Request​

Attributes​

Example​

Void Response​

Attributes​

Example​

Refund​

Refund Request​

Attributes​

Example​

Refund Response​

Attributes​

Example​

Request headers

Retain

Retain Request

Attributes

Example

Retain Response

Attributes

Example

Auth

Auth Request

Attributes

Example

Auth Response

Attributes

Example

Capture

Capture Request

Attributes

Example

Capture Response

Attributes

Example

Void

Void Request

Attributes

Example

Void Response

Attributes

Example

Refund

Refund Request

Attributes

Example

Refund Response

Attributes

Example