Save Customer Payment Methods

Overview

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.

Vaulting

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

Example

1234567891011121314151617181920212223242526272829303132333435363738394041424344POST /client-session // REQUEST{    "customerId": "john-apple-123",    "orderId": "order-123",    "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  }}

json

copy

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.

Example

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071POST /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"        }    ]}

json

copy

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)

Save Card Checkbox

Universal Checkout comes with a save card checkout module, providing the UI for your customer to indicate their vaulting preference.

Save Card Checkbox

If the customer specifies that they want to save their details for future use, Universal Checkout will set the vaultOnSuccess flag to true in the client session and the customer’s payment method will be stored for future use.

The vaulting of the payment method occurs on successful payment authorization.

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

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:

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

javascript

copy

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

12345678910111213// 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"    }  ]}

json

copy