Manage payment methods

Use the Payment Methods API to securely store your customers' payment details for faster checkout or recurring payments.

How it works

The Payment Methods API allows you to store a customer's payment instruments in the secure Primer vault. A payment instrument is a specific instance of a payment method. If the payment method is a card, then the payment instrument is the corresponding set of card details such as the card number, expiry date, etc.

To store a payment instrument, you send Primer a single-use token and a customer identifier. Primer stores this information securely in the vault and returns a new token to you. This token is multi-use and has no expiry date.

You can also store a payment instrument on payment creation, by using the vault option. Read our Payments API guide to find out more.

Integrating with the Payment Methods API

Before you start managing payment methods, we'll show you how to authenticate against our API.

Environments

You can use our dedicated Sandbox environment to test your integration. Visit our Test your integration page for more information.

API authentication

Authentication is handled via the X-Api-Key header.

To use the Payment Methods API, the following scopes need to be enabled:

  • payment_instrument:read
  • payment_instrument:write

Manage your API keys and scopes from the Dashboard in the Developers area.

Storing a payment method

To store a customer's payment instrument, you need to provide:

  • a single-use token representing this payment instrument, generated using one of Primer's checkout libraries
  • a customerId of your choice, which Primer will use to identify this customer
1
2
3
4
5
6
curl --location --request \
POST 'https://api.sandbox.primer.io/payment-instruments/<TOKEN>/vault' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
--data '{
"customerId": "<CUSTOMER_ID>"
}'
curl

If this is the first time you store a payment method for this customer, it will be set as their default payment instrument. The default payment method is at the top of the list when retrieving payment methods via the API and displayed first in the Universal Checkout. You can always update the default payment method later.

A successful response includes the token, customer ID, and the paymentInstrumentData object. The fields included in this object depend on the paymentInstrumentType.

This is an example response for a vaulted Visa debit card:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"createdAt": "2021-03-02T14:00:00.123456",
"token": "_xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5",
"token_type": "MULTI_USE",
"customerId": "customer-1234",
"analyticsId": "vuXhpZouWxaZpRZ-x_brZmtT",
"paymentInstrumentType": "PAYMENT_CARD",
"paymentInstrumentData": {
"last4Digits": "4242",
"expirationMonth": "09",
"expirationYear": "2030",
"cardholderName": "Mr John Smith",
"network": "VISA",
"networkTransactionId": "020220629172526",
"accountFundingType": "DEBIT"
},
"default": true
}
json

To view details of the fields included for other payment method types, check the API reference.

Listing all stored payment methods

To retrieve a list of all stored payment methods for a customer, specify their customerId in this request:

1
2
3
curl --location --request \
GET 'https://api.sandbox.primer.io/payment-instruments/?customer_id=<CUSTOMER_ID>' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
curl

A successful response contains a data array with details of all of the customer's stored payment methods. The default payment instrument is always first in the list.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
"data": [
{
"createdAt": "2021-03-01T12:00:00.123456",
"token": "_xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5",
"token_type": "MULTI_USE",
"customerId": "customer-1234",
"default": "true",
"analyticsId": "vuXhpZouWxaZpRZ-x_brZmtT",
"paymentInstrumentType": "PAYMENT_CARD",
"paymentInstrumentData": {
"last4Digits": "4242",
"expirationMonth": "09",
"expirationYear": "2030",
"cardholderName": "Mr John Smith",
"network": "VISA",
"networkTransactionId": null,
"accountFundingType": "DEBIT"
},
"default": true
},
{
"createdAt": "2021-03-02T14:00:00.123456",
"token": "_j4nf9Ruy3uhdKvhWCUWZfq3ePJ4G6XAHb3K",
"token_type": "MULTI_USE",
"customerId": "customer-1234",
"default": "false",
"analyticsId": "dEmev5SFKRCFBNv8uR59EALy",
"paymentInstrumentType": "PAYPAL_BILLING_AGREEMENT",
"paymentInstrumentData": {
"paypalBillingAgreementId": "P-1WJ68935LL406420PUTFNA2I",
"externalPayerInfo": {
"externalPayerId": "NEW8A85AK4ET4",
"email": "john.smith@example.com",
"firstName": "John",
"lastName": "Smith"
},
"shippingAddress": {
"addressLine1": "123 Fake Street",
"city": "London",
"countryCode": "GB"
},
"paypalStatus": "Completed"
},
"default": false
}
]
}
json

Deleting a payment method

You can remove a customer's stored payment method from the Primer vault. If there are multiple stored payment methods and you delete the one that is currently the default, then a previously stored method will become the new default.

To delete a customer's stored payment method, specify the multi-use token in this request:

1
2
3
curl --location --request \
DELETE 'https://api.sandbox.primer.io/payment-instruments/<TOKEN>' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
curl

A successful response has the deleted field set to true, confirming that the payment method has been deleted.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"createdAt": "2021-03-02T14:00:00.123456",
"token": "_xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5",
"token_type": "MULTI_USE",
"customerId": "customer-1234",
"analyticsId": "vuXhpZouWxaZpRZ-x_brZmtT",
"paymentInstrumentType": "PAYMENT_CARD",
"paymentInstrumentData": {
"last4Digits": "4242",
"expirationMonth": "09",
"expirationYear": "2030",
"cardholderName": "Mr John Smith",
"network": "VISA",
"networkTransactionId": "020220629172526",
"accountFundingType": "DEBIT"
},
"deleted": true,
"deletedAt": "2021-03-06T15:00:00.123456",
"default": false
}
json

Updating a customer's default payment method

If a customer has multiple payment instruments, you can allow them to choose which one to have as their default.

To set a new default stored payment method, specify the multi-use token in this request:

1
2
3
curl --location --request \
POST 'https://api.sandbox.primer.io/payment-instruments/<TOKEN>/default' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
curl

A successful response has the default field set to true, confirming that this is now the default payment method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"createdAt": "2021-03-02T14:00:00.123456",
"token": "_xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5",
"token_type": "MULTI_USE",
"customerId": "customer-1234",
"analyticsId": "vuXhpZouWxaZpRZ-x_brZmtT",
"paymentInstrumentType": "PAYMENT_CARD",
"paymentInstrumentData": {
"last4Digits": "4242",
"expirationMonth": "09",
"expirationYear": "2030",
"cardholderName": "Mr John Smith",
"network": "VISA",
"networkTransactionId": null,
"accountFundingType": "DEBIT"
},
"deleted": false,
"deletedAt": null,
"default": true
}
json