Payment webhook specifications

payment_authorized

📘
This webhook is optional, and is disabled by default. It is particularly useful in geographies where banks can take a long time to notify that payments have been executed. Contact us if you would like this webhook to be enabled.

The following table includes the fields that appear in the payment_authorized notification:

Field	Type	Optional	Description
`type`	string	No	Type of the event (`"payment_authorized"`)
`event_id`	string	No	A UUID for the event
`event_version`	string	No	The version of the event schema
`payment_id`	string	No	The unique ID for the payment
`metadata`	object	Yes	A set of key-value pairs of custom data that was provided when the payment was created
`authorized_at`	datetime	No	An RFC-3339 timestamp of when the payment was authorized
`payment_source`	object	Yes	Information about the source account of the payment, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

{
  "type": "payment_authorized",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "authorized_at": "2021-12-25T15:00:00.000Z",
  "payment_source": {
    "account_holder_name": "HOLDER NAME",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "111111",
        "account_number": "00000111"
      }
    ]
  }
}

payment_executed

The following table includes the fields that appear in the payment_executed notification:

Field	Type	Optional	Description
`type`	string	No	Type of the event (`"payment_executed"`)
`event_id`	string	No	A UUID for the event
`event_version`	string	No	The version of the event schema
`payment_id`	string	No	The unique ID for the payment
`metadata`	object	Yes	A set of key-value pairs of custom data that was provided when the payment was created
`payment_method`	object	No	Method of the payment. type can be `"mandate"` or `"bank_transfer"`.Mandates contain `mandate_id` and bank transfers contain `provider_id` and `scheme_id`, if available.
`executed_at`	datetime	No	An RFC-3339 timestamp of when the payment was executed
`settlement_risk`	object	Yes	The payment's settlement risk rating. Only available for EUR closed-loop payouts in Private Beta. Subject to change Contains a single value, `category`, which will be one of `"low_risk"` or `"high_risk"` If `low_risk`, you can immediately consider the payment complete. If `high_risk`, wait until you receive a `payment_settled` webhook before considering the payment complete
`payment_source`	object	Yes	Information about the source account of the payment, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

{
  "type": "payment_executed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "mock-payments-gb-redirect",
    "scheme_id": "faster_payments_service"
  },
  "settlement_risk":
  {
    "category": "low_risk"
  },
  "payment_source": {
    "account_holder_name": "HOLDER NAME",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "111111",
        "account_number": "00000111"
      }
    ]
  }
}

payment_failed

The following table includes the fields that appear in the payment_failed notification:

Field	Type	Optional	Description
`type`	string	No	Type of the event (`"payment_failed"`)
`event_id`	string	No	A UUID for the event
`event_version`	string	No	The version of the event schema
`payment_id`	string	No	The unique ID for the payment
`metadata`	object	Yes	A set of key-value pairs of custom data that was provided when the payment was created
`payment_method`	object	No	Method of the payment. type can be `"mandate"` or `"bank_transfer"`.Mandates contain `mandate_id` and bank transfers contain `provider_id` and `scheme_id`, if available.
`failed_at`	datetime	No	An RFC-3339 timestamp of when the payment failed
`failure_stage`	string	No	An enum identifying where the payment failed in it's lifecycle. Can be one of `"authorization_required"`, `"authorizing"`, `"authorized"`
`failure_reason`	string	No	The reason the payment failed. Read more about failure reasons.
`payment_source`	object	Yes	Information about the source account of the payment, if available from the remitter's bank. The account identifiers available will be those provided by the bank. This field is optional.

{
  "type": "payment_failed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_stage": "authorizing",
  "failure_reason": "provider_rejected",
  "payment_method": {
    "type": "mandate",
    "mandate_id": "d65f3521-fa55-44fc-9a75-ba43456de7f2",
  },
  "payment_source": {
    "account_holder_name": "HOLDER NAME",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "111111",
        "account_number": "00000111"
      }
    ]
  }
}

payment_settled

The following table includes the fields that appear in the payment_settled notification. Note that this webhook is only available when using closed-loop payments:

