--- title: "Get payment" method: GET path: "/v3/payments/{id}" tags: ["Payments"] --- # Get payment `GET /v3/payments/{id}` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/payments/{id}` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments` - HTTP bearer Returns payment details. This API can be called: - using the `resource_token` associated with the payment you are trying to fetch; - using a backend bearer token. _**Note:** Some fields are required when OAuth2 token is used._ ## Path parameters - `id` string, required: Unique ID for the Payment ## Response `200` Payment - union - PaymentAuthorizationRequired: A payment yet to be authorized. This is the first status for a payment that requires further actions to be authorized. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'authorization_required', required - PaymentAuthorizing: A payment yet to be authorized. This is the first status for a payment that requires further actions to be authorized. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'authorizing', required - `authorization_flow` object, required: Contains information regarding the nature and the state of the authorization flow - `actions` object, required - `next` union, required: The next action can be performed via `POST /v3/payments/{id}/authorization_flow/action/{action_name}` - check its documentation for relevant examples. - ActionSpecProviderSelection: Provider selection represents the end user action of selecting a provider - `type` 'provider_selection', required - `providers` Provider[], required: List of providers to be presented to the end user - … - ActionSpecSchemeSelection: Scheme selection represents the end user action of selecting a scheme - `type` 'scheme_selection', required - `schemes` Scheme[], required: List of schemes to be presented to the end user - … - ActionSpecRedirect - `type` 'redirect', required - `uri` string, url, required: URL the end user must be redirected to. - ActionSpecWaitForOutcome: Indication that there are currently no actions to perform. Clients must poll the `GET /v3/payment/{id}` endpoint until the status changes, or the next action is available. - `type` 'wait', required - `display_message` DisplayText - … - ActionSpecForm: Form action represents the end user action of entering further details into the UI. - `type` 'form', required - `inputs` ActionSpecAdditionalInput[], required: The inputs to be presented to the end user in the UI. - … - ActionSpecConsent - `type` 'consent', required - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `subsequent_action_hint` 'redirect' | 'form' | 'wait', required - ActionSpecUserAccountSelection: Provides the end user with a list of previously saved user accounts for reuse. - `type` 'user_account_selection', required - `user_accounts` UserAccountDetails[], required: List of user accounts to be presented to the end user - … - ActionSpecRetry - `type` 'retry', required - `retry_options` RetryOption[], required: List of retry options available - ActionSpecBranchSelection: Branch selection represents the end user action of selecting a branch of the provider - `type` 'branch_selection', required - `branches` Branch[], required: List of branches to be presented to the end user - … - `adjacent` AdjacentActions: Actions that can be submitted alongside the next action - `consent` object - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `configuration` PaymentAuthorizationFlowConfiguration - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - PaymentAuthorized: An authorized payment - no more actions required, waiting for outcome. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'authorized', required - `authorization_flow` PaymentAuthorizationFlowFrozen: Information about the authorization flow the payment went through. If the payment transitioned immediately to `authorized` or `failed`, this field will be null. - `configuration` PaymentAuthorizationFlowConfiguration, required - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - `payment_source` PaymentSource: Information about the source of funds, if available from the remitter's bank. Account identifiers will be those provided by the bank. - `account_holder_name` string, required - `account_identifiers` AccountIdentifier[], required - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - `type` 'sort_code_account_number', required: The type of scheme identifier. - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$` - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$` - AccountIdentifierIban: The international bank account number. - `type` 'iban', required: The type of scheme identifier. - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - `type` 'nrb', required: The type of scheme identifier. - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. - `creditable_at` string, datetime: The date and time that TrueLayer determined that the payment was ready to be credited. - PaymentExecuted: An executed payment. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'executed', required - `executed_at` string, datetime: The date and time the payment executed at. _**Note:** This field is required when OAuth2 token is used._ - `authorization_flow` PaymentAuthorizationFlowFrozen: Information about the authorization flow the payment went through. If the payment transitioned immediately to `authorized` or `failed`, this field will be null. - `configuration` PaymentAuthorizationFlowConfiguration, required - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - `payment_source` PaymentSource: Information about the source of funds, if available from the remitter's bank. Account identifiers will be those provided by the bank. - `account_holder_name` string, required - `account_identifiers` AccountIdentifier[], required - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - `type` 'sort_code_account_number', required: The type of scheme identifier. - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$` - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$` - AccountIdentifierIban: The international bank account number. - `type` 'iban', required: The type of scheme identifier. - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - `type` 'nrb', required: The type of scheme identifier. - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. - `creditable_at` string, datetime: The date and time that TrueLayer determined that the payment was ready to be credited. - `settlement_stalled_at` string, datetime: The date and time at which TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one. - `disputed_at` string, datetime: The date and time that TrueLayer received an indemnity claim for the payment. - `disputed_reason` string: The reason that the indemnity claim was made against the payment. - PaymentSettled: A settled payment, i.e. the funds have settled into the beneficiary account. Status only available for payments into merchant accounts. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'settled', required - `payment_source` SettledPaymentSource - `id` string, uuid, required - `account_holder_name` string, required - `account_identifiers` AccountIdentifier[], required - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - `type` 'sort_code_account_number', required: The type of scheme identifier. - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$` - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$` - AccountIdentifierIban: The international bank account number. - `type` 'iban', required: The type of scheme identifier. - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - `type` 'nrb', required: The type of scheme identifier. - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. - `executed_at` string, datetime, required: Date and time the payment executed. _**Note:** This field is required when OAuth2 token is used._ - `settled_at` string, datetime: Date and time the payment settled. _**Note:** This field is required when OAuth2 token is used._ - `authorization_flow` PaymentAuthorizationFlowFrozen: Information about the authorization flow the payment went through. If the payment transitioned immediately to `authorized` or `failed`, this field will be null. - `configuration` PaymentAuthorizationFlowConfiguration, required - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - `creditable_at` string, datetime: The date and time that TrueLayer determined that the payment was ready to be credited. - `settlement_stalled_at` string, datetime: The date and time at which TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one. - `disputed_at` string, datetime: The date and time that TrueLayer received an indemnity claim for the payment. - `disputed_reason` string: The reason that the indemnity claim was made against the payment. - `reversed_at` string, datetime: Date and time the payment was reversed. - `reversal_reason` 'corrected' | 'failed' | 'disputed': The reason for the payment reversal. - PaymentFailed: A failed payment - it was authorized successfully, but the money did not move. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'failed', required - `failed_at` string, datetime: The date and time the payment was marked as failed. _**Note:** This field is required when OAuth2 token is used._ - `failure_stage` 'authorization_required' | 'authorizing' | 'authorized' | 'executed', required: The status the payment was in when it failed. - `failure_reason` string, required: The reason that the payment failed. - `failure_funds_stage` 'received' | 'not_received': The status of the funds when the payment failed. - `authorization_flow` PaymentAuthorizationFlowFrozen: Information about the authorization flow the payment went through. If the payment transitioned immediately to `authorized` or `failed`, this field will be null. - `configuration` PaymentAuthorizationFlowConfiguration, required - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - `payment_source` PaymentSource: Information about the source of funds, if available from the remitter's bank. Account identifiers will be those provided by the bank. - `account_holder_name` string, required - `account_identifiers` AccountIdentifier[], required - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - `type` 'sort_code_account_number', required: The type of scheme identifier. - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$` - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$` - AccountIdentifierIban: The international bank account number. - `type` 'iban', required: The type of scheme identifier. - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - `type` 'nrb', required: The type of scheme identifier. - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. - `creditable_at` string, datetime: The date and time that TrueLayer determined that the payment was ready to be credited. - `settlement_stalled_at` string, datetime: The date and time at which TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one. - `reversed_at` string, datetime: Date and time the payment was reversed. - `reversal_reason` 'corrected' | 'failed' | 'disputed': The reason for the payment reversal. - PaymentAttemptFailed: A failed payment attempt - it was authorized successfully, but the money did not move. - `id` string, required: Unique ID for the Payment - `amount_in_minor` integer, required - `currency` 'GBP' | 'EUR', required - `user` PaymentUser - `id` string, required: Unique ID for the User - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the user selects the provider that they want to pay with from a list. - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilterResponse: Configuration options to constrain which providers should be available during the `provider_selection` action. _**Note:** This field is required when OAuth2 token is used._ - … - `scheme_selection` union: Scheme Selection - … - `provider_id` string: The provider ID that the end user uses for this payment. Populated when provider selection has been submitted. - `branch_selection` GetBranchSelectionUserSelected: Indicates that the branch is to be selected from a collection. - … - `scheme_id` string: The ID of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later. - object: Preselected provider. Indicates that the provider for this payment is preselected. - `type` 'preselected', required: The type of provider. - `provider_id` string, required: The provider ID the end user will use for this payment. - `branch_selection` union: Branch Selection - … - `scheme_id` string: The ID of the scheme to make the payment over. - `scheme_selection` union: Scheme Selection - … - `remitter` RemitterResponse: Remitter _**Note:** This field is required when OAuth2 token is used._ - … - `beneficiary` union, required - PaymentDestinationMerchantAccountResponse: The identifier for a TrueLayer's merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string: Unique ID for the Merchant Account _**Note:** This field is required when OAuth2 token is used._ - `account_holder_name` string: The name of the beneficiary, which displays in the remitter's bank statement. If unspecified, the API uses the account owner name associated with the selected merchant account. - `reference` string: A reference for the payment. Not visible to the remitter. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `verification` Verification: In an automated verification, TrueLayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both. - … - `statement_reference` string: Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccountResponse: The routing information for an external bank account. - `type` 'external_account', required: The type of destination. - `account_holder_name` string, required: The name of the external account holder. - `account_identifier` union: A unique account identifier for an external account. _**Note:** This field is required when OAuth2 token is used._ - … - `reference` string, required - `retry` BankTransferRetryResponse: This parameter indicate that the payment support retries (only available for GBP payments) - object - `type` 'mandate', required: The type of payment method. - `user_interaction` 'present' | 'not_present': It indicates whether the user is present at the moment this payment is created or not. This field can have a value only if the mandate is commercial. It's required when the commercial mandate was created with the `use_case` field set. - `mandate_id` string, required: The identifier of the mandate. - `reference` string: Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters. - `retry` union: > 🚧 This is an opt-in feature. > > Please Contact us to enable this feature. Optional field to enable Retry for this payment. Retry is performed as frequently as possible based on the nature of the error in order to maximise conversion. Read more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments). - object - `type` 'standard', required: Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error. This feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `6h`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - object - `type` 'smart', required: Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria. This feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code. - `for` string: How long to retry this payment for (between `30m` - `90d`). This should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively). - `ensure_minimum_balance_in_minor` number: The payment is attempted only if the remaining balance in the account is at least this amount. This should be 'cent' value, e.g. 100 = 1GBP. Payment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`. - `created_at` string, datetime: The date and time the payment was created at. _**Note:** This field is required when OAuth2 token is used._ - `metadata` Metadata: Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters. - `related_products` RelatedProducts: Optional field for adding related products, at least one product should be set. Not available when creating recurring payments. - `signup_plus` object: Signup+ product. - `sub_merchants` PaymentSubMerchants: The details related to any applicable sub-merchants, for example an underlying division of the overall business. - `ultimate_counterparty` union, required - UltimateCounterpartyBusinessDivision: The business details of the ultimate counterparty. - `type` 'business_division', required: The ultimate counterparty is a division of the main business. - `id` string, required: The identifier of the business division. - `name` string, required: The name of the business division. - UltimateCounterpartyBusinessClient: The business details of the ultimate counterparty. - `type` 'business_client', required: The ultimate counterparty is a registered business. - `id` string, required: The identifier of the business client. - `trading_name` string, required: The trading name of the business. pattern: `^.{1,70}$` - `commercial_name` string: The commercial name of the business. pattern: `^.{1,100}$` - `url` string: The website of the business. This must be a valid URL. - `mcc` string: The ISO 18245 merchant category code (MCC) of the business. pattern: `^[0-9]{4}$` - `registration_number` string: The registration number of the business. This is required if `address` is not provided. pattern: `^.{1,35}$` - `address` Address - `address_line1` string, required: The full street address including house number and street name. pattern: `^.{1,50}$`` - `address_line2` string: Further details like building name, suite, apartment number, etc. pattern: `^.{1,50}$` - `city` string, required: Name of the city / locality. pattern: `^.{1,50}$` - `state` string: Name of the county / state. pattern: `^.{1,50}$` - `zip` string, required: Zip code or postal code. pattern: `^.{1,20}$` - `country_code` string, required: The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `user_consent` union: Information of how the user's consent is captured for the payment. - object: The consent has been captured prior to the payment being created. - `type` 'precaptured', required: The consent has been captured prior to the payment being created. - `captured_at` string, datetime: The date and time the consent was captured. _**Note:** This field is required when OAuth2 token is used._ - object: The consent will be captured as part of the payment authorization flow. - `type` 'authorization_flow_captured', required: The consent will be captured as part of the payment authorization flow. - `failed_attempts` PaymentFailedAttempt[]: The list of failed payment attempts, if any. Each entry contains details about when the attempt failed and the reason for failure. - `attempt_number` integer, required: The sequential number of the payment attempt. - `failed_at` string, datetime, required: The date and time when the payment attempt failed. - `failure_reason` string, required: The reason that the payment failed. - `status` 'attempt_failed', required - `failed_at` string, datetime: The date and time the payment was marked as failed. _**Note:** This field is required when OAuth2 token is used._ - `failure_stage` 'authorization_required' | 'authorizing' | 'authorized' | 'executed', required: The status the payment was in when it failed. - `failure_reason` string, required: The reason that the payment failed. - `authorization_flow` object: Contains information regarding the nature and the state of the authorization flow - `actions` object, required - `next` union, required: The next action can be performed via `POST /v3/payments/{id}/authorization_flow/action/{action_name}` - check its documentation for relevant examples. - ActionSpecProviderSelection: Provider selection represents the end user action of selecting a provider - `type` 'provider_selection', required - `providers` Provider[], required: List of providers to be presented to the end user - … - ActionSpecSchemeSelection: Scheme selection represents the end user action of selecting a scheme - `type` 'scheme_selection', required - `schemes` Scheme[], required: List of schemes to be presented to the end user - … - ActionSpecRedirect - `type` 'redirect', required - `uri` string, url, required: URL the end user must be redirected to. - ActionSpecWaitForOutcome: Indication that there are currently no actions to perform. Clients must poll the `GET /v3/payment/{id}` endpoint until the status changes, or the next action is available. - `type` 'wait', required - `display_message` DisplayText - … - ActionSpecForm: Form action represents the end user action of entering further details into the UI. - `type` 'form', required - `inputs` ActionSpecAdditionalInput[], required: The inputs to be presented to the end user in the UI. - … - ActionSpecConsent - `type` 'consent', required - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `subsequent_action_hint` 'redirect' | 'form' | 'wait', required - ActionSpecUserAccountSelection: Provides the end user with a list of previously saved user accounts for reuse. - `type` 'user_account_selection', required - `user_accounts` UserAccountDetails[], required: List of user accounts to be presented to the end user - … - ActionSpecRetry - `type` 'retry', required - `retry_options` RetryOption[], required: List of retry options available - ActionSpecBranchSelection: Branch selection represents the end user action of selecting a branch of the provider - `type` 'branch_selection', required - `branches` Branch[], required: List of branches to be presented to the end user - … - `adjacent` AdjacentActions: Actions that can be submitted alongside the next action - `consent` object - `requirements` ConsentRequirements, required: The details of the consents required to be captured from the user. - … - `configuration` PaymentAuthorizationFlowConfiguration - `provider_selection` object: Can your UI render a provider selection screen? In payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI. This parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional. - `icon` Icon - `type` 'default' | 'extended' | 'extended_small' | 'extended_medium' | 'extended_large': Configuration for the type of icon. Available options are: - `default`: Default icon with no background (SVG). - `extended`: Extended as a square with an appropriate background colour (SVG). - `extended_small`: Extended icon with a 192x192 pixel resolution (JPEG). - `extended_medium`: Extended icon with a 432x432 pixel resolution (JPEG). - `extended_large`: Extended icon with an 864x864 pixel resolution (JPEG). - `branches` BranchesAuthorizationFlow - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI can render a screen where the user can select their payments branch. - `scheme_selection` object: Can your UI render a scheme selection screen? For payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme. This field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional. - `redirect` object: Can your UI redirect the user to a third-party page? For most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect. - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page. This URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `direct_return_uri` string, url: Only applicable if you're regulated and have a direct return URI registered with UK providers. If you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer. We recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a TrueLayer domain. - `form` object: Can your UI render form inputs for the user to interact with? Some providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs. This parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. If the provider has been preselected and requires additional inputs, this field is required. - `input_types` AdditionalInputType[], required: The types of input that your UI can render a form to collect. - `consent` object: Can your UI capture the user's consent? This parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment. If you omit this, the API may restrict the available providers if explicit consent is required. - `action_type` 'explicit' | 'adjacent': How you will capture consent as part of the authorisation flow: - `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow. - `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions. - `requirements` ConsentSupported: The details of the consents supported to be captured from the user. - `pis` ConsentSupportedPis, required - `ais` ConsentSupportedAis - … - `user_account_selection` object: Can your UI render a user account selection screen? If the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments. This field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option. - `payment_source` PaymentSource: Information about the source of funds, if available from the remitter's bank. Account identifiers will be those provided by the bank. - `account_holder_name` string, required - `account_identifiers` AccountIdentifier[], required - union: A unique scheme identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - `type` 'sort_code_account_number', required: The type of scheme identifier. - `sort_code` string, required: 6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$` - `account_number` string, required: 8 digit account number. pattern: `^[0-9]{8}$` - AccountIdentifierIban: The international bank account number. - `type` 'iban', required: The type of scheme identifier. - `iban` string, required: Valid International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - `type` 'nrb', required: The type of scheme identifier. - `nrb` string, required: Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. Equivalent to a Polish IBAN with the country code removed. ## Other responses - `401`: Unauthenticated - `403`: Forbidden - `404`: Payment Not Found - `500`: Unknown Error --- [API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)