Mandate webhooks

Below are the webhook types that you can receive as a mandate moves through its lifecycle.

Configure the URI where you receive webhooks in Console.

All our webhooks include these headers:

Field	Type	Description
`X-TL-Webhook-Timestamp`	ISO-8601 Timestamp	Time that the webhook was sent to you. This will be in the following format: 2020-05-18T10:17:47Z.
`TL-Signature`	string	JSON web signature with a detached payload of the form {HEADER}..{SIGNATURE} All incoming webhook requests must have verified signatures, or you risk accepting fraudulent payment status events.

Webhook bodies are encoded in JSON format with the following fields:

Field	Type	Description
`type`	string	Event type
`event_id`	string	A UUID for the event
`event_version`	string	Version of the event type

Webhooks may include additional fields. See the specific event webhook for more information.

mandate_authorized

The mandate_authorized webhook tells you when a user authorises a mandate.

Field	Type	Description
`type`	string	Type of the event (`"mandate_authorized"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`mandate_id`	string	The unique ID for the mandate
`authorized_at`	datetime	An RFC-3339 timestamp of when the mandate was authorized
`metadata`	object	Custom key-value data supplied during mandate creation

{
  "type": "mandate_authorized",
  "event_version": 1,
  "authorized_at": "2021-12-25T15:00:00.000Z"
}

mandate_failed

The mandate_failed webhook tells you when a mandate failed and why.

Field	Type	Description
`type`	string	Type of the event (`"mandate_failed"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`mandate_id`	string	The unique ID for the mandate
`failed_at`	datetime	An RFC-3339 timestamp of when the mandate failed to be authorized
`failure_stage`	string	An enum identifying where the mandate failed in it's lifecycle. Can be one of `"authorization_required"`, `"authorizing"`, `"authorized"`
`failure_reason`	string	The reason the payment failed. Example values to expect: `"authorization_failed"`, `"provider_error"`, `"provider_rejected"`, `"internal_server_error"`, `"invalid_sort_code"`, `"invalid_request"`, `"unknown_error"`. Implementations should expect other values, since there may be more failure reasons added in future
`metadata`	object	Custom key-value data supplied during mandate creation

{
  "type": "mandate_failed",
  "event_version": 1,
  "failure_stage": "authorization_required"
}

mandate_revoked

You receive the mandate_revoked when you or a banking provider revoke a mandate.

Field	Type	Description
`type`	string	Type of the event (`"mandate_revoked"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`mandate_id`	string	The unique ID for the mandate
`revoked_at`	datetime	An RFC-3339 timestamp of when the mandate was revoked
`revocation_source`	string	An enum identifying who revoked the mandate. Can be one of `"client"`, `"provider"`
`metadata`	object	Custom key-value data supplied during mandate creation

{
  "type": "mandate_revoked",
  "event_version": 1,
  "revocation_source": "client"
}

mandate_remitter_changed

🚧
This webhook is only available for direct debits, which are in development. Contact us to learn more.

The mandate_remitter_changed webhook is for direct debit integrations.

This webhook tells you when the remitter bank account for a mandate has changed. This could apply when the user changes their bank account, for example through the Current account switch guarantee.

Field	Type	Description
`type`	string	Type of the event (`"mandate_remitter_changed"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`mandate_id`	string	The unique ID for the mandate
`remitter_changed_at`	datetime	An RFC-3339 timestamp of when the mandate's remitter changed
`account_holder_name`	string	The name associated with the new remitter account
`account_identifier`	object	The account identifier for the new remitter account, typically their SCAN
`metadata`	object	Custom key-value data supplied during mandate creation

{
  "type": "mandate_remitter_changed",
  "event_version": 1,
  "account_identifier": {
    "type": "sort_code_account_number"
  }
}