Get data about a payment

Learn how to get information about an individual payment, including its status.

If you want to learn more about an individual payment, make a GET request to the /payments/{id} endpoint with the payment id as the path parameter.

Use this alongside webhooks and the merchant account dashboard to monitor the status of payments as they move through their lifecycle.

This request also gives you additional data about a payment, including:

  • the amount paid
  • the currency that your user paid with
  • the method that your user used to pay
  • information about provider selection
  • the scheme that the user paid with
  • the user id (we generate a new one if this is the first time your user has paid you)
  • the beneficiary type, account holder name and (if a merchant account) id
  • the time the payment was created at
  • the reason why the payment failed, if it failed

You may also receive other information. Depending on the payment status, and whether you supplied certain data when you created the payment, the response is different. See below for more on possible responses.

Before you start

To make a GET request to the /v3/payments/{id} endpoint, you need:

Request parameters

Make a GET request to the following endpoint:

Live endpointSandbox endpoint
https://api.truelayer.com/v3/payments/{id}https://api.truelayer-sandbox.com/v3/payments/{id}

Substitute {id} with the payment id as a path parameter:

Path parameterParameter typeDescription
Payment idstringThe UUID associated with an individual payment.

GET Payment responses

Below are the responses you receive, depending on the status of the payment.

authorization_required

The first status of any payment, indicating that the user needs to authorise the payment with their provider.

FieldDescription
idThe ID of the payment.
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
user object, containing user.idThe ID that refers to an individual paying user. If this is the first time your user is paying you, we automatically generate a new one.
payment_methodCan be bank_transfer or mandate.

If bank_transfer, this includes:
- type
- provider_selection object
- scheme_selection object
- beneficiary (merchant account or external account)

If mandate, this includes:
- type
- mandate_id
- reference
- retry information (if you have enabled this)
created_atAn RFC-3339 timestamp of when the payment was created.
metadataAny metadata that you set during payment creation.
statusauthorization_required
{
  "id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "amount_in_minor": 0,
  "currency": "GBP",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": [
          "GB"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ],
        "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "string",
      "account_holder_name": "string"
    }
  },
  "created_at": "string",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "status": "authorization_required"
}

authorizing

This status indicates that the user is in the process of authorising a payment with their provider.

FieldDescription
idThe ID of the payment
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
user object, containing user.idThe ID that refers to an individual paying user. If this is the first time your user is paying you, we automatically generate a new one.
payment_methodCan be bank_transfer or mandate.

If bank_transfer, this includes:
- type
- provider_selection object
- scheme_selection object
- beneficiary (merchant account or external account)

If mandate, this includes:
- type
- mandate_id
- reference
- retry information (if you have enabled this)
created_atAn RFC-3339 timestamp of when the payment was created.
metadataAny metadata that you set during payment creation.
statusauthorizing
authorization_flowInformation about the authorisation flow. Contains:
- configuration, which indicates any filters that you set for provider selection and redirects
- actions, which indicates what the next action is for that payment.
{
  "id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "amount_in_minor": 0,
  "currency": "GBP",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": [
          "GB"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ],
        "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "string",
      "account_holder_name": "string",
      "verification": {
        "type": "automated",
        "remitter_name": true,
        "remitter_date_of_birth": true
      }
    }
  },
  "created_at": "string",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "status": "authorizing"
}

authorized

The user has authorised the payment, but it has not yet reached a terminal status (executed, settled or failed).

FieldDescription
idThe ID of the payment
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
created_atAn RFC-3339 timestamp of when the payment was created
statusauthorized
metadataAny metadata that you set during payment creation.
authorization_flowInformation about the authorisation flow. Contains:

- configuration, which indicates any filters that you set for provider selection and redirects
payment_sourceAn object that contains information about the account that the payment comes from, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

