> ## Documentation Index
> Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payout

> Creates a payout transaction by transferring funds to a specified beneficiary. The required fields in the `recipient` object depend on the destination `currency`.

## Error responses

| **Status** | **Message**                                           | **What it means**                                         | **How to fix**                                                   |
| ---------- | ----------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| 400        | `Insufficient wallet balance for transaction`         | Wallet cannot cover the payout total.                     | Deposit more funds or reduce the amount before retrying.         |
| 400        | `Quotes only last for 10 minutes`                     | The referenced quote expired.                             | Fetch a new quote and submit the payout right away.              |
| 400        | `Invalid country or currency ISO code`                | Payload contains an unsupported corridor combination.     | Use valid ISO codes for corridors enabled on your workspace.     |
| 400        | `Account name mismatch, use account enquiry endpoint` | Account name conflicts with bank enquiry data.            | Run the account enquiry endpoint and mirror its response.        |
| 400        | `Invalid Bank Sortcode`                               | Provided sort code is missing, malformed, or unsupported. | Retrieve the correct sort code from the bank list endpoint.      |
| 400        | `{field_name} cannot be empty`                        | Required recipient attribute missing from the payload.    | Populate every mandatory field before sending the request.       |
| 401        | `API key missing or incorrect`                        | Authentication header missing/invalid.                    | Include the proper `x-api-key` for the environment.              |
| 403        | `IP not whitelisted`                                  | Call originated from an unapproved IP address.            | Add your server IP to the dashboard whitelist.                   |
| 404        | `The requested endpoint does not exist`               | Incorrect path or API version.                            | Ensure you are calling `POST /v2/payout` on the right base URL.  |
| 422        | `Invalid quote ID provided`                           | Quote ID missing, expired, or already consumed.           | Create a new quote and reference its `id`.                       |
| 500        | `Service temporarily unavailable`                     | Backend disruption prevented processing.                  | Retry later with exponential backoff; contact support if needed. |


## OpenAPI

