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.

Webhook parameters

The collection webhook body may contain the following parameters:

FieldTypeDescription
webhook_typestringDescribes the type of event: collection_submitted collection_success collection_declined
webhook_idstringUUID assigned by Acquired.com for the notification.
timestampintegerExact date of when the webhook was delivered in UNIX timestamp format.
webhook_bodyJSON objectN/A
transaction_idstringUUID assigned by Acquired.com for the transaction.
statusstringThe status of the collection: submitted success declined
reasonstringProvides further information relating to a declined transaction.
order_idstringThe order ID value that was passed by you in the payment request.
detailJSON objectHolds additional details about the Direct Debit event.
schemestringSpecifies the scheme or system used for the Direct Debit: bacs
reportstringRefers to the associated report type: ARUDD
reason_codestringThe reason code detailing the reason for the decline.
reason_descriptionstringProvides a description explaining the reason_code, such as "Account closed".
is_retryablebooleanSet 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

Direct 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

Following 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

Once 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": "Insufficient Funds"
        },
        "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"
        }
    ]
}