Field	Type	Optional	Description
`type`	string	No	Type of the event (`"payment_settled"`)
`event_id`	string	No	A UUID for the event
`event_version`	string	No	The version of the event schema
`payment_id`	string	No	The unique ID for the payment
`metadata`	object	Yes	A set of key-value pairs of custom data that was provided when the payment was created
`payment_method`	object	No	Method of the payment. type can be `"mandate"` or `"bank_transfer"`. Mandates contain `mandate_id` and bank transfers contain `provider_id` and `scheme_id`, if available.
`settled_at`	datetime	No	An RFC-3339 timestamp of when the payment was settled
`settlement_risk`	object	Yes	The payment's settlement risk-rating. Only available for closed-loop EUR payments in Private Beta and subject to change. Contains a single value, `category`, which will be one of `"low_risk"`, `"high_risk"`
`payment_source`	object	No	Source of the payment for which the event is being sent. This object contains a `id` for the settled payment's source, which can be used in closed-loop payouts. Read more about payment sources
`user_id`	string	No	The user id for this payment, which can be used in closed-loop payouts. This is the same value received in the create payment response.

{
  "type": "payment_settled",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "settled_at": "2021-12-25T15:00:00.000Z",
  "payment_source": {
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "111111",
        "account_number": "00000111"
      },
      {
        "type": "iban",
        "iban": "GB11CLRB01011100000111"
      }
    ],
    "id": "1f111d3c-9427-43be-1111-1111219d111c",
    "account_holder_name": "HOLDER NAME"
  },
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "mock-payments-gb-redirect",
    "scheme_id": "faster_payments_service"
  },
  "user_id": "ec01ece1-1dbe-48f1-82b2-bce8cfa44d08"
}

external_payment_received

You receive the external_payment_received webhook notification when a payment made using a payment method not offered by TrueLayer settles in your merchant account. This table includes the fields that appear in the notification body:

Field	Type	Optional	Description
`type`	string	No	Type of the event (`"external_payment_received"`)
`event_id`	string	No	A UUID for the event
`event_version`	string	No	The version of the event schema
`transaction_id`	string	No	The unique ID for the transaction
`currency`	string	No	The currency of the payment
`amount_in_minor`	string	No	The amount of the payment
`settled_at`	datetime	No	An RFC-3339 timestamp of when the payment was settled
`merchant_account_id`	string	No	The unique ID for the Merchant Account
`remitter.account_holder_name`	string	No	The remitter information of the payment
`remitter.account_identifiers`	array	No	The remitter account identifiers of the payment. We support the following identifiers: `sort_code_account_number`, `iban`, `bban`, `nrb`

{
  {
  "type": "external_payment_received",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "transaction_id": "string",
  "currency": "GBP",
  "amount_in_minor": 1,
  "settled_at": "2021-12-25T15:00:00.000Z",
  "merchant_account_id": "string",
  "remitter": {
    "account_holder_name": "string",
    "account_identifiers": [{
      "type": "sort_code_account_number",
      "sort_code": "string",
      "account_number": "string"
    },
    {
      "type": "iban",
      "iban": "string"
    }]
  }
}

How to handle external_payment_received webhooks

Typically, you receive the external_payment_received webhook notification in the following scenarios:

When an existing user pays into your merchant account again using saved SCAN/IBAN details.
For example, through a Send again button in their banking app.
When you fund your merchant account from a corporate bank account through your SCAN/IBAN details.
When a new and unknown user pays into your account using your merchant account's SCAN/IBAN details.

Out of the above payment scenarios, you likely only want to keep the payments from an existing user or your corporate bank account, not from an unknown account. You can create an allow list that defines the bank details you want to receive payments from.

📘
Payments that return the external_payment_received webhook are tagged as External Deposit in Console.

If you're receiving external_payment_received payments, you could flag them internally for manual review. Alternatively, you could handle these payments automatically by returning funds to the user as a payout. You can populate the payout instantly using the information in the external_payment_received webhook, or through the /transactions endpoint.