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	Description
`type`	string	Type of the event (`"payment_authorized"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`payment_id`	string	The unique ID for the payment
`authorized_at`	datetime	An 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:

Field	Type	Description
`type`	string	Type of the event (`"payment_executed"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`payment_id`	string	The unique ID for the payment
`payment_method`	json object	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	An RFC-3339 timestamp of when the payment was executed
`settlement_risk.category`	string	The 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:

Field	Type	Description
`type`	string	Type of the event (`"payment_failed"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`payment_id`	string	The unique ID for the payment
`payment_method`	json object	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	An RFC-3339 timestamp of when the payment failed
`failure_stage`	string	An enum identifying where the payment failed in it's lifecycle. Can be one of `"authorization_required"`, `"authorizing"`, `"authorized"`
`failure_reason`	string	The 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:

Field	Type	Description
`type`	string	Type of the event (`"payment_settled"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`payment_id`	string	The unique ID for the payment
`payment_method`	json object	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	An RFC-3339 timestamp of when the payment was settled
`settlement_risk.category`	string	The 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_source`	json object	Source 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:

Field	Type	Description
`type`	string	Type of the event (`"external_payment_received"`)
`event_id`	string	A UUID for the event
`event_version`	string	The version of the event schema
`transaction_id`	string	The unique ID for the transaction
`currency`	string	The currency of the payment
`amount_in_minor`	string	The amount of the payment
`settled_at`	datetime	An RFC-3339 timestamp of when the payment was settled
`merchant_account_id`	string	The unique ID for the Merchant Account
`remitter.account_holder_name`	string	The remitter information of the payment
`remitter.account_identifier`	string	The 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"
    }
  }
}