GoCardlessDeveloper Docs
Create a sandbox account

Customer Notification

View as Markdown

Customer Notifications represent the notification which is due to be sent to a customer after an event has happened. The event, the resource and the customer to be notified are all identified in the links property.

Note that these are ephemeral records - once the notification has been actioned in some way, it is no longer visible using this API.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

Handle a notification#

POST/customer_notifications/{customer_notification_id}/actions/handle

"Handling" a notification means that you have sent the notification yourself (and don't want GoCardless to send it). If the notification has already been actioned, or the deadline to notify has passed, this endpoint will return an already_actioned error and you should not take further action. This endpoint takes no additional parameters.

Path Parameters

NameTypeDescription
customer_notification_idrequiredstring

The customer notification id

POST https://api.gocardless.com/customer_notifications/EV1D18JEXAMPLE/actions/handle HTTP/1.1
@client.customer_notifications.handle("EV1D18JEXAMPLE")
client.customer_notifications.handle("EV1D18JEXAMPLE")
const customerNotification = await client.customerNotifications.handle("EV1D18JEXAMPLE");
$client->customerNotifications()->handle("EV1D18JEXAMPLE");
CustomerNotification customerNotification = client.customerNotifications().handle("EV1D18JEXAMPLE").execute();
customerNotificationHandleParams := gocardless.CustomerNotificationHandleParams{}
customerNotification, err := client.CustomerNotifications.Handle(ctx, "EV1D18JEXAMPLE", customerNotificationHandleParams)
var customerNotificationResponse = await client.CustomerNotifications.HandleAsync("EV1D18JEXAMPLE");
GoCardless.Resources.CustomerNotification customerNotification = customerNotificationResponse.CustomerNotification;
Responsehttp
HTTP/1.1 201 Created
Content-Type: application/json
{
  "customer_notifications": {
    "id": "EV1D18JEXAMPLE",
    "type": "payment_created",
    "action_taken": "handled",
    "action_taken_at": "2018-08-01T13:42:56.000Z",
    "action_taken_by": "Partner name",
    "links": {
      "customer": "CU123",
      "event": "EV123",
      "payment": "PM123"
    }
  }
}


POST https://api.gocardless.com/customer_notifications/EV1D18JEXAMPLE/actions/handle HTTP/1.1

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "error": {
    "message": "You are not authorised to handle notifications of this type.",
    "documentation_url": "https://developer.gocardless.com/api-reference#notification_type_forbidden",
    "type": "gocardless",
    "code": 403,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "notification_type_forbidden",
         "message": "You are not authorised to handle notifications of this type."
      }
    ]
  }
}


POST https://api.gocardless.com/customer_notifications/EV1D18JEXAMPLE/actions/handle HTTP/1.1

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "error": {
    "message": "You are not the notification owner for this resource.",
    "documentation_url": "https://developer.gocardless.com/api-reference#not_notification_owner",
    "type": "gocardless",
    "code": 403,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "not_notification_owner",
         "message": "You are not the notification owner for this resource."
      }
    ]
  }
}


POST https://api.gocardless.com/customer_notifications/EV1D18JEXAMPLE/actions/handle HTTP/1.1

HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": {
    "message": "This notification can no longer be handled.",
    "documentation_url": "https://developer.gocardless.com/api-reference#already_actioned",
    "type": "gocardless",
    "code": 410,
    "request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
    "errors": [
      {
         "reason": "already_actioned",
         "message":  "This notification can no longer be handled."
      }
    ]
  }
}
Request Body
customer_notificationsobject
Response 200

Action completed successfully

customer_notificationsobject
6 properties
idstring

The id of the notification.

typestring

The type of notification the customer shall receive. One of:

  • payment_created
  • payment_cancelled
  • mandate_created
  • mandate_blocked
  • subscription_created
  • subscription_cancelled
  • instalment_schedule_created
  • instalment_schedule_cancelled
payment_createdpayment_cancelledmandate_createdmandate_blockedsubscription_createdsubscription_cancelledinstalment_schedule_createdinstalment_schedule_cancelled
action_takenstring

The action that was taken on the notification. Currently this can only be handled, which means the integrator sent the notification themselves.

handled
action_taken_atstring

Fixed timestamp, recording when this action was taken.

action_taken_bystring

A string identifying the integrator who was able to handle this notification.

linksobject
6 properties
paymentstring

The identifier of the related payment.

mandatestring

The identifier of the related mandate.

refundstring

The identifier of the related refund.

subscriptionstring

The identifier of the related subscription.

customerstring

The customer who should be contacted with this notification.

eventstring

The event that triggered the notification to be scheduled.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard