Payment webhook specifications

payment_executed

Notification that a payment has been executed

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

Notification that a payment has failed

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

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

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

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