Bolt Payments API
Use the Payments API to process credit card and alternative payment methods with Bolt.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference Account Payments API
description: A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.
termsOfService: https://www.bolt.com/end-user-terms
contact:
name: Bolt
email: merchantsupport@bolt.com
url: https://help.bolt.com/api-bolt/
servers:
- url: https://{environment}.bolt.com/v3
variables:
environment:
enum:
- api
- api-sandbox
default: api-sandbox
tags:
- name: Payments
description: Use the Payments API to process credit card and alternative payment methods with Bolt.
paths:
/payments:
post:
summary: Initialize a Bolt payment for logged in shoppers
operationId: paymentsInitialize
x-speakeasy-group: Payments.LoggedIn
x-speakeasy-name-override: Initialize
description: '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.
'
tags:
- Payments
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-initialize-request'
examples:
reference:
$ref: '#/components/examples/payment-initialize-payment-method-reference'
credit_card:
$ref: '#/components/examples/payment-initialize-payment-method-credit-card'
paypal:
$ref: '#/components/examples/payment-initialize-payment-method-paypal'
responses:
'200':
description: The payment was successfully initialized, and was either immediately finalized or is pending
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
pending:
$ref: '#/components/examples/payment-response-pending'
4XX:
$ref: '#/components/responses/response-payment-error'
default:
$ref: '#/components/responses/response-default'
/payments/{id}:
post:
summary: Finalize a pending payment
operationId: paymentsAction
x-speakeasy-group: Payments.LoggedIn
x-speakeasy-name-override: PerformAction
description: 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.
tags:
- Payments
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: iKv7t5bgt1gg
required: true
description: The ID of the payment to operate on
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-action-request'
responses:
'200':
description: The action was successfully applied to the pending payment
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/guest/payments:
post:
summary: Initialize a Bolt payment for guest shoppers
operationId: guestPaymentsInitialize
x-speakeasy-group: Payments.Guest
x-speakeasy-name-override: Initialize
description: 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.
tags:
- Payments
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/guest-payment-initialize-request'
examples:
credit_card:
$ref: '#/components/examples/payment-initialize-guest-payment-method-credit-card'
paypal:
$ref: '#/components/examples/payment-initialize-guest-payment-method-paypal'
responses:
'200':
description: The payment was successfully initialized, and was either immediately finalized or is pending
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
pending:
$ref: '#/components/examples/payment-response-pending'
4XX:
$ref: '#/components/responses/response-payment-error'
default:
$ref: '#/components/responses/response-default'
/guest/payments/{id}:
post:
summary: Finalize a pending guest payment
operationId: guestPaymentsAction
x-speakeasy-group: Payments.Guest
x-speakeasy-name-override: PerformAction
description: 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.
tags:
- Payments
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: iKv7t5bgt1gg
required: true
description: The ID of the guest payment to operate on
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-action-request'
responses:
'200':
description: The action was successfully applied to the pending guest payment
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
components:
schemas:
cart-discount:
required:
- amount
type: object
properties:
amount:
$ref: '#/components/schemas/amount'
code:
type: string
description: Discount code.
maxLength: 1024
example: SUMMER10DISCOUNT
details_url:
type: string
description: Used to provide a link to additional details, such as a landing page, associated with the discount offering.
maxLength: 8192
format: url
example: https://www.example.com/SUMMER-SALE
payment-initialize-request:
type: object
required:
- cart
- payment_method
properties:
cart:
$ref: '#/components/schemas/cart'
payment_method:
$ref: '#/components/schemas/payment-method-extended'
seller_splits:
items:
$ref: '#/components/schemas/seller-split'
nullable: true
type: array
authorization_type:
type: string
description: The type of authorization to perform. 'estimated' for pre-authorization, 'final' for final authorization.
example: final
auto_capture:
type: boolean
description: '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:
type: string
description: Reference value from cardinal.
example: b0f0d4d0-4630-4ec8-8f5e-a19234567890
marketplace-commission-fee:
properties:
bps:
format: int64
type: integer
example: 100
flat_cents:
format: int64
type: integer
example: 100
metadata:
type: object
additionalProperties:
type: string
nullable: true
example:
plan_type: pro
tier: premium
region: us-east-1
type: object
seller-split:
properties:
amounts:
$ref: '#/components/schemas/seller-split-amounts'
marketplace_commission_fee:
$ref: '#/components/schemas/marketplace-commission-fee'
seller_id:
type: string
example: seller_12345
type: object
payment-response-three-ds-required:
type: object
required:
- .tag
- step_up_url
- jwt_payload
properties:
.tag:
type: string
enum:
- three_ds_required
example: three_ds_required
id:
type: string
format: id
example: iKv7t5bgt1gg
x-order: 1
step_up_url:
type: string
format: url
example: https://www.example.com/payments/finalize
jwt_payload:
type: string
example: eyJ0cmFuc
seller-split-amounts:
properties:
discount_total:
format: int64
type: integer
example: 100
gross_total:
format: int64
type: integer
example: 1000
merchant_subtotal:
format: int64
type: integer
example: 900
shipping_total:
format: int64
type: integer
example: 100
tax_total:
format: int64
type: integer
example: 100
type: object
processor-response:
description: Raw authorization response from the payment processor
properties:
content_type:
type: string
example: application/json
api_version:
type: string
example: '3.3'
text:
type: string
example: <?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>
address-reference-partial:
type: object
title: Partial Address Reference
required:
- .tag
- postal_code
properties:
.tag:
type: string
enum:
- partial
description: The type of address reference
example: partial
x-order: 0
postal_code:
type: string
description: The postal code associated with the credit card billing address.
example: '94105'
x-order: 1
payment-method-klarna-paynow:
type: object
required:
- .tag
- return_url
title: Klarna Pay Now Payment Method
properties:
.tag:
type: string
enum:
- klarna_paynow
example: klarna_paynow
return_url:
type: string
description: Return URL to return to after payment completion in Klarna.
format: url
writeOnly: true
example: https://www.example.com/handle_klarna_paynow_success
cart:
required:
- total
- tax
- order_reference
type: object
properties:
order_reference:
type: string
description: This value is used by Bolt as an external reference to a given order. This reference must be unique per successful transaction.
example: order_100
order_description:
type: string
description: Used optionally to pass additional information like order numbers or other IDs as needed.
maxLength: 1024
example: 'Order #1234567890'
display_id:
type: string
description: A shopper-facing identifier corresponding to the order reference associated with this transaction.
maxLength: 128
example: '215614191'
shipments:
type: array
items:
$ref: '#/components/schemas/cart-shipment'
discounts:
type: array
items:
$ref: '#/components/schemas/cart-discount'
items:
type: array
items:
$ref: '#/components/schemas/cart-item'
total:
description: The total amount of the cart including its items and taxes (if applicable).
$ref: '#/components/schemas/amount'
tax:
$ref: '#/components/schemas/amount'
payment-method-googlepay:
title: Googlepay Payment Method
allOf:
- type: object
required:
- .tag
- type
properties:
.tag:
type: string
enum:
- googlepay
example: googlepay
x-order: 0
id:
type: string
format: id
readOnly: true
example: X5h6j8uLpVGK
x-order: 1
type:
type: string
description: The type of payment method
example: googlepay
x-order: 2
billing_address:
$ref: '#/components/schemas/address-reference'
- $ref: '#/components/schemas/credit-card'
payment-response-pending:
type: object
required:
- .tag
- status
- action
- url
properties:
.tag:
type: string
enum:
- pending
example: pending
x-order: 0
id:
type: string
format: id
example: iKv7t5bgt1gg
x-order: 1
status:
type: string
enum:
- awaiting_user_confirmation
example: awaiting_user_confirmation
action:
type: string
enum:
- redirect
example: redirect
url:
type: string
format: url
example: https://www.example.com/payments/finalize
payment-method-affirm:
type: object
required:
- .tag
- return_url
title: Affirm Payment Method
properties:
.tag:
type: string
enum:
- affirm
example: affirm
return_url:
type: string
description: Return URL to return to after payment completion in Affirm.
format: url
writeOnly: true
example: https://www.example.com/handle_affirm_success
address-reference:
oneOf:
- $ref: '#/components/schemas/address-reference-id'
- $ref: '#/components/schemas/address-reference-explicit'
- $ref: '#/components/schemas/address-reference-partial'
discriminator:
propertyName: .tag
mapping:
id: '#/components/schemas/address-reference-id'
explicit: '#/components/schemas/address-reference-explicit'
partial: '#/components/schemas/address-reference-partial'
payment-method-afterpay:
type: object
required:
- .tag
- return_url
title: Afterpay Payment Method
properties:
.tag:
type: string
enum:
- afterpay
example: afterpay
return_url:
type: string
description: Return URL to return to after payment completion in Afterpay.
format: url
writeOnly: true
example: https://www.example.com/handle_afterpay_success
payment-method-reference:
type: object
required:
- .tag
- id
title: Payment by reference Method
properties:
.tag:
type: string
enum:
- id
example: id
id:
type: string
format: id
description: Payment ID of the saved Bolt Payment method.
example: X5h6j8uLpVGK
credit-card:
required:
- network
- bin
- last4
- expiration
- token
type: object
properties:
network:
$ref: '#/components/schemas/credit-card-network'
bin:
type: string
description: The Bank Identification Number (BIN). This is the first 4 to 8 digits of the account number.
pattern: ^\d+$
example: '411111'
last4:
type: string
description: The account number's last four digits.
pattern: ^\d{4}$
example: '1004'
expiration:
type: string
description: The expiration date, in YYYY-MM format.
pattern: ^\d{4}-\d{2}$
example: 2029-03
token:
type: string
description: The Bolt token associated with the credit card.
writeOnly: true
example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
affirm_vcn_token:
type: string
description: The checkout token associated with Affirm VCN credit cards.
example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
default:
type: boolean
description: Indicates whether this credit card is the default payment method.
example: true
payment-response-finalized:
type: object
required:
- .tag
- status
- transaction
properties:
.tag:
type: string
enum:
- finalized
example: finalized
x-order: 0
id:
type: string
format: id
example: iKv7t5bgt1gg
x-order: 1
status:
type: string
enum:
- success
example: success
transaction:
$ref: '#/components/schemas/transaction'
field-error:
type: object
description: An error that pertains to validation of a specific field in the request.
required:
- .tag
- message
- field
properties:
.tag:
type: string
enum:
- invalid_input_parameter
description: The type of error returned
example: invalid_input_parameter
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: We were unable to process your request.
field:
type: string
description: The field (in its hierarchical form) that is failing validation.
example: address.phone
country-code:
type: string
description: The country (in its ISO 3166 alpha-2 format) associated with this address.
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BH
- BS
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CW
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- US
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
example: US
x-oapi-codegen-extra-tags:
validate: country,required
x-order: 11
payment-method-klarna:
type: object
required:
- .tag
- return_url
title: Klarna Payment Method
properties:
.tag:
type: string
enum:
- klarna
example: klarna
return_url:
type: string
description: Return URL to return to after payment completion in Klarna.
format: url
writeOnly: true
example: https://www.example.com/handle_klarna_success
profile-creation-data:
allOf:
- type: object
required:
- create_account
properties:
create_account:
type: boolean
description: Whether or not an account should be created.
example: true
- $ref: '#/components/schemas/profile'
credit-card-error:
type: object
required:
- .tag
- message
properties:
.tag:
type: string
enum:
- declined
- declined_invalid_amount
- declined_invalid_cvv
- declined_invalid_merchant
- declined_invalid_number
- declined_expired
- declined_call_issuer
- declined_unsupported
description: The type of error returned
example: declined_invalid_cvv
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: The payment was declined because the CVV is not valid
cart-error:
type: object
required:
- .tag
- message
properties:
.tag:
type: string
enum:
- payment_already_exists
- currency_not_supported
description: The type of error returned
example: payment_already_exists
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: A payment for this order already exists
three-ds-error:
type: object
description: An error that occurs during 3D Secure authentication or verification.
required:
- .tag
- message
properties:
.tag:
type: string
enum:
- three_ds_authentication_failed
- three_ds_verification_failed
- three_ds_reference_missing
description: The type of 3DS error returned
example: three_ds_authentication_failed
message:
type: string
description: A human-readable error message about the 3DS failure.
example: 3DS authentication with the card issuer failed
transaction:
type: object
properties:
reference:
type: string
example: OBYG-X1PX-FN55
authorizations:
description: Payment authorization events attached to a transaction
type: array
items:
$ref: '#/components/schemas/transaction-authorization'
amount:
type: object
description: A monetary amount, i.e. a base unit amount and a supported currency.
required:
- currency
- units
properties:
currency:
type: string
description: A supported currency.
enum:
- AUD
- CAD
- EUR
- GBP
- USD
example: USD
units:
type: integer
description: A monetary amount, represented in its base units (e.g. USD/EUR cents).
format: int64
example: 900
profile:
type: object
description: An account's identifying information.
required:
- first_name
- last_name
- email
properties:
first_name:
type: string
description: The given name of the person associated with this profile.
example: Alice
x-order: 1
last_name:
type: string
description: The last name of the person associated with this profile.
example: Baker
x-order: 2
email:
type: string
format: email
description: The email address asscoiated with this profile.
example: alice@example.com
x-order: 3
phone:
type: string
format: phone
description: The phone number associated with this profile.
example: '+14155550199'
x-order: 4
payment-method-klarna-account:
type: object
required:
- .tag
- return_url
title: Klarna Account Payment Method
properties:
.tag:
type: string
enum:
- klarna_account
example: klarna_account
return_url:
type: string
description: Return URL to return to after pay
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bolt/refs/heads/main/openapi/bolt-payments-api-openapi.yml