Update Payment Details

👍

Check our Reference Materials for more details about a payment connector.

Description

This tutorial describes how to implement a change of payment details for a customer using the Cleeng Payment API and the payment gateway.

This is the use case when a customer:

• changes e.g. his/her card details (within the same payment gateway) or
• changes a payment method e.g. from a card to PayPal (that involves changing a payment gateway from Adyen to PayPal).

Process Flow

📘

Note

Details of the implementation will depend on a specific payment gateway solution.

Step-by-Step Guide

Prerequisites

Make sure that you subscribe to the following webhook event: PaymentDetailsDeactivated.

To learn more about how to configure and use Cleeng Webhooks, please click here. You can also find the list of available webhooks here.

Note:
Please note that webhook handler should return "200" http status code meaning that it was successfully processed.

Update Payment Details

“Update Payment Details” process can involve one connector (e.g. just a change of a card without changing payment gateway) or it can involve two connectors (if the change of payment gateway is involved, e.g. from Adyen to PayPal).

No matter what the use case, in this documentation we refer to the old payment details connector and the new payment details connector:

• If there is no change of payment gateway - both will refer to the same connector.
• If a new payment gateway is involved, then two connectors are necessary.

The process involves:

1. Creation of new payment details
2. Deactivation of old payment details (optional)
3. Cancellation of existing authorised payments and cleaning up of old payment details (optional, but recommended if old payment details were deactivated)
4. Deletion of old payment details (optional)

How to create new payment details:
(This is done by the new payment details connector).

1. A user selects a payment method and provides new payment details in the front-end app.
2. The connector processes new payment details creation with a payment gateway.
3. To create new payment details in Cleeng, the connector calls Cleeng Payment API POST /3.1/payment_details

📘

Important

Please pay attention to the active parameter:

• If active: true - new payment details will be used for recurring payments. All old payment details will be deactivated.
• If active: false- new payment details, though created, won’t be used in a recurring process.

How to clean up old payment details (deactivate old payment details, cancel authorised payments and delete old payment details):
(This is done by the old payment details connector).

1. To clean up, you must subscribe to the PaymentDetailsDeactivated webhook event - notifications will be sent every time payment details are deactivated.
2. To get authorised payments, the connector makes an API call to Cleeng Payment API using POST /3.1/payment_details/{paymentDetailsId:/d+}/authorised_payments.
3. If there are any authorised payments, they should be cancelled in the payment gateway and in Cleeng. To cancel payments in Cleeng, the connector makes an API call to Cleeng Payment API using PATCH 3.1/payments/{paymentId}/cancel
4. At this stage, old payment details can be deleted in Cleeng (this is optional, but recommended). To delete payment details, an API call should be made to deletePaymentDetails. If payment details are deleted in Cleeng, they should be deleted in the payment gateway too.

Up Next

You're almost there. Please continue to Termination.