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. In order for you to start processing the payments, you need to have the two major configurations completed

Step 1: 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 BSS 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

Note: If you prefer to use Adyen payment gateway, we need the list of origins for your domain. Send us a list of origins where you want to use them, so we will add them to the whitelist for Adyen clientKey.

Step 2: 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.

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 Adyen and PayPal, use the appropriate URL from the tables below (the URL of Adyen or PayPal connector).

• 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 for reporting purposes.

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 Adyen and PayPal's endpoints

Here are tables with Cleeng connectors production endpoints which will be needed if you are using Cleeng connectors (Adyen, PayPal):

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

Example

Scenario:
You want to set up recurring payments for Adeyn. You need to subscribe to all required topics, one by one. See point 1) below on how to subscribe to subscriptionReadyForPaymentAuthorisation.

You need to repeat it for each required webhook topic.

After you’ve done it, you may decide to also set up recurring payments for PayPal. Then, you also need to subscribe to all required topics, one by one. See point 2) on how to subscribe to subscriptionReadyForPaymentAuthorisation.

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

1. You subscribe to subscriptionReadyForPaymentAuthorisation webhook for Adyen

PUT 'https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/subscriptionReadyForPaymentAuthorisation' \
[
    {
        "url": "https://adyenapi-sandbox.cleeng.com/adyen/recurring/authorisations",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $adyenPaymentMethodId
                }
            }
        ]
    },
]

Response 200 - OK:

{
        “success”: true,
        “data”: {
              “topic”: “subscriptionReadyForPaymentAuthorisation”,
              “endpoints”: [
                {
        "url": "https:///adyenapi-sandbox.cleeng.com/adyen/recurring/authorisations",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": 451494717
                }
            }
        ]
                “Verification”: null
    }    
     ]
}
“message”: “Successfully subscribed to webhook”
}

2. You decide that you also want to subscribe to the same webhook topic for PayPal:

You must be careful not to override your subscription for Adyen. You need to repeat the subscription to Adyen, not to replace it.
This is what you need to do:

PUT 'https://api.sandbox.cleeng.com/3.1/webhook_subscriptions/subscriptionReadyForPaymentAuthorisation' \
[
    {
        "url": "https://adyenapi-sandbox.cleeng.com/adyen/recurring/authorisations",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $adyenPaymentMethodId
                }
            }
        ]
    },

                {
        "url": "https://connector-sandbox.cleeng.com/paypal/v1/payments/authorize",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": $paypalPaymentMethodId
                }
            }
        ]
    },

]

Response 200 - OK:

{
        “success”: true,
        “data”: {
              “topic”: “subscriptionReadyForPaymentAuthorisation”,
              “endpoints”: [
                {
        "url": "https:///adyenapi-sandbox.cleeng.com/adyen/recurring/authorisations",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": 451494717
                }
            }
        ]
                “Verification”: null
    }



          {
        "url": "https://connector-sandbox.cleeng.com/paypal/v1/payments/authorize",
        "filters": [
            {
                "name": "paymentMethodId",
                "options": {
                    "value": 123456789
                }
            }
        ]
                “Verification”: null

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

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