> ## 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. > ## Agent Instructions > Money amounts are always major-unit decimal strings (e.g. "1000.00"), never floats and never minor units, in every request, response, and webhook payload. > Authentication is OAuth 2.0 client credentials: exchange the Client ID and Client Secret at the Token URL for a 24-hour JWT and cache it; do not request a token per call. > Set a unique clientRef on every money-moving request; it is the idempotency key, and retries return the original resource. > Quotes are single-use, intent-locked, and expire fast: always read expiresAt, consume the quote with the executor matching its intent, and re-quote on expiry instead of retrying. > Prefer webhooks over polling for payout, order, application, and virtual-account status tracking. > Use the sandbox (api.sandbox.zuba.com) with its deterministic magic values before touching production. # Get the field requirements for a payout corridor > Returns what a payout into a corridor requires of both parties: the beneficiary fields and the `senderInfo` keys that must and may be provided, reported for an individual and for a business of each party so a caller never has to declare one type to learn the other. Pass `route` (and, for mobile money or SWIFT, `country`) to narrow the answer to one corridor; without them it is combined across every rail serving the currency, so satisfying it satisfies the most demanding one. For the recipient it also reports the rules a field value must satisfy, such as an individual name that must split into a first and a last name, as a pattern to validate against before submitting. Each rule is enforced at submit with a 400 naming the field and carrying a stable code; without `route`, a combined rule is enforced only where the provider that pays out applies it. ## OpenAPI ````yaml /openapi.json get /v2/payouts/requirements 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: Per-country bank directories and bank-account enquiries name: Banks - 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: /v2/payouts/requirements: get: tags: - Payouts summary: Get the field requirements for a payout corridor description: >- Returns what a payout into a corridor requires of both parties: the beneficiary fields and the `senderInfo` keys that must and may be provided, reported for an individual and for a business of each party so a caller never has to declare one type to learn the other. Pass `route` (and, for mobile money or SWIFT, `country`) to narrow the answer to one corridor; without them it is combined across every rail serving the currency, so satisfying it satisfies the most demanding one. For the recipient it also reports the rules a field value must satisfy, such as an individual name that must split into a first and a last name, as a pattern to validate against before submitting. Each rule is enforced at submit with a 400 naming the field and carrying a stable code; without `route`, a combined rule is enforced only where the provider that pays out applies it. operationId: PayoutRequirementsV2Controller_getRequirements parameters: - description: Destination currency (e.g. NGN, EUR, USD, GBP) in: query name: currency required: true schema: example: EUR pattern: ^[A-Za-z]{3,10}$ type: string - description: >- The rail the payout will take, as sent on POST /v1/payouts. Narrows both parties to the rules of that corridor: without it the answer is combined across every rail serving the currency, so satisfying it satisfies the most demanding one. in: query name: route required: false schema: enum: - sepa_inst - sepa_credit - bank_transfer - ach - fedwire - swift - crypto - mobile_money example: swift type: string - description: >- An ISO 3166-1 alpha-2 country code. With `route=mobile_money` it is the destination country, and narrows rules that apply to one country of a currency, such as the sender phone a mobile-money payout into Cameroon carries. With `route=swift` it is the beneficiary's country, which decides the provider that pays out and so the recipient `rules` that apply. Ignored on any other rail, and ignored when no `route` is named. in: query name: country required: false schema: example: CM pattern: ^[A-Za-z]{2}$ type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PayoutRequirementsDto' description: Field requirements for both parties of a payout into the corridor '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponseDto' description: Missing or malformed currency, unknown route, or malformed country '401': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: >- No provider serves the currency, the currency over the named route, mobile money into the named country, or international transfer to the named country '429': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: Rate limit exceeded security: - bearer: [] components: schemas: PayoutRequirementsDto: properties: beneficiary: allOf: - $ref: '#/components/schemas/BeneficiaryRequirementsDto' description: >- What the recipient must and may carry, for each recipient type: the fields that must and may be provided, and the rules their values must satisfy, such as a corridor that addresses an individual recipient by first and last name separately. sender: allOf: - $ref: '#/components/schemas/SenderRequirementsDto' description: >- What the originator must and may carry, for each sender type, and whether `senderInfo` can be omitted at all. required: - beneficiary - sender type: object ValidationErrorResponseDto: properties: details: description: Array of detailed validation errors example: - field: accounts.0.data message: crAccount must be exactly 10 digits for Nigerian accounts items: $ref: '#/components/schemas/ValidationErrorDetailDto' type: array error: description: Error type identifier example: BAD_REQUEST type: string message: description: >- The `details` messages joined with `; `, so a client that reads only this field still sees every failing field example: crAccount must be exactly 10 digits for Nigerian accounts type: string path: description: Request path that generated the error example: /v1/resource 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 GenericErrorResponseDto: properties: error: description: Error type identifier example: BAD_REQUEST type: string message: description: Error message example: Bad Request type: string path: description: Request path that generated the error example: /v1/resource 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 type: object BeneficiaryRequirementsDto: properties: business: allOf: - $ref: '#/components/schemas/BeneficiaryFieldsDto' description: >- Requirements for a business recipient, identified by its legal name in `name` and never asked for a date of birth. individual: allOf: - $ref: '#/components/schemas/BeneficiaryFieldsDto' description: >- Requirements for an individual recipient. `dateOfBirth` is required on a crypto corridor while Travel Rule screening is enabled. required: - individual - business type: object SenderRequirementsDto: properties: business: allOf: - $ref: '#/components/schemas/SenderFieldsDto' description: Requirements for a business originator. individual: allOf: - $ref: '#/components/schemas/SenderFieldsDto' description: Requirements for an individual originator. senderInfoRequired: description: >- Whether the payout must carry a `senderInfo` block. When false, omitting it attributes your own workspace as a business originator. When true, the corridor requires a field the workspace identity cannot carry, such as the sender phone on a mobile-money payout into Cameroon. example: false type: boolean required: - senderInfoRequired - individual - business type: object ValidationErrorDetailDto: properties: code: description: >- Stable machine-readable code for client-side branching. Present on structural-validation failures of the recipient (e.g. MISSING_BENEFICIARY_NAME, INVALID_IBAN, BENEFICIARY_INCOMPLETE) and of the sender (SENDER_INFO_INCOMPLETE, SENDER_INFO_INVALID); absent on generic DTO validation errors. example: MISSING_BENEFICIARY_NAME type: string field: description: >- The field path that failed validation. A bank account format rule reports the account object it checked (e.g. accounts.0.data) and names each failing field in its message. example: accounts.0.data type: string message: description: Human-readable error message describing the validation failure example: crAccount must be exactly 10 digits for Nigerian accounts type: string required: - field - message type: object BeneficiaryFieldsDto: properties: optional: description: >- Beneficiary fields that may optionally be provided. Every field named here is accepted by POST /v1/beneficiaries. example: - email - addressLine2 - countrySubdivision - dateOfBirth items: enum: - email - address - addressLine2 - city - postcode - countrySubdivision - dateOfBirth type: string type: array required: description: >- Beneficiary fields that must be provided. `name`, `country` and `accounts` are always required and are not listed here. example: - address - city - postcode items: enum: - email - address - addressLine2 - city - postcode - countrySubdivision - dateOfBirth type: string type: array rules: description: >- Constraints on the shape of a field value on this corridor, each enforced at submit with a 400 naming the field. Empty when the corridor constrains no value beyond presence. Without `route` this is combined across every provider serving the currency, and on `route=swift` without `country` across the providers that can pay out over SWIFT; a combined rule is enforced only where the provider that pays out applies it. With `route`, `required` and `optional` come from the providers in default routing on that rail, while `rules` come from the providers whose value checks run at submit, so the two may reflect different providers on a rail served only outside default routing. items: $ref: '#/components/schemas/BeneficiaryFieldRuleDto' type: array required: - required - optional - rules type: object SenderFieldsDto: properties: optional: description: >- Keys of `senderInfo` that may optionally be provided. A key in neither list is not part of this sender's shape: it is dropped from the stored sender identity, and `dateOfBirth` on a business sender is refused outright. example: - dateOfBirth - address - postalCode - city - country - phoneNumber - fundOrigin - gender items: enum: - firstName - lastName - dateOfBirth - companyName - registrationNumber - address - postalCode - city - country - phoneNumber - fundOrigin - gender type: string type: array required: description: >- Keys of `senderInfo` that must be provided when you supply a `senderInfo` block of this type. They come from the checks a payout is put through, so a payout carrying every one of them, together with the `senderInfo.type` this list is reported for, is not refused for an incomplete sender. See `senderInfoRequired` for whether the block can be omitted altogether. example: - firstName - lastName items: enum: - firstName - lastName - dateOfBirth - companyName - registrationNumber - address - postalCode - city - country - phoneNumber - fundOrigin - gender type: string type: array required: - required - optional type: object BeneficiaryFieldRuleDto: properties: description: description: >- What the rule asks for, suitable to show beside the field when a value does not match. example: >- An individual recipient needs a first and a last name, separated by a space. type: string field: description: The beneficiary field the rule constrains. enum: - name example: name type: string pattern: description: >- An ECMAScript regular expression, without delimiters or flags, that a value satisfying the rule matches. Test the value exactly as it will be submitted. example: ^[^\S ]*\S[^ ]* \s*\S[\s\S]*$ type: string required: - field - pattern - description type: object securitySchemes: bearer: bearerFormat: JWT description: Enter Auth0 JWT token scheme: bearer type: http ````