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.

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. <For Edit: Let's put the information that we only supporton_session in a banner> 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.<For Edit: Let's highlight the note for this process instead or if you think its better for a banner here, let's put it in a banner>

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