POST
/
v1
/
account
/
payment_methods
Add Payment Method
curl --request POST \
  --url https://api.bolt.com/v1/account/payment_methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "billing_address": {
    "country_code": "US",
    "email": "alan.watts@example.com",
    "first_name": "Alan",
    "last_name": "Watts",
    "locality": "Brooklyn",
    "postal_code": "10044",
    "region": "NY",
    "street_address1": "888 main street",
    "company": "Bolt",
    "country": "United States",
    "default": true,
    "door_code": "123456",
    "name": "Alan Watts",
    "phone": "+12125550199",
    "region_code": "NY",
    "street_address2": "apt 3021",
    "street_address3": "c/o Alicia Watts",
    "street_address4": "Bridge Street Apartment Building B"
  },
  "expiration": "2025-11",
  "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
  "billing_address_id": null,
  "bin": 411111,
  "cryptogram": "<string>",
  "eci": "<string>",
  "last4": "1234",
  "metadata": {
    "customer_id": 234
  },
  "number": "<string>",
  "postal_code": "10044",
  "save": true,
  "token_type": "bolt",
  "currency": "USD"
}
'
{
  "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"
  },
  "id": "<string>",
  "last4": "4021",
  "exp_month": 11,
  "exp_year": 2024,
  "network": "visa",
  "default": true,
  "description": "<string>",
  "metadata": {
    "customer_id": 234
  }
}

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

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.

​
billing_address
object
required

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

​
expiration
string
required

The expiration date of the credit card.

Example:

"2025-11"

​
token
string
required

The Bolt token associated to the credit card.

Example:

"a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"

​
billing_address_id
string | null

The unique Bolt ID associated with a saved shopper address. This can be obtained by accessing a shopper's account details. If you use this field, you do not need to use billing_address.

Example:

null

​
bin
string

The Bank Identification Number for the credit card. This is typically the first 4-6 digits of the credit card number.

Required string length: 4 - 6
Example:

411111

​
cryptogram
string
​
eci
string
​
last4
string

The last 4 digits of the credit card number.

Required string length: 4
Example:

"1234"

​
metadata
object

A key-value pair object that allows users to store arbitrary information associated with an object. For any individual account object, we allow up to 50 keys. Keys can be up to 40 characters long and values can be up to 500 characters long. Metadata should not contain any sensitive customer information, like PII (Personally Identifiable Information). For more information about metadata, see our documentation.

Example:
{ "customer_id": 234 }
​
network
enum<string>
Available options:
visa,
mastercard,
amex,
discover,
dinersclub,
jcb,
unionpay,
alliancedata,
citiplcc,
unknown
​
number
string

Used to provide ApplePay DPAN or private label credit card PAN when applicable. Required when charging a private label credit card.

​
postal_code
string

Used for the postal or zip code associated with the credit card.

Maximum string length: 32
Example:

"10044"

​
priority
enum<integer>

Used to indicate the card's priority. '1' indicates primary, while '2' indicates a secondary card.

Available options:
1,
2
​
save
boolean

Determines whether or not the credit card will be saved to the shopper's account. Defaults to true.

​
token_type
enum<string>

Used to define which payment processor generated the token for this credit card. For those using Bolt's tokenizer, the value must be bolt.

Available options:
vantiv,
applepay,
bolt,
stripe,
plcc
Example:

"bolt"

​
currency
string

This can be left empty. A 3-digit ISO code for currency that will be used in the credit card authorization.

Example:

"USD"

Response

200 - application/json

Payment Method Added

Saved Credit Card Detail

​
billing_address
object

The address object returned in the response.

​
id
string

The ID of the payment method associated with the Shopper's account.

​
last4
string

The card's last 4 digits. Nullable for Transactions Details.

Required string length: 4
Example:

"4021"

​
exp_month
integer

The expiration month of the credit card.

Example:

11

​
exp_year
integer

The expiration year of the credit card.

Example:

2024

​
network
enum<string>

The card's network code. Nullable for Transactions Details. Note: LEGACY diners_club_us_ca now tagged as mastercard

Available options:
visa,
mastercard,
amex,
discover,
dinersclub,
jcb,
unionpay,
alliancedata,
citiplcc,
unknown
Example:

"visa"

​
default
boolean

The default card payment method chosen by the shopper.

​
type
enum<string>

The payment method type. If empty, the property defaults to card.

Available options:
card,
paypal
​
description
string

The APM account identifier; usually the email address.

​
metadata
object

A key-value pair object that allows users to store arbitrary information associated with an object. For any individual account object, we allow up to 50 keys. Keys can be up to 40 characters long and values can be up to 500 characters long. Metadata should not contain any sensitive customer information, like PII (Personally Identifiable Information). For more information about metadata, see our documentation.

Example:
{ "customer_id": 234 }