Stored Instruments API (Beta) - Stores V3 Server Operations

List All Instruments

GET /payments/stored-instruments

Request

Lists all available stored instruments for a store. This list will include all types of stored instruments namely card, account, and bank_account instruments.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • page in query - integer

    The requested page.

  • limit in query - integer

    The maximum number of results.

example

Response

OK

Body

object | application/json

  • data    array[]

  • meta    object

    Data about the response, including pagination and collection totals.

credit_card_example

paypal_account_example

bank_account_example

Bulk Import Instruments

POST /payments/stored-instruments

Request

Imports instruments that were vaulted outside the store.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

array | application/json

  • payment_method_id    string
    required

    Identifier for the payment method that will be used for this instrument is obtained from the Payment Methods API.

    Example: braintree.credit_card

  • currency_code    string
    required

    The instrument currency.

    Example: USD

  • customer_id    integer
    required

    The ID of the customer.

    Example: 1

  • instrument

    The instrument details.

    Any of:

    • vault_token      string

      The token from the provider's vault.

      Example: 5292sx35

    • provider_customer_id      string

      The customer ID in the provider's vault.

      Example: 321123

    • type      string

      The instrument type.

      Example: credit_card

    • brand      string

      Card brand.

      Example: visa

    • expiry_year      integer

      Expiration year.

      Example: 2066

    • expiry_month      integer

      Expiration month.

      Example: 12

    • last_4      string

      Last four digits of card.

      Example: 1111

    • iin      string

      Issuer identification number.

      Example: 411111

  • billing_address    object
    required

    Example: {"first_name":"Sam","last_name":"Williams","email":"sam.williams@email.com","company":"BigCommerce","street_1":"1 Sample Street","street_2":"Bldg 5","city":"Austin","state_or_province":"Texas","state_or_province_code":"TX","phone":"101-192-0293","postal_code":"55555","country_code":"US"}

  • trusted_shipping_addresses    array[object]

    The trusted shipping address for an instrument.

  • default_instrument    boolean

    Make instrument default.

example

Response

All instruments were successfully imported.

Body

object | application/json

  • data    array[]

    Successfully imported instruments.

  • errors    array[object]

    Errors with detailed errors indexed by input parameters.

  • meta    object

    Response metadata.

example

Update Instrument

PUT /payments/stored-instruments

Request

Updates an instrument in store and can update billing address in the provider's vault.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

object | application/json

  • token    string

  • billing_address    object

    Example: {"first_name":"Sam","last_name":"Williams","email":"sam.williams@email.com","company":"BigCommerce","street_1":"1 Sample Street","street_2":"Bldg 5","city":"Austin","state_or_province":"Texas","state_or_province_code":"TX","phone":"101-192-0293","postal_code":"55555","country_code":"US"}

  • trusted_shipping_addresses    array[object]

  • make_default    boolean

example

Response

Instrument successfully updated.

Body

object | application/json

  • data

    Any of:

    • customer_id      integer

      The ID of the customer.

      Example: 1

    • token      string

      An identifier representing this stored instrument.

      Example: 84596bea275fa254da820056bdc3e495bdf01fd11c51b0336347d447ee16200c

    • type      string

      Type of instrument.

      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.

    • iin      string

      The issuer 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":"","address1":"1 Sample Street\"","address2":"","city":"some city","state_or_province":"Nevada","state_or_province_code":"NV","country_code":"US","phone":"101-192-0293","postal_code":"55555"}

  • meta    object

    Response metadata.

example

Bulk Delete Instruments

DELETE /payments/stored-instruments

Request

Deletes instruments from the store without triggering deletion on the provider side.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • token:in in query - string
    required

    Filter by a list of tokens.

example

Response

Remove Instrument from Store and Gateway

DELETE /payments/stored-instruments/{instrument_token}

Request

Deletes instrument from store and provider's vault.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • instrument_token in path - string
    required

example

Response

Did you find what you were looking for?