Includes:
- account_identifiers: the sort code and account number, or IBAN, of the account
- account_holder_name: the name of the account's owner
{
	"id": "6bf3eb76-9cd3-4ee0-b789-0ade91ab7fa3",
	"amount_in_minor": 28,
	"currency": "GBP",
	"user": {
		"id": "4de58777-29bb-482f-89a2-8008f9352b1f"
	},
	"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"provider_selection": {
			"type": "user_selected"
		},
    "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
	},
	"created_at": "2023-03-14T11:40:33.046689Z",
	"status": "authorized",
	"authorization_flow": {
		"configuration": {
			"provider_selection": {},
			"redirect": {
				"return_uri": "https://payment.truelayer-sandbox.com/payments/completed"
			},
			"form": {
				"input_types": [
					"text",
					"select",
					"text_with_image"
				]
			}
		}
	},
	"payment_source": {
		"account_identifiers": [
			{
				"type": "sort_code_account_number",
				"sort_code": "040668",
				"account_number": "00000871"
			}
		],
		"account_holder_name": "JOHN SANDBRIDGE"
	}
}

📘

payment_source information

Payments in the authorized, executed, and failed states include a payment_source object, including payments not made into a TrueLayer merchant account, if they come from a UK CMA9 bank (except ob-boi).

If a payment does not settle into a TrueLayer merchant account, the payment_source object does not include the id field.

executed

This is a terminal status for payments into an external account (not into a merchant account).

FieldDescription
idThe ID of the payment.
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
created_atAn RFC-3339 timestamp of when the payment was created.
metadataAny metadata that you set during payment creation.
statusexecuted
executed_atAn RFC-3339 timestamp of when the payment was executed.
authorization_flowInformation about the authorisation flow. Contains:

- configuration, which indicates any filters that you set for provider selection and redirects
settlement_riskA rating that indicates how likely a payment is to settle. Only available for closed-loop EUR payments in Private Beta and subject to change.

Can be low_risk or high_risk.
payment_sourceAn object that contains information about the account that the payment comes from, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

Includes:
- account_identifiers: the sort code and account number, or IBAN, of the account
- account_holder_name: the name of the account's owner
{
	"id": "72cab501-e22b-4a61-b3fe-3f75697d3118",
	"amount_in_minor": 1,
	"currency": "GBP",
	"user": {
		"id": "818ae339-a164-4e6d-99e6-a714c321cf50"
	},
	"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "external_account",
			"account_identifier": {
				"type": "sort_code_account_number",
				"sort_code": "123456",
				"account_number": "12345678"
			},
			"account_holder_name": "Beneficiary Name",
			"reference": "RefTest"
		},
		"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"provider_selection": {
			"type": "user_selected"
		},
    "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
	},
	"created_at": "2023-03-14T11:36:20.273485Z",
	"status": "executed",
	"authorization_flow": {
		"configuration": {
			"provider_selection": {},
			"redirect": {
				"return_uri": "https://payment.truelayer-sandbox.com/payments/completed"
			},
			"form": {
				"input_types": [
					"text",
					"select",
					"text_with_image"
				]
			}
		}
	},
	"executed_at": "2023-03-14T11:36:53.023642Z",
	"payment_source": {
		"account_identifiers": [
			{
				"type": "sort_code_account_number",
				"sort_code": "040668",
				"account_number": "00000871"
			}
		],
		"account_holder_name": "JOHN SANDBRIDGE"
	}
}

settled

This is a terminal status for payments into a merchant account.

FieldDescription
idThe ID of the payment.
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
created_atAn RFC-3339 timestamp of when the payment was created.
metadataAny metadata that you set during payment creation.
statussettled
executed_atAn RFC-3339 timestamp of when the payment was executed.
settled_atAn RFC-3339 timestamp of when the payment was settled.
authorization_flowInformation about the authorisation flow. Contains:

- configuration, which indicates any filters that you set for provider selection and redirects
settlement_riskA rating that indicates how likely a payment is to settle. Only available for closed-loop EUR payments in Private Beta and subject to change.

Possible values are low_risk or high_risk.
payment_sourceAn object that contains information about the account that the payment comes from, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

