Card vaulting

Overview

Card vaulting lets you store a tokenized version of a customer's card on a PayMongo Customer object. Once vaulted, the customer can pay again without re-entering their card number — useful for repeat purchases and one-click checkout flows. Vaulting is supported for Visa and Mastercard only.

PayMongo stores the card as a token. The actual card number never touches your server after the initial tokenization, keeping your integration out of full PCI DSS scope for card storage.

Account configuration required: Card Vaulting is only available for select accounts. Contact [email protected] to request for configuration.

Key terms

Only on-session vaulting is supported via card vaulting. For off-session charging (automatic subscription billing), use the Subscriptions API.

How it works

First purchase — saving the card

1. Customer checks out and enters their card details
2. They are prompted to save the card for future use (OTP verification required)
3. PayMongo tokenizes and stores the card — the raw card number is never stored
4. The payment completes

Subsequent purchases — using the saved card

1. Customer returns to checkout
2. Their saved card is displayed; they enter the CVC only
3. Payment processes using the vaulted token

Vault a card

Create a Customer

curl -X POST https://api.paymongo.com/v1/customers \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'sk_test_YOUR_SECRET_KEY:' | base64)" \
  -d '{
    "data": {
      "attributes": {
        "first_name": "Juan",
        "last_name": "dela Cruz",
        "email": "[email protected]",
        "phone": "09171234567"
      }
    }
  }'

Email and phone must be unique per customer. Save the Customer id linked to your user record. Customers are scoped to your merchant account — a vaulted card cannot be used across different merchants.

Create a Payment Intent with setup_future_usage

{
  "data": {
    "attributes": {
      "amount": 10000,
      "currency": "PHP",
      "payment_method_allowed": ["card"],
      "setup_future_usage": {
        "session_type": "on_session",
        "customer_id": "cus_Exy3jegPk4eEagpQcE6wnLB4"
      }
    }
  }
}

setup_future_usage tells PayMongo to vault the card upon successful payment.

Complete the payment

Attach the Payment Method as normal. On successful payment, the card is vaulted to the Customer.

Charging a saved card

1. Retrieve saved payment methods

GET https://api.paymongo.com/v1/customers/{customer_id}/payment_methods

2. Update the CVC (required for on-session charges)

Before attaching a saved card, collect the CVC from the customer and update the Payment Method:

curl -X PATCH https://api.paymongo.com/v1/payment_methods/{id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'sk_test_YOUR_SECRET_KEY:' | base64)" \
  -d '{
    "data": {
      "attributes": {
        "details": {
          "cvc": "123"
        }
      }
    }
  }'

3. Attach to a new Payment Intent

Create a new Payment Intent and attach the saved Payment Method ID. The customer may still need to complete 3DS authentication depending on their bank.

Deleting a customer or saved card

Use the Delete a Customer or Delete a Payment Method of a Customer endpoints. Once deleted, the card cannot be reused — a new vaulting flow is required.