Mandate Webhooks

Set up webhooks to get real-time updates on mandate events.

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.

For more information on webhook structure and how to validate the integrity of a webhook, please refer to our webhook notifications guide.

📘

Note

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.

Webhook parameters

The mandate webhook body may contain the following parameters:

FieldTypeDescription
webhook_typestringDescribes the type of event: mandate_active mandate_rejected mandate_cancelled
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
mandate_idstringUUID assigned by Acquired.com for the mandate.
statusstringThe status of the mandate: active rejected cancelled
detailJSON objectHolds additional details about the Direct Debit mandate.
schemestringSpecifies the scheme or system used for the Direct Debit: bacs
reportstringRefers to the associated report type: ADDACS AUDDIS
reason_codestringThe reason code defined by BACS explains the cause of the event.
reason_descriptionstringProvides an easily understandable description of the reason_code

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