Payments API webhook reference

Webhooks are JSON-format notifications you receive when any event occurs within the Payments API v3. You can use these to trigger processes within your backend or integration. This is especially useful for asynchronous events, such as a user authorising a payment.

In order to receive webhooks, you must specify a Webhook URI for them to be sent to on the Settings page in Console.

What webhooks can tell you

We recommend that you use webhooks in all integrations. They inform you when events take place within a payment's lifecycle, including when a payment, mandate, payout or refund transitions between statuses. For example, webhooks inform you about:

when a payment changes to a new status in the authorisation process
whether a payment has succeeded or failed
more details about why and when a payment failed
when your merchant account is approaching or below a certain amount of funds, and when it has just been topped up
when you can consider a payment to be creditable, even if it hasn't settled
when the settlement of a payment has stalled for a defined period of time

When we add new webhooks, they are added to the list on this page, in the relevant webhook documentation, and also the API reference.

Webhook categories

There are a variety of webhooks, split into categories for each type of payment. Click a category to see a full list of webhooks for that payment type with examples. Alternatively, see the table on this page that contains a full list of possible webhooks.

Payment webhooks

Payment webhooks apply to all payments, including:

pay-ins to your merchant account (closed-loop payments)
payments to an external account (open-loop payments)
payments on a mandate

There are a variety of payment webhooks, which you receive when a payment transitions to each possible status. Additionally, there are extra webhooks you receive that confirm when a payment is creditable, when a payment has stalled, or when you receive a payment from an external account.

Payout webhooks

There are only two webhooks for payouts, payout_executed and payout_failed. However, the content of these webhooks varies based on the type of payout, which can be:

a payout to a source that paid in (closed-loop payout)
a payout to an external account (open-loop payout)
a payout to the business account linked to your merchant account

As such, there are six possible webhook formats for payouts.

Refund webhooks

You receive two webhooks for refunds, one when a refund is executed, or one when a refund fails.

Mandate webhooks

Mandate webhooks relate specifically to payment mandates, which determine the constraints that apply to a mandate, and whether it is currently authorised and valid.

For variable recurring payments made over a mandate, you receive payment webhooks with a payment_method.type of mandate.

Merchant account webhooks

Merchant account webhooks apply specifically to your merchant account and their associated client_id.

There is currently one merchant account webhook, which informs you when your merchant account balance is approaching a value you specify with us.

Payment link webhooks

There are two webhooks for payment links. One that tells you when a payment is created by a user through a payment link, and one that tells you when a payment link expires.

Notably, the payment_linked_payment_created webhook contains a payment id. You should use that payment id to track the progress of the payment through payment webhooks.

Possible webhooks

The Payments API v3 currently supports the following webhooks. Click a webhook to see more information about it within the appropriate area of the documentation.

Webhook	Description
`payment_authorized`	The payment was authorised by the user with their bank.
`payment_executed`	The payment was executed.
`payment_failed`	The payment failed.
`payment_settled`	The payment has settled.
`payment_creditable`	You can consider the payment to have settled.
`payment_settlement_stalled`	The payment did not reach settled status after a specified amount of time.
`external_payment_received`	The external payment has settled.
`mandate_authorized`	The mandate was authorized.
`mandate_failed`	The mandate creation failed.
`mandate_revoked`	The mandate was revoked.
`payment_link_payment_created`	A payment was created through a payment link.
`payment_link_disabled`	The payment link was disabled.
`payout_executed`	The payout was executed. Notification structure differs between closed-loop, open-loop or business account payouts.
`payout_failed`	The payout failed. Notification structure differs between closed-loop, open-loop or business account payouts.
`refund_executed`	The refund was executed.
`refund_failed`	The refund failed.
`balance_notification`	An update on when a merchant account balance hits 100%, 150% or 200% of a specified threshold.

Webhook structure

All our webhooks include the following two headers:

Field	Type	Description
`X-TL-Webhook-Timestamp`	ISO-8601 Timestamp	Time that the webhook was sent to you. This is in this 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 their signatures verified, otherwise you risk accepting fraudulent payment status events. Learn more about how to validate received webhook signatures.

All webhook bodies are encoded in JSON format with the following fields:

Field	Type	Description
`type`	string	The type of the webhook. This can be any of the Payments API webhooks.
`event_id`	string	A UUID for the webhook event.
`event_version`	string	The version of the webhook event. Currently, this can only have a value of 1.

However, each type of event contains other fields. See the documentation for different categories of webhook for more information and examples.

Handling duplicated webhooks

TrueLayer can't guarantee that you’ll only receive a single webhook notification for any one event. As such, your integration should have logic that can handle receiving multiple webhooks for a given event.

For example, imagine TrueLayer sends a payment_executed webhook, but doesn't receive a 200 response due to network issues from the recipient. In this case, TrueLayer sends an extra payment_executed webhook as it can't confirm the previous one was received, regardless of the current status of the payment. The recipient's integration should be able to hand such possibilities.

We ensure that the event_id is the same for duplicated webhooks, but you should check the payment_id or payout_id as well.