Includes:
- id: the ID of the merchant account that the payment was made into
- account_identifiers: the sort code and account number, or IBAN, of the account
- account_holder_name: the name of the account's owner
{
	"id": "01ec8fec-0094-4258-a67d-e534d94d8ba8",
	"amount_in_minor": 28,
	"currency": "GBP",
	"user": {
		"id": "b7a3cae2-4d43-4a62-be30-919671634742"
	},
	"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"provider_selection": {
			"type": "user_selected"
		},
    "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
	},
	"created_at": "2023-03-14T11:20:36.038579Z",
	"status": "settled",
	"authorization_flow": {
		"configuration": {
			"provider_selection": {},
			"redirect": {
				"return_uri": "https://payment.truelayer-sandbox.com/payments/completed"
			},
			"form": {
				"input_types": [
					"text",
					"select",
					"text_with_image"
				]
			}
		}
	},
	"executed_at": "2023-03-14T11:26:04.267719Z",
	"payment_source": {
		"account_identifiers": [
			{
				"type": "sort_code_account_number",
				"sort_code": "040668",
				"account_number": "00000871"
			},
			{
				"type": "iban",
				"iban": "GB75CLRB04066800000871"
			}
		],
		"id": "3ad9485d-d5a8-4935-b6d1-f0686b995205",
		"account_holder_name": "JOHN SANDBRIDGE"
	},
	"settled_at": "2023-03-14T11:26:07.416152Z"
}

failed

This is a terminal status for all payments.

FieldDescription
idThe ID of the payment
amount_in_minorThe amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
currencyThe currency of the payment as an ISO 4217 code.
created_atAn RFC-3339 timestamp of when the payment was created.
metadataAny metadata that you set during payment creation.
statusfailed
failed_atAn RFC-3339 timestamp of when the payment failed.
failure_stageThe state that the payment was in just before it failed.
failure_reasonThe reason that the payment failed.

Possible values are:
authorization_failed: The end user did not authorise the payment.
blocked: The payment has been blocked because of a regulatory requirement. This may happen if the end user fails a sanctions check.
canceled: The end user cancelled the payment during authorisation (for example, on the hosted payment page) or the payment was cancelled using the cancel payment endpoint.
expired: The payment token expired before the end user authorised the payment, so the payment cannot be executed.
internal_server_error: An error has occurred within TrueLayer when processing the payment.
rejected: The payment was rejected for an unspecified reason.
not_authorized: The end user cancelled the payment or did not successfully authenticate on the provider's UI.
provider_error: The provider has unexpectedly failed when creating the payment.
provider_rejected: The payment was rejected by the provider for an unspecified reason.
scheme_unavailable: There is no scheme available given the provider selection configuration.

Make sure to also include a generic failure reason for any values not on this list.
authorization_flowInformation about the authorisation flow. Contains:

- configuration, which indicates any filters that you set for provider selection and redirects
payment_sourceAn object that contains information about the account that the payment comes from, if available from the remitter's bank. The account identifiers available will be those provided by the bank.

Includes:
- account_identifiers: the sort code and account number, or IBAN, of the account
- account_holder_name: the name of the account's owner
{
	"id": "91831544-dbae-4136-a536-16f3126de10d",
	"amount_in_minor": 28,
	"currency": "GBP",
	"user": {
		"id": "7bf9d3ca-e454-4bd1-ac78-4d9c8dbed9ae"
	},
	"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"payment_method": {
		"type": "bank_transfer",
		"beneficiary": {
			"type": "merchant_account",
			"account_holder_name": "Beneficiary Name",
			"merchant_account_id": "af6b1163-14bb-4491-afc7-abeb67adc07f"
		},
		"provider_selection": {
			"type": "user_selected"
		},
    "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
	},
	"created_at": "2023-03-14T10:03:46.175025Z",
	"status": "failed",
	"failed_at": "2023-03-14T10:18:46.243403Z",
	"failure_stage": "authorization_required",
	"failure_reason": "expired"
}