Payment webhook specifications

Payment notifications sent to your webhook URI registered in the console, when a payment succeeds, fails, or settles.

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:

FieldTypeDescription
typestringType of the event ("payment_authorized")
event_idstringA UUID for the event
event_versionstringThe version of the event schema
payment_idstringThe unique ID for the payment
authorized_atdatetimeAn RFC-3339 timestamp of when the payment was authorized
{
  "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_executed

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

FieldTypeDescription
typestringType of the event ("payment_executed")
event_idstringA UUID for the event
event_versionstringThe version of the event schema
payment_idstringThe unique ID for the payment
payment_methodjson objectMethod 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_atdatetimeAn RFC-3339 timestamp of when the payment was executed
settlement_risk.categorystringThe payment's settlement risk-rating. Only available for closed-loop EUR payments in Private Beta and subject to change. Will be one of "low_risk", "high_risk"
{
  "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"
  }
}

payment_failed

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

FieldTypeDescription
typestringType of the event ("payment_failed")
event_idstringA UUID for the event
event_versionstringThe version of the event schema
payment_idstringThe unique ID for the payment
payment_methodjson objectMethod 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_atdatetimeAn RFC-3339 timestamp of when the payment failed
failure_stagestringAn enum identifying where the payment failed in it's lifecycle. Can be one of "authorization_required", "authorizing", "authorized"
failure_reasonstringThe reason the payment failed. Read more about failure reasons.
{
  "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_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:

FieldTypeDescription
typestringType of the event ("payment_settled")
event_idstringA UUID for the event
event_versionstringThe version of the event schema
payment_idstringThe unique ID for the payment
payment_methodjson objectMethod 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_atdatetimeAn RFC-3339 timestamp of when the payment was settled
settlement_risk.categorystringThe payment's settlement risk-rating. Only available for closed-loop EUR payments in Private Beta and subject to change. Will be one of "low_risk", "high_risk"
payment_sourcejson objectSource of the payment for which the event is being sent. Read more about payment sources
{
  "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'll get the external_payment_received notification when a payment, made using a payment method not offered by TrueLayer, to a merchant account has settled in that merchant account. The following table includes the fields that appear in the notification body:

FieldTypeDescription
typestringType of the event ("external_payment_received")
event_idstringA UUID for the event
event_versionstringThe version of the event schema
transaction_idstringThe unique ID for the transaction
currencystringThe currency of the payment
amount_in_minorstringThe amount of the payment
settled_atdatetimeAn RFC-3339 timestamp of when the payment was settled
merchant_account_idstringThe unique ID for the Merchant Account
remitter.account_holder_namestringThe remitter information of the payment
remitter.account_identifierstringThe remitter account identifier 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_identifier": {
      "type": "sort_code_account_number",
      "sort_code": "string",
      "account_number": "string"
    }
  }
}