🚧

This feature is currently open for early access! We need to configure your account (whether you are planning to use our test keys or live keys) before your developers can start testing and integration. Kindly message [email protected] to request for key configuration.

What is Card Vaulting

Card vaulting allows merchants the ability to save and reuse card details on our platform. This serves a variety of purposes:

1. Better user experience for returning customers
2. Allows merchants to charge customers off session.

To distinguish between the two main use cases, we'll denote the first as on session while the latter as off session. This is because the customer is in the checkout session for the previous case, while the merchant charges the merchants, like a subscription service, while the cardholder is not on the checkout page.

For now, we only support payments via on session transactions.

Integrating through the Payment Intent Workflow

The payment intent workflow is the main workflow used to make payments via PayMongo. It's in this flow where straight card payments are made. To enable card vaulting, a few additional steps just need to be added to the existing workflow.

Vaulting a Card

1. Creating a Customer

The merchant has to create a customer to be able to save cards to that merchant's customer. Note that customers are unique to a merchant. The same customer, or the vaulted cards to the customer, currently can't be used for another merchant's transactions. This will be for future use.

2. Saving a Card to a Customer

Once the customer is created, the merchant will be able to vault the card. The following attributes have to be added when creating a payment intent when vaulting a card:

"setup_future_usage": {
  "session_type": "on_session",
  "customer_id": "cus_Exy3jegPk4eEagpQcE6wnLB4"
}

The setup_future_usage parameter indicates that the payment method will be used in future transactions. The session_type indicates how the payment method will be used; either on_session or off_session charges. For now, only on_session is supported. The customer_id is the customer ID corresponding to the cardholder.

Using a Vaulted Card

We designed the following workflow to use a vaulted card:

1. Verify existence of Customer

The idea of this is to be able to verify if the customer in their checkout page exists in the list of already existing merchants. If the merchant is sufficiently confident that the customer exists, then they don't need to do this step.

To be able to verify the customer, the merchant can either:

1. Save the customer ID in their database
2. Verify the existence based on email and phone number.

The merchant can use the email or phone number as we made them unique per customer of each merchant. This is in preparation for the future where we can send OTPs to the email and phone number to verify the cardholder on checkout.

For any of these, the merchant can use the Retrieve a Customer endpoint.

2. Choose among the vaulted payment methods

Once the merchant identifies the customer in their checkout page, the merchant can fetch all the vaulted payment methods of the customer. The merchant can use the Retrieve the Payment Methods of a Customer endpoint. Once fetched, the customer can choose among the returned payment methods to charge with.

3. Charge the vaulted payment method

Once the customer has chosen their desired payment method, the merchant can do the standard payment intent process of:

1. Creating a payment intent
2. Attaching the vaulted payment method to the payment intent.