Collection Webhooks

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:

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": "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"
        }
    ]
}