Collection Webhooks
Set up webhooks to get real-time updates on collection events.
Overview
Acquired will dispatch webhook events to your server, notifying you of events related to your collections. This guide aims to give you a comprehensive overview of the pivotal events associated with collections which you should be mindful of.
For more information on webhook structure and how to validate the integrity of a webhook, please refer to our webhook notifications guide.
Note
While webhooks provide real-time data, it's important to note that they can occasionally experience interruptions or be missed by end-users. As a result, we advise utilising the GET endpoint as well to ensure updates on collections are reliably retrieved.
Webhook parameters
The collection webhook body may contain the following parameters:
Field | Type | Description |
---|---|---|
webhook_type | string | Describes the type of event: collection_submitted collection_success collection_declined |
webhook_id | string | UUID assigned by Acquired.com for the notification. |
timestamp | integer | Exact date of when the webhook was delivered in UNIX timestamp format. |
webhook_body | JSON object | N/A |
transaction_id | string | UUID assigned by Acquired.com for the transaction. |
status | string | The status of the collection: submitted success declined |
reason | string | Provides further information relating to a declined transaction. |
order_id | string | The order ID value that was passed by you in the payment request. |
detail | JSON object | Holds additional details about the Direct Debit event. |
scheme | string | Specifies the scheme or system used for the Direct Debit: bacs |
report | string | Refers to the associated report type: ARUDD |
reason_code | string | The reason code detailing the reason for the decline. |
reason_description | string | Provides a description explaining the reason_code , such as "Account closed". |
is_retryable | boolean | Set to true if the declined collection can be retried. (This is only available when the ARUDD reason_code is set to 0 .) |
Collections webhooks
Typically, Acquired will inform you on the third working day after the collection attempt. However, in some situations, you might receive the notification on the fourth business day after the attempt.
To understand at what stage each webhook will be sent, please view our collections timings section.
collection_submitted
webhook
collection_submitted
webhookDirect Debit operates as a file-based system, where collections are sent in bulk to the Bacs scheme and the respective banks. The collection_submitted
webhook event serves as confirmation that the collection has been dispatched to the banks for processing. This means that all created collections will transition from pending
to submitted
status.
{
"webhook_type": "collection_submitted",
"webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
"timestamp": 32908394083,
"webhook_body": {
"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
"status": "submitted",
"order_id": "12345"
},
"links": [
{
"rel": "self",
"href": "/v1/transactions/29c05255-8905-f38f-1446-03f83de52d7c"
},
{
"rel": "mandate",
"href": "/v1/mandates/adb88e28-6731-4d1b-bfa4-6f2207c7cb44"
},
{
"rel": "customer",
"href": "/v1/customer/94c7e517-a06b-4abf-96c3-98e642c402ba"
}
]
}
collection_success
webhook
collection_success
webhookFollowing the submission of the collection to the banks, there will be a brief period before it is withdrawn from the end customer’s bank account. The collection_success
webhook event serves as confirmation that the payment has been successfully collected. You can utilise the transaction_id
and order_id
values for reconciling the payment within your systems.
Within the lifecycle of Direct Debit collections, payments are assumed successful unless a subsequent notification of failure. Consequently, all collections will be transitioned from submitted
to success
status.
{
"webhook_type": "collection_success",
"webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
"timestamp": 32908394083,
"webhook_body": {
"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
"status": "success",
"order_id": "12345"
},
"links": [
{
"rel": "self",
"href": "/v1/transactions/29c05255-8905-f38f-1446-03f83de52d7c"
},
{
"rel": "mandate",
"href": "/v1/mandates/3a7fc149-3d6c-496e-808b-688dfb65bc77"
},
{
"rel": "customer",
"href": "/v1/customer/952930b3-e2c6-43a9-b9d5-a9bdcb588df5"
}
]
}
collection_declined
webhook
collection_declined
webhookOnce a collection transitions to the success
status, there is the potential for Acquired to receive notified that the payment has, in fact, failed. The occurrence of this event is confirmed through the collection_declined
webhook type, where the status
will be marked as declined
.
This event’s detail object includes the reason_code
and reason_description
for the failure, facilitating an understanding of the cause. For a comprehensive list of possible values, please refer to the ARUDD report of the Bacs reason code guide.
This webhook event will also incorporate the is_retryable
boolean value, indicating whether the payment can be retried. The value is set to true
when the reason
value equals insufficient_funds
. For other reasons, the boolean value will be set to false
.
For more information on retrying declined collections, please refer to this guide.
{
"webhook_type": "collection_declined",
"webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
"timestamp": 32908394083,
"webhook_body": {
"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
"status": "declined",
"reason": "insufficient_funds",
"order_id": "12345",
"detail": {
"scheme": "bacs",
"report": "ARUDD",
"reason_code": "0",
"reason_description": "Refer to payer"
},
"is_retryable": true
},
"links": [
{
"rel": "self",
"href": "/v1/transactions/29c05255-8905-f38f-1446-03f83de52d7c"
},
{
"rel": "mandate",
"href": "/v1/mandates/c26bf223-afd3-4a4b-9c3e-b375bf38c917"
},
{
"rel": "customer",
"href": "/v1/customer/2e794e1f-6021-4058-a331-a3e12595e214"
}
]
}
Updated 29 days ago