Mandate Webhooks

Overview

Acquired will dispatch webhook events to your server, notifying you of events related to your mandates. This guide aims to give you a comprehensive overview of the pivotal events associated with mandates which you should be mindful of.

Please refer to our guide containing all of the potential Bacs reason_code and reason_description from ARUDD, DDIC, AUDDIS and ADDACS reports for further information.

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 offer real-time data, it's important to acknowledge that they may occasionally falter or be missed by end-users. Therefore, it's advisable to also utilise the GET endpoint for retrieving updates on mandates to ensure reliable data retrieval.

Webhook parameters

The mandate webhook body may contain the following parameters:

mandate_active webhook

Upon a mandate being created, there is a waiting period for submission to the bank and setup completion, typically taking a few days. The activation of the mandate and successful completion of this process and confirmed via the mandate active webhook notification.

{
    "webhook_type": "mandate_active",
    "webhook_id": "7dd4b51a-19f0-4baa-844a-ec4d30d09ae8",
    "timestamp": 32908394083,
    "webhook_body": {
        "mandate_id": "ece28804-338f-4434-97e5-760c96620394",
        "status": "active"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/mandates/1d0483a7-6f84-4784-9fba-3c7553847be0"
        },
        {
            "rel": "customer",
            "href": "/v1/customers/49bd2d4e-7ae3-4c99-bfd3-32599b79ff11"
        }
    ]
}

mandate_rejected webhook

In specific instances, the mandate setup process may fail, such as when the customer's bank account does not support Direct Debit or if the bank account has been closed. In such cases, the mandate status will be marked as rejected, and Acquired will generate a mandate_rejected webhook notification to inform your systems of this development.

In the event of a failure, you should consider contacting the customer and suggesting that they try again with a different bank account or make an alternative payment arrangement.

For insights into the reason behind the failure, refer to the reason_code and reason_description values. You can access a comprehensive list of potential values by referring to the AUDDIS report table in our Bacs reason code guide.

The webhook event also includes the customer resource associated with the mandate. You can utilise the provided link to retrieve and access the details stored for that specific customer.

{
    "webhook_type": "mandate_rejected",
    "webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
    "timestamp": 32908394083,
    "webhook_body": {
        "mandate_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
        "status": "rejected"
    },
    "detail": {
        "scheme": "bacs",
        "report": "AUDDIS",
        "reason_code": "3",
        "reason_description": "Account Transferred"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/mandates/1d0483a7-6f84-4784-9fba-3c7553847be0"
        },
        {
            "rel": "customer",
            "href": "/v1/customers/d47690d4-6a43-4c82-913b-48dd7fab8a66"
        }
    ]
}

mandate_cancelled webhook

Mandates are flexible and can be cancelled at any time. For example, end customers can cancel mandates by contacting their bank. In such cases, you will receive a mandate_cancelled webhook type.

Upon mandate cancellation, consider appropriate actions within your response. For instance, you may want to:

• Deactivate the end customer’s access to the provided service
• Contact the end customer to inform them that further payments will not be collected until a new mandate is established

The event’s detail object includes a reason_code and reason_description, aiding in understanding the cause of the mandate cancellation. Refer to the Bacs reason code guide for a comprehensive list of possible values.

The webhook event also includes the customer resource associated with the mandate. You can utilise the provided link to retrieve and access the details stored for that specific customer.

{
    "webhook_type": "mandate_cancelled",
    "webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
    "timestamp": 32908394083,
    "webhook_body": {
        "mandate_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
        "status": "cancelled"
    },
    "detail": {
        "scheme": "bacs",
        "report": "ADDACS",
        "reason_code": "B",
        "reason_description": "Account closed"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/mandates/1d0483a7-6f84-4784-9fba-3c7553847be0"
        },
        {
            "rel": "customer",
            "href": "/v1/customers/a30e1510-585c-4de8-b74d-0e6d9efc7665"
        }
    ]
}