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":"Tester","last_name":"Tester","email":"example@email.co","company":"","address1":"1 Sample Street","address2":"","city":"some city","state_or_province":"Nevada","state_or_province_code":"NV","phone":"101-192-0293","postal_code":"55555"}

  • trusted_shipping_addresses
    array[object]

    The trusted shipping address for an instrument.

  • default_instrument
    boolean

    Make instrument default.

    Example: false

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":"Tester","last_name":"Tester","email":"example@email.co","company":"","address1":"1 Sample Street","address2":"","city":"some city","state_or_province":"Nevada","state_or_province_code":"NV","phone":"101-192-0293","postal_code":"55555"}

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

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