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.
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 totrue
Example
1234567891011121314151617181920212223242526272829303132333435363738394041424344
POST /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 }}
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 apaymentMethodToken
. Create a payment using only the payment method token.
Example
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071
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 thecustomerId
.
Save Card Checkbox
Universal Checkout comes with a save card checkout module, providing the UI for your customer to indicate their vaulting preference.
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.
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:
12345
const checkout = await primer.checkout({ // ... uxFlow: Primer.CheckoutUXFlow.MANAGE_PAYMENT_METHODS, // ...})
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.
How It Works
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.
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 🙂
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" } ]}