Webhooks - Payments

Webhooks are a mechanism that allows external applications, like the payment connectors, to be notified about events happening inside Cleeng.

Cleeng is working with industry-leading payments providers Adyen and PayPal to provide merchant services to our clients. Webhooks setup for Adyen is automatic (no action on your side is needed), but if PayPal is your choice, you need to complete the configuration manually in order to start processing payments.

Similarly, if you want to use a custom connector, it’s your responsibility to configure webhooks.

Prerequisites: Enable Payment Service Provider (PSP)

Before you start configuring the webhooks, you need to enable the Payment Service Provider (PSP) (whether it's Adyen/PayPal or both) for your integration. To do so, you can contact our support team to enable it for you. Simply, use this form with category Payment Integration/API.

You can find more about setup in Payment with Adyen and Payment with PayPal Express Checkout

Configure Webhooks

❗️

Important!

Subscribing to the webhooks and making filtering setup is required for recurring payments to work properly.

The following webhooks are required:

• subscriptionReadyForPaymentAuthorisation
• subscriptionReadyForPaymentCapture
• subscriptionReadyForTermination
• refundPayment
• capturePayment
• paymentDetailsDeactivated

Configure them with Webhook settings (please pay attention to the tables below). Remember to take into account any connectors you use (PayPal and custom connectors).

To configure webhooks:

• Make an API call: PUT https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/{topic}

• Replace {topic} with the topic you want to subscribe to (i.e. the event you want to be notified about), e.g. subscriptionReadyForPaymentAuthorisation. A topic identifies what event has occurred in the Cleeng system.

• Provide a list of endpoints to which notifications should be delivered.
  For PayPal, use the appropriate URL of PayPal connector from the tables below.

• No matter what connector you choose, you should apply the webhook filtering logic - filtering by paymentMethodId. This allows you to differentiate transactions coming from the respective connectors.

NOTE: You have to repeat the configuration steps for each required topic.

🚧

Warning

Be careful not to override the webhooks you have already subscribed to (see the example).

If, for example, in your first request you provided two endpoints, and in the following request just one endpoint -> the endpoint from the latest request will override the two endpoints from the first request. This is because the PUT method creates a new resource or replaces a representation of the target resource with the request message payload.

List of PayPal's endpoints

Here are tables with Cleeng connectors production endpoints which will be needed if you are using Cleeng PayPal connector:

Here are tables with Cleeng connectors sandbox (test) endpoints which will be needed if you are using Cleeng PayPal connector:

Example

Scenario:

1. You want to set up recurring payments for PayPal. You need to subscribe to all required topics, one by one.

   You need to repeat it for each required webhook topic.

2. After you’ve done it, you may decide to also set up recurring payments for another - custom payment gateway. Then, you also need to subscribe to all required topics, one by one.

   Let’s say you decide that you also want to subscribe to the same webhook topic as for PayPal. This is what you need to do to subscribe to subscriptionReadyForPaymentAuthorisation:

   You must be careful not to override your subscription for PayPal. You need to repeat the subscription to PayPal, not to replace it.

   
   

PUT 'https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/subscriptionReadyForPaymentAuthorisation' \
[
    {
        "url": "https://connector-sandbox.cleeng.com/paypal/v1/payments/authorize",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $paypalPaymentMethodId
                }
            }
        ]
    },

                {
        "url": "https://[yourcustomconnectorurl]",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $yourcustomconnectorPaymentMethodId
                }
            }
        ]
    },

]

Response 200 - OK:

{
        “success”: true,
        “data”: {
              “topic”: “subscriptionReadyForPaymentAuthorisation”,
              “endpoints”: [
                {
        "url": "https://connector-sandbox.cleeng.com/paypal/v1/payments/authorize",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": 451494717
                }
            }
        ]
                “Verification”: null
    }



          {
        "url": "https://[yourcustomconnectorurl]",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": 123456789
                }
            }
        ]
                “Verification”: null

            }
     ]
}
“message”: “Successfully subscribed to webhook”
}

If you want to add another connector, you need to repeat the previous two.

3. You can check the topics you subscribed to with GET https://api.sandbox.cleeng.com/3.1/webhook_subscriptions (List webhook subscriptions)

Up Next

Now that we have configured the webhooks for recurring billing, let's look into dunning action settings.

Dunning action settings