Skip to main content

Integrate an External Payment Gateway

In this tutorial, you will learn how to integrate an external payment gateway with Bold Checkout.

Architecture requirements​

Integrating an external payment gateway requires the following:

Prerequisites​

Before you get started, complete the instructions in the Checkout Getting Started guide.

Implement the external payment gateway connector​

Bold Checkout requires an external payment gateway connector on an accessible server to communicate with the external payment gateway.

Refer to the Implement an External Payment Gateway guide for connector requirements.

Register the external payment gateway​

To register an external payment gateway for a particular store, use the Create External Payment Gateway endpoint.

The following snippet shows an example call to register an external payment gateway:

curl --request POST 'https://api.boldcommerce.com/shop/{shop_identifier}/external-payment-gateways' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "external_payment_gateways": [
             {
                 "name": "Example External Payment Gateway",
                 "public_id": "VfYRxzOjRkwG6B2xWbxhPQ",
                 "base_url": "www.example.com/payments",
                 "iframe_url": "www.example.com/gateway",
                 "api_token": "XjqnSQWYAZXt",
                 "partial_capture": true,
                 "additional_order_details": true,
                 "provider_id": "8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228",
                 "currency": "CAD",
                 "location": "payment_method_below"
             }
         ]
     }'

To perform request header verification, you must include the api_token in the registration request.

Verify requests from Bold Checkout​

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"
note

The headers only appear if you set the api_token when registering your external payment gateway, as shown in the previous section.

In order to verify that a request is from Bold, you can use the date and your stored shared secret to calculate a SHA-256 hash and ensure it matches what was sent in the Authorization and X-Bold-Api-Authorization headers. These headers should contain the same value.

The following JavaScript snippet shows an example of programmatically verifying that the request you receive is from Bold:

const httpSignature = require("http-signature");
const verify_signature = (req, res, next) => {
  // Verify Bold Checkout's HTTP signature.
  try {
    // Avoid failing validation if date header contains `request-target`.
    const tempURL = req.url;
    req.url = req.originalUrl;
    const parsed = httpSignature.parse(req);
    req.url = tempURL;

    // Verify that the request originated from Bold Checkout.
    if (httpSignature.verifyHMAC(parsed, process.env.SHARED_SECRET)) {
      next();
    } else {
      res.status(401).end();
    }
  } catch (error) {
    res.status(401).end();
  }
};
module.exports = {
  verify_signature,
};

Next steps​

Place a test order (optional)​

Now you can place an order to ensure that everything has been set up correctly. After ensuring that your store is in developer mode, navigate to the storefront and complete a checkout using the external payment gateway.

Modify the external payment gateway (optional)​

Bold also provides API endpoints to interact with your external payment gateways.

You can find the endpoints to list, update, and remove external payment gateways for a store in the Checkout Admin API specification file.