Beta Programs
Stored Payment Instruments
Guide

Guide to the Stored Instruments API (Beta)

The Stored Instruments API lets developers empower shoppers to save credit cards, bank accounts, and PayPal accounts for a faster checkout experience. You can create, modify, list, and delete stored instruments, as well as set default stored payment instruments for a given customer.

The Stored Instruments API consists of endpoints that use two different servers:

Stores V3 server operations

Most Stored Instruments operations are available using the Stores V3 API URL. To use these endpoints, create a store-level or app-level API account with the "Stored Payment Instruments" scope and authenticate using the X-Auth-Token header.

The "Stored Payment Instruments" scope has the following permission levels:

OAuth scopes

UI NamePermissionParameter
Stored Payment Instrumentsread-onlystore_stored_payment_instruments_read_only
Stored Payment Instrumentsmodifystore_stored_payment_instruments

To learn more about OAuth scopes, see the Guide to API Accounts.

The following sections show request and response pairs for the Stores V3 endpoints.

Create an IAT instrument access token

This endpoint lets you Create an instrument access token for storing instruments. Requires the modify permission level for the Stored Payment Instruments scope.

Create an IAT
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments/access-tokens
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

Import instruments

  • Adds already vaulted instruments to customer accounts in our system.
  • This endpoint supports bulk import. Please note that we do not validate imported instruments with the payment gateway, so if you post incorrect data, the instrument will not work for payment.
  • This endpoint does not add instruments to the provider's vault; it only adds already vaulted instruments to customers.
Import instruments
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/stored-instruments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json
 
[
  {
    "billing_address": {
      "first_name": "test",
        "last_name": "shop",
        "email": "example@email.com",
        "street_1": "Station Yard, Weybridge Station",
        "city": "Weybridge",
        "zip": "KT13 8UD",
        "country_code": "GB"
    },
    "trusted_shipping_addresses": [
      {
        "first_name": "test",
        "last_name": "shop",
        "email": "example@email.com",
        "street_1": "Station Yard, Weybridge Station",
        "city": "Weybridge",
        "country_code": "GB",
        "zip": "KT13 8UD"
      }
    ],
    "default_instrument": false,
    "payment_method_id": "braintree.paypal",
    "currency_code": "GBP",
    "customer_id": 1,
    "instrument": {
      "vault_token": "pm_1NcbZ2FYHgt19eoyCcvXptfS",
      "provider_customer_id": "cus_ONhsna5PAbiZeW",
      "type": "credit_card",
      "brand": "visa",
      "expiry_year": 2026,
      "expiry_month": 11,
      "last_4": "4242",
      "iin": "424242"
    }
  }
]

List all instruments for store

The List all instruments endpoint returns all instruments for the subject store and supports pagination. You can use either the read-only or modify permission levels for the Stored Payment Instruments scope.

List all instruments
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Update an instrument

The Update an instrument endpoint does the following:

  • adds trusted shipping addresses to the instrument
  • sets an instrument default for the customer
  • updates the customer billing address. In this case, it updates the billing address in our system and the provider's system.

As of this writing, only the Braintree gateway supports updating customer billing addresses.

Requires the modify permission level for the Stored Payment Instruments scope.

Update an instrument
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments/{{instrument_token}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json
 
{
  "billing_address": {
    "first_name": "shop",
    "email": "example@email.com",
    "street_1": "1 Main St",
    "city": "San Jose",
    "state_code": "CA",
    "country_code": "US",
    "zip": "95131"
  },
  "trusted_shipping_addresses": [
    {
      "first_name": "test",
      "last_name": "shop",
      "email": "example@email.com",
      "street_1": "1 Main St",
      "city": "San Jose",
      "state_code": "CA",
      "country_code": "US",
      "zip": "95131"
    }
  ],
  "make_default": true,
  "token": "29a45728486dab7f8844fb57ea88fb701edf787fc296cdffebb9f4df22a9e86c"
}

Remove instrument from store and gateway

The Remove instrument from store and gateway endpoint removes the instrument from our system and the payment gateway's vault. Requires modify permission level for the Stored Payment Instruments scope.

Remove instrument
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments/{{instrument_token}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Bulk delete instruments

The Bulk delete instruments endpoint removes instruments only from our system.

Requires modify permission level for the Stored Payment Instruments scope.

Bulk delete instruments
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

List available payment methods by currency code

The List available payment methods by currency code endpoint returns payment method IDs and instrument types that are available for the store to vault. You can use these IDs later in import or vault endpoints.

Requires read-only permission level for the Stored Payment Instruments scope.

List payment methods
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/payments/stored-instruments/methods?currency_code=usd
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Payments server operations

For PCI compliance, the Payments server handles raw card data manipulation. To attach an instrument to a customer, use the Payments server endpoint.

To authenticate, this endpoint uses the Authorization header with a special bearer token, known as an instrument access token. Use the Create an instrument access token endpoint to generate an IAT.

This operation needs a payment_method_id field, which exists for all stored payment methods. Obtain the id from the Get accepted payment methods endpoint or the method_id from the List available methods by currency code.

Finally, obtain the list and descriptions of supported gateways and instrument types for your currency using the List available methods by currency code endpoint. The response returns available payment methods for the provided currency. Below is a list of all supported gateways compatible with our public Payments API.

Attach instrument to customer

The following is an example request-response pair for the Attach instrument to customer endpoint:

Headers, Attach instrument to customer
POST https://payments.bigcommerce.com/stores/{{STORE_HASH}}/stored-instruments
Authorization: IAT {{INSTRUMENT_ACCESS_TOKEN}}
Accept: application/vnd.bc+json
Content-Type: application/json
 
{
  "payment_method_id": "braintree.paypal",
  "currency_code": "USD",
  "customer_id": "1",
  "default_instrument": false,
  "instrument": {
    "number": "4242424242424242",
    "expiration_year": "2024",
    "expiration_month": "12",
    "verification_value": "123",
    "cardholders_name": "Jane Cardholder",
    "type": "raw_card"
  },
  "trusted_shipping_addresses": [
    {
      "first_name": "Jane",
      "last_name": "Cardholder",
      "email": "jane@example.com",
      "company": "",
      "street_1": "1 Main St",
      "street_2": "",
      "city": "San Jose",
      "state_code": "CA",
      "country_code": "US",
      "phone": "101-192-0293",
      "zip": "95131"
    }
  ],
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Cardholder",
    "email": "jane@example.com",
    "company": "",
    "street_1": "1 Main St",
    "street_2": "",
    "city": "San Jose",
    "state_code": "CA",
    "country_code": "US",
    "phone": "101-192-0293",
    "zip": "95131"
  }
}

Supported payment gateways

The following table lists the supported payment providers. Only Braintree supports processing a payment using PayPal and credit card accounts. The other providers only support credit card vaulting.

Payment GatewayPayPal AccountsCredit Card Vaulting
braintree✓✓
stripe✓
adyenv2✓
adyenv3✓
authorizenet✓
bluesnapv2✓
bnz✓
cba_mpgs✓
checkoutcom✓
cybersourcev2✓
digital_river✓
elavon✓
mollie✓
moneris✓
orbital✓
worldpayaccess✓

Resources

Articles

API Reference

Endpoint Reference

Stores V3 endpoints

Payments endpoints

Did you find what you were looking for?
Open BetaAttach Instrument to Customer