When upgrading your legacy integration to the new API, you will need to adjust your webhook handler to manage the new types of webhooks that we send you.
A number of actions we sent in the legacy system have also now been changed. Please find below a mapping of these changes, as well as new actions you may wish to account for:
Authorisations > Mandates
Authorisations are now mandates. Mandates are far more flexible - you can create one off payments or subscriptions against the same mandate, and mandates can have multiple subscriptions against them. There is no need for the customer to re-authorise any new payments or subscriptions on a mandate.
Legacy API - pre-authorisation / subscription actions | New API - mandate actions | Action description |
cancelled | cancelled | The mandate has been cancelled, either by the customer through their bank or this API, or automatically when their bank account is closed. |
expired | expired | No collection attempts were made against the mandate for over 13 months. As a result it has expired, and no further collections can be taken against it. If you wish to continue taking payments from this customer you should request their permission and use the reinstate endpoint. |
New API - additional mandate actions | Action description |
created | The mandate has been created. |
customer_approval_granted | The mandate required additional approval from the customer (e.g. permission from a second signatory), and that approval has been granted. |
customer_approval_skipped | The mandate originally was believed to require additional approval from the customer (e.g. permission from a second signatory), but approval has been skipped (for example because the mandate was erroneously marked as needing a second signature). |
active | The mandate has been successfully set up by the customer’s bank. |
failed | The mandate could not be set up, generally because the specified bank account does not accept Direct Debit payments or is closed. |
transferred | The mandate has been transferred to a different bank account. The event will include links[previous_customer_bank_account] and links[new_customer_bank_account], and the mandate may have been submitted again, depending on how the banks involved handled the transfer. |
submitted | The mandate has been submitted to the banks, and should become active in a few days, unless the bank declines the request. |
resubmission_requested | A request to resubmit the mandate was made by the mandate reinstate endpoint. |
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. |
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. |
Bills > Payments
Our Legacy API offered the ability to create one-off bills, or a series of one-off bills, on a pre-authorisation. Bills are now called payments, and a payment can either be created as a one-off or as part of a subscription.
Legacy API - bill actions | New API - payment actions | Action description |
created | created | The payment has been created. |
paid | confirmed | The payment has been collected from the customer’s bank account, and is now being held by GoCardless. It can take up to 5 working days for a payment to be collected, and will then be held for a short time before becoming paid_out. |
withdrawn | paid_out | The payment has left GoCardless and has been sent to the creditor’s bank account. |
failed | failed | The payment could not be collected, usually because the customer did not have sufficient funds available. GoCardless will not automatically retry the payment. |
cancelled | cancelled | The payment was cancelled. |
refunded | (sent as a refund object) ** | |
chargedback | charged_back | The customer asked their bank to refund the payment under the Direct Debit Guarantee, and it has been returned to the customer. |
retried | resubmission_requested | A request to resubmit the payment was made by the payment retry endpoint. |
New API - additional payment actions | Action description |
submitted | The payment has been submitted to the banks. It will be a few days until it is collected, or fails. |
late_failure_settled | The payment was a late failure which had already been paid out, and has been debited from a payout. |
chargeback_cancelled | The customer’s bank has cancelled the chargeback request. This is almost always at the request of the customer. |
chargeback_settled | The payment was charged back, having previously been paid out, and has been debited from a payout. |
** Refunds are now represented by their own resource. If a payment is refunded, the status of the payment resource will remain confirmed with a refund resource being created separately from the payment.
New API - refund actions | Action description |
created |
A refund has been created. The details[cause] will be payment_refunded, and the details[origin] will be api. |
paid | The refund has been paid to your customer. The details[cause] will be refund_paid, and the details[origin] will be gocardless. |
refund settled | The refund has been deducted from a payout. The details[cause] will be refund_settled, and the details[origin] will be gocardless. |
Subscriptions are now created against a mandate. You’ll receive the following webhook actions:
New API - subscription actions | Action description |
created | The subscription has been created. |
customer_approval_granted | The subscription required additional approval from the customer before it could become active, and that approval has been granted. |
customer_approval_denied | The subscription required additional approval from the customer before it could become active, and that approval has been denied. |
payment_created | A payment has been created by this subscription. |
cancelled | This subscription has been cancelled. No further payments will be created. |
finished | This subscription has finished. No further payments will be created. |
Payouts
Our new API still allows you to query the payouts you receive from GoCardless. In addition, we've added some steps to help you reconcile payouts with Events, meaning you'll be able to get a list of payments in a specific payout through the API.
New API - payout actions | Action description |
paid | GoCardless has transferred the payout to the creditor’s bank account. The details[cause] will always be payout_paid, and the details[origin] will be gocardless. |
Webhook Format
Our Legacy API sent webhooks about the status of a bill, pre-authorisation or subscription. Our new API sends webhooks containing a lot more information, and can be sent to multiple endpoints. When a resource changes status we record an event, and events are batched into arrays and POSTed as webhooks.
Example legacy pre-authorisation webhook:
{
"payload": {
"resource_type": "pre_authorization",
"action": "cancelled",
"pre_authorizations": [{
"id": "AKJ398H8KBOOO3",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOO3"
}, {
"id": "AKJ398H8KBOOOA",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOOA"
}],
"signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
}
}
Example new API mandate webhook:
{
"events": [
{
"id": "EVTESTWKH4MPNG",
"created_at": "2017-04-25T11:20:47.542Z",
"resource_type": "mandates",
"action": "cancelled",
"links": {
"mandate": "MD123"
},
"details": {
"origin": "api",
"cause": "mandate_cancelled",
"description": "The mandate was cancelled at your request."
},
"metadata": {}
}
]
}
You’ll also find a useful tool in the developer tab of your new sandbox or live dashboard for testing these new webhooks. Once you’re on the developer section, click “Send test webhook” to send any webhook that we might send to your webhook endpoint.