Mandate webhooks
Notifications sent to your webhook URI registered in the Console, when a mandate becomes authorized, fails, or is revoked.
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"
}
}
Updated about 2 months ago