Sign in

v2

latestOpenAPI 3.0.02026-07-3139594346.4 KB
Account

Add Payment Method

Add a payment method to a shopper's Bolt account Wallet. For security purposes, this request must come from your backend because authentication requires the use of your private key.

Note: Before using this API, the credit card details must be tokenized using Bolt's JavaScript library function, which is documented in Install the Bolt Tokenizer.

post/v1/account/payment_methods

Headers

X-Publishable-Keystring

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-Keystring

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

Request body

billing_address_idstring nullable

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.

binstring

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

cryptogramstring
ecistring
expirationstring required

The expiration date of the credit card.

last4string

The last 4 digits of the credit card number.

network'visa' | 'mastercard' | 'amex' | 'discover' | 'dinersclub' | 'jcb' | 'unionpay' | 'alliancedata' | 'citiplcc' | 'unknown'
numberstring

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

postal_codestring

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

priority1 | 2

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

saveboolean

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

tokenstring required

The Bolt token associated to the credit card.

token_type'vantiv' | 'applepay' | 'bolt' | 'stripe' | 'plcc'

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

currencystring

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

Example request

{
  "billing_address": {
    "company": "Bolt",
    "country": "United States",
    "country_code": "US",
    "default": true,
    "door_code": "123456",
    "email": "alan.watts@example.com",
    "first_name": "Alan",
    "last_name": "Watts",
    "locality": "Brooklyn",
    "name": "Alan Watts",
    "phone": "+12125550199",
    "postal_code": "10044",
    "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"
  },
  "expiration": "2025-11",
  "last4": "1234",
  "metadata": {
    "customer_id": 234
  },
  "postal_code": "10044",
  "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
  "token_type": "bolt",
  "currency": "USD"
}

Response

Payment Method Added

idstring

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

last4string

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

exp_monthinteger

The expiration month of the credit card.

exp_yearinteger

The expiration year of the credit card.

network'visa' | 'mastercard' | 'amex' | 'discover' | 'dinersclub' | 'jcb' | 'unionpay' | 'alliancedata' | 'citiplcc' | 'unknown'

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

defaultboolean

The default card payment method chosen by the shopper.

type'card' | 'paypal'

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

descriptionstring

The APM account identifier; usually the email address.

Example response

{
  "billing_address": {
    "company": "Bolt",
    "country": "United States",
    "country_code": "US",
    "door_code": "123456",
    "email_address": "alan.watts@example.com",
    "first_name": "Alan",
    "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"
  },
  "last4": "4021",
  "exp_month": 11,
  "exp_year": 2024,
  "network": "visa",
  "metadata": {
    "customer_id": 234
  }
}