Authorize a Card

This endpoint authorizes card payments and has three main use cases:

• Authorize a payment using an unsaved payment method for a guest or logged-in shopper.
• Authorize a payment using a saved payment method for a logged-in shopper.
• Re-charge a previous transaction using the credit_card_id of the transaction.

Authorization

OAuth X-API-Key

AuthorizationBearer <token>

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.

In: header

X-API-Key<token>

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

In: header

Header Parameters

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.

Request 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.

TypeScript Definitions

Use the request body type in TypeScript.

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

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.

cart*

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

create_bolt_account*boolean

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*

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

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.

merchant_event_id?transaction_merchant_event_id

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.

previous_transaction_id?|

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

processing_initiator?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.

Value in

"initial_card_on_file"
"initial_recurring"
"stored_cardholder_initiated"
"stored_merchant_initiated"
"following_recurring"
"cardholder_initiated"
"recurring"

shipping_address?

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

source*"direct_payments"

Value in

"direct_payments"

user_identifier*

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

user_identity*

Response Body

`application/json`

curl -X POST "https://example.com/v1/merchant/transactions/authorize" \  -H "Content-Type: application/json" \  -d '{    "cart": {      "total_amount": 900,      "currency": "USD",      "order_reference": "order_100"    },    "create_bolt_account": true,    "credit_card": {      "bin": "411111",      "expiration": "2025-11",      "last4": "1234",      "postal_code": "10044",      "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",      "token_type": "bolt"    },    "division_id": "3X9aPQ67-YrB",    "source": "direct_payments",    "user_identifier": {      "phone": "+12125550199"    },    "user_identity": {}  }'

{  "did_create_bolt_account": true,  "order_number": "string",  "transaction": {    "amount": {      "amount": 754,      "currency": "USD",      "currency_symbol": "$"    },    "authorization": {      "auth": "string",      "avs_response": "00",      "cvv_response": "M",      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",      "metadata": {        "property1": "string",        "property2": "string"      },      "processor": "vantiv",      "reason": "none",      "status": "succeeded"    },    "capture": {      "amount": {        "amount": 754,        "currency": "USD",        "currency_symbol": "$"      },      "id": "BcDE4fafd2a4",      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",      "metadata": {        "property1": "string",        "property2": "string"      },      "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": {          "property1": {            "key1": "value1",            "key2": "value2"          },          "property2": {            "key1": "value1",            "key2": "value2"          }        },        "splits": {          "amount": {            "amount": 754,            "currency": "USD",            "currency_symbol": "$"          },          "type": "net"        },        "status": "succeeded"      }    ],    "credit": {      "status": "succeeded",      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567"    },    "date": 1615407159447,    "from_consumer": {      "authentication": {        "actions": [          "set_password"        ],        "methods": [          "code"        ],        "sso_authorization_url": "string"      },      "email_verified": true,      "emails": [        {          "address": "string",          "id": "string",          "priority": "primary",          "status": "string"        }      ],      "first_name": "string",      "id": "string",      "last_name": "string",      "phones": [        {          "country_code": "US",          "id": "string",          "number": "string",          "priority": "primary",          "status": "string"        }      ],      "platform_account_status": "none"    },    "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": 0,    "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_type": "1",      "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": 0    },    "processor": "adyen_gateway",    "reference": "LBLJ-TWW7-R9VC",    "review_ticket": {      "id": "string",      "request_deadline": 0,      "status": "string"    },    "risk_insights": {      "available": true,      "decision_factors": [        "string"      ],      "fraud_probability": 0,      "payment_instrument_factors": {        "property1": {          "factor1": "factor1",          "factor2": "factor2"        },        "property2": {          "factor1": "factor1",          "factor2": "factor2"        }      }    },    "risk_review_status": "reviewed",    "risk_score": 0,    "splits": [      {        "amount": {          "amount": 754,          "currency": "USD",          "currency_symbol": "$"        },        "type": "net"      }    ],    "status": "cancelled",    "to_consumer": {      "authentication": {        "actions": [          "set_password"        ],        "methods": [          "code"        ],        "sso_authorization_url": "string"      },      "email_verified": true,      "emails": [        {          "address": "string",          "id": "string",          "priority": "primary",          "status": "string"        }      ],      "first_name": "string",      "id": "string",      "last_name": "string",      "phones": [        {          "country_code": "US",          "id": "string",          "number": "string",          "priority": "primary",          "status": "string"        }      ],      "platform_account_status": "none"    },    "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": {      "property1": {        "key1": "value1",        "key2": "value2"      },      "property2": {        "key1": "value1",        "key2": "value2"      }    },    "type": "cc_payment",    "void": {      "cause": "merchant_action",      "merchant_event_id": "dbe0cd5d-3261-41d9-ba61-49e5b9d07567",      "status": "succeeded",      "void": "123456"    },    "view_status": "not_viewed"  }}

Authorization

Header Parameters

Request Body

Response Body

200application/json

`application/json`