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
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"
}
}
}
Updated 13 days ago
Did this page help you?