Stored Instruments

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. As of this writing, only the Braintree gateway supports updating customer billing addresses. If billing_address is included in the request, an attempt will be made to update the billing address at 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
    required

  • 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]
    required

  • 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?