Implement a pre-authorization flow by creating an order in your ecommerce platform before starting the authorization process. This prevents capturing funds on orders that have failed for various reasons.

How to Create & Authorize an Order

The order.create Merchant Callback API is called after a shopper has selected Pay and directly before Bolt process with payment authorization.

1. Implement order_create Merchant Callback API on your server.
2. Respond to Bolt’s order.create POST request from your Merchant Callback API.
3. Verify the authenticity of the request by confirming that it originated from Bolt.

Request and Response Shape

Bolt sends this event, like every callback, as an envelope of event and data. For order.create, data holds the order, the payment method, and the currency:

{
  "event": "order.create",
  "data": {
    "order": {
      "token": "a1b2c3...",
      "cart": { "display_id": "displayid_100", "order_reference": "order_100" },
      "user_note": ""
    },
    "payment_method": "credit_card",
    "currency": "USD"
  }
}

Respond with the same envelope, putting display_id and, if you want Bolt to redirect the shopper, order_received_url inside data. Returning order_received_url suppresses the frontend success and close callbacks, so do not settle orders from success if you use it:

{
  "event": "order.create",
  "status": "success",
  "data": {
    "display_id": "displayid_100",
    "order_received_url": "https://example.com/order_confirmation"
  }
}

PHP Example

<?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);
$baseUrl = $exampleData->getBaseUrl();

// Bolt sends every callback as {event, data}. The order lives under `data`.
$order = @$requestData->data->order;

$response = [
    'event' => 'order.create',
    'status' => 'success',
    'data' => [
        'order_received_url' => $baseUrl . '/example/order_confirmation.php',
        'display_id' => @$order->cart->display_id
    ]
];

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

Test the Endpoint

Pre-Auth Flow

1. Create an order in a pending state. The transaction must still undergo Bolt’s fraud review.
2. Listen for a Bolt webhook informing whether this order has been accepted or denied.

Without Pre-Auth Flow

1. Create an order upon receiving a pending webhook or from the frontend success callback.
2. Verify one of the following based on your setup:
   • If you respond to Bolt with an order_received_url (confirmation page), then Bolt will redirect the shopper to that URL when the order is complete. The frontend success and close callbacks do not run in this case.
   • If you choose not to respond with an order_received_url, the frontend callbacks run and your storefront is responsible for navigation.
   • If the card authorization fails after a successful pre-auth request, Bolt will send a webhook to inform that this order has failed card authorization.