Connector Checklist
Once you have followed all the steps for adding a payment connector, use the checklist below to make sure the necessary functions are supported.
Check our Reference Materials for more details about a payment connector.
Important:
Each payment in Cleeng should have externalPaymentId (the same as the payment identifier from an external payment gateway system).
PaymentId identifies transactions in a payment gateway and Cleeng. If a different payment Id is used for authorization and a different one for capture in a payment gateway, it must be updated in Cleeng. This update is important for example for a refund to be properly handled.
Please make sure that the following functions are supported:
-
When you build a connector for single purchases, you need to implement the functions of the Subscription Initial Purchase.
-
When you build a connector also for recurring purchases, you need to implement Recurring Billing and Termination functions, too.
If you want to offer "Update payment details" feature (optional, but recommended), you need to implement the functions of Update payment details.
Additionally, for refunds to work, you also need to subscribe to webhook - see the Refund Payment section.
1) Subscription Initial Purchase:
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Front-end Application | orderID and any relevant gateway- specific data should be passed to the connector | |
| Connector | Process payment in the payment gateway | |
| Connector | Create payment in Cleeng (if success) Pass paymentId from payment gateway to Cleeng Payment API as externalPaymentId | POST /3.1/payments (status ‘captured’) |
| Connector | Create rejected payment in Cleeng (if failure) | POST /3.1/payments (status ‘rejected’) |
2) Recurring Billing
2.1) Recurring Billing: Authorise + Capture Steps
See here for more information on authorisation and capture steps of the recurring billing process used for subscriptions.
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Subscribe to Webhooks: - subscriptionReadyForPaymentAuthorisation; - subscriptionReadyForPaymentCapture | ||
| Set up Dunning Actions Settings |
Authorise
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Connector | Create order based on webhook subscriptionReadyForPaymentAuthorisation | POST /3.1/orders |
| Connector | Authorise in payment gateway | |
| Connector | Create payment in Cleeng (if “authorised” success) | POST /3.1/payments (status ‘authorised’) |
| Connector | Create rejected payment in Cleeng (if “authorised” failure) | POST /3.1/payments (status ‘rejected’) |
Capture
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Connector | Fetch payment based on Webhook subscriptionReadyForPaymentCapture | |
| Connector | Capture in payment gateway | |
| Connector | Update payment in Cleeng (if capture successful) | PATCH /3.1/payments (status ‘captured’) |
| Connector | Create rejected payment in Cleeng (if capture failed) | PATCH /3.1/payments (status ‘rejected’) |
2.2) Recurring Billing: Capture Only
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Subscribe to Webhooks: subscriptionReadyForPaymentCapture | ||
| Set up Dunning Actions Settings | ||
| Connector | Create order based on webhook subscriptionReadyForPaymentCapture | POST /3.1/orders |
| Connector | Capture in payment gateway | |
| Connector | Create payment in Cleeng (if capture successful) | POST /3.1/payments (status ‘captured’) |
| Connector | Create rejected payment in Cleeng (if capture failed) | POST /3.1/payments (status ‘rejected’) |
3) Termination
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Subscribe to Webhooks: subscriptionReadyForTermination | ||
| Set up Dunning Actions Settings | ||
| Connector | Terminate subscription in Cleeng based on webhook subscriptionReadyForTermination | PATCH /3.1/subscriptions/{subscriptionId} |
4) Update Payment Details
Note:
“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.
| Agent | Action | Cleeng Payment API |
|---|---|---|
Subscribe to Webhooks:PaymentDetailsDeactivated | ||
| New payment details connector | Create new payment details in Cleeng | POST /3.1/payment_details |
| Old payment details connector | Fetch authorised payments based on webhook PaymentDetailsDeactivated | POST /3.1/payment_details/{paymentDetailsId:/d+}/authorised_payments |
| Old payment details connector | Cancel authorised payments | PATCH 3.1/payments/{paymentId}/cancel |
| Old payment details connector | Delete old payment details (optional) | deletePaymentDetails |
5) Refund Payment
Additonally, for refunds to work, you also need to subscribe to refundPayment webhhook.
| Agent | Action | Cleeng Payment API |
|---|---|---|
| Subscribe to Webhook: refundPayment | ||
| Connector | Refund payment in external payment gateway | |
| Connector | Refund payment in Cleeng | PATCH /3.1/payments/{paymentId}) |
Up Next
Once your connector is ready, please make sure that you display your offer with available payment methods (see Offer Display).
Updated 11 months ago