Sensitive payment data is stored as a secure multi-use paymentMethodToken. This paymentMethodToken enables you to make recurring payments on behalf of customers and enable customers to pay faster using previously saved payment methods.

This guide will enable you to securely store customer payment information and allow your customers to manage their stored payment methods via the checkout.

Vaulting Token Flow

Make sure you are familiar with initializing the Universal Checkout and the associated callbacks.


You can automatically vault a payment method when a payment is authorized by a payment processor.

Vault on Successful Payment Authorization

  • Create a Client Session with the following required fields:
    • customerId: set to your internal customer identifier (e.g. email address)
    • vaultOnSuccess: set to true


POST /client-session // REQUEST{    "customerId": "john-apple-123",    "orderId": "order-123",    "amount": 2100,    "order": {      "lineItems": [      {        "itemId": "item-1",        "description": "White T-Shirt",        "amount": 2000,        "quantity": 1      }    ]    },    "currencyCode": "GBP",    "paymentMethod": {      "vaultOnSuccess": true  }} // RESPONSE{    "clientToken": "<A JWT TOKEN>",  "clientTokenExpirationDate": "2022-01-01T00:00:00",    "customerId": "john-apple-123",    "orderId": "order-123",    "amount": 2000,  "order": {    "lineItems": [      {        "itemId": "item-1",        "description": "White T-Shirt",        "amount": 2000,        "quantity": 1      }    ]  },    "currencyCode": "GBP",    "paymentMethod": {      "vaultOnSuccess": true  }}
  • Initialize your checkout with the clientToken you received in the previous step.

    The checkout will display the customer’s stored payment method information.
  • The customer selects a payment method and selects to pay.

  • When the onTokenizeSuccess callback is triggered, you receive a paymentMethodToken. Create a payment using only the payment method token.


POST /payments // REQUEST{   "paymentMethodToken": "<YOUR PAYMENT METHOD TOKEN>"} // RESPONSE{    "id": "Dejzuq29",    "date": "2022-01-01T00:00:0.0",    "amount": 2000,    "currencyCode": "GBP",    "customerId": "john-apple-123",    "orderId": "order-123",    "status": "AUTHORIZED",    "order": {        "lineItems": [        {            "itemId": "item-1",            "description": "White T-Shirt",            "amount": 2000,            "quantity": 1        }        ]    },    "paymentMethod": {        "paymentMethodToken": "<YOUR PAYMENT METHOD TOKEN>",        "vaultedPaymentMethodToken": "<A NEW PAYMENT METHOD TOKEN>",        "analyticsId": "XXX",        "paymentMethodType": "PAYMENT_CARD",        "paymentMethodData": {            "last4Digits": "1111",            "expirationMonth": "12",            "expirationYear": "2030",            "cardholderName": "John Apple",            "network": "Visa",            "isNetworkTokenized": false,            "binData": {                "network": "VISA",                "issuerCountryCode": "US",                "issuerName": "JPMORGAN CHASE BANK, N.A.",                "regionalRestriction": "UNKNOWN",                "accountNumberType": "UNKNOWN",                "accountFundingType": "UNKNOWN",                "prepaidReloadableIndicator": "NOT_APPLICABLE",                "productUsageType": "UNKNOWN",                "productCode": "VISA",                "productName": "VISA"            }        },        "threeDSecureAuthentication": {            "responseCode": "NOT_PERFORMED"        }    },    "processor": {        "name": "STRIPE",        "processorMerchantId": "acct_1234",        "amountCaptured": 0,        "amountRefunded": 0    },    "transactions": [        {            "transactionType": "SALE",            "processorTransactionId": "xxxx",            "processorName": "STRIPE",            "processorMerchantId": "acct_1234",            "processorStatus": "AUTHORIZED"        }    ]}
  • If the payment successfully authorized, you will receive a vaultedPaymentMethodToken that is associated with the customerId.

You can use this token for recurring payments where the customer isn’t present (e.g. recurring monthly payments)

Enable Customers to Manage Stored Payment Methods

Universal Checkout allows your customers to store their payment methods and manage existing stored ones.

Universal Checkout Vault

When using Universal Checkout, customers have the ability to pay with a previously vaulted payment method or remove any of their previously vaulted ones.

If the friendly card name checkout module is enabled, then customer’s can also provide a name for the payment method they save.

Universal Checkout Vault

Universal Checkout Vault

Manage Payment Methods Flow (Web SDK)

You also have the option to allow customers to vault their payment methods by selecting the MANAGE_PAYMENT_METHODS UX flow in Universal Checkout:

const checkout = await primer.checkout({    // ...    uxFlow: Primer.CheckoutUXFlow.MANAGE_PAYMENT_METHODS,    // ...})

Manage Payment Methods Flow

This avails the Vault Manager, which looks and feels similar to the default checkout experience. The Vault Manager allows users to vault new payment methods without needing to create a successful payment.

To learn more about the Vault Manager and how to use it with your Universal Checkout integration, take a look at its documentation:

Saved Payment Method Description

Universal Checkout now allows for the saving payment methods with descriptions defined by your customers.

For the time being, a description can only be saved for cards. This feature will be expanded to allow for a description to be saved against any payment method which can be vaulted.

How It Works

Card form with card description input

Availing the card description input

Once the capturing of a card description has been enabled for this session, the input will be availed via the card form.
This field is optional by default and can be left empty by your customers.

Previously used

Description shown in saved payment method button

After your customer has successfully paid with card information that includes a card description, their saved payment method will contain their new description.

Enabling the Card Description Input

In order to avail the card description field via the card form, you will need to contact your Primer representative.

Currently, this can only be configured by us, but we’re working hard to allow the configuration of form inputs via the dashboard, so keep your eyes peeled for updates 🙂

Don’t have a contact at Primer? Reach out to us → support@primer.io

Card Description on the Payment Methods API

The description has also been added to the Payment Methods API. If you fetch a customer’s list of saved payment methods, the response will now contain description

// GET /payment-instruments?customer_id=cust-123 {  "data": [    {      "createdAt": "2021-03-01T12:00:00.123456",      "token": "_xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5",            ...  // Other payment method token fields      "customerId": "cust-123",            "description": "My business card"    }  ]}