--- title: "Initiate payout" method: POST path: "/payment/v2/payouts" tags: ["Fiat Payments"] --- # Initiate payout `POST /payment/v2/payouts` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/payment/v2/payouts` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a payout to business or individual customers. In case of payment in Euro, the transaction is subject to **Verification of Payee** (VoP): if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the status 202 Verification Failed is returned. To proceed with the payment, you must [Confirm Beneficiary's name](https://docs.bvnk.com/bvnk/api-explorer/endpoints/payout-confirm-beneficiary-v-2). For the details, refer to the [Initiate Payouts](https://docs.bvnk.com/bvnk/use-cases/virtual-accounts/send-payment-via-va) guide. We recommend sending as much beneficiary and bank information as you can. Complete details help correspondent banks and payment networks process the payout and reduce the risk of delays or rejections. ## Headers - `Idempotency-Key` string, uuid, required - `X-Verification-Id` string, uuid ## Request body - PayoutRequest - `walletId` string, required: Identifier for your debit wallet associated with the transaction - `amount` number, float, required: Payout amount in major currency units - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code. The following payment `method` is supported for each currency: - USD: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `FEDNOW`, `SWIFT`, or `RTP`. Use `SWIFT` for international payouts and the other methods for domestic transactions. - EUR: `SEPA_CT`, `SEPA_INST`, or `SWIFT` - GBP: `FASTER_PAYMENT` `BOOK` is also available for all three currencies, for transfers between accounts within the same financial institution. - `reference` string: Internal identifier that is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment. The field is for information purposes only. It will be fully supported in future releases. - `method` 'ACH' | 'ACH_SAME_DAY' | 'SEPA_CT' | 'SEPA_INST' | 'FEDWIRE' | 'FASTER_PAYMENT' | 'BOOK' | 'SWIFT' | 'RTP' | 'FEDNOW': Payment method when sending out of USA. The field is mandatory for the `USD` payouts and optional for other currencies. If not provided, the optimal payment method is selected automatically based on dynamically determined attributes. If you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred. When `EUR` is set in `currency`, you can select the following payment `method`: - `SEPA_CT`: Standard SEPA bank transfer. Payment processing time is 1-2 business days. - `SEPA_INST`: Instant bank transfer. Funds arrive in seconds, 24/7. May incur a small fee. - `beneficiary` BeneficiaryRequest, required - `remittanceInformation` string, required: Payment reference sent to the beneficiary. Can contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols. Other allowed characters and number of symbols vary depending on the used payment method or currency. Cannot be "null" or empty string. - `entity` union, required - IndividualRequest - `type` 'INDIVIDUAL', required: Entity type. Always present. - `firstName` string, required: First name - `lastName` string, required: Last name - `dateOfBirth` string: Date of birth in DD-MM-YYYY format - `address` BeneficiaryRequestAddress, required: Address of the beneficiary provided in a payout request. To maximise Straight-Through Processing (STP) rates, we strongly recommend providing the most complete address available. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string, required: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string, required: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - CompanyRequest - `type` 'COMPANY', required: Entity type. - `legalName` string, required: Legal company name - `address` BeneficiaryRequestAddress, required: Address of the beneficiary provided in a payout request. To maximise Straight-Through Processing (STP) rates, we strongly recommend providing the most complete address available. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string, required: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string, required: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - `bankAccount` BankAccountV2, required - `accountNumber` string, required: Bank account number. - `accountType` 'CHEQUE' | 'CHECKING' | 'SAVINGS' | 'TRANSMISSION': Type of bank account. Mandatory for the `USD` payouts. - `bank` BankV2, required - `identificationCode` string: Bank identification code (SWIFT/BIC). Mandatory for non-IBAN accounts, for example, use it as a routing number for local `USD` payments. Optional for local payments in EUR. - `nid` string: National bank identifier. For the SWIFT USD payments, this is the account routing number: a nine-digit code that identifies your specific financial institution for electronic transactions. Mandatory for the Swift USD payments. We recommend providing `nid` at any time, as some banks may not process the payments without it. - `address` object: Bank branch address. For SWIFT payments, `addressLine1`, `city`, `postCode`, and `country` are required. - `addressLine1` string: Bank branch primary address line. - `addressLine2` string: Bank branch secondary address line. - `region` string: Bank branch state or region. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Bank branch city. - `country` string, required: Bank branch country code. - `postCode` string: Postal or ZIP code of the bank branch. - `intermediaryBanks` BankV2[]: List of intermediary banks. - `identificationCode` string: Bank identification code (SWIFT/BIC). Mandatory for non-IBAN accounts, for example, use it as a routing number for local `USD` payments. Optional for local payments in EUR. - `nid` string: National bank identifier. For the SWIFT USD payments, this is the account routing number: a nine-digit code that identifies your specific financial institution for electronic transactions. Mandatory for the Swift USD payments. We recommend providing `nid` at any time, as some banks may not process the payments without it. - `address` object: Bank branch address. For SWIFT payments, `addressLine1`, `city`, `postCode`, and `country` are required. - `addressLine1` string: Bank branch primary address line. - `addressLine2` string: Bank branch secondary address line. - `region` string: Bank branch state or region. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Bank branch city. - `country` string, required: Bank branch country code. - `postCode` string: Postal or ZIP code of the bank branch. - `fees` object - `customerFee` object - `amount` number, float: Transfer amount in major currency units. - `currency` 'USD' | 'EUR' | 'GBP': Three-letter ISO-4217 currency code. - `metadata` Metadata: Custom metadata key-value pairs. Structure: key: value. Restrictions: - Maximum five keys. - Each key maximum length 50 characters. - Each value maximum length 100 characters. - Keys and values must be simple strings. - `requestDetails` RequestDetails - `originator` object, required: Originator details. - `ipAddress` string: The IP address of the customer initiating the payout. Only required when you make a payment from a customer's wallet. ## Response `201` Payment accepted for processing. - PayoutResponse - `id` string, uuid, required: Unique payout identifier. - `method` 'SEPA_CT' | 'SEPA_INST' | 'FASTER_PAYMENT' | 'BACS' | 'TARGET2' | 'TIPS' | 'SWIFT' | 'ACH' | 'ACH_SAME_DAY' | 'FEDWIRE' | 'FEDNOW' | 'RTP' | 'BOOK' | 'UNKNOWN' | 'BANK_TRANSFER' | 'WIRE' | 'SEPA', required: Payment method used in the transaction. Note: This list can be changed in the future. - `reference` string: Free text reference provided during payout creation (used mostly for reconciliation reasons). - `status` 'PENDING' | 'PROCESSING' | 'PENDING_APPROVAL' | 'ON_HOLD' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED' | 'RETURNED', required: Current payout status: - `PENDING_APPROVAL`: Payouts from the wallet require approval. The payout stays in this status until all approvals are received, then moves to `PROCESSING`. Only relevant for fiat payouts. - `PROCESSING`: Waiting for a final response from BVNK's processing partners. - `ON_HOLD`: Screening is taking longer than anticipated. - `COMPLETED`: The payout is complete on BVNK's side. The beneficiary bank may still reject the funds. - `FAILED`: The processing partners couldn't complete the payout. The funds remain in your wallet. - `CANCELLED`: The payout was cancelled, for example because a four-eyes approval was rejected or timed out. The funds are returned to your wallet. - `RETURNED`: The funds came back after the processing partners responded. The funds are returned to your wallet. - `fees` FeesResponse, required - `customerFee` MoneyFeeV2 - `amount` number, required: Fee amount in fiat or crypto currency units. - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and cryptocurrencies. - `processingFee` MoneyFeeV2, required - `amount` number, required: Fee amount in fiat or crypto currency units. - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and cryptocurrencies. - `originator` object, required - `amount` number, float, required: Amount of the payout. - `currency` string, required: Currency of the payout. - `walletId` string, required: The ID of the originator's wallet associated with the payout. - `customerId` string: The ID of the originator's customer associated with the payout. - `entity` union, required - Individual - `type` 'INDIVIDUAL', required: Entity type. Always present. - `firstName` string, required: First name - `lastName` string, required: Last name - `dateOfBirth` string: Date of birth in DD-MM-YYYY format - `address` BeneficiaryAddress: Address of the beneficiary. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - Company - `type` 'COMPANY', required: Entity type. - `legalName` string, required: Legal company name - `address` BeneficiaryAddress: Address of the beneficiary. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - `beneficiary` BeneficiaryResponse, required - `remittanceInformation` string, required: Payment reference information. Can contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols. Other allowed characters vary depending on the used payment method or currency. Always required for payouts. - `amount` number, float, required: Amount received by the beneficiary. - `currency` string, required: Currency of the transaction received by the beneficiary. - `entity` union, required - Individual - `type` 'INDIVIDUAL', required: Entity type. Always present. - `firstName` string, required: First name - `lastName` string, required: Last name - `dateOfBirth` string: Date of birth in DD-MM-YYYY format - `address` BeneficiaryAddress: Address of the beneficiary. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - Company - `type` 'COMPANY', required: Entity type. - `legalName` string, required: Legal company name - `address` BeneficiaryAddress: Address of the beneficiary. At a minimum, the following fields are always required: - `addressLine1` - `city` - `country` Additional address fields may be mandatory depending on the payment method. For example: - Fedwire, FedNow, RTP, ACH and ACH_SAME_DAY (US local rails): `postCode` and `region` - SWIFT: `postCode` **Important**: `city`, `region`, `country`, and `postCode` must be provided in their dedicated fields and not repeated in `addressLine1` or `addressLine2`. Including these values in the address lines may cause payment rejection for certain payment methods. - `addressLine1` string: Recipient's primary address line. Typically contains the street name and building number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `addressLine2` string: Recipient's secondary address line. Typically contains additional details such as apartment, suite, or floor number. Do not include the city, country, region/state, or postal code in this field; these values must be provided in their respective dedicated fields. - `region` string: Recipient's state or region of the address. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Recipient's city of the address. - `country` string, required: Recipient's two-letter country code in the ISO 3166-1 alpha-2 format. - `postCode` string: Postal or ZIP code of the recipient's address. - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type. - `bankAccount` BankAccountV2 - `accountNumber` string, required: Bank account number. - `accountType` 'CHEQUE' | 'CHECKING' | 'SAVINGS' | 'TRANSMISSION': Type of bank account. Mandatory for the `USD` payouts. - `bank` BankV2, required - `identificationCode` string: Bank identification code (SWIFT/BIC). Mandatory for non-IBAN accounts, for example, use it as a routing number for local `USD` payments. Optional for local payments in EUR. - `nid` string: National bank identifier. For the SWIFT USD payments, this is the account routing number: a nine-digit code that identifies your specific financial institution for electronic transactions. Mandatory for the Swift USD payments. We recommend providing `nid` at any time, as some banks may not process the payments without it. - `address` object: Bank branch address. For SWIFT payments, `addressLine1`, `city`, `postCode`, and `country` are required. - `addressLine1` string: Bank branch primary address line. - `addressLine2` string: Bank branch secondary address line. - `region` string: Bank branch state or region. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Bank branch city. - `country` string, required: Bank branch country code. - `postCode` string: Postal or ZIP code of the bank branch. - `intermediaryBanks` BankV2[]: List of intermediary banks. - `identificationCode` string: Bank identification code (SWIFT/BIC). Mandatory for non-IBAN accounts, for example, use it as a routing number for local `USD` payments. Optional for local payments in EUR. - `nid` string: National bank identifier. For the SWIFT USD payments, this is the account routing number: a nine-digit code that identifies your specific financial institution for electronic transactions. Mandatory for the Swift USD payments. We recommend providing `nid` at any time, as some banks may not process the payments without it. - `address` object: Bank branch address. For SWIFT payments, `addressLine1`, `city`, `postCode`, and `country` are required. - `addressLine1` string: Bank branch primary address line. - `addressLine2` string: Bank branch secondary address line. - `region` string: Bank branch state or region. If the region is a US state, provide the two-letter state code (minimum and maximum length is 2 characters), for example, `NY`. - `city` string: Bank branch city. - `country` string, required: Bank branch country code. - `postCode` string: Postal or ZIP code of the bank branch. - `metadata` Metadata, required: Custom metadata key-value pairs. Structure: key: value. Restrictions: - Maximum five keys. - Each key maximum length 50 characters. - Each value maximum length 100 characters. - Keys and values must be simple strings. - `createdAt` string, date-time, required: Creation timestamp. - `updatedAt` string, date-time, required: Last update timestamp. - `type` 'payment:payout:fiat', required: Payment type constant. - `direction` 'OUT', required: Payment direction constant. - `trackingDetails` object[]: External identifiers for the payment transaction, including tracking references for different payment methods. These can be used to trace transactions across global payment networks such as Fedwire and ACH. - `externalTransactionId` string: External identifier for the payout. - `imad` string: Input Message Accountability Data. Used as the originator's tracking reference for WIRE transfers. Generated by the sending bank when a wire transfer is initiated in the US banking system. - `omad` string: Output Message Accountability Data. Used as beneficiary's tracking reference for WIRE transfers. Generated by the receiving bank upon delivery of a wire transfer in the US banking system. - `traceNumber` string: Payment reference used for ACH payments. - `uetr` string: Unique End-to-End Transaction Reference. Used in SWIFT payments. Remains consistent throughout the entire international payment journey across all participating banks. ## Other responses - `202`: Confirmation required. - `400`: Bad request. - `403`: Forbidden. - `404`: Not found. - `422`: Unprocessable entity. ## Changes - **2026-11-06** `c386d436bf2c`: 4 breaking, 5 warning, 4 info - removed `#/components/schemas/Individual, #/components/schemas/Company` from the `beneficiary/entity` request property `oneOf` list - the `beneficiary/entity/oneOf[#/components/schemas/Individual]/dateOfBirth` response's property format changed from `date` to no format for status `201` - the `originator/entity/oneOf[#/components/schemas/Individual]/dateOfBirth` response's property format changed from `date` to no format for status `201` - removed the required property `Id` from the response with the `202` status - …9 more - **2026-06-16** `97d6c0d2fe2e`: 2 breaking, 1 warning, 5 info - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `3` to `36` - the `beneficiary/remittanceInformation` request property's maxLength was decreased to `34` - changed the pattern of the request property `beneficiary/remittanceInformation` from `^[A-Za-z0-9.,\-\s]+$` to `^[a-zA-Z0-9\s,.-]{5,34}$` - added the media type `application/json` for the response with the status `400` - …4 more [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v2/payouts/post.md) --- [API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)