Payment webhook specifications

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

payment_executed

Notification that a payment has been executed

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

Notification that a payment has failed

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.
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. Example values to expect: "authorization_failed", "rejected", "provider_error", "provider_rejected", "internal_server_error", "canceled", "expired". Implementations should expect other values, since there may be more failure reasons added in future
{
  "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

Notification that a payment has settled (only available when using closed-loop payments)

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.
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

Notification that a payment made from a non-TrueLayer payment method to a Merchant Account has settled in that Merchant Account.

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"
    }
  }
}

Did this page help you?