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 which 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 which 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:

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

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

1. You must be approved to handle notifications of this type
2. You must be the “notification owner” for that payment, mandate, or subscription

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 (e.g. the partner which created the payment). 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",
        "organisation": "OR123"
      },
      "details": {
        "origin": "api",
        "cause": "payment_created",
        "descriptions": "Payment created via the API."
      },
      "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 which 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:

require "gocardless_pro"

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox,
)

GoCardlessPro::Webhook.parse(**args).each do |event|
  notifications = event.customer_notifications

  # We might want to handle mandate_created emails and send an email which
  # includes both the mandate and upcoming payments for it.
  mandate_notifications = notifications.select { |n| n.type == "mandate_created" }

  mandate_notifications.each do |notification|
    client.customer_notifications.handle(notification.id)
    MyNotificationSystem.enqueue_email(notification, event)
  end

  # If a payment_created email was already sent, we still need to handle
  # the notification to prevent GoCardless from sending it.
  payment_notifications = notifications.select { |n| n.type == "payment_created" }

  payment_notifications.each do |notification|
    if notification_sent_previously?(notification)
      client.customer_notifications.handle(notification.id)
    end
  end
end

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.