---
title: "Mandate webhooks"
method: POST
path: "mandates"
tags: ["Mandates"]
---

# Mandate webhooks

`POST mandates` (webhook)

Sent to the webhook URI you registered in Console when a mandate becomes authorized, fails, or is revoked.

## Headers

- `Tl-Signature` string, required

## Payload

- union
  - WebhookMandateAuthorized
    - `type` 'mandate_authorized', required
    - `event_version` 1, required: The version of the event schema.
    - `event_id` string, required: Unique ID of the event.
    - `mandate_id` string, required: Unique ID for the mandate
    - `authorized_at` string, datetime, required: Date and time the mandate became authorized
    - `statement_reference` string, required: Statement reference for the mandate
    - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.
  - WebhookMandateFailed
    - `type` 'mandate_failed', required
    - `event_version` 1, required: The version of the event schema.
    - `event_id` string, required: Unique ID of the event.
    - `mandate_id` string, required: Unique ID for the mandate
    - `failed_at` string, datetime, required: Date and time the mandate failed
    - `failure_stage` 'authorization_required' | 'authorized' | 'authorizing' | 'revoked', required: The status the mandate was in when it failed.
    - `failure_reason` string, required: A readable detail for why the mandate failed. Example values to expect: - `authorization_failed` - `provider_error` - `provider_rejected` - `internal_server_error` - `invalid_sort_code` - `invalid_request` - `expired` - `unknown_error`
    - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.
  - WebhookMandateRevoked
    - `type` 'mandate_revoked', required
    - `event_version` 1, required: The version of the event schema.
    - `event_id` string, required: Unique ID of the event.
    - `mandate_id` string, required: Unique ID for the mandate
    - `revoked_at` string, datetime, required: Date and time the mandate became revoked
    - `revocation_source` 'client' | 'provider', required: Source for the revocation
    - `revocation_reason` string: The reason why the mandate was revoked. This is currently only available for direct debit mandates.
    - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.
  - WebhookMandateRemitterChanged
    - `type` 'mandate_remitter_changed', required
    - `event_version` 1, required: The version of the event schema.
    - `event_id` string, required: Unique ID of the event.
    - `mandate_id` string, required: Unique ID for the mandate
    - `remitter_changed_at` string, datetime, required: Date and time the remitter details of the mandate were changed.
    - `account_holder_name` string, required: The name associated to the new remitter account.
    - `account_identifier` union, required: A unique account identifier for an external account.
      - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes.
        - `type` 'sort_code_account_number', required: The type of scheme identifier.
        - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$`
        - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$`
      - AccountIdentifierIban: The international bank account number.
        - `type` 'iban', required: The type of scheme identifier.
        - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$`
      - AccountIdentifierBban: Basic bank account number.
        - `type` 'bban', required: The type of scheme identifier.
        - `bban` string, required: Valid Basic Bank Account Number (no spaces). Consists of up to 30 alphanumeric characters, with a fixed length per country. Forms the latter part of the IBAN as described above.
      - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes.
        - `type` 'nrb', required: The type of scheme identifier.
        - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed.
    - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.
  - WebhookMandateInitialPaymentCreated
    - `type` 'mandate_initial_payment_created', required
    - `event_version` 1, required: The version of the event schema.
    - `event_id` string, required: Unique ID of the event.
    - `mandate_id` string, required: Unique ID for the mandate
    - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.
    - `payment` MandateInitialPayment, required
      - `id` string, required: Unique ID of the payment
      - `created_at` string, datetime, required: Date and time the payment was created

## Acknowledgement `200`

Webhook Handled

---

[API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)