> ## Documentation Index > Fetch the complete documentation index at: https://docs.zuba.com/llms.txt > Use this file to discover all available pages before exploring further. # Create one or multiple payouts > Create a single payout or batch of payouts. Send a single payout object or an array of payout objects. The source currency can be specified via inputCurrency field, or will be automatically selected from the currency with the largest available balance. When the beneficiary is supplied inline (no `beneficiary.id`), the beneficiary is resolved idempotently: if any account matches an existing active beneficiary for this client, the existing beneficiary is reused and no duplicate row is created. ## OpenAPI ````yaml /openapi.json post /v1/payouts openapi: 3.0.0 info: contact: {} description: >- Comprehensive payment platform API supporting fiat and crypto payments, currency conversion, and compliance management title: Zuba Payment Platform API version: '1.0' servers: [] security: [] tags: - description: Manage M2M API keys and credentials name: API Keys - description: Internal ledger accounts and transactions name: Ledger - description: Handle incoming payments and deposits name: Pay-ins - description: Manage payouts, beneficiaries, and SEPA transfers name: Payouts - description: Manage outbound webhook endpoints and deliveries name: Webhooks paths: /v1/payouts: post: tags: - Payouts summary: Create one or multiple payouts description: >- Create a single payout or batch of payouts. Send a single payout object or an array of payout objects. The source currency can be specified via inputCurrency field, or will be automatically selected from the currency with the largest available balance. When the beneficiary is supplied inline (no `beneficiary.id`), the beneficiary is resolved idempotently: if any account matches an existing active beneficiary for this client, the existing beneficiary is reused and no duplicate row is created. operationId: PayoutController_createPayouts parameters: - description: >- Client-generated key scoped per workspace. A repeat with the same key and the same request body replays the original response without creating a second payout. A repeat with the same key and a different body is rejected (422). A repeat while the first request is still in flight returns a retryable 409. Keys expire 24 hours after the original request completes; a repeat after expiry is treated as a new request. in: header name: Idempotency-Key required: false schema: type: string requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreatePayoutDto' - items: $ref: '#/components/schemas/CreatePayoutDto' type: array description: Single payout object or array of payout objects required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PayoutDto' description: |- Multiple payouts created Single payout created '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponseDto' description: >- SWIFT_UNAVAILABLE | RAIL_UNAVAILABLE - Rail unavailable for this corridor QUOTE_REQUIRED | QUOTE_NOT_FOUND | QUOTE_MISMATCH | AMOUNT_OUT_OF_BOUNDS | QUOTE_ALREADY_USED | QUOTE_EXPIRED - Cross-rate quote validation failed Validation failed - invalid payout data '401': description: Unauthorized '409': description: >- IDEMPOTENCY_KEY_PROCESSING - a request with the same Idempotency-Key is still in flight (retryable) '422': description: >- IDEMPOTENCY_KEY_REUSED - the Idempotency-Key was reused with a different request body '500': description: Internal Server Error security: - bearer: [] components: schemas: CreatePayoutDto: properties: amount: description: >- Amount to be paid out (as string to avoid floating-point precision issues) example: '100.50' pattern: ^[0-9]+(.[0-9]{1,8})?$ type: string beneficiary: allOf: - $ref: '#/components/schemas/CreateBeneficiaryDto' description: >- Beneficiary information. RECOMMENDED: Reference an existing beneficiary by providing just the ID (e.g., {"id": "uuid"}). Alternatively, provide the full beneficiary object with account details to create a new one inline. example: id: cc82fa1d-fc7a-478c-a734-d3bce40464e7 clientRef: description: Client reference for idempotency (max 100 characters) example: PAYOUT-REF-12345 maxLength: 100 type: string comment: description: Comment for the payout example: Monthly salary payment maxLength: 500 type: string currency: description: >- Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS - ZMW - MZN - MWK - EGP example: EUR type: string description: description: Optional description of the payout (max 500 characters) example: Payment for services rendered maxLength: 500 type: string externalSenderId: description: >- External sender (originator) reference. Used as the crypto Travel Rule originator id; defaults to your client id when omitted. example: SENDER-123 maxLength: 100 type: string inputCurrency: description: >- Input currency to debit from (optional). If provided, this currency will be used as the source for the payout. If not provided, the system will automatically select the currency with the largest available balance (balance minus pending transactions). Defaults to USD if no balances are found. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS example: EUR type: string invoiceId: description: Invoice ID associated with the payout example: INV-2024-001 maxLength: 100 type: string purpose: description: Purpose of the payout example: salary maxLength: 100 type: string purposeOfPaymentDocumentKey: description: >- S3 key of the uploaded purpose-of-payment document. REQUIRED for SWIFT payouts. Obtain it from POST /v1/payouts/pop-documents/upload-url. example: >- pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf maxLength: 512 type: string quoteId: description: >- Cross-rate FX quote ID. Required for cross-currency payouts in supported corridors (e.g., NGN->GBP). Optional for same-currency payouts. example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string reference: description: Optional reference for the payout (max 140 characters) example: PAYOUT-2024-001 maxLength: 140 type: string route: description: Payment route to use enum: - sepa_inst - sepa_credit - bank_transfer - ach - fedwire - swift - crypto - mobile_money example: sepa_inst type: string senderInfo: allOf: - $ref: '#/components/schemas/SenderInfoDto' description: >- Sender (originator) information. Used as the originator identity for the crypto Travel Rule, and required for card payouts. If omitted, the workspace (your account) is used as the business originator — so supply this only when paying out on behalf of a distinct third party. required: - clientRef - amount - currency - route - beneficiary type: object PayoutDto: properties: amount: description: >- Amount of the payout (as string to avoid floating-point precision issues) example: '100.50' type: string balanceAfter: description: >- Account balance after this transaction (in input currency, e.g., EUR) example: '98.87' type: string beneficiary: allOf: - $ref: '#/components/schemas/BeneficiaryDto' description: Beneficiary information example: accounts: - createdAt: '2024-01-15T10:30:00Z' currency: EUR data: bic: DEUTDEFF iban: DE89370400440532013000 id: 123e4567-e89b-12d3-a456-426614174000 status: active type: iban updatedAt: '2024-01-15T10:35:00Z' createdAt: '2024-01-15T10:30:00Z' email: john.doe@example.com id: 123e4567-e89b-12d3-a456-426614174000 name: John Doe status: active updatedAt: '2024-01-15T10:35:00Z' clientRef: description: >- Client-supplied idempotency reference provided at payout creation. Stable across retries and the natural lookup key for support / reconciliation. Absent on provider-synthesized DTOs (e.g. webhook callbacks) where the original client ref is not in scope. example: PAYOUT-REF-12345 maxLength: 100 type: string completedAt: description: Completion timestamp example: '2024-01-15T10:40:00Z' format: date-time type: string createdAt: description: Creation timestamp example: '2024-01-15T10:30:00Z' format: date-time type: string currency: description: >- Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS example: EUR type: string description: description: Description of the payout example: Payment for services rendered type: string failureCategory: description: Category of failure for client-facing display enum: - payment_not_approved - recipient_details - amount_issue - technical_error example: payment_not_approved type: string failureReason: description: Reason for failure if payout failed example: Insufficient funds type: string fee: description: >- Fee charged for the payout (as string to avoid floating-point precision issues) example: '2.50' type: string fxRate: description: >- FX rate applied (rate with markup charged to the client, e.g., 970.87 NGN per EUR) example: '970.87378641' type: string id: description: Unique identifier for the payout example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string inputAmount: description: >- Input amount (total amount charged to the client including fee, in input currency) example: '1.13' type: string inputCurrency: description: >- Input currency (the currency debited from the client account). This is determined by the inputCurrency provided in the request, or automatically selected as the currency with the largest available balance, or defaults to USD. For example, EUR when paying out NGN. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS example: EUR type: string payoutAccountData: additionalProperties: true description: Payout account data (JSONB) example: account: 123456789 bankCode: '044' crAccount: '0123456789' type: object payoutAccountId: description: Payout account ID example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string processedAt: description: Processing start timestamp example: '2024-01-15T10:32:00Z' format: date-time type: string providerReference: description: Reference from the payment provider example: TXN123456789 type: string reference: description: >- Optional free-text memo/narration that appears on the recipient side. Use clientRef for idempotency / support lookups. example: January invoice type: string route: description: >- Client-facing payment rail. Provider names are never exposed; a provider-routed transfer reads as a generic rail (e.g. `international`). example: international type: string status: description: Current status of the payout enum: - created - queued - processing - paid - failed - cancelled example: processing type: string txHash: description: >- On-chain transaction hash for crypto payouts, once the transfer is broadcast to the network. Null for non-crypto payouts or before broadcast. example: '0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70' nullable: true type: string type: description: Type of payout enum: - fiat - crypto example: fiat type: string uetr: description: >- SWIFT UETR (Unique End-to-end Transaction Reference) for SWIFT payouts, once the provider exposes it. Null otherwise. example: 4afd0a57-03af-4138-9341-373a78891ea9 nullable: true type: string updatedAt: description: Last update timestamp example: '2024-01-15T10:35:00Z' format: date-time type: string required: - id - amount - currency - route - type - beneficiary - status - fee - createdAt - updatedAt type: object ValidationErrorResponseDto: properties: details: description: Array of detailed validation errors example: - field: accounts.0.data.crAccount message: crAccount must be exactly 10 digits for Nigerian accounts value: '12345678901' items: $ref: '#/components/schemas/ValidationErrorDetailDto' type: array error: description: Error type identifier example: BAD_REQUEST type: string message: description: Error summary message example: Validation failed type: string path: description: Request path that generated the error example: /v1/beneficiaries type: string statusCode: description: HTTP status code example: 400 type: number timestamp: description: ISO timestamp when the error occurred example: '2024-01-15T10:30:00.000Z' type: string required: - statusCode - message - error - timestamp - path - details type: object CreateBeneficiaryDto: properties: accounts: description: Array of payment accounts for this beneficiary example: - currency: EUR data: accountHolderName: John Doe bic: DEUTDEFF iban: DE89370400440532013000 type: iban items: $ref: '#/components/schemas/CreateAccountDto' type: array address: description: Address line 1 of the beneficiary (max 200 characters) example: Hauptstraße 123 maxLength: 200 type: string addressLine2: description: Address line 2 of the beneficiary (max 200 characters) example: Apt 4B, 3rd Floor maxLength: 200 type: string city: description: >- City of the beneficiary. May be required depending on corridor — use GET /v1/payouts/requirements to check. example: Berlin maxLength: 100 type: string country: description: Country code (ISO 3166-1 alpha-2, e.g., "DE", "GB", "US") example: DE maxLength: 2 minLength: 2 type: string countrySubdivision: description: Country subdivision code (e.g., US state code "NY", "CA") example: NY maxLength: 50 type: string dateOfBirth: description: >- Date of birth in YYYY-MM-DD format (individual beneficiaries only). Required for individual crypto counterparties when the Sumsub Travel Rule gate is enabled. example: '1985-05-20' type: string email: description: Email address of the beneficiary example: john.doe@example.com format: email type: string id: description: >- UUID of an existing beneficiary. If provided, other fields are ignored and the existing beneficiary is referenced. example: cc82fa1d-fc7a-478c-a734-d3bce40464e7 format: uuid type: string middleName: description: Middle name of the beneficiary (max 100 characters) example: James maxLength: 100 type: string name: description: Full name of the beneficiary (2-100 characters) example: John Doe maxLength: 100 minLength: 2 type: string notes: description: Optional notes about the beneficiary (max 500 characters) example: Regular client, prefers SEPA Instant maxLength: 500 type: string postcode: description: Postal code of the beneficiary example: '10115' maxLength: 20 type: string type: default: individual description: Beneficiary type. Defaults to "individual" if not provided. enum: - individual - business example: individual type: string required: - name - country - accounts type: object SenderInfoDto: properties: address: description: Sender address example: 123 Main Street type: string city: description: Sender city example: New York type: string companyName: description: Company legal name. Required when type is 'business'. example: Acme Trading Ltd type: string country: description: >- Sender country code (ISO 3166-1 alpha-2). Required when type is 'business' (jurisdiction of incorporation). example: US type: string dateOfBirth: description: Sender date of birth in YYYY-MM-DD format (individual only). example: '1990-01-01' type: string firstName: description: Sender first name. Required when type is not 'business'. example: John type: string lastName: description: Sender last name. Required when type is not 'business'. example: Doe type: string phoneNumber: description: >- Sender (originator) contact phone in international format (with country code, e.g. +237…). Required by some mobile-money corridors. example: '+237650000000' type: string postalCode: description: Sender postal code example: '12345' type: string registrationNumber: description: >- Business registration number. Required when type is 'business'. Used as AML pivot for sanctions/UBO screening. example: '12345678' type: string type: description: Sender type. Defaults to 'individual' when omitted. enum: - individual - business example: individual type: string type: object BeneficiaryDto: properties: accounts: description: Array of associated payment accounts items: $ref: '#/components/schemas/AccountDto' type: array address: description: Address line 1 of the beneficiary example: Hauptstraße 123 type: string addressLine2: description: Address line 2 of the beneficiary example: Apt 4B, 3rd Floor type: string city: description: City of the beneficiary example: Berlin type: string country: description: Country code (ISO 3166-1 alpha-2) example: DE type: string countrySubdivision: description: Country subdivision code (e.g., US state code "NY", "CA") example: NY type: string createdAt: description: ISO timestamp when the beneficiary was created example: '2024-01-15T10:30:00Z' format: date-time type: string dateOfBirth: description: Date of birth in YYYY-MM-DD format (individual beneficiaries only). example: '1985-05-20' type: string email: description: Email address of the beneficiary example: john.doe@example.com type: string id: description: Unique identifier for the beneficiary example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string middleName: description: Middle name of the beneficiary example: James type: string name: description: Full name of the beneficiary example: John Doe type: string notes: description: Notes about the beneficiary example: Regular client, prefers SEPA Instant type: string postcode: description: Postal code of the beneficiary example: '10115' type: string status: description: Beneficiary status enum: - active - inactive - suspended example: active type: string type: description: Beneficiary type enum: - individual - business example: individual type: string updatedAt: description: ISO timestamp when the beneficiary was last updated example: '2024-01-15T10:30:00Z' format: date-time type: string required: - id - name - type - country - accounts - status - createdAt - updatedAt type: object ValidationErrorDetailDto: properties: code: description: >- Stable machine-readable code for client-side branching. Present on provider structural-validation failures (e.g. MISSING_BENEFICIARY_NAME, INVALID_IBAN, BENEFICIARY_INCOMPLETE); absent on generic DTO validation errors. example: MISSING_BENEFICIARY_NAME type: string field: description: The field path that failed validation example: accounts.0.data.crAccount type: string message: description: Human-readable error message describing the validation failure example: crAccount must be exactly 10 digits for Nigerian accounts type: string value: description: The invalid value that was provided (may be omitted for security) example: '12345678901' type: object required: - field - message type: object CreateAccountDto: properties: currency: description: >- Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS example: EUR type: string data: additionalProperties: true description: Account data specific to the account type example: bic: DEUTDEFF iban: DE89370400440532013000 type: object type: description: Type of payment account enum: - iban - card - bank_account - wallet - swift - mobile example: iban type: string required: - type - currency - data type: object AccountDto: properties: createdAt: description: Creation timestamp example: '2024-01-15T10:30:00Z' format: date-time type: string currency: description: >- Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies. enum: - EUR - USD - GBP - USDC - USDT - EURC - NGN - XOF - XAF - GHS example: EUR type: string data: additionalProperties: true description: Account data specific to the account type example: bic: DEUTDEFF iban: DE89370400440532013000 type: object id: description: Unique identifier for the account example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string resolutionStatus: description: >- Resolution status of the account number against the bank (NGN bank accounts only). enum: - unresolved - resolved - invalid example: resolved type: string resolvedAccountName: description: >- Account-holder name returned by the bank when the account was resolved, if available. example: JANE DOE type: string status: description: Status of the account enum: - active - suspended - closed example: active type: string type: description: Type of payment account enum: - iban - card - bank_account - wallet - swift - mobile example: iban type: string updatedAt: description: Last update timestamp example: '2024-01-15T10:35:00Z' format: date-time type: string required: - id - type - currency - data - status - createdAt - updatedAt type: object securitySchemes: bearer: bearerFormat: JWT description: Enter Auth0 JWT token scheme: bearer type: http ````