--- title: "Create payment" method: POST path: "/v3/payments" tags: ["Payments"] --- # Create payment `POST /v3/payments` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/payments` - Auth: OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments` Create a new payment This API must be called using a backend bearer token. ## Headers - `Idempotency-Key` string, required - `Tl-Signature` string, required - `X-Forwarded-For` string - `X-Device-User-Agent` string ## Request body - CreatePayment - `amount_in_minor` integer, required: A 'cent' value representing the amount, e.g. 100 = 1GBP or 100 = 1EUR - `currency` 'GBP' | 'EUR', required - `payment_method` union, required - object - `type` 'bank_transfer', required: The type of payment method. - `provider_selection` union, required: Provider Selection - object: Indicates that the provider is to be selected from a collection - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilter: Configuration options to constrain which providers should be available during the `provider_selection` action. - `countries` CountryCode[]: Only providers from the specified countries will be returned. - `release_channel` 'general_availability' | 'public_beta' | 'private_beta': The lowest stability release stage of a provider that should be returned. Note that many EUR providers are in `public_beta` or `private_beta`. - `customer_segments` string[]: The customer segments that providers cater to that should be returned. By default, returns retail only. - `provider_ids` string[]: IDs of providers to include in those returned. - `excludes` object: Options to exclude providers included by the filters - … - `scheme_selection` union: Scheme Selection - object: Only allow providers that support instant payments. - … - object: Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable. - … - object: Indicates that the scheme is to be selected from a collection. Note: This scheme selection method is only supported by some versions of TrueLayer's mobile SDKs. Only use this option when you're sure that the end user has a version of your app on their device that supports scheme selection, or they won't be able to complete the payment. If you integrate with TrueLayer APIs directly, you must show the user a UI for scheme selection. - … - `remitter` ProviderSelectionUserSelectedRemitter: Remitter - `account_holder_name` string, required: The name of the external account holder. This field will be required if the selected provider requires it, otherwise it will be optional. pattern: `^[^\(\)]{1,80}$` - 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 - object: Indicates that the branch for this payment is preselected. - … - object: Indicates that the branch is to be selected from a collection. - … - `scheme_selection` union, required: Scheme Selection - object: Only allow providers that support instant payments. - … - object: Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable. - … - object: Indicates that the scheme for this payment is preselected. - … - object: Indicates that the scheme is to be selected from a collection. Note: This scheme selection method is only supported by some versions of TrueLayer's mobile SDKs. Only use this option when you're sure that the end user has a version of your app on their device that supports scheme selection, or they won't be able to complete the payment. If you integrate with TrueLayer APIs directly, you must show the user a UI for scheme selection. - … - `remitter` ProviderSelectionPreselectedRemitter: Remitter - `account_holder_name` string: The name of the external account holder. This field will be required if the preselected provider requires it, otherwise it will be optional. pattern: `^[^\(\)]{1,80}$` - `account_identifier` union: A unique account identifier for an external account. - … - `data_access_token` string: If the provider only allows a single active consent across both AIS (data) and PIS (payments) services, in order to prevent invalidating an existing AIS consent, you can pass the data access token in this field, and we will preserve the data consent when requesting authorisation for the payment. pattern: `^[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*$` - `beneficiary` union, required - PaymentDestinationMerchantAccount: The identifier for a TrueLayer merchant account. - `type` 'merchant_account', required: The type of destination. - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `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. pattern: `^[^\(\)]+$` - `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. - `type` 'automated', required: The type of verification. - `remitter_name` boolean: Enable verification for the remitter name. - `remitter_date_of_birth` boolean: Enable verification for the remitter date of birth. - `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-:()\.,'\+ \?\/]+$` - PaymentDestinationExternalAccount: 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. Note that some providers have an 18-character upper limit for this. pattern: `^[^\(\)]+$` - `account_identifier` union, required: A unique account identifier for an external account. - AccountIdentifierScan: The scheme identifier for a bank account participating in UK payment schemes. - … - AccountIdentifierIban: The international bank account number. - … - AccountIdentifierBban: Basic bank account number. - … - AccountIdentifierNrb: The scheme identifier for a bank account participating in Poland's payment schemes. - … - `reference` string, required: A reference for the payment. pattern: `^[a-zA-Z0-9-:()\.,'\+ \?\/]+$` - `retry` BankTransferRetry: Include this parameter to 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`. - `user` PaymentUserCreate, required: Details of the end user who is making the payment. If you are using your own PISP licence, these fields are not required. Payments over a mandate don't need user information as this was collected at mandate creation. - `id` string: Unique ID for the User - `name` string: This is the full first and last name of your end user (not initials). If you are using your own PISP licence this field is optional, otherwise it is required. pattern: `^[^\(\)]+$` - `email` string, email: The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822). If you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required. - `phone` string, phone: The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`. If you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required. - `date_of_birth` string, date: The date of birth of your end user, in `YYYY-MM-DD` format. - `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) - `political_exposure` 'current' | 'none': The user's political exposure (PEP), if known this field should be set to `current` otherwise to `none`. If not known this field can be ignored or a `null` value can be sent. - `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. - `authorization_flow` StartPaymentAuthorizationFlow: This object contains a declaration of the client UI's capabilities. The API will adjust the flow depending on this declaration and filter out unsupported providers. - `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. This parameter is required for payments with `user_selected` provider selection. For preselected provider selection, it's optional. Use the `provider_selection.filter` parameter at payment creation to determine the list of providers you can choose to display in your UI. - `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 - `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. - `branch_selection` object: Can your UI render a branch selection screen? For payments where you set `branch_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments branch. This field is required for payments with `user_selected` branch selection. For other branch 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 flow, the end user authorises the payment on a third-party site, such as a bank. The return URI you set is where the user is redirected to after they complete authorisation on the third-party site. 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 - `scopes` AisScope[], required - `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. - `hosted_page` HostedPageParameters: Provide these parameters to have an auto constructed [hosted page](https://docs.truelayer.com/docs/hosted-payment-page) URI returned on the response. This cannot be provided if starting the `authorization_flow` explicitly. - `return_uri` string, url, required: The URI where the user will be redirected to after the authorization flow has completed on the hosted page. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris). - `country_code` string: The country code of the user. This is used to determine which banks to show on the hosted page initially. The country code must be in ISO 3166-1 alpha-2 format. - `language_code` string: The language code of the user. This is used to determine which language to show on the hosted page, overriding the browser's locale. The language code must be in ISO 639-1 format. - `max_wait_for_result` integer: The maximum time to wait for a result from the hosted page after the user has completed the authorization flow, in seconds. - `risk_assessment` RiskAssessment: An optional field for configuring risk assessment and the `payment_creditable` webhook. [Learn how to enable this field](/docs/payment-risk-and-credit-notifications#multiple-payment_creditable-behaviours-with-the-segment-parameter). - `segment` string: The risk segment of this payment. Please contact us before sending this field. pattern: `^[^\(\)]+$` - `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, required: The date and time the consent was captured. - 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. ## Response `201` Payment - union - PaymentCreatedAuthorizationRequired - `id` string, required: ID of the payment - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `resource_token` string, required: A payment token in JWT format, with a limited scope that is authorised to be used with a single payment - `status` 'authorization_required', required - `hosted_page` HostedPage: Returned if the `hosted_page` object in the request body is populated. - `uri` string, url, required: The URI to redirect the user to authorize the payment using the hosted page. - PaymentCreatedAuthorizing - `id` string, required: ID of the payment - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `resource_token` string, required: A payment token in JWT format, with a limited scope that is authorised to be used with a single payment - `status` 'authorizing', required - `authorization_flow` PaymentAuthorizationFlow, 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. - … - PaymentCreatedAuthorized - `id` string, required: ID of the payment - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `resource_token` string, required: A payment token in JWT format, with a limited scope that is authorised to be used with a single payment - `status` 'authorized', required - PaymentCreatedFailed - `id` string, required: ID of the payment - `user` PaymentUser, required - `id` string, required: Unique ID for the User - `resource_token` string, required: A payment token in JWT format, with a limited scope that is authorised to be used with a single payment - `status` 'failed', required - `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. ## Other responses - `400`: Invalid Parameters - `401`: Unauthenticated - `403`: Forbidden - `409`: Idempotency-Key Concurrency Conflict - `422`: Idempotency-Key Reuse - `429`: Rate Limit Exceeded - `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)