POST
/
v1
/
merchant
/
transactions
/
authorize
Authorize a Card
curl --request POST \
  --url https://api.bolt.com/v1/merchant/transactions/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "cart": {
    "total_amount": 900,
    "currency": "USD",
    "order_reference": "order_100",
    "add_ons": [
      {
        "name": "<string>",
        "price": 123,
        "productId": "<string>",
        "description": "<string>",
        "imageUrl": "<string>",
        "productPageUrl": "<string>"
      }
    ],
    "discounts": [
      {
        "amount": 100,
        "code": "SUMMER10DISCOUNT",
        "description": "10% off our summer collection",
        "details_url": "https://boltswagstore.com/SUMMERSALE",
        "reference": "DISC-1234",
        "type": "percentage"
      }
    ],
    "fees": [
      {
        "reference": "ItemFee",
        "name": "Item Fee",
        "unit_price": 123,
        "unit_tax_amount": 123,
        "quantity": 123,
        "description": "Item Fee"
      }
    ],
    "fulfillments": [
      {
        "cart_items": [
          {
            "name": "Bolt Swag Bag",
            "quantity": 1,
            "reference": "item_100",
            "total_amount": 1000,
            "unit_price": 1000,
            "brand": "Bolt",
            "category": "bags",
            "collections": [
              "summer"
            ],
            "color": "Bolt Blue",
            "customizations": [
              {
                "attributes": {
                  "key1": "value1",
                  "key2": "value2"
                },
                "name": "<string>",
                "price": 754
              }
            ],
            "description": "Large tote with Bolt logo.",
            "details_url": "https://boltswagstore.com/products/123456",
            "external_inputs": {
              "shopify_line_item_reference": 123,
              "shopify_product_reference": 123,
              "shopify_product_variant_reference": 123
            },
            "gift_option": {
              "cost": 770,
              "merchant_product_id": "881",
              "message": "Happy Anniversary, Smoochy Poo!",
              "wrap": false
            },
            "image_url": "https://boltswagstore.com/products/123456/images/1.png",
            "isbn": "9780091347314",
            "item_group": "<string>",
            "manufacturer": "Bolt Textiles USA",
            "merchant_product_id": "881",
            "merchant_variant_id": "888",
            "msrp": 123,
            "options": "Special Edition",
            "properties": [
              {
                "color": "<string>",
                "display": true,
                "name": "<string>",
                "name_id": 123,
                "value": "<string>",
                "value_id": 123
              }
            ],
            "shipment": {
              "carrier": "FedEx",
              "cost": 770,
              "discounted_by_membership": false,
              "estimated_delivery_date": "08-30-2022",
              "expedited": false,
              "package_depth": 90,
              "package_dimension_unit": "cm",
              "package_height": 103,
              "package_type": "A big package.",
              "package_weight_unit": "kg",
              "package_width": 222,
              "service": "Option 1",
              "shipping_address_id": "address1",
              "shipping_method": "unknown",
              "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
              "tax_amount": 230,
              "tax_code": "tax-12345",
              "total_weight": 55,
              "total_weight_unit": "kg",
              "type": "door_delivery"
            },
            "size": "Large",
            "sku": "BOLT-SKU_100",
            "source": "<string>",
            "seller_id": "seller-1234",
            "tags": "tote, blue, linen, eco-friendly",
            "tax_amount": 0,
            "tax_code": "<string>",
            "taxable": true,
            "uom": "inches",
            "upc": "0825764603119",
            "weight": 10,
            "weight_unit": "pounds"
          }
        ],
        "cart_shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "digital_delivery": {
          "email": "<string>",
          "phone": "<string>"
        },
        "in_store_cart_shipment": {
          "cart_shipment": {
            "carrier": "FedEx",
            "cost": 770,
            "discounted_by_membership": false,
            "estimated_delivery_date": "08-30-2022",
            "expedited": false,
            "package_depth": 90,
            "package_dimension_unit": "cm",
            "package_height": 103,
            "package_type": "A big package.",
            "package_weight_unit": "kg",
            "package_width": 222,
            "service": "Option 1",
            "shipping_address_id": "address1",
            "shipping_method": "unknown",
            "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
            "tax_amount": 230,
            "tax_code": "tax-12345",
            "total_weight": 55,
            "total_weight_unit": "kg",
            "type": "door_delivery"
          },
          "description": "Pick up in-store at 123 Main St.",
          "distance": 3,
          "distance_unit": "mile",
          "pickup_window_close": 123,
          "pickup_window_open": 123,
          "store_name": "Bolt Collective"
        }
      }
    ],
    "in_store_cart_shipments": [
      {
        "cart_shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "description": "Pick up in-store at 123 Main St.",
        "distance": 3,
        "distance_unit": "mile",
        "pickup_window_close": 123,
        "pickup_window_open": 123,
        "store_name": "Bolt Collective"
      }
    ],
    "items": [
      {
        "name": "Bolt Swag Bag",
        "quantity": 1,
        "reference": "item_100",
        "total_amount": 1000,
        "unit_price": 1000,
        "brand": "Bolt",
        "category": "bags",
        "collections": [
          "summer"
        ],
        "color": "Bolt Blue",
        "customizations": [
          {
            "attributes": {
              "key1": "value1",
              "key2": "value2"
            },
            "name": "<string>",
            "price": 754
          }
        ],
        "description": "Large tote with Bolt logo.",
        "details_url": "https://boltswagstore.com/products/123456",
        "external_inputs": {
          "shopify_line_item_reference": 123,
          "shopify_product_reference": 123,
          "shopify_product_variant_reference": 123
        },
        "gift_option": {
          "cost": 770,
          "merchant_product_id": "881",
          "message": "Happy Anniversary, Smoochy Poo!",
          "wrap": false
        },
        "image_url": "https://boltswagstore.com/products/123456/images/1.png",
        "isbn": "9780091347314",
        "item_group": "<string>",
        "manufacturer": "Bolt Textiles USA",
        "merchant_product_id": "881",
        "merchant_variant_id": "888",
        "msrp": 123,
        "options": "Special Edition",
        "properties": [
          {
            "color": "<string>",
            "display": true,
            "name": "<string>",
            "name_id": 123,
            "value": "<string>",
            "value_id": 123
          }
        ],
        "shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "size": "Large",
        "sku": "BOLT-SKU_100",
        "source": "<string>",
        "seller_id": "seller-1234",
        "tags": "tote, blue, linen, eco-friendly",
        "tax_amount": 0,
        "tax_code": "<string>",
        "taxable": true,
        "uom": "inches",
        "upc": "0825764603119",
        "weight": 10,
        "weight_unit": "pounds"
      }
    ],
    "loyalty_rewards": [
      {
        "amount": 123,
        "coupon_code": "<string>",
        "description": "$5 off (100 Points)",
        "details": "{\"id\": 123456, \"icon\": \"fa-dollar\", \"name\": \"$15.00 Off\", \"type\": \"Coupon\", \"amount\": 100, \"duration\": \"single_use\", \"cost_text\": \"150 Points\",  \"description\": \"Get $15 off your next purchase for 150 points\", \"discount_type\": \"fixed_amount\", \"unrendered_name\": \"$15.00 Off\",  \"discount_percentage\": null, \"discount_rate_cents\": null, \"discount_value_cents\": null, \"discount_amount_cents\": 1500,  \"unrendered_description\": \"Get $15 off your next purchase for 150 points\", \"applies_to_product_type\": \"ALL\"}",
        "points": 123,
        "source": "<string>",
        "type": "<string>"
      }
    ],
    "shipments": [
      {
        "carrier": "FedEx",
        "cost": 770,
        "discounted_by_membership": false,
        "estimated_delivery_date": "08-30-2022",
        "expedited": false,
        "package_depth": 90,
        "package_dimension_unit": "cm",
        "package_height": 103,
        "package_type": "A big package.",
        "package_weight_unit": "kg",
        "package_width": 222,
        "service": "Option 1",
        "shipping_address_id": "address1",
        "shipping_method": "unknown",
        "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
        "tax_amount": 230,
        "tax_code": "tax-12345",
        "total_weight": 55,
        "total_weight_unit": "kg",
        "type": "door_delivery"
      }
    ],
    "tax_amount": 123,
    "cart_url": "https://boltswagstore.com/orders/123456765432",
    "display_id": "displayid_100",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "order_description": "Order #1234567890"
  },
  "create_bolt_account": true,
  "credit_card": {
    "bin": "411111",
    "expiration": "2025-11",
    "last4": "1234",
    "postal_code": "10044",
    "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
    "token_type": "bolt",
    "save": true,
    "affirm_vcn_token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"
  },
  "division_id": "3X9aPQ67-YrB",
  "source": "direct_payments",
  "user_identifier": {
    "phone": "+12125550199",
    "artifact": null,
    "email": "alan.watts@example.com",
    "email_id": null,
    "phone_id": null
  },
  "user_identity": {
    "first_name": "Charlotte",
    "last_name": "Charles"
  },
  "auto_capture": true,
  "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",
  "previous_transaction_id": null
}
'
{
  "did_create_bolt_account": true,
  "order_number": "<string>",
  "transaction": {
    "amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "authorization": {
      "auth": "<string>",
      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",
      "metadata": {},
      "status": "succeeded"
    },
    "capture": {
      "amount": {
        "amount": 754,
        "currency": "USD",
        "currency_symbol": "$"
      },
      "id": "BcDE4fafd2a4",
      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",
      "metadata": {},
      "splits": [
        {
          "amount": {
            "amount": 754,
            "currency": "USD",
            "currency_symbol": "$"
          },
          "type": "processing_fee"
        }
      ],
      "status": "succeeded"
    },
    "captures": [
      {
        "amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "id": "BcDE4fafd2a4",
        "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",
        "metadata": {},
        "splits": {
          "amount": {
            "amount": 754,
            "currency": "USD",
            "currency_symbol": "$"
          }
        },
        "status": "succeeded"
      }
    ],
    "credit": {
      "status": "succeeded",
      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567"
    },
    "date": 1615407159447,
    "from_consumer": {
      "first_name": "Alan",
      "id": "<string>",
      "last_name": "Watts",
      "authentication": {
        "actions": [],
        "methods": [],
        "sso_authorization_url": "<string>"
      },
      "email_verified": true,
      "emails": [
        {
          "address": "<string>",
          "id": "<string>",
          "priority": "primary",
          "status": "<string>"
        }
      ],
      "phones": [
        {
          "country_code": "US",
          "id": "<string>",
          "number": "<string>",
          "status": "<string>"
        }
      ]
    },
    "from_credit_card": {
      "billing_address": {
        "company": "Bolt",
        "country": "United States",
        "country_code": "US",
        "door_code": "123456",
        "email_address": "alan.watts@example.com",
        "first_name": "Alan",
        "id": "<string>",
        "last_name": "Watts",
        "locality": "Brooklyn",
        "name": "Alan Watts",
        "phone_number": "+12125550199",
        "postal_code": "10044",
        "priority": "primary",
        "region": "NY",
        "region_code": "NY",
        "street_address1": "888 main street",
        "street_address2": "apt 3021",
        "street_address3": "c/o Alicia Watts",
        "street_address4": "Bridge Street Apartment Building B"
      },
      "bin": "402201",
      "display_network": "Visa",
      "expiration": 1654041600000,
      "icon_asset_path": "img/issuer-logos/visa.png",
      "id": "AB3rJKam5DhYE",
      "last4": "4021",
      "network": "visa",
      "priority": "primary",
      "status": "active",
      "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
      "token_type": "bolt"
    },
    "id": "T1c3p4yBuVYJ9",
    "indemnification_decision": "indemnified",
    "indemnification_reason": "merchant_force_approved",
    "last4": "4021",
    "last_viewed_utc": 123,
    "merchant_division": {
      "account_page_url": "<string>",
      "api_base_domain_url": "<string>",
      "base_domain_url": "<string>",
      "confirmation_redirect_url": "<string>",
      "create_order_url": "<string>",
      "debug_url": "<string>",
      "description": "<string>",
      "display_name": "<string>",
      "get_account_url": "<string>",
      "shopper_custom_fields_updated_url": "<string>",
      "hook_url": "<string>",
      "id": "<string>",
      "is_universal_merchant_api": true,
      "is_webhooks_v2": true,
      "logo": {
        "domain": "<string>",
        "resource": "<string>"
      },
      "logo_dashboard": {
        "domain": "<string>",
        "resource": "<string>"
      },
      "merchant_id": "<string>",
      "mobile_app_domain_url": "<string>",
      "oauth_logout_url": "<string>",
      "oauth_redirect_url": "<string>",
      "platform": "<string>",
      "plugin_config_url": "<string>",
      "privacy_policy_url": "<string>",
      "product_info_url": "<string>",
      "public_id": "<string>",
      "remote_apiurl": "<string>",
      "shipping_and_tax_url": "<string>",
      "shipping_url": "<string>",
      "status": "<string>",
      "tax_url": "<string>",
      "terms_of_service_url": "<string>",
      "universal_merchant_api_url": "<string>",
      "update_cart_url": "<string>",
      "use_async_refunds_amazon_pay": true,
      "use_async_refunds_paypal": true,
      "validate_additional_account_data_url": "<string>",
      "merchant_password_login_url": "https://www.example.com/login"
    },
    "merchant_order_number": "<string>",
    "order_decision": {
      "decision_factors": [
        "<string>"
      ],
      "score": 123
    },
    "processor": "adyen_gateway",
    "reference": "LBLJ-TWW7-R9VC",
    "review_ticket": {
      "id": "<string>",
      "request_deadline": 123,
      "status": "<string>"
    },
    "risk_insights": {
      "available": true,
      "decision_factors": [
        "<string>"
      ],
      "fraud_probability": 123,
      "payment_instrument_factors": {}
    },
    "risk_review_status": "reviewed",
    "risk_score": 123,
    "splits": [
      {
        "amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        }
      }
    ],
    "status": "cancelled",
    "to_consumer": {
      "first_name": "Alan",
      "id": "<string>",
      "last_name": "Watts",
      "authentication": {
        "actions": [],
        "methods": [],
        "sso_authorization_url": "<string>"
      },
      "email_verified": true,
      "emails": [
        {
          "address": "<string>",
          "id": "<string>",
          "priority": "primary",
          "status": "<string>"
        }
      ],
      "phones": [
        {
          "country_code": "US",
          "id": "<string>",
          "number": "<string>",
          "status": "<string>"
        }
      ]
    },
    "to_credit_card": {
      "billing_address": {
        "company": "Bolt",
        "country": "United States",
        "country_code": "US",
        "door_code": "123456",
        "email_address": "alan.watts@example.com",
        "first_name": "Alan",
        "id": "<string>",
        "last_name": "Watts",
        "locality": "Brooklyn",
        "name": "Alan Watts",
        "phone_number": "+12125550199",
        "postal_code": "10044",
        "priority": "primary",
        "region": "NY",
        "region_code": "NY",
        "street_address1": "888 main street",
        "street_address2": "apt 3021",
        "street_address3": "c/o Alicia Watts",
        "street_address4": "Bridge Street Apartment Building B"
      },
      "bin": "402201",
      "display_network": "Visa",
      "expiration": 1654041600000,
      "icon_asset_path": "img/issuer-logos/visa.png",
      "id": "AB3rJKam5DhYE",
      "last4": "4021",
      "network": "visa",
      "priority": "primary",
      "status": "active",
      "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
      "token_type": "bolt"
    },
    "transaction_properties": {},
    "type": "cc_payment",
    "void": {
      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",
      "status": "succeeded",
      "void": "123456"
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs. For all APIs that require authorization, please provide your access_token returned from /v1/oauth/token via the basic auth bearer header Authorization: bearer ${TOKEN}. Read more about the OAuth token endpoint.

​
X-API-Key
string
header
required

Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.

Headers

​
X-Publishable-Key
string

The publicly viewable identifier used to identify a merchant division. This key is found in the Developer > API section of the Bolt Merchant Dashboard [RECOMMENDED].

​
Idempotency-Key
string

A key created by merchants that ensures POST and PATCH requests are only performed once. Read more about Idempotent Requests here.

Body

application/json

Authorize a Transaction

  • • merchant_credit_card_authorization: For authorizing with a new, unsaved card. This can be for a guest checkout flow, one-time payment, or an existing Bolt shopper.
  • • merchant_credit_card_authorization_recharge: For authorizing a card using a shoppers saved payment methods.
  • • Anytime the shopper is paying while logged-in attach their OAuth access_token to the request.

This request is used for authorizing a new, unsaved card.

​
cart
object
required

The cart_create object is a composite of the base_cart object and additional order details.

​
create_bolt_account
boolean
required

If true, the guest shopper is provided a Bolt Account using their email address as its unique ID; if false, no information is saved at checkout.

​
credit_card
object
required

The credit_card object is used to to pay for guest-checkout transactions or save payment method details to an account. Once saved, you can reference the credit card with the associated credit_card_id for future transactions. Add billing_address to this if storing a billing address for a returning shopper.

​
division_id
string
required

The unique ID associated to the merchant's Bolt Account division; Merchants can have different divisions to suit multiple use cases (storefronts, pay-by-link, phone order processing). Use the Bolt Merchant Dashboard to switch between divisions and find the division ID under Merchant Division Public ID.

Example:

"3X9aPQ67-YrB"

​
source
enum<string>
required
Available options:
direct_payments
​
user_identifier
object
required

The object containing key lookup IDs associated with the shopper's account, such as the unique email address and phone number.

​
user_identity
object
required
​
auto_capture
boolean

This property determines how the transaction is processed after authorization. If set to true, the transaction is placed in a queue for automatic capture. This process is asynchronous, meaning the transaction may not immediately appear as captured after the authorization request. This is because the transaction is in a transitional state as it moves from authorization to capture. If auto_capture is set to false, the transaction is only authorized and must be manually captured.

​
merchant_event_id
string

The reference ID associated with a transaction event (auth, capture, refund, void). This is an arbitrary identifier created by the merchant. Bolt does not enforce any uniqueness constraints on this ID. It is up to the merchant to generate identifiers that properly fulfill its needs.

Example:

"dbe0cd5d-3261-41d9-ba61-49e5b9d07567"

​
previous_transaction_id
string | null

The unique ID associated with to the shopper's previous subscription-based transaction. Leave null for standard, non-subscription transactions.

Example:

null

​
processing_initiator
enum<string>

Determines who initiated the transaction (e.g. shopper, merchant) and how they did it (e.g. recurring subscription, on-file card).

  • initial_card_on_file - The first transaction made for a card. The system then saves this card for future transactions.
  • initial_recurring - The first time any card is used to pay for a recurring charge. For example, a subscription.
  • stored_cardholder_initiated - The subsequent (second, third, etc.) transactions a shopper initiates with a stored card. This includes every situation during which a cardholder requests a charge, for example if the cardholder requests a merchant charge their card.
  • stored_merchant_initiated - The subsequent (second, third, etc.) transactions a merchant initiates with a stored card only when the cardholder does not request the charge. For example, when a customer service representative buys on behalf of a shopper or when a business adds funds to a public transit card.
  • following_recurring - The subsequent (second, third, etc.) transactions a card is used to pay for a recurring charge. For example, a subscription.
  • cardholder_initiated - When a cardholder begins a transaction that isn’t stored in Bolt and won’t be stored in Bolt for future transactions.
  • recurring - Any time a card is used to pay for a recurring charge (for example, a subscription). Only use this value when you don’t know if it’s the first recurring charge.
Available options:
initial_card_on_file,
initial_recurring,
stored_cardholder_initiated,
stored_merchant_initiated,
following_recurring,
cardholder_initiated,
recurring
​
shipping_address
object

The Address object is used for billing, shipping, and physical store address use cases.

Response

200 - application/json

Authorization Successful

​
did_create_bolt_account
boolean
​
order_number
string
​
transaction
object