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
details, specifying why the event happened

{
  "events": {
    "id": "EV123",
    "created_at": "2014-04-08T17:01::06.000Z",
    "resource_type": "payments",
    "action": "failed",
    "details": {
      "origin": "bank",
      "cause": "insufficient_funds",
      "description": "The customer's account had insufficient funds to make this payment.",
      "scheme": "sepa_core",
      "reason_code": "AM04",
      "will_attempt_retry": false
    },
    "metadata": {},
    "links": {
      "payment": "PM123"
    }
  }
}

Key Webhook Events#

Billing Request Webhooks#

Event	Description	Suggested Handling
`flow_visited`	The billing request flow has been visited	Use to detect payer inactivity and expire the billing request if needed
`flow_exited`	The payer exited the flow without completing it	Consider triggering a push notification for mobile experiences
`bank_authorisation_denied`	A bank authorisation was denied by the payer	Display the denial reason from `details.description`
`bank_authorisation_failed`	A bank authorisation failed due to a bank account mismatch	Display the failure reason from `details.description`
`fulfilled`	The billing request was fulfilled and the mandate and/or payment have been created	Save the mandate and/or payment ID to your database

billing-request-state-diagram

See the full list of billing request webhooks in the API reference.

Mandate Webhooks#

Event	Description	Suggested Handling
`created`	The mandate has been created	Save the mandate ID to your database
`submitted`	The mandate has been submitted to the banks	Update the mandate status in your billing system
`active`	The mandate has been successfully set up by the customer's bank	Update the mandate status in your billing system
`failed`	The mandate could not be set up — the bank account does not accept Direct Debit or is closed	Update status; allow the customer to use another payment method or re-attempt with a new account
`cancelled`	The mandate was cancelled by the customer, via the API, or automatically when their account was closed	Update status; request a new payment method and cancel any associated subscriptions
`expired`	No collections were made within the dormancy period and the mandate has expired	Update status; use the reinstate endpoint or create a new mandate
`resubmission_requested`	A reinstate request was made via the mandate reinstate endpoint	Update the mandate status in your billing system
`reinstated`	The mandate has become active again after being cancelled or expired	Update the mandate status in your billing system
`replaced`	The mandate was cancelled and replaced by a new one. The event includes `links.new_mandate`	Update the stored mandate ID to the value in `links.new_mandate`
`blocked`	The mandate matched fraud information or a block list and cannot be unblocked	Update status; cancel any subscriptions against this mandate

mandate-state-diagram

See the full list of mandate webhooks in the API reference.

Payment Webhooks#

Event	Description	Suggested Handling
`created`	The payment has been created	Save the payment ID to your database
`submitted`	The payment has been submitted to the banks	Update the payment status in your billing system
`confirmed`	The payment has been collected and is held by GoCardless before payout	Update the payment and invoice status
`paid_out`	The payment has been sent to the creditor's bank account	Update the payment and invoice status
`failed`	The payment could not be collected. If `will_attempt_retry` is true, Success+ will retry automatically	Update the payment and invoice status
`cancelled`	The payment was cancelled	Update the payment and invoice status
`resubmission_requested`	Success+ has scheduled an automatic retry (see `failed`)	Update the payment and invoice status
`charged_back`	The customer reclaimed the payment via the Direct Debit Guarantee	Update the payment and invoice status
`chargeback_cancelled`	The customer's bank cancelled the chargeback request	Update the payment and invoice status

payment-state-diagram

See the full list of payment webhooks in the API reference.

Refund Webhooks#

Event	Description	Suggested Handling
`created`	A refund has been created (`details.cause`: `payment_refunded`, `details.origin`: `api`)	Update the refund status and expose it to your merchants
`failed`	The refund did not reach the customer; funds are returned to you (`details.cause`: `refund_failed`)	Update the refund status and expose it to your merchants
`paid`	The refund has been paid to the customer (`details.cause`: `refund_paid`)	Update the refund status and expose it to your merchants

See the full list of refund webhooks in the API reference.

What's Next?#

Stay up to date with webhooks

Learn how to create a secure webhook endpoint and verify webhook signatures.

Learn more

Go-live checklist

Complete the self-assessment review and submit your integration for approval.

Learn more