Webhooks for partners
A webhook is a real-time request that GoCardless sends to your server to alert you of an event.
Adding support for webhooks allows you to receive real-time notifications from GoCardless when events happen in your account, so you can take automated actions. This is the suggested monitoring approach.
A webhook can contain multiple events, and each has:
a resource_type, telling us what kind of resource the event is for, for example, “payments” or “mandates”
an action, telling us what happened to the resource, for example, the “failed” action for a payment
and details, specifying why the event happened
1{
2 "events": {
3 "id": "EV123",
4 "created_at": "2014-04-08T17:01::06.000Z",
5 "resource_type": "payments",
6 "action": "failed",
7 "details": {
8 "origin": "bank",
9 "cause": "insufficient_funds",
10 "description": "The customer's account had insufficient funds to make this payment.",
11 "scheme": "sepa_core",
12 "reason_code": "AM04",
13 "will_attempt_retry": false
14 },
15 "metadata": {},
16 "links": {
17 "payment": "PM123"
18 }
19 }
20}Key Billing Request Webhooks
Billing Request Event | Description | Suggested Handling |
|---|---|---|
flow_visited | The billing request flow has been visited | For example, use to determine if the payer has been inactive in the flow for x period of time, and expire the billing request as needed |
flow_exited | The billing request flow has been exited by the payer | Indicates the payer did not complete the payment flow successfully before exiting. Consider handling for mobile experience (i.e. trigger push notification back to app) |
bank_authorisation_denied | A bank authorisation for this billing request has been denied by the payer | Consider displaying the denial reason (description) in billing system |
bank_authorisation_failed | A bank authorisation for this billing request has failed because of a bank account mismatch | Consider displaying the failure reason (description) in billing system |
fulfilled | This billing request has been fulfilled, and the resources (mandate and/or instant bank payment) have been created | Save the provided mandate and/or payment ID in your database for future use |
See the API Reference for the entire list of billing request webhooks.
Key Mandate Webhooks
Mandate Event | Description | Suggested Handling |
|---|---|---|
created | This mandate has been created | Save the provided mandate ID in your database |
active | The mandate has been successfully set up by the customer’s bank | Update the mandate status in your billing system |
cancelled | The mandate has been cancelled, either by the customer through their bank or this API, or automatically when their bank account is closed. No further collections can be taken against it | Update the mandate status in your billing system. Request a new payment method from the customer, and/or cancel the associated subscriptions |
failed | The mandate could not be set up, generally because the specified bank account does not accept Direct Debit payments or is closed. No collections can be taken against it | Update the mandate status in your billing system. Allow customer to use another payment method, or re-attempt the DD set up with a new bank account |
expired | No collection attempts were made against the mandate within the dormancy period of your service user number. As a result it has expired, and no further collections can be taken against it | Update the mandate status in your billing system. To continue taking payments from this customer, you can use the reinstate endpoint, or create a new mandate |
submitted | The mandate has been submitted to the banks, and should become active in a few days, unless the bank declined the request | Update the mandate status in your billing system |
resubmission_requested | A request to resubmit the mandate was made by the mandate reinstate endpoint (see ‘expired’ row) | Update the mandate status in your billing system |
reinstated | The mandate has become active again, after it was cancelled or expired. This can be due to the customer’s bank wishing to undo a cancellation or expiry notice they sent, or because the mandate was successfully reinstated via the reinstate endpoint | Update the mandate status in your billing system |
replaced | The mandate has been cancelled and replaced by a new mandate (for example, because the creditor has moved to a new Service User Number). The event will include links[new_mandate] with the ID of the new mandate | Update the mandate ID in your database to the new ID from the links[new_mandate] field |
blocked | The mandate has been blocked as it matched against either our own fraud information or an entry in a block list provided by you. This mandate cannot be unblocked and no payments can be created against it | Update the mandate status in your billing system. This mandate can no longer be used, so cancel any subscriptions against it |
See the API Reference for the entire list of mandate webhooks.
Key Payment Webhooks
Payment Event | Description | Suggested Handling |
|---|---|---|
created | This payment has been created | Save the provided payment ID in your database |
submitted | The payment has been submitted to the banks. It will be a few days until it is collected, or fails | Update the payment status in your billing system |
confirmed | The payment has been collected from the customer’s bank account, and is now being held by GoCardless for a short time before becoming paid_out | Update the payment & invoice status in your billing system |
paid_out | The payment has left GoCardless and has been sent to the creditor’s bank account | Update the payment & invoice status in your billing system |
failed | The payment could not be collected, usually because the customer did not have sufficient funds available. When Success+ is enabled, GC will automatically retry the payment if event’s will_attempt_retry field is true | Update the payment & invoice status in your billing system |
cancelled | The payment was cancelled | Update the payment & invoice status in your billing system |
resubmission_requested | Indicates the Success+ automatic payment retry is scheduled & contains the payment ID (see the ‘failed’ row) | Update the payment & invoice status in your billing system |
charged_back | The customer asked their bank to refund the payment under the Direct Debit Guarantee, and it has been returned to the customer | Update the payment & invoice status in your billing system |
chargeback_cancelled | The customer’s bank has cancelled the chargeback request. This is almost always at the request of the customer | Update the payment & invoice status in your billing system |
See the API Reference for the entire list of payment webhooks.
Key Refund Webhooks
Refund Event | Description | Suggested Handling |
|---|---|---|
created | A refund has been created. The details[cause] will be payment_refunded, and the details[origin] will be api | Update the refund status in your system & expose this to your merchants |
failed | The refund did not reach your customer, the funds will be returned to you. The details[cause] will be refund_failed, and the details[origin] will be gocardless. | Update the refund status in your system & expose this to your merchants |
paid | The refund has been paid to your customer. The details[cause] will be refund_paid, and the details[origin] will be gocardless. | Update the refund status in your system & expose this to your merchants |
See the API Reference for the entire list of refund webhooks.