📍 Bolt Help / Platforms / Direct API / Custom Cart Integration / Set Up Hook URLs

Set Up Hook URLs

Learn how to configure Hook URLs in the Bolt Merchant Dashboard.

Page Contents

Click to expand.

Set up Hook URLs in the Bolt Merchant Dashboard so Bolt can call your Merchant Callback API during checkout. Each Hook URL corresponds to a feature that must also be enabled.

WARNING

This page configures Merchant Callbacks, which Bolt calls during checkout. It does not configure transaction webhooks. Those are a separate system with a separate URL, set up under Administration > Developers > Webhooks, and the callback type dropdown below has no option for them. See transaction webhooks.

How to Set Up Hook URLs

Log in to the Bolt Merchant Dashboard.
Navigate to Administration > API.
Scroll to Merchant Callbacks.
Choose the base URL you want to update and click the pencil icon next to it.
Select the endpoint you want to declare in the dropdown menu.
Input the URL.
Select Add merchant callback to save.

Universal API URL

The Universal API endpoint can be used as an alternative to having many individually defined endpoints such as Shipping, Tax, and Create Order. One URL receives every event, and you branch on the event field described in Merchant Callback conventions.

Divisions set up as a custom cart can use it by default. If the Universal API type is not available to you, or you configure a URL and no callbacks ever arrive, your division is most likely not set up as a custom cart; see prerequisites and readiness. The individually defined Create Order, Shipping, and Tax types work regardless and are the fallback in the meantime.

PHP Example

https://your-store-url.com/example/universalapi.php

<?php
require(dirname(__FILE__) . '/init_example.php');

$hmacHeader = @$_SERVER['HTTP_X_BOLT_HMAC_SHA256'];

$signatureVerifier = new \BoltPay\SignatureVerifier(
    \BoltPay\Bolt::$signingSecret
);

$requestJson = file_get_contents('php://input');

if (!$signatureVerifier->verifySignature($requestJson, $hmacHeader)) {
    throw new Exception("Failed HMAC Authentication");
}

$requestData = json_decode($requestJson);
$event = $requestData->event;

header('Content-Type: application/json');
http_response_code(200);
$exampleData = new \BoltPay\Example\Data();
switch ($event) {
    case "order.shipping":
        $data = $exampleData->generateShippingOptions();
        break;
    case "order.tax":
        $shippingOption = @$requestData->data->shipping_option;
        $data = $exampleData->generateTaxOptions($shippingOption);
        break;
    case "order.shipping_and_tax":
        $data = $exampleData->generateShippingTaxOptions();
        break;
    case "order.create":
        $baseUrl = $exampleData->getBaseUrl();
        $data = [
            'status' => 'success',
            'message' => 'Order create was successful.',
            'order_received_url' => $baseUrl . '/example/order_confirmation.php',
            'display_id' => @$requestData->order->cart->display_id
        ];
        break;
}

echo json_encode(
    [
        'status' => 'success',
        'event' => $event,
        'data' => $data,
    ]
);

Shipping URL

The Shipping endpoint is the singular alternative to the combined Shipping and Tax endpoint.

PHP Example

https://your-store-url.com/example/shipping.php

<?php
require(dirname(__FILE__) . '/init_example.php');

$hmacHeader = @$_SERVER['HTTP_X_BOLT_HMAC_SHA256'];

$signatureVerifier = new \BoltPay\SignatureVerifier(
 \BoltPay\Bolt::$signingSecret
);

$requestJson = file_get_contents('php://input');

if (!$signatureVerifier->verifySignature($requestJson, $hmacHeader)) {
 throw new Exception("Failed HMAC Authentication");
}

$exampleData = new \BoltPay\Example\Data();
$response = $exampleData->generateShippingOptions();

header('Content-Type: application/json');
http_response_code(200);
echo json_encode($response);

Tax URL

The Tax endpoint is the singular alternative to the combined Shipping and Tax endpoint.

PHP Example

https://your-store-url.com/example/tax.php

<?php
require(dirname(__FILE__) . '/init_example.php');

$hmacHeader = @$_SERVER['HTTP_X_BOLT_HMAC_SHA256'];

$signatureVerifier = new \BoltPay\SignatureVerifier(
    \BoltPay\Bolt::$signingSecret
);

$requestJson = file_get_contents('php://input');

if (!$signatureVerifier->verifySignature($requestJson, $hmacHeader)) {
    throw new Exception("Failed HMAC Authentication");
}

$requestJson = file_get_contents('php://input');

$shippingOption = json_decode($requestJson)->shipping_option;
$exampleData = new \BoltPay\Example\Data();
$response = $exampleData->generateTaxOptions($shippingOption);

header('Content-Type: application/json');
http_response_code(200);
echo json_encode($response);

Shipping and Tax URL

The Shipping and Tax endpoint can be used to combined both Shipping and Tax calculations in one request.

PHP Example

https://your-store-url.com/example/shipping_and_tax.php

<?php
require(dirname(__FILE__) . '/init_example.php');

$hmacHeader = @$_SERVER['HTTP_X_BOLT_HMAC_SHA256'];

$signatureVerifier = new \BoltPay\SignatureVerifier(
    \BoltPay\Bolt::$signingSecret
);

$requestJson = file_get_contents('php://input');

if (!$signatureVerifier->verifySignature($requestJson, $hmacHeader)) {
    throw new Exception("Failed HMAC Authentication");
}

$exampleData = new \BoltPay\Example\Data();
$response = $exampleData->generateShippingTaxOptions();

header('Content-Type: application/json');
http_response_code(200);
echo json_encode($response);

Create Order URL

The Create Order endpoint is used to verify that an order can be created before payment is authorized.

PHP Example

https://your-store-url.com/example/preauth_create_order.php

<?php
require(dirname(__FILE__) . '/init_example.php');

$client = new \BoltPay\ApiClient([
    'api_key' => \BoltPay\Bolt::$apiKey,
    'is_sandbox' => \BoltPay\Bolt::$isSandboxMode
]);

$requestJson = file_get_contents('php://input');
$requestData = json_decode($requestJson);
$exampleData = new \BoltPay\Example\Data();
$baseUrl = $exampleData->getBaseUrl();
$response = [
    'status' => 'success',
    'message' => 'Order create was successful.',
    'order_received_url' => $baseUrl . '/example/order_confirmation.php',
    'display_id' => @$requestData->order->cart->display_id
];

header('Content-Type: application/json');
http_response_code(200);
echo json_encode($response);