--- title: "Create payout" method: POST path: "/v3/payouts" tags: ["Payouts"] --- # Create payout `POST /v3/payouts` ## Request - Base URL: `https://api.truelayer-sandbox.com` - URL: `https://api.truelayer-sandbox.com/v3/payouts` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments` - OAuth 2 - Client credentials - Token URL: `https://auth.truelayer.com/connect/token` scopes: `payments:payout:business_account` Pay out from one of your merchant accounts. ## Headers - `Idempotency-Key` string, required - `Tl-Signature` string, required ## Request body - CreatePayout - `merchant_account_id` string, uuid, required: Unique ID for the Merchant Account - `amount_in_minor` integer, required: A 'cent' value representing the amount, e.g. 100 == 1GBP - `currency` 'GBP' | 'EUR' | 'PLN', required - `beneficiary` union, required - PayoutIncomingDestinationExternalAccount: The routing information for an external bank account. - `type` 'external_account', required: Type `external_account` - `reference` string, required: The reference for the payout, which displays in the beneficiary's bank statement. For SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). For FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&*<>;{@\r\n]*$` For Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s]*$` - `account_holder_name` string, required: The name of the external account holder. For SEPA payments, the maximum length is **70 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). For FPS payments, the maximum length is **140 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&*<>;{@\r\n]*$` For Elixir payments, the maximum length is **70 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s]*$` - `account_identifier` union, required: 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. - `date_of_birth` string, date: If your transactions are subject to sanctions screening, you must provide the `date_of_birth` (in `YYYY-MM-DD` format), otherwise it is optional. - `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) - PayoutIncomingDestinationVerifiedExternalAccount: Payout to an external account using a previously completed verification. The beneficiary details (name and account identifier) are retrieved using the provided verification ID. No second verification check is performed when using this type. - `type` 'verified_external_account', required: Type `verified_external_account` - `account_holder_verification_id` string, uuid, required: The ID of a previously completed account holder verification. This verification must: - Be in "completed" or "failed" status - Have a match result (not "pending") The verification ID could be obtained either from: - An executed or a failed `external_account` payout (in the `account_holder_verification.id` field) (or) - The Account Holder Verification API response - `override_bank_matched_name` boolean: Determines whether to override the bank-matched account holder name and use the original account holder name for the payout. When set to `true`, the original account holder name (provided in the create account holder verification or create payout endpoint) is used. When set to `false`, the account holder name matched by the bank is used instead of the original name. Note: This field is only relevant for partial matches in account holder verification results. For all other account holder verification results, the original account holder name is used regardless of this field's value. If not provided, no override is applied and the bank-matched name is used. - PayoutIncomingDestinationPaymentSource - `type` 'payment_source', required: Type `payment_source` - `reference` string, required: The reference for the payout, which displays in the beneficiary's bank statement. For SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). For FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&*<>;{@\r\n]*$` For Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s]*$` - `payment_source_id` string, required: ID of the external account which has become a payment source. - `user_id` string, required: ID of the owning user of the external account. - PayoutIncomingDestinationBusinessAccount - `type` 'business_account', required: Type `business_account` paid to a preconfigured business IBAN. - `reference` string, required: The reference for the payout, which displays in the beneficiary's bank statement. For SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). For FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&*<>;{@\r\n]*$` For Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s]*$` - PayoutIncomingDestinationUserDetermined: Beneficiary details of type User Determined - `type` 'user_determined', required: Represents a beneficiary that is specified by the end-user. - `reference` string, required: The reference for the payout, which displays in the beneficiary's bank statement. For SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). For FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&*<>;{@\r\n]*$` For Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\/\-?:().,'+\s]*$` - `user` PayoutUserCreate, required: Details of the beneficiary of the payment. - `id` string: Unique ID for the User - `name` string: This is the full first and last name of your end user (not initials). This field is required if at least one of the following conditions is met: - your business is not a regulated entity - `verification.verify_name` is set to `true` - `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) - `verification` PayoutIncomingBeneficiaryVerification, required: Object that describes the verification checks to run on the payout. At least one between `account_holder_name` and `transaction_search_criteria` must be specified. - `verify_name` boolean, required: Enable verification for the account holder name. _**Note:** This is expected to always be `true`. In future this will be made optional to support verification types that don't involve checking account holder names._ - `transaction_search_criteria` PayoutBeneficiaryVerificationTransactionSearchCriteria: An object describing the search criteria to use to look for a transaction in the transaction history of the bank account connected to the end user - `tokens` string[], required: A list of tokens to look for as transaction reference. The size of this array can vary between 1 and 5 items. Each item should present minimum 3 and maximum 50 characters, including spaces. We recommend adding the merchant's name and an identifier in the transaction's description. e.g. `["18db38", "Betropolis LTD", "LC Betropolis"]` - `amount_in_minor` integer, required: A 'cent' value representing the amount, e.g. 100 == 1GBP - `currency` 'GBP', required: The currency that the payout will be in. - `created_at` string, date, required: The date the transaction was created at, e.g. `"2024-05-07"` - `provider_selection` union, required: Provider Selection used for `User Determined` beneficiaries - object: Indicates that the provider is to be selected from a collection - `type` 'user_selected', required: The type of provider. - `filter` ProviderFilter2: Configuration options to constrain which providers should be available during the `provider_selection` action. - `countries` string[]: 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. - `provider_ids` string[]: IDs of providers to include in those returned. - `excludes` object: Options to exclude providers included by the filters - … - 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. - `scheme_selection` union - PayoutIncomingSchemeSelectionInstantPreferred - `type` 'instant_preferred', required: Automatically select a payment scheme that supports instant payments based on currency and geography, with a fallback to a non-instant scheme if instant payment is unavailable. The `payout_executed` webhook will specify the actual scheme used. This is optimal when slow settlement is not a concern. This is used by default if no `scheme_selection` is provided. - PayoutIncomingSchemeSelectionInstantOnly - `type` 'instant_only', required: Automatically select a payment scheme that supports instant payments based on currency and geography. This is optimal when quick settlement is essential. - PayoutIncomingSchemeSelectionPreselected - `type` 'preselected', required: Specify - `scheme_id` 'faster_payments_service' | 'sepa_credit_transfer_instant' | 'sepa_credit_transfer' | 'polish_domestic_standard' | 'polish_domestic_express', required: Select a payment scheme compatible with the currency and geographic region to avoid payout failures after submission. This helps with payouts by selecting the better-performing scheme between two similar options in a region, based on various criteria. - `sub_merchants` PayoutIncomingSubmerchants: The details related to any applicable sub-merchants, for example a partner you are working with. - `ultimate_counterparty` union - 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) - `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. ## Response `202` Payout - union - PayoutCreatedRegular - `id` string, required: ID of the payout - PayoutCreatedUserDetermined - `id` string, required: ID of the payout - `status` 'authorization_required', required: Status of the created payout. 🚧 Currently, this exists exclusively for `user_determined` payouts, and `authorization_required` is the only possible value; however, future standard payout scenarios may introduce additional statuses. - `resource_token` string, application/jwt, required: A payout token in JWT format, with a limited scope that is authorized to be used with a single payout Only available in payouts with `user_determined` beneficiary type. - `user` PaymentUser, required - `id` string, required: Unique ID for the User ## 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)