Bolt HelpDocs
SupportMerchant Dashboard
DocumentationAPI ReferenceAI Agents
Skip to content

Initialize a Bolt payment for guest shoppers

POST
/guest/payments

Initialize a Bolt guest shopper's intent to pay for a cart, using the specified payment method. Payments must be finalized before indicating the payment result to the shopper. Some payment methods will finalize automatically after initialization. For these payments, they will transition directly to "finalized" and the response from Initialize Payment will contain a finalized payment.

Authorization

api-key
X-API-Key<token>

In: header

Header Parameters

X-Publishable-Key*string

The publicly shareable identifier used to identify your Bolt merchant division.

X-Merchant-Client-Id?string

A unique identifier for a shopper's device, generated by Bolt. The value is retrieved with Bolt.state.merchantClientId in your frontend context, per-shopper. This header is required for proper attribution of this operation to your analytics reports. Omitting this header may result in incorrect statistics.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/guest/payments" \  -H "X-Publishable-Key: string" \  -H "Content-Type: application/json" \  -d '{    "profile": {      "create_account": true,      "first_name": "Alice",      "last_name": "Baker",      "email": "alice@example.com",      "phone": "+14155550199"    },    "cart": {      "total": {        "units": 9000,        "currency": "USD"      },      "tax": {        "units": 100,        "currency": "USD"      },      "order_reference": "order_100",      "order_description": "Order #1234567890",      "display_id": "215614191",      "items": [        {          "name": "Bolt Swag Bag",          "reference": "item_100",          "description": "Large tote with Bolt logo.",          "total_amount": {            "units": 9000,            "currency": "USD"          },          "unit_price": 1000,          "quantity": 9,          "image_url": "https://www.example.com/products/123456/images/1.png"        }      ],      "shipments": [        {          "cost": {            "units": 10000,            "currency": "USD"          },          "carrier": "FedEx",          "address": {            ".tag": "explicit",            "first_name": "Alice",            "last_name": "Baker",            "street_address1": "535 Mission St, Ste 1401",            "locality": "San Francisco",            "postal_code": "94105",            "region": "CA",            "country_code": "US"          }        }      ],      "discounts": [        {          "amount": {            "units": 10000,            "currency": "USD"          },          "code": "SUMMER10DISCOUNT",          "details_url": "https://www.example.com/SUMMER-SALE"        }      ]    },    "payment_method": {      ".tag": "credit_card",      "type": "credit",      "network": "visa",      "bin": "411111",      "last4": "1004",      "expiration": "2025-03",      "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",      "billing_address": {        ".tag": "explicit",        "first_name": "Alice",        "last_name": "Baker",        "street_address1": "535 Mission St, Ste 1401",        "locality": "San Francisco",        "postal_code": "94105",        "region": "CA",        "country_code": "US"      }    }  }'

{  ".tag": "finalized",  "id": "iKv7t5bgt1gg",  "status": "success",  "transaction": {    "reference": "OBYG-X1PX-FN55",    "authorizations": [      {        "processor_reference": "123456789XYZ"      }    ]  }}

Finalize a pending payment POST

Finalize a pending payment being made by a Bolt logged-in shopper. Upon receipt of a finalized payment result, payment success should be communicated to the shopper.

Finalize a pending guest payment POST

Finalize a pending payment being made by a Bolt guest shopper. Upon receipt of a finalized payment result, payment success should be communicated to the shopper.