Console

Webhook notifications for Payments v3

Set up webhooks to get updates on payments or mandates in our Payments API v3.

Suggest Edits

You can register to receive notifications about your payment or mandate statuses via webhooks. Configure the URI endpoint for webhooks in Console.

Currently supported notifications

TypeNotification descriptionSpecification
payment_authorizedThe payment was authorized.docs
payment_executedThe payment was executed.docs
payment_failedThe payment failed.docs
payment_settledThe payment was settled.docs
external_payment_receivedThe external payment has settled.docs
mandate_authorizedThe mandate was authorized.docs
mandate_failedThe mandate creation failed.docs
mandate_revokedThe mandate was revoked.docs
payout_executedThe payout was executed. Notification structure differs between closed-loop, open-loop or business account payouts.docs
payout_failedThe payout failed. Notification structure differs between closed-loop, open-loop or business account payouts.docs
refund_executedThe refund was executed.docs
refund_failedThe refund failed.docs

Webhook structure

All our webhooks are sent with the following headers:

FieldTypeDescription
X-TL-Webhook-TimestampISO-8601 TimestampTime that the webhook was sent to you. This will be in the following format: 2020-05-18T10:17:47Z.
TL-SignaturestringJSON 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. See Validate the received webhook signature.

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

FieldTypeDescription
typestringType of the event
event_idstringA UUID for the event
event_versionstringVersion of the event type

Each type of event may provide other fields. See the the specifications of the mandate or payment webhooks for more details.

Webhook retry policy

We consider a webhook successfully delivered when we receive a success status code (2xx) from your webhook URI.

If we receive any other status code (for instance, if your API is temporarily unavailable), we will start retrying. Our retry policy is jittered exponential backoff. We will immediately perform some fast retries and then start waiting increasingly longer. We will keep retrying for up to 72 hours. If we continue to receive any other status codes than 2xx after retrying for 72 hours, we will discard the webhook.

We apply the above retry policy for payments, payment refunds, payouts, and mandates.

Validate the received webhook signature

We recommend that developers use our signing libraries to verify the Tl-Signature of the received webhooks.

E.g. Java com.truelayer.truelayer-signing

Verifier.verifyWithJwks(jwks)
        .method("POST")
        .path(path)
        .headers(allWebhookHeaders)
        .body(body)
        .verify(webhookSignature);

📘

For the best development experience, use our signing libraries to verify signatures.

Verifying the signature manually

For a full reference to our signing requirements, refer to our request signing docs on Github

Updated 2 months ago