To receive notifications about payment or mandate statuses, set up webhooks. You configure the URI endpoint for webhooks in Console.
|The payment was authorised.||docs|
|The payment was executed.||docs|
|The payment failed.||docs|
|The payment was settled.||docs|
|The external payment has settled.||docs|
|The mandate was authorized.||docs|
|The mandate creation failed.||docs|
|The mandate was revoked.||docs|
|A payment was created through a payment link.||docs|
|The payment link was disabled.||docs|
|The payout was executed. Notification structure differs between closed-loop, open-loop or business account payouts.||docs|
|The payout failed. Notification structure differs between closed-loop, open-loop or business account payouts.||docs|
|The refund was executed.||docs|
|The refund failed.||docs|
All our webhooks include these headers:
|ISO-8601 Timestamp||Time that the webhook was sent to you. This will be in the following format: |
|string||JSON web signature with a detached payload of the form |
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:
|string||Type of the event|
|string||A UUID for the event|
|string||Version of the event type|
All incoming webhook requests must be verified via signature, or you risk accepting fraudulent payment status events.
TrueLayer signing libraries
For the best development experience, we recommend that developers use our signing libraries to verify the
Tl-Signatureof the webhooks they receive.
Verifier.verifyWithJwks(jwks) .method("POST") .path(path) .headers(allWebhookHeaders) .body(body) .verify(webhookSignature);
For a full reference to our signing requirements, refer to our request signing docs on Github.
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 this retry policy for payments, payment links, payment refunds, payouts, and mandates.
TrueLayer can't guarantee that you only receive a single webhook notification for each payment status. As such, your integration should have logic that can handle receiving multiple webhooks for a given payment status.
For example, imagine TrueLayer sends an
executed webhook, but doesn't receive a 200 response due to network issues from the recipient. In this case, TrueLayer sends an extra
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 handle such possibilities.
Updated about 1 month ago