Get data about a payment

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. This feature is only available for closed-loop payments (payments into a merchant account).

Use this alongside webhooks and the merchant account dashboard to monitor the status of payments as they move through their lifecycle. You can use this API endpoint, instead of webhooks, to poll for information about an individual payment (though we still recommend that you use webhooks if possible).

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:

The id of the payment you want to know about
An access_token
A Tl-Signature and idempotency key

Request parameters

Make a GET request to the following endpoint:

Live endpoint	Sandbox 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 parameter	Parameter type	Description
Payment `id`	string	The 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.

Field	Description
`id`	The ID of the payment.
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`user` object, containing `user.id`	The 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_method`	Can be `bank_transfer` or `mandate`. If `bank_transfer`, this includes: - `type` - `provider_selection` object - `beneficiary` (merchant account or external account)If `mandate`, this includes: - `type` - `mandate_id` - `reference` - `retry` information (if you have enabled this)
`created_at`	An RFC-3339 timestamp of when the payment was created.
`metadata`	Any metadata that you set during payment creation.
`status`	`authorization_required`

{
  "id": "a8dd3846-f8ca-4a29-a9f2-51aac617da38",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:39:06.739771Z",
  "status": "authorization_required"
}

`authorizing`

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

Field	Description
`id`	The ID of the payment
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`user` object, containing `user.id`	The 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_method`	Can be `bank_transfer` or `mandate`. If `bank_transfer`, this includes: - `type` - `provider_selection` object - `beneficiary` (merchant account or external account)If `mandate`, this includes: - `type` - `mandate_id` - `reference` - `retry` information (if you have enabled this)
`created_at`	An RFC-3339 timestamp of when the payment was created.
`metadata`	Any metadata that you set during payment creation.
`status`	`authorizing`
`authorization_flow`	Information 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": "a8dd3846-f8ca-4a29-a9f2-51aac617da38",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_id": "faster_payments_service",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:39:06.739771Z",
  "status": "authorizing",
  "authorization_flow": {
    "actions": {
      "next": {
        "type": "redirect",
        "uri": "https://pay-mock-connect.truelayer-sandbox.com/login/5b8a509c-97a1-4634-be76-bc73cd20f983#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1YjhhNTA5Yy05N2ExLTQ2MzQtYmU3Ni1iYzczY2QyMGY5ODMiLCJzY29wZSI6InBheS1tb2NrLWNvbm5lY3QtYXBpIiwibmJmIjoxNzEzNTIzMjY3LCJleHAiOjE3MTM1MjY4NjcsImlzcyI6Imh0dHBzOi8vcGF5LW1vY2stY29ubmVjdC50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJhdWQiOiJodHRwczovL3BheS1tb2NrLWNvbm5lY3QudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.D3HjqSLmJHnkosLUQH7qn1ZIpk30SBNa-HZBfU2LX0Q"
      }
    },
    "configuration": {
      "provider_selection": {},
      "redirect": {
        "return_uri": "https://payment.truelayer-sandbox.com/payments/completed"
      },
      "form": {
        "input_types": [
          "text",
          "select",
          "text_with_image"
        ]
      },
      "consent": {
        "action_type": "adjacent",
        "requirements": {
          "pis": {},
          "ais": {
            "scopes": [
              "accounts",
              "balance"
            ]
          }
        }
      },
      "user_account_selection": {},
      "scheme_selection": {}
    }
  }
}

`authorized`

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

Field	Description
`id`	The ID of the payment
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`created_at`	An RFC-3339 timestamp of when the payment was created
`status`	`authorized`
`metadata`	Any metadata that you set during payment creation.
`authorization_flow`	Information about the authorisation flow. Contains: - `configuration`, which indicates any filters that you set for provider selection and redirects
`payment_source`	An 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": "a8dd3846-f8ca-4a29-a9f2-51aac617da38",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_id": "faster_payments_service",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:39:06.739771Z",
  "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"
        ]
      },
      "consent": {
        "action_type": "adjacent",
        "requirements": {
          "pis": {},
          "ais": {
            "scopes": [
              "accounts",
              "balance"
            ]
          }
        }
      },
      "user_account_selection": {},
      "scheme_selection": {}
    }
  },
  "payment_source": {
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "040668",
        "account_number": "00000871"
      }
    ],
    "account_holder_name": "J &+ SANDBRIDGE JR."
  }
}

📘
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 usually a terminal status for payments into an external account (not into a merchant account).

Field	Description
`id`	The ID of the payment.
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`created_at`	An RFC-3339 timestamp of when the payment was created.
`metadata`	Any metadata that you set during payment creation.
`status`	`executed`
`executed_at`	An RFC-3339 timestamp of when the payment was executed.
`authorization_flow`	Information about the authorisation flow. Contains: - `configuration`, which indicates any filters that you set for provider selection and redirects
`payment_source`	An 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
`creditable_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment was ready to be credited.
`settlement_stalled_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one.

