The Stored Instruments API lets developers empower shoppers to save credit cards, bank accounts, and PayPal accounts for a faster checkout experience. You can create, modify, list, and delete stored instruments, as well as set default stored payment instruments for a given customer.
The Stored Instruments API consists of endpoints that use two different servers:
Most Stored Instruments operations are available using the Stores V3 API URL. To use these endpoints, create a store-level or app-level API account with the “Stored Payment Instruments” scope and authenticate using the X-Auth-Token header.
The “Stored Payment Instruments” scope has the following permission levels:
To learn more about OAuth scopes, see the Guide to API Accounts.
The following sections show request and response pairs for the Stores V3 endpoints.
This endpoint lets you Create an instrument access token for storing instruments. Requires the modify permission level for the Stored Payment Instruments scope.
The List all instruments endpoint returns all instruments for the subject store and supports pagination. You can use either the read-only or modify permission levels for the Stored Payment Instruments scope.
The Update an instrument endpoint does the following:
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.
Requires the modify permission level for the Stored Payment Instruments scope.
The Remove instrument from store and gateway endpoint removes the instrument from our system and the payment gateway’s vault. Requires modify permission level for the Stored Payment Instruments scope.
The Bulk delete instruments endpoint removes instruments only from our system.
Requires modify permission level for the Stored Payment Instruments scope.
The List available payment methods by currency code endpoint returns payment method IDs and instrument types that are available for the store to vault. You can use these IDs later in import or vault endpoints.
Requires read-only permission level for the Stored Payment Instruments scope.
For PCI compliance, the Payments server handles raw card data manipulation. To attach an instrument to a customer, use the Payments server endpoint.
To authenticate, this endpoint uses the Authorization header with a special bearer token, known as an instrument access token. Use the Create an instrument access token endpoint to generate an IAT.
This operation needs a payment_method_id field, which exists for all stored payment methods. Obtain the id from the Get accepted payment methods endpoint or the method_id from the List available methods by currency code.
Finally, obtain the list and descriptions of supported gateways and instrument types for your currency using the List available methods by currency code endpoint. The response returns available payment methods for the provided currency. Below is a list of all supported gateways compatible with our public Payments API.
The following is an example request-response pair for the Attach instrument to customer endpoint:
The following table lists the supported payment providers. Only Braintree supports processing a payment using PayPal and credit card accounts. The other providers only support credit card vaulting.