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

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

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
  • 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
  • instrument_token in path - string
    required

example

Response

Did you find what you were looking for?