v2
latestOpenAPI 3.0.02026-07-261677104.9 KBPayments
Initialize a Bolt payment for logged in shoppers
Initialize a Bolt logged-in 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.
post/payments
Headers
X-Publishable-Keystring required
The publicly shareable identifier used to identify your Bolt merchant division.
X-Merchant-Client-Idstring
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
Example request
{
"cart": {
"order_reference": "order_100",
"order_description": "Order #1234567890",
"display_id": "215614191",
"shipments": [
{
"address": {
".tag": "id",
"id": "D4g3h5tBuVYK9"
},
"cost": {
"currency": "USD",
"units": 900
},
"carrier": "FedEx"
}
],
"discounts": [
{
"amount": {
"currency": "USD",
"units": 900
},
"code": "SUMMER10DISCOUNT",
"details_url": "https://www.example.com/SUMMER-SALE"
}
],
"items": [
{
"name": "Bolt Swag Bag",
"reference": "item_100",
"description": "Large tote with Bolt logo.",
"seller_id": "seller_123",
"total_amount": {
"currency": "USD",
"units": 900
},
"unit_price": 1000,
"quantity": 1,
"image_url": "https://www.example.com/products/123456/images/1.png",
"subscription_plan_id": "spl_123"
}
],
"total": {
"currency": "USD",
"units": 900
},
"tax": {
"currency": "USD",
"units": 900
}
},
"payment_method": {
".tag": "id",
"id": "X5h6j8uLpVGK"
},
"seller_splits": [
{
"amounts": {
"discount_total": 100,
"gross_total": 1000,
"merchant_subtotal": 900,
"shipping_total": 100,
"tax_total": 100
},
"marketplace_commission_fee": {
"bps": 100,
"flat_cents": 100,
"metadata": {
"plan_type": "pro",
"tier": "premium",
"region": "us-east-1"
}
},
"seller_id": "seller_12345"
}
],
"authorization_type": "final",
"auto_capture": true,
"three_ds_reference": "b0f0d4d0-4630-4ec8-8f5e-a19234567890"
}Response
The payment was successfully initialized, and was either immediately finalized or is pending
Example response
{
".tag": "finalized",
"id": "iKv7t5bgt1gg",
"status": "success",
"transaction": {
"reference": "OBYG-X1PX-FN55",
"authorizations": [
{
"processor_reference": "123456789XYZ",
"processor_response": {
"content_type": "application/json",
"api_version": "3.3",
"text": "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <transaction> <id>bfraj39q</id> <status>authorized</status> <type>sale</type> <currency-iso-code>USD</currency-iso-code> <amount>57.71</amount> <amount-requested>57.71</amount-requested> <merchant-account-id>GenericMerchant</merchant-account-id> <order-id>ORDER123456</order-id> <created-at type=\"datetime\">2024-11-20T12:36:53Z</created-at> <updated-at type=\"datetime\">2024-11-20T12:36:54Z</updated-at> <customer> <first-name>John</first-name> <last-name>Doe</last-name> <email>example@example.com</email> <phone>1234567890</phone> <international-phone></international-phone> </customer> <billing> <first-name>John</first-name> <last-name>Doe</last-name> <street-address>123 Generic St</street-address> <locality>GenericCity</locality> <region>GenericRegion</region> <postal-code>12345</postal-code> <country-name>GenericCountry</country-name> <country-code-alpha2>GC</country-code-alpha2> <country-code-alpha3>GCR</country-code-alpha3> <country-code-numeric>999</country-code-numeric> <international-phone></international-phone> </billing> <refund-ids type=\"array\"></refund-ids> <partial-settlement-transaction-ids type=\"array\"></partial-settlement-transaction-ids> <shipping> <international-phone></international-phone> </shipping> <custom-fields></custom-fields> <account-funding-transaction type=\"boolean\">false</account-funding-transaction> <avs-postal-code-response-code>M</avs-postal-code-response-code> <avs-street-address-response-code>M</avs-street-address-response-code> <cvv-response-code>I</cvv-response-code> <processor-authorization-code>123456</processor-authorization-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <tax-exempt type=\"boolean\">false</tax-exempt> <processed-with-network-token type=\"boolean\">false</processed-with-network-token> <credit-card> <image-url>https://assets.braintreegateway.com/payment_method_logo/unknown.png?environment=production</image-url> <is-network-tokenized type=\"boolean\">false</is-network-tokenized> <prepaid>Unknown</prepaid> <healthcare>Unknown</healthcare> <debit>Unknown</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>Unknown</commercial> <payroll>Unknown</payroll> <issuing-bank>Unknown</issuing-bank> <country-of-issuance>Unknown</country-of-issuance> <product-id>Unknown</product-id> <venmo-sdk type=\"boolean\">false</venmo-sdk> </credit-card> <apple-pay> <prepaid>No</prepaid> <healthcare>Unknown</healthcare> <debit>No</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>No</commercial> <payroll>Unknown</payroll> <issuing-bank>GenericBank</issuing-bank> <country-of-issuance>GCR</country-of-issuance> <product-id>Unknown</product-id> <bin>411111</bin> <card-type>Apple Pay - GenericCard</card-type> <last-4>1234</last-4> <expiration-month>12</expiration-month> <expiration-year>2028</expiration-year> <image-url>https://assets.braintreegateway.com/payment_method_logo/apple_pay.png?environment=production</image-url> <payment-instrument-name>Card 1234</payment-instrument-name> <source-description>Card 1234</source-description> </apple-pay> <status-history type=\"array\"> <status-event> <timestamp type=\"datetime\">2024-11-20T12:36:54Z</timestamp> <status>authorized</status> <amount>57.71</amount> <transaction-source>api</transaction-source> </status-event> </status-history> <subscription></subscription> <add-ons type=\"array\"></add-ons> <discounts type=\"array\"></discounts> <descriptor></descriptor> <recurring type=\"boolean\">false</recurring> <channel></channel> <disbursement-details></disbursement-details> <disputes type=\"array\"></disputes> <authorization-adjustments type=\"array\"></authorization-adjustments> <payment-instrument-type>generic_card</payment-instrument-type> <processor-settlement-response-code></processor-settlement-response-code> <processor-settlement-response-text></processor-settlement-response-text> <network-transaction-id>123456789012345</network-transaction-id> <processor-response-type>approved</processor-response-type> <authorization-expires-at type=\"datetime\">2024-11-27T12:36:54Z</authorization-expires-at> <retry-ids type=\"array\"></retry-ids> <retried type=\"boolean\">false</retried> <refund-global-ids type=\"array\"></refund-global-ids> <partial-settlement-transaction-global-ids type=\"array\"></partial-settlement-transaction-global-ids> <global-id>generic_global_id</global-id> <retry-global-ids type=\"array\"></retry-global-ids> <retrieval-reference-number>123456789012345</retrieval-reference-number> <installments type=\"array\"></installments> <refunded-installments type=\"array\"></refunded-installments> <merchant-address></merchant-address> <pin-verified type=\"boolean\">false</pin-verified> <payment-receipt> <id>bfraj39q</id> <global-id>generic_global_id</global-id> <amount>57.71</amount> <currency-iso-code>USD</currency-iso-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <processor-authorization-code>123456</processor-authorization-code> <merchant-address></merchant-address> <type>sale</type> <pin-verified type=\"boolean\">false</pin-verified> </payment-receipt> </transaction>"
}
}
]
}
}