Handling Customer Notifications

GoCardless automatically sends notifications to customers whenever an event happens in our system. For example, when a payment has been created, the customer will receive an email that informs them about the amount, description and cause of the payment.

You have the ability to send some of these notifications yourself, and we’ll honour your request if it is made within our stated deadline: otherwise, we will send the notification ourselves.

This feature is especially handy if you want to combine multiple notifications into a single one, for example:

a welcome email which includes mandate setup information
an email that lists the schedule of all upcoming payments
an email that combines a notice of a new mandate and a new subscription

Here is an example of the workflow:

Your integration creates a payment
The payment event schedules a payment_created notification
We send a webhook to your application which includes notification metadata
Your application notifies us that it will handle the notification

There are three conditions that you must satisfy to be able to handle a notification:

You must be approved to handle notifications of this type
You must be the “notification owner” for that payment, mandate, or subscription
You must be on the Pro package

Currently, the following notifications can be handled:

payment_created
mandate_created
subscription_created

Getting approved to handle notifications

To be able to handle customer notifications yourself, you will need to be granted permission. Please get in touch with the GoCardless support team to get started.

Permissions are very granular and cover the type & scheme of the notification. For example, you might be approved to handle the payment_created notification just in the scheme sepa.

Compliant notifications must include all of the required information for that notification type, and be sent within the correct interval. More information about the required information for each type of notification can be found in our platform guides.

Notification ownership

A merchant may be connected to multiple partners, or have multiple integrations, so to avoid the problem of multiple integrations all trying to handle the same notification, we track the “owner” for all customer notifications in our system.

Only the owner will have the ability to handle notifications for that resource, falling back to GoCardless if the notification deadline is missed.

The owner is usually defined as the creator of that resource. For example, if your integration creates a payment, the owner will be your integration. Currently, our system does not permit any kind of ownership transfer from one integration to another. Resources created via dashboard will not record any owner (and therefore cannot be handled by your integration).

Getting notified about notifications

Notification information is currently only delivered in webhooks. When your application receives a webhook, each event may include a customer_notifications payload, which contains a list of one or more notifications that were triggered by that event. (If you don’t receive this information, it’s because you are not the owner for that resource or have not been granted any permissions):

POST https://example.com/webhooks HTTP/1.1
Content-Type: application/json
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2018-08-03T12:00:00.000Z",
      "action": "created",
      "resource_type": "payments",
      "links": {
        "payment": "PM123",
      },
      "details": {},
      "customer_notifications": [
        {
          "id": "PCN123",
          "type": "payment_created",
          "deadline": "2018-08-25T12:09:06.000Z",
          "mandatory": true
        }
      ]
    }
  ]
}

Note that each notification for an event includes an id, type, deadline and mandatory flag:

id is used to handle the notification (see below)
type can be used to filter notifications that you don’t handle. For example, if your integration only handles payment_created notifications, you can safely ignore notifications that are of another type.
deadline is the time by which your application must respond. If we don’t hear from you before this deadline, we’ll send the notification ourselves. The deadline is typically 10 minutes from the point at which we send the webhook but in the case of payment_created notifications, the deadline is the last possible time to notify the customer before the payment collects (this mirrors GoCardless’ behaviour).
mandatory is whether the notification needs to be handled by somebody (currently always true).

Handling notifications yourself

If your application intends to handle a notification, you should let us know before you take action. If you wait until after sending the notification, there is a chance that we also sent it in the meantime (e.g. if the deadline had elapsed), which would result in the customer receiving two notifications, one from each of us.

So, we recommend that you declare your intent first, and then send the notification using whichever mechanism is most appropriate for your system:

<?php
// We recommend storing your webhook endpoint secret in an environment variable
// for security
$webhook_endpoint_secret = getenv("GOCARDLESS_WEBHOOK_ENDPOINT_SECRET");
$access_token = getenv("GOCARDLESS_ACCESS_TOKEN");
$request_body = file_get_contents('php://input');

$headers = getallheaders();
$signature_header = $headers["Webhook-Signature"];

try {
    // The parse method will first verify the signature of the webhook body
    // in order to ensure it has not been tampered with. Without a valid
    // signature, a \GoCardlessPro\Core\Exception\InvalidSignatureException
    // will be thrown.
    $events = \GoCardlessPro\Webhook::parse($request_body,
                                            $signature_header,
                                            $webhook_endpoint_secret);
    $client = new \GoCardlessPro\Client([
        'access_token' => $access_token,
        'environment' => \GoCardlessPro\Environment::SANDBOX
    ]);

    // Each webhook may contain multiple events to handle, batched together
    foreach ($events as $event) {
        // We might want to handle mandate_created emails and send an email which
        // includes both the mandate and upcoming payments for it.
        foreach ($events->customer_notifications as $notification) {
            if ($notification->type === "mandate_created") {
                $client->customerNotifications()->handle($notification->id);
                // We recommend processing data asynchronously, so as to
                // promptly respond to the  webhook and avoid timeouts. In this
                // example, the application  uses a message  queue to send the
                // email later.
                \MyNotificationsSystem::enqueue($notification, $event);
            } elseif ($notification->type === "payment_created") {
                // If your mandate_created email properly notifies of the
                // payment schedule, we still need to handle the payment_created
                // notification to prevent GoCardless from sending it.
                $client->customerNotifications()->handle($notification->id);
            }
        }
    }

    header("HTTP/1.1 204 No Content");
} catch(\GoCardlessPro\Core\Exception\InvalidSignatureException $e) {
    header("HTTP/1.1 498 Invalid Token");
}

Alternatively, if your application does not respond, or does not respond before the deadline, GoCardless will send the notification instead and there will be no opportunity to handle after that point.

In all cases, GoCardless will record the outcome for each notification for audit purposes.

Need help?

Connect as a partner

Handling Customer Notifications

For Partners

Notification ownership

Getting notified about notifications

Handling notifications yourself