Skip to main content

Create a Checkout Remote State Authority

The Checkout Remote State Authority (RSA) enables Bold to interact with a remote system that owns and has complete control over the state of an order during checkout. When a Checkout RSA is configured, Bold Checkout sends requests to the Checkout RSA, which enables the platform to manipulate the order and sends an updated order back to Bold Checkout. Create a Checkout RSA by implementing the API.

For more information about how it works, refer to the Concepts page.

This document outlines the steps required to create a Checkout RSA and connect it to your store.

Prerequisites​

Before you get started, complete the following steps:

  1. Install and configure Bold Checkout.
  2. Build a platform connector using the following guides:
    1. Getting Started
    2. Implement Platform Connector APIs
    3. Implement Platform Event Notifications
    4. Verify the Platform Connector

General server requirements​

The main component of your Checkout RSA is a server that can accept and respond to calls from Bold.

The server you implement must meet the following requirements:

  • Must have a publicly accessible hosting server.
  • Must accept requests from api.boldcommerce.com.
  • Must support HTTPS and must have a signed SSL/TLS certificate for the server.
  • Must handle JSON requests and return JSON responses.
  • All requests sent to the server require the shop_identifier as a path parameter.
    • After obtaining your API access token, you can call the Get Info endpoint to get the shop_identifier. For more information, refer to Making API Calls.

Choose the destination URL​

Bold requires a destination URL, where all requests to the Remote Authority are sent. Only one URL is required.

You can either use a unique destination URL or an existing destination URL (such as one from your existing platform connector).

Create the API server​

Your application must handle requests from Bold as well as interact with your own solutions. Create the code manually or use an OpenAPI generator.

Either method begins with retrieving the Checkout Remote State Authority specifications. To download the raw version of the OpenAPI specification file, click the Download button at the top of the page.

OpenAPI Generator​

Bold recommends using an OpenAPI generator to create a server stub for the RSA. Using an OpenAPI generator speeds up the development process by automatically generating boilerplate code to handle incoming requests.

There are a few open source options for API generators available:

note

Bold does not officially support or endorse any specific OpenAPI generator. Use your best judgment when choosing and implementing a solution.

Manual​

Creating the API server code manually is a larger effort, but this method can help ensure your server is constructed to meet your unique needs. It also requires a stronger knowledge of the OpenAPI Specification standard. Ensure all paths are handled as outlined in the specification.

Extend the server stub​

The Checkout Remote State Authority specifications outline the expected behavior of the server. Ensure the request handlers are responding in accordance to this behavior. The specific implementation is unique to your environment, but here are some general guidelines:

  • Fields prefixed with platform_ must have unique values that are generated by your implementation. platform_id fields are expected to be unique within the given resource. For example, no two customers can have the same platform_id.
  • All timestamps are in accordance with RFC 3339 (e.g., 2021-03-11T17:16:51Z).

Connect Checkout RSA to your store​

To connect your Checkout RSA to your store, call the Connect Remote State Authority endpoint. Provide your chosen destination URL and shared secret (which can be any string you choose). Bold uses the shared secret and the current date to create a signature for each request.

The following code snippet shows an example of this call:

curl --request POST 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/rsa_config' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "url": "https://example.com/my_remote_state_authority",
         "shared_secret": "d5210fa5563dd4f5b06f00d0"
     }'

Ensure the security of your Checkout RSA​

Bold provides several mechanisms for you to be sure that calls to your Checkout RSA are valid and coming from Bold, including an HMAC signature and a User-Agent header.

Filter on User-Agent header​

Each call from Bold to your Checkout RSA is accompanied by a User-Agent header with a value of Bold-API. This header enables you to filter traffic from Bold through your firewall system, if applicable.

Verify the signature​

Each call from Bold to your Checkout RSA is accompanied by an HMAC (hash-based message authentication code) signature. This signature is constructed from your shared secret (provided to Bold when you call the Connect Remote State Authority endpoint) and a timestamp, using Base64 encoding.

Upon receiving a call to your destination URL, verify that the request came from Bold by decoding the signature. The following code sample includes an example of creating an HMAC signature, which you would verify against Bold's signature:

const crypto = require("crypto");

const sharedSecret = "{shared_secret}"; // Your shared secret provided to the RSA congifuration endpoint
const providedSignature = "{x-hmac}"; // The x-hmac value from the signature header
const timestamp = "{x-hmac-timestamp}"; // The timestamp from the x-hmac-timestamp header
const signature = `x-hmac-timestamp: ${timestamp}`; // The string to sign

// The generated hmac to compare against the provided hmac
const calculatedSignature = crypto.createHmac("sha256", sharedSecret).update(signature).digest("base64");

if (calculatedSignature == providedSignature) {
  console.log("Signatures match!");
} else {
  console.log("Signatures do not match!");
}

Verify the RSA functionality​

To verify RSA functionality, place a test order on your store. Ensure that the information in your remote authority matches the information in Bold Checkout, either by a call to the Get Application State endpoint or viewing the Order details page in the Bold Checkout admin.