````yaml post /v2/payout
openapi: 3.0.3
info:
  title: meCash API
  version: 3.0.3
  description: >-
    API for meCash services, including FIAT and Ramp operations. This is the
    OpenAPI specification for the meCash API, covering all available endpoints
    for wallet management, currency quotes, and payouts.


    It follows a design-first approach based on OpenAPI 3.0.


    Authentication is handled via an API key passed in the `x-api-key` header.
    Replace `YOUR_API_KEY` with your actual key when making requests.


    Some useful links:

    - [meCash Documentation](https://docs.me-cash.com/)

    - [Authentication Guide](https://docs.me-cash.com/authentication)
servers:
  - url: https://sandboxapi.me-cash.com
    description: Sandbox Server for Testing
security:
  - ApiKeyAuth: []
tags:
  - name: Wallet
    description: Wallet management operations
  - name: Quote
    description: Currency quote operations
  - name: Payout
    description: Payout operations
  - name: Transaction
    description: Transaction management
  - name: Virtual Account
    description: Virtual account operations for static and dynamic accounts
  - name: Bank
    description: Bank account and list operations
  - name: Ramp
    description: Ramp operations for crypto
  - name: Miscellaneous
    description: Utility and miscellaneous operations
  - name: Collection
    description: Mobile money and wallet funding operations
  - name: Bulk Payout
    description: >-
      Bulk transfer operations for sending to multiple beneficiaries in a single
      request
paths:
  /v2/payout:
    post:
      tags:
        - Payout
      summary: Create Payout
      description: >-
        Creates a payout transaction by transferring funds to a specified
        beneficiary. The required fields in the `recipient` object depend on the
        destination `currency`.
      operationId: createPayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
            examples:
              NGN_BankTransfer_Payout:
                summary: Example Payout to Nigeria (NGN) via Bank Transfer
                value:
                  remark: Testing
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  quoteId: 91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx
                  recipient:
                    name: Adeolu Adebayo
                    paymentChannel: BANK_TRANSFER
                    currency: NGN
                    country: NG
                    account:
                      bankName: GT Bank
                      accountNumber: 001040XXXXX
                      sortCode: '058'
              USD_SWIFT_Payout:
                summary: Example Payout to the USA (USD) via SWIFT
                value:
                  recipient:
                    name: James Wilson
                    nickName: Blue
                    gender: M
                    occupation: business entrepreneur
                    type: BUSINESS
                    account:
                      sortCode: '02090'
                      swiftCode: GTBINGLA
                      bankCity: Atlanta
                      accountNumber: '885406477269'
                      bankName: DBS Bank Limited
                      intermediarySwiftCode: CHASUS33XXX
                    sender:
                      name: Test Limited
                      icNumber: '96671733919'
                      nationality: NG
                      address:
                        line1: 12 main st
                      mobileNumber: '+234872272808'
                      occupation: HEALTHCARE
                    paymentChannel: SWIFT_CUSTOMER
                    country: US
                    currency: USD
                  quoteId: 859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  remark: Testing
              EUR_BankTransfer_Payout:
                summary: Example Payout to Europe (EUR) via Bank Transfer
                value:
                  quoteId: a4f7b2c1-ef14-4999-906b-xxxxxxxxxxxxx
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  remark: Testing
                  name: Sam James
                  address: 12 street
                  type: BUSINESS
                  country: DE
                  currency: EUR
                  paymentChannel: BANK_TRANSFER
                  stored: true
                  account:
                    iban: DE89XXXXXXXX3000
                    swiftCode: SWIFT2346
                    accountNumber: '566432345678765'
                    bankName: Best Bank
                    address: 12 brown
              GBP_BankTransfer_Payout:
                summary: Example Payout to the United Kingdom (GBP) via Bank Transfer
                value:
                  quoteId: a4f7b2c1-ef14-4999-906b-xxxxxxxxxxxxx
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  remark: Testing
                  recipient:
                    firstName: Derick
                    lastName: Heaney
                    type: BUSINESS
                    account:
                      bankName: Investment Account
                      sortCode: '040004'
                      address: 8190 Amely Freeway
                      accountNumber: '78355047'
                    paymentChannel: BANK_TRANSFER
                    currency: GBP
                    country: GB
                    stored: true
              CAD_BankTransfer_Payout:
                summary: Example Payout to Canada (CAD) via Bank Transfer
                value:
                  quoteId: f1474828-6a2e-4ee8-8598-xxxxxxxxxxxx
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  remark: test
                  recipient:
                    name: John Chuks
                    address: 12 blue street
                    account:
                      bankName: Bank of Test
                      accountNumber: 23099XXXXX
                      address: bank address
                      sortCode: '890'
                      swiftCode: SWIFT1234
                      transitNumber: '12345'
                    paymentChannel: BANK_TRANSFER
                    currency: CAD
                    country: CA
              CAD_INTERAC_Payout:
                summary: Example Payout to Canada (CAD) via INTERAC
                value:
                  quoteId: 5392890f-cab6-40ee-8db2-xxxxxxxxxx
                  reason: Gift
                  invoice: 4b9b6d30-a2ed-421a-bd69-11536344f071
                  remark: Testing
                  recipient:
                    name: Nettie Wuckert
                    mobileNumber: '6137007875'
                    email: Guiseppe_Wisoky77@example.net
                    type: BUSINESS
                    account: {}
                    paymentChannel: INTERAC
                    currency: CAD
                    country: CA
                    stored: true
              CNY_BankTransfer_Payout:
                summary: NGN to CNY (Bank Transfer)
                value:
                  quoteId: 91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx
                  reason: Gift
                  remark: Testing
                  recipient:
                    name: 张少杰
                    nickName: Mr Lee
                    occupation: HEALTHCARE
                    icNumber: '130132198812201310'
                    relationship: SELF
                    type: BUSINESS
                    account:
                      accountNumber: '6217000130064754343'
                      sortCode: '01026'
                      bankName: BAOSHANG BANK (包商银行)
                      bankCity: SHENZHEN
                    companyName: 龙口市玉杰五金工具有限公司
                    companyIdNumber: 91370681MABU8HLY6N
                    gender: F
                    nationality: CN
                    itemCategory: PRD0003
                    itemType: Pipe Wrench
                    quantity: 100
                    paymentChannel: BANK_TRANSFER
                    currency: CNY
                    country: CN
                    stored: false
              KRW_BankTransfer_Payout:
                summary: NGN to KRW (Bank Transfer) via Bank Transfer
                value:
                  quoteId: b51741c8-05c5-41af-9bbf-582fef04dcb8
                  reason: Gift
                  remark: Testing
                  recipient:
                    name: Min-jun Kim
                    nickName: TestLRQ
                    gender: M
                    mobileNumber: '08012345678'
                    occupation: business entrepreneur
                    countryName: KR
                    type: BUSINESS
                    stored: false
                    account:
                      bankName: KDB산업:Korea Development Bank
                      sortCode: '01462'
                      swiftCode: DBSSSGSGXXX
                      bankCity: Seoul
                      accountNumber: '001299123456'
                    sourceOfFunds: I1
                    paymentChannel: BANK_TRANSFER
                    currency: KRW
                    country: KR
              SGD_BankTransfer_Payout:
                summary: NGN to SGD (Bank Transfer) via Bank Transfer
                value:
                  quoteId: d3b47ced-ff79-436f-a926-2d19b03e9fa6
                  reason: Gift
                  remark: Testing
                  recipient:
                    name: Jayden Tan
                    nickName: TestLRQ
                    gender: M
                    occupation: business entrepreneur
                    countryName: SG
                    type: BUSINESS
                    stored: false
                    account:
                      bankName: DBS Bank
                      sortCode: '00120'
                      swiftCode: DBSSSGSGXXX
                      bankCity: Suntec City
                      accountNumber: '0012345678'
                    sourceOfFunds: I1
                    paymentChannel: BANK_TRANSFER
                    currency: SGD
                    country: SG
              THB_BankTransfer_Payout:
                summary: NGN to THB (Bank Transfer) via Bank Transfer
                value:
                  quoteId: d3b47ced-ff79-436f-a926-2d19b03e9fa6
                  reason: Gift
                  remark: Testing
                  recipient:
                    name: Jayden Tan
                    nickName: TestLRQ
                    gender: M
                    occupation: business entrepreneur
                    countryName: TH
                    type: BUSINESS
                    stored: false
                    account:
                      bankName: DBS Bank
                      sortCode: '00120'
                      swiftCode: DBSSSGSGXXX
                      bankCity: Suntec City
                      accountNumber: '0012345678'
                    sourceOfFunds: I1
                    paymentChannel: BANK_TRANSFER
                    currency: THB
                    country: TH
              MYR_BankTransfer_Payout:
                summary: USD to MYR (Bank Transfer) via Bank Transfer
                value:
                  quoteId: '779997685832'
                  reason: Gift
                  remark: TestMYR
                  recipient:
                    name: Jayden Tan
                    nickName: TestMY
                    type: BUSINESS
                    stored: false
                    account:
                      bankName: Affin Bank Berhad
                      sortCode: '00163'
                      swiftCode: AFFNMYKLXXX
                      accountNumber: '0012345678'
                    sourceOfFunds: I1
                    paymentChannel: BANK_TRANSFER
                    currency: MYR
                    country: MY
              VND_BankTransfer_Payout:
                summary: USD to VND (Bank Transfer) via Bank Transfer
                value:
                  quoteId: vn-usd-quote-id-sample
                  reason: Gift
                  remark: TestVND
                  recipient:
                    name: Nguyễn Văn Nam
                    nickName: DemoVNNickname
                    type: BUSINESS
                    stored: false
                    account:
                      bankName: Vietnam Bank
                      sortCode: '00205'
                      swiftCode: VNTBVNHNXXX
                      bankCity: Hanoi
                      accountNumber: '0012345678'
                    sourceOfFunds: I1
                    paymentChannel: BANK_TRANSFER
                    currency: VND
                    country: VN
      responses:
        '200':
          $ref: '#/components/responses/CreatePayoutSuccess'
        '400':
          $ref: '#/components/responses/PayoutBadRequest'
        '401':
          $ref: '#/components/responses/PayoutUnauthorized'
        '403':
          $ref: '#/components/responses/PayoutForbidden'
        '500':
          $ref: '#/components/responses/PayoutInternalServerError'
components:
  schemas:
    CreatePayoutRequest:
      type: object
      description: >-
        Request body for creating a payout. Select the tab for your target
        corridor.
      oneOf:
        - $ref: '#/components/schemas/NgnPayoutRequest'
        - $ref: '#/components/schemas/UsdSwiftPayoutRequest'
        - $ref: '#/components/schemas/EurPayoutRequest'
        - $ref: '#/components/schemas/GbpPayoutRequest'
        - $ref: '#/components/schemas/CadBankPayoutRequest'
        - $ref: '#/components/schemas/CadInteracPayoutRequest'
        - $ref: '#/components/schemas/SgdPayoutRequest'
        - $ref: '#/components/schemas/KrwPayoutRequest'
        - $ref: '#/components/schemas/ThbPayoutRequest'
        - $ref: '#/components/schemas/MyrPayoutRequest'
        - $ref: '#/components/schemas/VndPayoutRequest'
        - $ref: '#/components/schemas/CnyPayoutRequest'
        - $ref: '#/components/schemas/MwkPayoutRequest'
      discriminator:
        propertyName: corridorKey
        mapping:
          NGN:
            $ref: '#/components/schemas/NgnPayoutRequest'
          USD_SWIFT:
            $ref: '#/components/schemas/UsdSwiftPayoutRequest'
          EUR:
            $ref: '#/components/schemas/EurPayoutRequest'
          GBP:
            $ref: '#/components/schemas/GbpPayoutRequest'
          CAD_BANK:
            $ref: '#/components/schemas/CadBankPayoutRequest'
          CAD_INTERAC:
            $ref: '#/components/schemas/CadInteracPayoutRequest'
          SGD:
            $ref: '#/components/schemas/SgdPayoutRequest'
          KRW:
            $ref: '#/components/schemas/KrwPayoutRequest'
          THB:
            $ref: '#/components/schemas/ThbPayoutRequest'
          MYR:
            $ref: '#/components/schemas/MyrPayoutRequest'
          VND:
            $ref: '#/components/schemas/VndPayoutRequest'
          CNY:
            $ref: '#/components/schemas/CnyPayoutRequest'
          MWK:
            $ref: '#/components/schemas/MwkPayoutRequest'
    NgnPayoutRequest:
      title: NGN Payout
      description: Payout to a Nigerian bank account (NGN).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/NgnRecipient'
    UsdSwiftPayoutRequest:
      title: USD SWIFT Payout
      description: Payout to a US bank account via SWIFT.
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/UsdSwiftRecipient'
    EurPayoutRequest:
      title: EUR Payout
      description: Payout to a SEPA European bank account (EUR).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/EurRecipient'
    GbpPayoutRequest:
      title: GBP Payout
      description: Payout to a UK bank account (GBP).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/GbpRecipient'
    CadBankPayoutRequest:
      title: CAD (Bank Transfer) Payout
      description: Payout to a Canadian bank account via bank transfer (CAD).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/CadRecipient'
    CadInteracPayoutRequest:
      title: CAD (Interac) Payout
      description: Payout to a Canadian recipient via Interac e-Transfer (CAD).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient: f4243545-d7f6-488b-a4a3-91014a8a0166
    SgdPayoutRequest:
      title: SGD Payout
      description: Payout to a Singapore bank account (SGD).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/SgdRecipient'
    KrwPayoutRequest:
      title: KRW Payout
      description: Payout to a South Korean bank account (KRW).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/KrwRecipient'
    ThbPayoutRequest:
      title: THB Payout
      description: Payout to a Thai bank account (THB).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/ThbRecipient'
    MyrPayoutRequest:
      title: MYR Payout
      description: Payout to a Malaysian bank account (MYR).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/MyrRecipient'
    VndPayoutRequest:
      title: VND Payout
      description: Payout to a Vietnamese bank account (VND).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/VndRecipient'
    CnyPayoutRequest:
      title: CNY Payout
      description: Payout to a Chinese bank account (CNY).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient:
              $ref: '#/components/schemas/CnyRecipient'
    MwkPayoutRequest:
      title: MWK Payout
      description: Payout to a Malawian bank account (MWK).
      allOf:
        - $ref: '#/components/schemas/BasePayoutRequest'
        - type: object
          properties:
            recipient: 686581bd-521b-471b-a638-a03fd1a3ed9f
    Payout:
      type: object
      properties:
        id:
          type: string
          example: c6611ad3-805a-415b-98b7-xxxxxxxxxxxxx
        remark:
          type: string
          example: Testing
        invoice:
          type: object
          properties:
            fileName:
              type: string
              example: image.png
        reason:
          type: string
          example: Gift
        referenceNumber:
          type: string
          example: L2TEZEHNXXXXXX
        type:
          type: string
          example: SEND
        state:
          type: string
          example: COMPLETED
        quote:
          $ref: '#/components/schemas/CreateQuoteSuccessData'
        recipient:
          description: >-
            Details of the recipient. Structure mirrors
            `CreatePayoutRequest.recipient`.
          oneOf:
            - $ref: '#/components/schemas/NgnRecipient'
            - $ref: '#/components/schemas/UsdSwiftRecipient'
            - $ref: '#/components/schemas/EurRecipient'
            - $ref: '#/components/schemas/GbpRecipient'
            - $ref: '#/components/schemas/CadRecipient'
            - $ref: '#/components/schemas/SgdRecipient'
            - $ref: '#/components/schemas/KrwRecipient'
            - $ref: '#/components/schemas/ThbRecipient'
            - $ref: '#/components/schemas/MyrRecipient'
            - $ref: '#/components/schemas/VndRecipient'
            - $ref: '#/components/schemas/CnyRecipient'
        created:
          type: string
          format: date-time
        processed:
          type: string
          format: date-time
    PayoutFailedResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message.
        status:
          type: string
          example: failed
      required:
        - message
        - status
    BasePayoutRequest:
      type: object
      required:
        - quoteId
        - recipient
      properties:
        quoteId:
          type: string
          description: The unique identifier for the quote (valid for 10 minutes).
        reason:
          type: string
          description: The purpose of the transfer.
          enum:
            - FAMILY_SUPPORT
            - GIFT
            - SALARY_PAYMENT
            - EDUCATIONAL_FEES
            - BUSINESS_INVOICE
            - OTHER
        invoice:
          type: string
          description: Optional invoice file ID (returned from the file upload endpoint).
        remark:
          type: string
          description: >-
            An optional note about the transaction. Use `fail` in sandbox to
            trigger a failed payout webhook.
    NgnRecipient:
      title: NGN Payout
      description: Recipient details for a payout to Nigeria (NGN).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Full name of the recipient.
            account:
              type: object
              required:
                - accountNumber
                - bankCode
              properties:
                bankName:
                  type: string
                  description: The name of the Bank
                accountNumber:
                  type: string
                  example: '0010401234'
                  description: Recipient's account number
                sortCode:
                  type: string
                  description: The 3-digit NIP sort code.
                  example: '058'
    UsdSwiftRecipient:
      title: USD SWIFT Payout
      description: Recipient details for USD to USD SWIFT payout to the USA (USD).
      type: object
      required:
        - name
        - type
        - account
        - nickName
        - gender
        - occupation
      properties:
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        country:
          $ref: '#/components/schemas/CountryCode'
        name:
          type: string
          description: Full name of the recipient.
        nickName:
          type: string
          description: Nickname or alias for the recipient.
        gender:
          type: string
          description: Gender of the recipient.
          enum:
            - M
            - F
        occupation:
          type: string
          description: Occupation or profession of the recipient.
          enum:
            - C-Suite executive / Board member
            - Employee
            - Entrepreneur / Business owner
            - Foreign worker
            - Foreign domestic worker
            - Home-maker
            - Middle management employee
            - Pilot
            - Professional
            - Senior management employee
            - Student
        type:
          type: string
          description: Recipient type; use `BUSINESS`
          enum:
            - BUSINESS
        account:
          type: object
          required:
            - accountNumber
            - swiftCode
            - bankName
          properties:
            bankName:
              type: string
              description: The name of the bank.
              example: DBS Bank Limited
            accountNumber:
              type: string
              description: The recipient's bank account number.
              example: '885406477269'
            swiftCode:
              type: string
              description: SWIFT/BIC code for international wire transfers.
              example: GTBINGLA
            sortCode:
              type: string
              description: Bank sort code.
              example: '02090'
            bankCity:
              type: string
              description: City where the bank is located.
              example: Atlanta
            intermediarySwiftCode:
              type: string
              description: >-
                The SWIFT/BIC code of the intermediary bank, required for some
                international USD transfers.
              example: CHASUS33XXX
    EurRecipient:
      title: EUR Payout
      description: Recipient details for a payout within Europe (EUR).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - firstName
            - lastName
            - type
            - address
          properties:
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; align with the actual customer profile (e.g.
                `BUSINESS`).
            firstName:
              type: string
              description: Recipient's first name.
            lastName:
              type: string
              description: Recipient's last name.
            address:
              type: string
              description: Mailing address of the recipient; required for EUR payouts.
            account:
              type: object
              required:
                - bankName
                - bankCountry
                - address
                - swiftCode
                - accountNumber
                - iban
              properties:
                bankName:
                  type: string
                  description: Name of the bank, e.g Adria Bank
                bankCountry:
                  type: string
                  description: The two-letter ISO country code of the recipient's bank.
                address:
                  type: string
                  description: The bank's physical address.
                swiftCode:
                  type: string
                  description: The SWIFT/BIC code for the bank.
                  example: '3456765'
                accountNumber:
                  type: string
                  description: The recipient's local bank account number.
                  example: '34567876545'
                iban:
                  type: string
                  description: The recipient's International Bank Account Number (IBAN).
                  example: '123454'
    GbpRecipient:
      title: GBP Payout
      description: Recipient details for a payout to the UK (GBP).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - firstName
            - lastName
            - type
          properties:
            firstName:
              type: string
              description: Recipient's first name.
            lastName:
              type: string
              description: Recipient's last name.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; use `BUSINESS` for corporate payouts or
                `INDIVIDUAL` for consumers.
            account:
              type: object
              required:
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of the bank
                accountNumber:
                  type: string
                  description: The 8-digit UK bank account number.
                  example: '78355047'
                sortCode:
                  type: string
                  description: The 6-digit UK bank sort code.
                  example: '040004'
                address:
                  type: string
                  description: The bank's physical address.
    CadRecipient:
      title: CAD Payout
      description: Recipient details for a payout to Canada (CAD).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - address
          properties:
            name:
              type: string
              description: Full name of the recipient.
            address:
              type: string
              description: Mailing address of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: >-
                Recipient type; optional for CAD payouts but recommended when
                sending to businesses.
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - transitNumber
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                  example: '2309912345'
                address:
                  type: string
                  description: The bank's physical address.
                sortCode:
                  type: string
                  description: Bank sort code.
                swiftCode:
                  type: string
                  description: SWIFT/BIC code, if applicable.
                transitNumber:
                  type: string
                  description: The 5-digit branch transit number.
                  example: '12345'
                institutionNumber:
                  type: string
                  description: The 3-digit financial institution number.
                  example: '004'
    SgdRecipient:
      title: SGD Payout
      description: Recipient details for a payout to Singapore (SGD).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
              description: Recipient type (INDIVIDUAL or BUSINESS).
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - swiftCode
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code / Sort code.
                swiftCode:
                  type: string
                  description: SWIFT/BIC code.
                bankCity:
                  type: string
                  description: City of the bank.
    KrwRecipient:
      title: KRW Payout
      description: Recipient details for a payout to South Korea (KRW).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
            - mobileNumber
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            mobileNumber:
              type: string
              description: Recipient mobile number.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 01462).
                bankCity:
                  type: string
                  description: City of the bank.
    ThbRecipient:
      title: THB Payout
      description: Recipient details for a payout to Thailand (THB).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00301).
                bankCity:
                  type: string
                  description: City of the bank.
    MyrRecipient:
      title: MYR Payout
      description: Recipient details for a payout to Malaysia (MYR).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00163).
    VndRecipient:
      title: VND Payout
      description: Recipient details for a payout to Vietnam (VND).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            nickName:
              type: string
              description: Recipient nickname.
            sourceOfFunds:
              $ref: '#/components/schemas/SourceOfFunds'
            account:
              type: object
              required:
                - bankName
                - accountNumber
                - sortCode
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code (e.g. 00205).
                bankCity:
                  type: string
                  description: City of the bank.
    CnyRecipient:
      title: CNY Payout
      description: Recipient details for a payout to China (CNY).
      allOf:
        - $ref: '#/components/schemas/BaseRecipient'
        - type: object
          required:
            - name
            - type
          properties:
            name:
              type: string
              description: Full name of the recipient. (Must be in Chinese characters)
            nickName:
              type: string
              description: Recipient nickname.
            occupation:
              type: string
              description: Occupation of the recipient.
            icNumber:
              type: string
              description: Identity card number of the recipient.
            relationship:
              type: string
              description: Relationship with the recipient.
            type:
              $ref: '#/components/schemas/RecipientType'
            account:
              type: object
              required:
                - bankName
                - accountNumber
              properties:
                bankName:
                  type: string
                  description: Name of bank
                accountNumber:
                  type: string
                  description: Recipient account number
                sortCode:
                  type: string
                  description: Bank code / Sort code.
                bankCity:
                  type: string
                  description: City of the bank.
            companyName:
              type: string
              description: Company name (if business).
            companyIdNumber:
              type: string
              description: Company identification number.
            gender:
              type: string
              description: Gender of the recipient.
              enum:
                - M
                - F
            nationality:
              type: string
              description: Nationality of the recipient (e.g., CN).
            itemCategory:
              type: string
              description: Category of items (e.g., PRD0003).
            itemType:
              type: string
              description: Type of item (e.g., Pipe Wrench).
            quantity:
              type: integer
              description: Quantity of items.
    CreateQuoteSuccessData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        source:
          type: object
          properties:
            currency:
              type: string
              example: NGN
            country:
              type: string
              example: NG
            amount:
              type: number
              example: 150000
        target:
          type: object
          properties:
            currency:
              type: string
              example: USD
            country:
              type: string
              example: US
            amount:
              type: number
              example: 81.97
        rate:
          type: number
          example: 1830
        fee:
          type: object
          properties:
            amount:
              type: number
              example: 0
            stampDuty:
              type: number
              example: 0
        rules:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
                example: LIMIT
              appliedCurrency:
                type: string
                example: USD
              appliedCountry:
                type: string
                example: US
              transaction:
                type: object
                properties:
                  minimum:
                    type: number
                    example: 1
                  maximum:
                    type: number
                    example: 20000000000000
              invoice:
                type: number
                example: 200000000000
        summary:
          type: object
          properties:
            total:
              type: number
              example: 150000
        settlementTime:
          type: string
          example: 1 hr
        settlement:
          type: string
          example: 1 hr
        quoteCurrency:
          type: string
          example: USD
        expiresInSeconds:
          type: integer
          example: 600
    BaseRecipient:
      type: object
      properties:
        paymentChannel:
          $ref: '#/components/schemas/PaymentChannel'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        country:
          $ref: '#/components/schemas/CountryCode'
        type:
          $ref: '#/components/schemas/RecipientType'
        stored:
          type: boolean
          description: Whether the recipient details should be saved in the address book.
          default: false
        address:
          type: string
          description: Full address of the recipient.
        account:
          type: object
          description: >-
            Currency-specific account details. Refer to the destination currency
            schema for the exact structure.
      required:
        - paymentChannel
        - currency
        - country
        - account
    PaymentChannel:
      type: string
      description: >-
        The channel through which the payment will be processed. For SWIFT
        transfers, use `SWIFT_CUSTOMER` (sender/customer bears all transfer
        charges), `SWIFT_SHARED` (charges split between sender and beneficiary),
        or `SWIFT_BENEFICIARY` (beneficiary bears all transfer charges).
      example: BANK_TRANSFER
      enum:
        - BANK_TRANSFER
        - INTERAC
        - SWIFT_CUSTOMER
        - SWIFT_SHARED
        - SWIFT_BENEFICIARY
        - MOBILE_MONEY
    CurrencyCode:
      type: string
      description: Currency code (ISO 4217).
      example: NGN
      enum:
        - NGN
        - USD
        - GBP
        - EUR
        - MWK
        - CAD
        - SGD
        - KRW
        - THB
        - MYR
        - VND
        - CNY
        - GHS
        - KES
        - RWF
        - XOF
        - ZAR
        - DKK
    CountryCode:
      type: string
      description: Country code (ISO 3166-1 alpha-2).
      example: NG
      enum:
        - NG
        - US
        - GB
        - DE
        - MW
        - CA
        - SG
        - KR
        - TH
        - MY
        - VN
        - CN
        - GH
        - CI
        - KE
        - RW
        - SN
        - ZA
        - AT
        - DK
    RecipientType:
      type: string
      description: The type of recipient.
      enum:
        - INDIVIDUAL
        - BUSINESS
    SourceOfFunds:
      type: string
      description: Code indicating the source of funds.
      enum:
        - D1
        - D2
        - D3
        - I1
        - I2
        - I3
        - I4
        - O1
        - O2
        - O3
        - O4
  responses:
    CreatePayoutSuccess:
      description: Payout transaction created successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: success
              message:
                type: string
                example: Transaction created successfully.
              data:
                $ref: '#/components/schemas/Payout'
            required:
              - status
              - message
              - data
          examples:
            USD_Payout_Success:
              summary: USD Payout Success Response
              value:
                message: transaction created successfully
                status: success
                data:
                  id: 274fd8a4-38f1-43c9-bf74-ae7744a0dba5
                  remark: User-friendly
                  reason: Gift
                  referenceNumber: 0XCGU0EYFEK0Y
                  invoice:
                    fileName: image.png
                  type: SEND
                  state: PENDING
                  quote:
                    id: 4da9d52d-618b-4683-b408-8844d1b520cd
                    paymentChannel: SWIFT_CUSTOMER
                    source:
                      currency: USD
                      country: US
                      amount: 10
                    target:
                      currency: USD
                      country: US
                      amount: 10
                    rate: 1
                    fee:
                      amount: 100
                      stampDuty: 0
                    summary:
                      total: 110
                    settlement: 1hr
                    quoteCurrency: USD
                  recipient:
                    name: Crystal Strosin
                    nickName: magenta
                    gender: M
                    type: BUSINESS
                    account:
                      bankName: DBS Bank Limited
                      sortCode: '02090'
                      accountNumber: '885406477269'
                      bankCity: Atlanta
                      swiftCode: GTBINGLA
                    occupation: business enterpreneur
                  sender:
                    name: Test Limited
                    icNumber: '96671733919'
                    nationality: NG
                    address:
                      line1: 12 main st
                    mobileNumber: '+234872272808'
                    occupation: HEALTHCARE
                  created: '2026-04-23T18:06:41.022734019Z'
                  processed: '2026-04-23T18:06:41.022734019Z'
    PayoutBadRequest:
      description: >-
        Bad Request. The request could not be processed due to a client-side
        error, such as an expired quote or insufficient funds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          examples:
            QuoteExpired:
              summary: Quote has expired
              value:
                message: Quote expired
                status: failed
            InsufficientBalance:
              summary: Insufficient wallet balance
              value:
                message: Insufficient Balance
                status: failed
            DuplicateQuoteId:
              summary: Duplicate quote ID in bulk order
              value:
                message: >-
                  Duplicate quote ID in bulk order:
                  537a5e91-3aa6-4e3f-9ed7-c16066ced503
                status: failed
    PayoutUnauthorized:
      description: Unauthorized. The provided API key is invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Invalid API key
            status: failed
    PayoutForbidden:
      description: >-
        Forbidden. The request is not allowed because the source IP is not
        whitelisted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: 'Access denied: IP address not whitelisted'
            status: failed
    PayoutInternalServerError:
      description: Internal Server Error. The server failed to process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Server failed to process request.
            status: failed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````