Overview of Primer's Vault

Securely store payment method information

Primer's Vault is a centralized PCI-DSS Level 1 service you can use to store the details of a customer payment method in a unified way.

Sensitive payment data is stored as a secure multi-use paymentMethodToken that enables:

• recurring merchant-initiated payments
• a seamless one-click experience for your customers with Universal Checkout

Each paymentMethodToken is paired with a customerId which uniquely identifies identify a customer. You can use any unique identifier for this such as a UUID or an email address.

This customerId is required for:

• generating a client session to allow Universal Checkout to present your customer's vaulted payment data for one-click checkout
• creating a payment request using vaultOnSuccess to save the customer's payment data once it has been successfully authorized
• managing stored payment data with the Payment Methods API to allow customers to add and delete vaulted payment method data from your site or app

Intelligently optimized for auth rate approval

We're fanatical about improving payments success. Primer will intelligently store data returned from your underlying processors to ensure the highest likelihood of success for recurring payments. This includes SCA authentication data as well as other data returned from card schemes and acquirers.

Minimize Fraud

You can further boost success rates for subscription payments and minimize fraudulent orders by optionally running an active card check before choosing to vault customer’s card details. The card verification is entirely configurable, giving you the power to set the amount, currency, and backing processor of your choice.

Trusted, Verified Vault

If the card verification fails, say in the case of an expired card, Primer will not store or vault any payment method data. You will be notified of the failure. In response, you can immediately prompt your customer for retrying with another valid payment method.

What this means is, if you verify before vaulting, you can rest assured and have confidence that subsequent payments from verified cards will be successful as Primer vault will not store any invalid card data.

Add payment methods to the vault

Vaulting a payment method starts by capturing the payment method credentials using Drop-In Checkout or Headless Checkout.

You will then encounter two distinct behaviors:

• Vault the payment method directly after the user has completed the payment method flow
• Vault after a successful authorization

Vault directly

To vault a supported payment method directly, additional options have to be passed to the SDK. Check the payment method guides to properly configure the Drop-in Checkout and Headless Checkout to vault each compatible payment method.

Vault after a successful authorization

For card-based payment methods (Cards, Google Pay and Apple Pay), it is recommended to vault after a payment has been successfully authorized. This ensures the card is valid and is suitable for making payments.

Primer supports this flow out of the box using the paymentMethod.vaultOnSuccess flag in the Client Session API or the Payments API. When this flag is set to true, and if the payment method supports it, the payment method credentials are automatically added to the vault once the payment is successfully authorized.

Make sure to also pass customerId to specify the customer's vault this payment method should be added to.

Make payments with a vaulted payment method

Simplify the drop-in payment flow

Vaulted payment methods appear automatically on the drop-in checkout if customerId has been provided in the client session and the customer has vaulted payment metohds stored with Primer. This enables your customers to seamlessly pay with one of their saved payment method.

We recommend to set paymentMethod.paymentType to ECOMMERCE in the client session or payment request. This ensures the right data is sent to the processor to maximize the authorization rate.

Create merchant-initiated payments

You can use the Payment Methods API and the Payments API together to create merchant-initiated payments with a saved payment method.

1. 1

   First, make a call to GET/payment-instruments to get the list of payment methods tied to a customerId. Each entry in the list contains a token representing the payment method token to use to create a payment.

2. 2

   Then, create a payment by calling POST/payments. In addition to the required fields for creating a payment, pass the following data:

Manage vaulted payment methods

With the Payment Methods API

The Payment Methods API lets you interact with the vaulted payment methods for all your customers.

Use the Payments API to:

• retrieve the saved payment methods associated to a customer with GET/payment-instruments
• delete a saved payent method with DELETE/payment-instruments/{paymentMethodToken}

With Drop-in Checkout

When using Drop-in Checkout, customers have the ability to remove any of their previously vaulted ones.