Initialize a Bolt payment for guest shoppers

curl --request POST \
  --url https://{environment}.boltapp.com/v3/guest/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Publishable-Key: <x-publishable-key>' \
  --data '
{
  "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"
      }
    ]
  }
}

POST

guest

payments

curl --request POST \
  --url https://{environment}.boltapp.com/v3/guest/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Publishable-Key: <x-publishable-key>' \
  --data '
{
  "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"
      }
    ]
  }
}

Authorizations

X-API-Key

string

header

required

Headers

X-Publishable-Key

string

required

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.

Body

application/json

profile

object

required

An account's identifying information.

Show child attributes

cart

object

required

Show child attributes

payment_method

Credit Card Payment Method · object

required

Show child attributes

seller_splits

object[] | null

Show child attributes

authorization_type

string

The type of authorization to perform. 'estimated' for pre-authorization, 'final' for final authorization.

Example:

"final"

auto_capture

boolean

Whether to automatically capture the payment after authorization. If true, the payment will be captured immediately. If false, the payment will only be authorized and require a separate capture call.

Example:

true

three_ds_reference

string

Reference value from cardinal.

Example:

"b0f0d4d0-4630-4ec8-8f5e-a19234567890"

co_funding

object | null

Optional co-funding contribution from another merchant. Exactly one of funder_public_id or receiver_public_id must be present.

Show child attributes

Response

The payment was successfully initialized, and was either immediately finalized or is pending

Option 1
Option 2
Option 3

.tag

enum<string>

required

Available options:

finalized

Example:

"finalized"

status

enum<string>

required

Available options:

success

Example:

"success"

transaction

object

required

Show child attributes

string<id>

Example:

"iKv7t5bgt1gg"

co_funding_summary

object | null

Co-funding details for this payment, if co-funding was used.

Show child attributes

Introduction

Merchant Callback

Merchant Callback reference

Endpoints

Embeddable Checkout v3

Embeddable Checkout v1

Tokenizer

Initialize a Bolt payment for guest shoppers

Authorizations

Headers

Body

Response