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:
- Your application 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 two 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
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 handlespayment_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 ofpayment_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.
payment_created
notifications to Danish payers, to avoid double-notifying them. If you wish to
send a payment-related notification, you can of course do so, but bear in mind that it
will not be the only one received by the payer.