> ## Documentation Index > Fetch the complete documentation index at: https://primer.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Save Payment Methods ## Overview of Primer's Vault > [!NOTE] > > Looking to migrate your existing saved payment methods to Primer? Check out our [token migration guide](https://primer.io/docs/changelogs/migration-guides/token-migration.md) ### 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` or `vaultOn3DS` to save the customer's payment data * **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 ![](https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/save-payment-methods/vault.png) Primer's Vault ### 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. ## Add payment methods to the vault > [!NOTE] > > Not all payment methods can be added to Primer's centralized vault. Refer to our [payment method guides](https://primer.io/docs/connections/payment-methods/overview.md) to know more about the capabilities of each payment method. 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](https://primer.io/docs/connections/payment-methods/overview.md) to properly configure the Drop-in Checkout and Headless Checkout to vault each compatible payment method. ### Vault after authorization success or 3DS authentication 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. > [!WARNING] > > A vaulted Apple Pay or Google Pay credential is not reusable in the same way as a saved card. You can charge it for **merchant-initiated** payments only. When the customer is present, the wallet's terms require a fresh authorization that generates a new cryptogram, so you cannot charge the stored credential as a customer-initiated payment. See [Reuse Apple Pay and Google Pay credentials](#reuse-apple-pay-and-google-pay-credentials). Primer supports two vaulting options for card flows. These can be set in the Client Session API or the Payments API under `paymentMethod`. Make sure to pass `customerId` to specify the customer's vault this payment method should be added to. ![](https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/save-payment-methods/vault-token-flow.png) Vaulting Token Flow #### vaultOnSuccess When `paymentMethod.vaultOnSuccess` is set to `true` (and the payment method supports it), the payment method is added to the vault **only after the authorization succeeds**. Use this when you want to save the card only if the payment is successful. #### vaultOn3DS When `paymentMethod.vaultOn3DS` is set to `true` (and the payment method supports it), the payment method is added to the vault **as soon as 3DS authentication succeeds**. Use this when your flow can have a successful 3DS authentication followed by an authorization that may fail (for example soft decline and later retry), and you still want to save the card after the customer completed SCA. #### vaultOnAgreement When `paymentMethod.vaultOnAgreement` is set to `true`, the payment method is added to the vault when the customer explicitly agrees to future payments. This option is intended for agreement or mandate based flows **without an immediate authorization**, such as ACH Direct Debit. At the moment, `vaultOnAgreement` is primarily supported for **ACH payments via Stripe**, where the customer mandate is collected separately from any charge. `vaultOnAgreement` is mutually exclusive with other vaulting options and cannot be combined with `vaultOnSuccess` or `vaultOn3DS`. > [!WARNING] > > Only one vaulting option is applied. > > If multiple vaulting options are set to `true`, the following rules apply: > > * If both `vaultOnSuccess` and `vaultOn3DS` are set, `vaultOnSuccess` takes precedence and `vaultOn3DS` is ignored. > * `vaultOnAgreement` cannot be combined with any other vaulting option. > > We recommend using only one vaulting strategy per flow. ## 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 methods stored with Primer. This enables your customers to seamlessly pay with one of their saved payment method. For saved cards, 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. Apple Pay and Google Pay are the exception: a stored wallet credential cannot be charged as an `ECOMMERCE` payment. The customer re-authorizes through the wallet instead, which produces a new single-use token for that payment. See [Reuse Apple Pay and Google Pay credentials](#reuse-apple-pay-and-google-pay-credentials). ![](https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/save-payment-methods/vault-1.png) Universal Checkout Vault ### Recapture the CVV of saved cards PCI standards prevent entities like Primer from [storing the CVV of a card](https://blog.pcisecuritystandards.org/faq-can-cvc-be-stored-for-card-on-file-or-recurring-transactions) when saving the card credentials for future payments. This means that subsequent card-on-file customer-initiated payments are always processed without the CVV. Although Primer sends the relevant parameters to tell each processor when a card-on-file payment occurs, some processors or issuers have a lower authorization rate when the CVV is not provided. To increase the chances of payment success, Primer enables you to ask the customer to re-enter the CVV of the selected saved card before processing the payment. #### Enabling CVV recapture on Drop-in Checkout Include the `captureVaultedCardCvv` option within the `PAYMENT_CARD` payment method options in the `POST /client-session` request. When set to `true`, this flag activates the CVV recapture functionality in the Drop-In implementation, providing an out-of-the-box solution for transactions with vaulted payment cards. **Example Request:** ```json JSON theme={"dark"} POST /client-session { "paymentMethod": { "options": { "PAYMENT_CARD": { "captureVaultedCardCvv": true } } } } ``` ### 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. First, make a call to GET 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. Then, create a payment by calling POST. In addition to the required fields for creating a payment, pass the following data: | Parameter Name | Description | | - | - | | paymentMethodToken | The vaulted payment method token | | paymentMethod ↳ [paymentType](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md#body-payment-method-type) | Type of payment. Used to improve conversion. | > [!NOTE] > > Reuse the multi-use (vaulted) token only for **subsequent** merchant-initiated payments (`SUBSCRIPTION` or `UNSCHEDULED`). The customer's **first** payment should use a single-use token with `vaultOnSuccess` — see [Choose the right token type](https://primer.io/docs/get-started/recurring-payments.md#choose-the-right-token-type). ### Reuse Apple Pay and Google Pay credentials Apple Pay and Google Pay credentials can be vaulted, but a stored wallet credential is not a drop-in replacement for a saved card. Both wallets allow you to charge a stored credential for merchant-initiated payments only. The wallet authorizes a payment with a cryptogram generated at the moment the customer confirms with Face ID, Touch ID, or their device unlock. That cryptogram covers one payment. If the customer is present in the flow, the wallet's terms require you to have them authorize again so the wallet issues a new cryptogram, rather than charging the credential you stored earlier. | Payment | Saved card | Vaulted Apple Pay or Google Pay | | - | - | - | | Customer-initiated, customer present (`ECOMMERCE`) | Charge the vaulted token | **Not permitted.** Have the customer authorize through the wallet again | | Merchant-initiated on a fixed schedule and amount (`SUBSCRIPTION`) | Charge the vaulted token | Charge the vaulted token | | Merchant-initiated with no fixed schedule or amount (`UNSCHEDULED`) | Charge the vaulted token | Charge the vaulted token | #### When the customer is present Present the Apple Pay or Google Pay button and let the customer complete the wallet flow, exactly as you would for a first payment. Each completed flow returns a new single-use token, which you charge for that payment. Don't send `paymentType: ECOMMERCE` with a vaulted wallet token. This also means a vaulted Apple Pay or Google Pay credential does not give the customer a one-click checkout. The customer confirms in the wallet on every payment. #### When the payment is merchant-initiated Charge the vaulted token with `paymentType: SUBSCRIPTION` or `UNSCHEDULED`, as described in [Create merchant-initiated payments](#create-merchant-initiated-payments). For Apple Pay, request a [merchant token (MPAN)](https://primer.io/docs/connections/payment-methods/apple-pay/overview.md#apple-pay-mpan-configuration) when you vault the credential, and set `firstPaymentReason` to match the payments you intend to make. A credential vaulted without the matching request configuration may not be chargeable later. > [!NOTE] > > This restriction is specific to Apple Pay and Google Pay, which are backed by network tokens and per-payment cryptograms. It does not apply to the other payment methods you can vault, such as PayPal billing agreements or ACH mandates. ## Manage vaulted payment methods ### With the Payment Methods API The [Payment Methods API](https://primer.io/docs/api-reference/v2.4/api-reference/payment-methods-api/list-saved-payment-methods.md) 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 * delete a saved payment method with DELETE ### With Drop-in Checkout When using Drop-in Checkout, customers have the ability to remove any of their previously vaulted ones. ![](https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/save-payment-methods/vault-1.png) ![](https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/save-payment-methods/dropin-vault-edit.png) Universal Checkout Vault This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.