Stored Instruments API (Beta) - Payments Server Operations

The Stored Instruments API gives shoppers the ability to save credit cards, bank accounts, and PayPal accounts for a faster checkout experience.

Attach Instrument to Customer

POST /stored-instruments

Request

Adds an instrument to customer.

Authentication

  • Authorization in header in the format of IAT {{INSTRUMENT_ACCESS_TOKEN}}

Parameters

  • store_hash in path - string
  • Accept in header with default of application/vnd.bc+json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • payment_method_id    string
    required

    Identifier for payment method that will be used for this instrument obtained from Payment Methods API.
    Example: braintree.paypal

  • currency_code    string
    required

    The instrument currency.
    Example: USD

  • customer_id    string
    required

    The ID of the customer to add instrument for.
    Example: 1

  • default_instrument    boolean

    Set this instrument as default for customer?

  • instrument
    required

    Any of:

    • number      string
      required

      The raw card number.
      Example: 4111111111111111

    • expiration_year      integer
      required

      The expiration year.
      Example: 2024

    • expiration_month      integer
      required

      The expiration day.
      Example: 12

    • verification_value      string
      required

      The security code.
      Example: 123

    • cardholder_name      string
      required

      The cardholder name.
      Example: test name

    • type      string
      required

      The type of instrument. For this case "raw_card".

      Allowed: raw_card | tokenized_card | tokenized_paypal_account

      Example: raw_card

  • trusted_shipping_addresses    array[object]

    Trusted shipping address for instrument.

  • billing_address    object
    required

    Example: {"first_name":"Tester","last_name":"Tester","email":"example@email.com","company":"","street_1":"1 Sample Street","street_2":"","city":"Tampa","state_or_province_code":"NV","country_code":"US","phone":"101-192-0293","postal_code":"55555"}

example

{
"payment_method_id": "braintree.paypal",
"currency_code": "USD",
"customer_id": "1",
"default_instrument": false,
"instrument": {
"number": "4111111111111111",
"expiration_year": 2024,
"expiration_month": 12,
"verification_value": "123",
"cardholder_name": "test name",
"type": "raw_card"
},
"trusted_shipping_addresses": [
{
"first_name": "Tester",
"last_name": "Tester",
"email": "example@email.com",
"company": "",
"street_1": "1 Sample Street",
"street_2": "",
"city": "Tampa",
"state_or_province_code": "NV",
"country_code": "US",
"phone": "101-192-0293",

Response

Created instrument

Body

object | application/json

  • data    object

    Any of:

    • token      string

      The BigCommerce instrument token.
      Example: e4e43db4454391cee7608673d530d91fc87ea3d5c75315601bd939d1281f70e2

    • type      string

      The instrument type.
      Example: credit_card

    • is_default      boolean

      Identifies whether this stored instrument is default for the customer.

    • brand      string

      The card brand.
      Example: visa

    • expiry_month      integer

      The expiry month for this card.
      Min: 1
      Max: 12

    • expiry_year      integer

      The expiry year for this card.

    • bin      string

      The bank identification number.
      Example: 411111

    • last_4      string

      The last four digits of this card.
      Example: 1111

    • billing_address      object

      Example: {"first_name":"Tester","last_name":"Tester","email":"example@email.com","company":"","street_1":"1 Sample Street","street_2":"","city":"","state_or_province_code":"NV","country_code":"US","phone":"101-192-0293","postal_code":"55555"}

  • meta    object

    Response metadata.

paypal_instrument

{
"data": {
"customer_id": "1",
"token": "e4e43db4454391cee7608673d530d91fc87ea3d5c75315601bd939d1281f70e2",
"type": "paypal_account",
"is_default": true,
"email": "bc-buyer-paypal-express@bigcommerce.com",
"billing_address": {
"first_name": "Tester",
"last_name": "Tester",
"email": "example@email.com",
"company": "",
"street_1": "1 Sample Street",
"street_2": "",
"city": "",
"state_or_province_code": "NV",
"country_code": "US",
"phone": "101-192-0293",
"postal_code": "55555"
}
},
"meta": {}
}

credit_card_instrument

{
"data": {
"customer_id": "1",
"token": "e4e43db4454391cee7608673d530d91fc87ea3d5c75315601bd939d1281f70e2",
"type": "credit_card",
"is_default": true,
"brand": "visa",
"expiry_month": 1,
"expiry_year": 1,
"bin": "411111",
"last_4": "1111",
"billing_address": {
"first_name": "Tester",
"last_name": "Tester",
"email": "example@email.com",
"company\"": "",
"street_1": "1 Sample Street",
"street_2": "",
"city": "",
"state_or_province_code": "NV",
"country_code": "US",
"phone": "101-192-0293",
"postal_code": "55555"
}
},
"meta": {}
Did you find what you were looking for?