Overview

The payment intent workflow is the main workflow to make payments via PayMongo. To enable Card Vaulting, a few additional steps just need to be added to your existing workflow.

Definition of Terms

Further context on the terms going to be used in the card vaulting process can be seen below:

Setup & Prerequisites

🚧

Account configuration required

This feature is only available for M2 accounts. Whether you are planning to use our test keys or live keys for Hold and Capture integration, you need to activate the Cards feature first by enabling it via the Developers tab (visible only for account owners).

If you are the account owner and you don't see the prompt on your dashboard, feel free to reach out to [email protected]

• For API Users:

  We need to onboard your account (whether you are planning to use our test keys or live keys) before you can start testing and integrating.

• For Shopify Users

  The feature will automatically be available to eligible merchants who have installed the Secure Payments via PayMongo Shopify plug-in.

Customer Experience Flow

The first time a customer checks out, they can choose to save their card. PayMongo stores a token (not the raw card number). Next time they check out, they can pay with the saved card by entering their CVC, making checkout faster and easier.

On their first purchase

1. The cardholder visits the merchant's checkout page and completes a purchase using their credit or debit card.

   

2. During checkout, they are prompted with the option to save their card for future use. Here, they will enter an OTP to verify the account.

   

3. If accepted, the card is securely tokenized and stored by PayMongo.

For their subsequent purchases

1. The cardholder returns to the merchant's site to place another order.

2. They are prompted to use their saved card.

   

3. The cardholder inputs the CVC, and the payment is processed instantly using the saved card.

   

Integrating Save Card through the Payment Intent Workflow

⚠️

Only On session support available for this feature

On-session vaulting requires customer interaction (e.g., entering CVC during checkout). Off-session charging (e.g., auto-billing subscriptions) is only supported via Subscriptions API.

For off session use cases, refer to our Subscriptions Guide.

Saving a card

You only need to do this for new customers. This is an indication to allow PayMongo to save the details of the customer's billing information after the customer's first transaction.

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 saved 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 save the card. The following attributes have to be added when creating a payment intent when saving 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.

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. Updating the CVC of the card (on_session transactions)

Once the customer picks a vaulted card, the merchant needs to collect the CVC and update the payment method in the backend. This is done by calling the Update a PaymentMethod endpoint. Once the payment method is updated, the card can now be charged.

4. Charge the saved payment method

To charge the vaulted card, the merchant can do the standard payment intent process of creating the payment intent by calling the Create a PaymentIntent endpoint. Shortly after this, the updated payment method needs to be attached to the created payment intent by calling the Attach to PaymentIntent endpoint.

Deleting a Customer or Saved Card

The merchant also has the ability to delete a customer or a saved card that is saved to a customer via PayMongo's API. Note that once the customer or saved card is deleted, it cannot be used again for future transactions without having to create a new customer or save the card again to a customer.

The merchant can use the Delete a Customer or the Delete a Payment Method of a Customer endpoints to do this.

Test Mode Support

Any test card that simulates a successful purchase can be used for vaulting.

System Limitations

We currently only support card vaulting for:

1. Merchants integrating via our API
2. Merchants who have undergone enhanced KYC
3. Merchants who have the ability to verify cardholder identity on checkout
   a) OTP system b) Account system