--- title: "Initiate Payout" method: POST path: "/payment/v1/payouts" tags: ["Fiat Payments"] deprecated: true --- # Initiate Payout `POST /payment/v1/payouts` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/payment/v1/payouts` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) > **Deprecated.** Creates a fiat payout with an existing beneficiary or by adding a new one. ## Headers - `X-Idempotency-Key` string, uuid, required ## Request body - UnifiedPayoutRequest - `walletId` string, required: Your debit wallet ID associated with the transaction. - `amount` Money, required - `value` number, float, required: Transfer amount in major currency units. - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code. - `paymentReference` string, required: Custom identifier supplied for a transaction. It is used to link a transaction to a specific customer or use case. Note that the value is visible to the beneficiary. Only whitespaces, alphanumeric characters (a-z, A-Z, 0-9), commas (,) and periods (.). For `ACH` and `ACH_SAME_DAY` payouts, the value must have a maximum length of 10 characters. - `instruction` object, required - `type` 'FIAT', required: The type of the instruction. Currently only 'FIAT' is supported. - `paymentMethod` 'ACH' | 'ACH_SAME_DAY' | 'SEPA_CT' | 'SEPA_INST' | 'FEDWIRE' | 'RTP' | 'FEDNOW': Payment method when sending out of USA. 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 `amount.currency`, you can select the following `paymentMethod` in `instruction`: - `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` object, required - `details` PayoutBeneficiaryDetails - `beneficiaryType` 'SELF_OWNED' | 'THIRD_PARTY', required: Type of the beneficiary. - `transferDestination` 'INTERNATIONAL' | 'LOCAL', required: Transfer destination of the beneficiary. - `LOCAL` for GBP (FPS), EUR (SEPA/SEPA Instant), and USD (ACH, ACH_SAME_DAY, and Fedwire). - `INTERNATIONAL` for EUR and USD via SWIFT. - `currency` 'USD' | 'EUR' | 'GBP', required: Currency code for the beneficiary. - `individualDetails` IndividualDetails - `firstName` string, required: First name of the individual. - `lastName` string, required: Last name of the individual. - `dateOfBirth` string, required: Date of birth in the 'dd/MM/yyyy' format. - `businessDetails` object - `businessName` string, required: Name of the recipient's business. - `companyRegistrationNumber` string: Registration number of the business. - `address` PayoutRequestAddress, 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. - `city` string, required: Recipient's city of the address. - `country` string, required: Recipient's country code. - `postCode` string: Postal or ZIP code of the recipient's address. - `bankDetails` BankDetails, required - `accountNumber` string: Recipient's bank account number. - `code` string: Recipient's bank or branch code. - `address` Address - `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. - `city` string: Recipient's city of the address. - `country` string, required: Recipient's country code. - `postCode` string: Postal or ZIP code of the recipient's address. - `accountType` 'CHEQUE' | 'SAVINGS' | 'TRANSMISSION': Type of bank account. - `bankTypeIdentifier` 'SCAN' | 'IBAN' | 'SWIFT' | 'ABA' | 'CUBIX' | 'UNKNOWN': Bank account type identifier. - `intermediaryBanks` IntermediaryBank[]: List of intermediary banks. - `bankName` string: Name of the bank. - `code` string, required: Bank code or branch code. - `address` Address - … - `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 `200` Created - UnifiedPayoutResponse - `transactionReference` string, uuid: Unique identifier for the transaction. - `paymentReference` string: Unique payment reference used to link a transaction to a specific customer or use case. The value is visible to the beneficiary. - `amount` Money - `value` number, float, required: Transfer amount in major currency units. - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code. - `fee` Money - `value` number, float, required: Transfer amount in major currency units. - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code. - `walletId` string: Identifier for your debit wallet associated with the transaction. - `status` 'PENDING_APPROVAL' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'RETURNED' | 'ON_HOLD': The status of the transaction. The PENDING_APPROVAL status is only relevant for **fiat payouts**. - `createdAt` string, date-time: Timestamp when the transaction was created. - `details` UnifiedPayoutDetails - `type` 'FIAT' | 'CRYPTO': Type of the payout. - `beneficiary` object - `entityType` 'INDIVIDUAL' | 'COMPANY': The type of entity, either INDIVIDUAL or COMPANY. - `companyDetails` CompanyDetails: Details of the company - `name` string, required: Name of the company. - `individualDetails` IndividualDetails - `firstName` string, required: First name of the individual. - `lastName` string, required: Last name of the individual. - `dateOfBirth` string, required: Date of birth in the 'dd/MM/yyyy' format. - `address` object: Address of the recipient. - `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: State or region of the address. - `city` string: City of the recipient's address. - `countryCode` string: Country code of the recipient's address. - `postCode` string: Postal or ZIP code of the recipient's address. - `fullAddress` string: Full address. - `bankAccount` BankAccount - `format` 'SCAN' | 'IBAN' | 'SWIFT' | 'ABA' | 'CUBIX': Format of the bank account number. - `bankName` string: Name of the bank associated with the account. - `accountNumber` string: Bank account number. - `bankCode` string: Bank or branch SWIFT/BIC code. - `bankAddress` object: Address of the bank. - `addressLine1` string: Primary address line. - `addressLine2` string: Secondary address line. - `region` string: State or region of the address. - `city` string: City of the address. - `countryCode` string: Country code. - `postCode` string: Postal or ZIP code of the address. - `fullAddress` string: Full address. - `correspondentBic` string: Correspondent bank BIC 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. ## Other responses - `400`: Bad request - `403`: Forbidden ## Changes - **2026-11-06** `c386d436bf2c`: 1 info - endpoint added [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v1/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)