{
  "id": "c037d909-6cc2-454e-b816-92b322e30284",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_id": "faster_payments_service",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:44:38.623757Z",
  "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"
        ]
      },
      "consent": {
        "action_type": "adjacent",
        "requirements": {
          "pis": {},
          "ais": {
            "scopes": [
              "accounts",
              "balance"
            ]
          }
        }
      },
      "user_account_selection": {},
      "scheme_selection": {}
    }
  },
  "executed_at": "2024-04-19T10:45:12.088247Z",
  "payment_source": {
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "040668",
        "account_number": "00000871"
      }
    ],
    "account_holder_name": "J &+ SANDBRIDGE JR."
  },
  "creditable_at": "2023-03-19T10:45:15.186297Z"
}

`settled`

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

Field	Description
`id`	The ID of the payment.
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`created_at`	An RFC-3339 timestamp of when the payment was created.
`metadata`	Any metadata that you set during payment creation.
`status`	`settled`
`executed_at`	An RFC-3339 timestamp of when the payment was executed.
`settled_at`	An RFC-3339 timestamp of when the payment was settled.
`authorization_flow`	Information about the authorisation flow. Contains: - `configuration`, which indicates any filters that you set for provider selection and redirects
`payment_source`	An 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
`creditable_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment was ready to be credited.
`settlement_stalled_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one.

{
  "id": "a8dd3846-f8ca-4a29-a9f2-51aac617da38",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_id": "faster_payments_service",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:39:06.739771Z",
  "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"
        ]
      },
      "consent": {
        "action_type": "adjacent",
        "requirements": {
          "pis": {},
          "ais": {
            "scopes": [
              "accounts",
              "balance"
            ]
          }
        }
      },
      "user_account_selection": {},
      "scheme_selection": {}
    }
  },
  "executed_at": "2024-04-19T10:43:53.533512Z",
  "payment_source": {
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "040668",
        "account_number": "00000871"
      },
      {
        "type": "iban",
        "iban": "GB75CLRB04066800000871"
      }
    ],
    "id": "41b500a4-5379-4f30-9eda-2fcc032afc37",
    "account_holder_name": "JOHN SANDBRIDGE"
  },
  "settled_at": "2024-04-19T10:43:55.315355Z",
  "creditable_at": "2024-04-19T10:43:55.41044Z"
}

`failed`

This is a terminal status for all payments.

Field	Description
`id`	The ID of the payment
`amount_in_minor`	The amount paid, in the smallest possible unit of its currency (pennies for GBP, cents for EUR, etc).
`currency`	The currency of the payment as an ISO 4217 code.
`created_at`	An RFC-3339 timestamp of when the payment was created.
`metadata`	Any metadata that you set during payment creation.
`status`	`failed`
`failed_at`	An RFC-3339 timestamp of when the payment failed.
`failure_stage`	The state that the payment was in just before it failed.
`failure_reason`	The 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_flow`	Information about the authorisation flow. Contains: - `configuration`, which indicates any filters that you set for provider selection and redirects
`payment_source`	An 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
`creditable_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment was ready to be credited.
`settlement_stalled_at`	An RFC-3339 timestamp of when TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one.

{
  "id": "2e099ae3-8dcc-4686-9c38-e6428dd4a98f",
  "amount_in_minor": 30000,
  "currency": "GBP",
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35"
  },
  "payment_method": {
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    },
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_id": "faster_payments_service",
      "scheme_selection": {
        "type": "user_selected"
      },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
    }
  },
  "created_at": "2024-04-19T10:48:01.660184Z",
  "status": "failed",
  "authorization_flow": {
    "configuration": {
      "provider_selection": {},
      "redirect": {
        "return_uri": "https://payment.truelayer-sandbox.com/payments/completed"
      },
      "form": {
        "input_types": [
          "text",
          "select",
          "text_with_image"
        ]
      },
      "consent": {
        "action_type": "adjacent",
        "requirements": {
          "pis": {},
          "ais": {
            "scopes": [
              "accounts",
              "balance"
            ]
          }
        }
      },
      "user_account_selection": {},
      "scheme_selection": {}
    }
  },
  "failed_at": "2024-04-19T10:48:23.542856Z",
  "failure_stage": "authorizing",
  "failure_reason": "not_authorized"
}

Before you start

Request parameters

GET Payment responses

authorization_required

authorizing

authorized

📘payment_source information

executed

settled

failed

`authorization_required`

`authorizing`

`authorized`

📘
`payment_source` information

`executed`

`settled`

`failed`