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

# Single Payout

> Send one payment to a saved beneficiary payment method

Send a single payment to a saved beneficiary. Debits your wallet at the time of submission.

```
POST https://api.yativo.com/api/v1/payout/simple
```

> [!NOTE]
>
> Requires `Idempotency-Key` header. Your wallet is charged immediately on submission.

`/payout/simple` works like [`POST /wallet/payout`](https://docs.yativo.com/yativo-fiat/wallets#quick-wallet-payout) with `beneficiary_details_id` in place of `payment_method_id`. To fix the amount the customer receives (`amount_type: "receive"`), use `/wallet/payout`.

Every payout goes through compliance checks before it's sent. If you include an invoice, it's reviewed with the payout, so make sure its total and beneficiary match. A payout that needs a closer look stays `pending` until the review is finished.

```bash cURL theme={null}
curl -X POST 'https://api.yativo.com/api/v1/payout/simple' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-simple-001' \
  -d '{
    "debit_wallet": "USD",
    "amount": 250,
    "beneficiary_details_id": 42,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "reference": "INV-2026-0042"
  }''
```

```json Success theme={null}
{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "transaction_id": "txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing",
    "amount": "250.00",
    "created_at": "2026-06-01T10:00:00.000000Z"
  }
}
```

```json Insufficient balance theme={null}
{
  "status": "failed",
  "status_code": 400,
  "message": "Insufficient wallet balance",
  "data": {
    "error": "Insufficient wallet balance"
  }
}
```


## OpenAPI

````yaml openapi-fiat.yaml POST /payout/simple
openapi: 3.0.3
info:
  title: Yativo Fiat API
  description: >
    The Yativo Fiat API enables businesses to manage customers, run KYC/KYB,
    send and receive

    cross-border payments, issue virtual accounts and virtual cards, accept card
    payments through

    Card Checkout, manage beneficiaries, and more.


    **Base URLs**

    | Environment | URL |

    |---|---|

    | Production | `https://api.yativo.com/api/v1` |

    | Sandbox | `https://smtp.yativo.com/api/v1` |


    **Authentication**

    Send `X-Api-Key` and `X-Api-Secret` on every request. Create keys in the
    dashboard under

    **Developers → API Keys**. Each key only works from the server IPs listed on
    it (enforced since

    14 October 2026). Keys don't expire and there's no login call or token
    refresh.


    Login tokens (`POST /auth/login` with an Account ID and App Secret, and
    `Authorization: Bearer`)

    have been discontinued and don't work for API requests.


    Endpoints that change how a person signs in (passkeys, two-factor
    authentication, PIN)

    or delete the account can't be called with an API key. Use the dashboard for
    those.

    API keys and IP whitelists can only be managed in the dashboard.


    **Rate limits**

    Per business account: 20 writes (`POST`, `PUT`, `PATCH`, `DELETE`) and 50
    reads (`GET`) a second.

    Some plans set their own limit. Enterprise plans have no general limit.


    **Idempotency**

    Send an `Idempotency-Key` header on every `POST`, `PUT`, `PATCH` and
    `DELETE` request. Use a new

    key for each distinct operation. Reusing a key for a completed request
    within 60 minutes returns

    `409`. Reusing a key with a different body also returns `409`.


    **KYC endpoints** are hosted on a separate platform at
    `https://kyc.yativo.com`. They are

    documented here for completeness but use that base URL, not the main API
    base.
  version: 1.0.0
  contact:
    name: Yativo Support
    url: https://yativo.com
servers:
  - url: https://api.yativo.com/api/v1
    description: Production
  - url: https://smtp.yativo.com/api/v1
    description: Sandbox
security:
  - apiKey: []
    apiSecret: []
tags:
  - name: Customers
    description: Create and manage customer profiles.
  - name: KYC / KYB
    description: >
      Identity verification for individual customers (KYC) and business
      customers (KYB).

      Submission endpoints are on `https://kyc.yativo.com/api`.
  - name: KYC Lookups
    description: >
      Lists your KYC and KYB forms need: countries, subdivisions, postal code
      formats, ID types,

      occupations, industries and allowed values. Served from
      `https://kyc.yativo.com/api`.
  - name: Payments & Transfers
    description: Exchange rates, quotes, payout methods, and wallet payouts.
  - name: Card Checkout
    description: >-
      Let your customers sell by debit and credit card on a Yativo-hosted
      checkout page.
  - name: Deposits
    description: Initiate and retrieve payin deposits.
  - name: Virtual Accounts
    description: Issue and manage virtual bank accounts for customers.
  - name: Wallets
    description: View balances, create wallets, and list wallet payouts.
  - name: Beneficiaries
    description: >-
      Save recipients' account details as beneficiaries and reuse them in
      payouts.
  - name: Transactions
    description: List, retrieve, track, and download receipts for all transaction types.
  - name: Virtual Cards
    description: >-
      Issue, manage, and terminate prepaid virtual cards. Every card request
      works only on your own cards. Any other card ID returns `404` with `Card
      not found`.
  - name: Payouts
    description: Single payouts to beneficiaries.
  - name: Currency Swap
    description: Swap balance between your own currency wallets.
  - name: IP Whitelist
    description: Check whether your server's IP can use your API key.
  - name: Corporate Cards
    description: >-
      Employees, their KYC, cards, card balances, memos and the USDC funding
      address. By invitation only.
  - name: Corporate Card Transactions
    description: Card activity on your corporate cards, with disputes, notes and invoices.
  - name: Corporate Card Links
    description: >-
      Each corporate card's employee-only page for card details and PIN,
      employee card sign-in, and branding.
  - name: Webhooks
    description: Register and manage webhook endpoints for real-time event notifications.
  - name: Sandbox
    description: Endpoints that exist only on the sandbox host. Production refuses them.
  - name: Developer
    description: Webhook event inspection.
  - name: RFIs
    description: >-
      Compliance requests for information; save draft answers via API (not
      auto-submitted upstream).
paths:
  /payout/simple:
    post:
      tags:
        - Payouts
      summary: Single Payout
      description: >
        Send a single payment to a saved beneficiary. Debits your wallet
        immediately on submission.

        Requires an `Idempotency-Key` header.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - debit_wallet
                - amount
                - beneficiary_details_id
                - customer_id
              properties:
                debit_wallet:
                  type: string
                  description: The source wallet currency to debit (e.g. `"USD"`, `"EUR"`).
                  example: USD
                amount:
                  type: number
                  description: Amount to send in the debit wallet currency.
                  example: 250
                beneficiary_details_id:
                  type: integer
                  description: >-
                    The saved beneficiary payment method ID (from `POST
                    /beneficiaries/payment-methods`).
                customer_id:
                  type: string
                  description: >-
                    The customer the payout is for. If the beneficiary belongs
                    to a customer, it must be that customer.
                  example: da44a3e6-eb5d-429f-8d17-357aa5a6cdf2
                beneficiary_id:
                  type: string
                  description: Optional. The beneficiary that owns the payment method.
                quote_id:
                  type: string
                  format: uuid
                  description: >-
                    A payout quote from `POST /exchange-rate`. Locks the rate
                    and fees for 5 minutes and supplies the amount.
                reference:
                  type: string
                  maxLength: 250
                  description: >-
                    Payment reference passed to the recipient's bank, up to 250
                    characters. Depending on the payout rail, it may be
                    shortened or have unsupported characters removed. For
                    example, ACH allows only 10 letters, numbers or spaces.
                invoice:
                  type: string
                  format: binary
                  description: >-
                    Supporting invoice: PDF, PNG or JPEG, up to 15 MB. Send the
                    request as `multipart/form-data` to attach it.
                invoice_url:
                  type: string
                  format: uri
                  description: >-
                    Public `http` or `https` link to the supporting invoice, as
                    an alternative to `invoice`.
      responses:
        '200':
          description: Payout initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  status_code:
                    type: integer
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      transaction_id:
                        type: string
                      status:
                        type: string
                      amount:
                        type: string
                      created_at:
                        type: string
                        format: date-time
        '400':
          description: Insufficient wallet balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
      description: A unique string per request to ensure idempotent processing.
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: failed
        status_code:
          type: integer
        message:
          type: string
          description: The error message, the same as `data.error`.
          example: Insufficient wallet balance
        data:
          type: object
          nullable: true
          properties:
            error:
              type: string
              example: Insufficient wallet balance
        error:
          $ref: '#/components/schemas/ErrorSummary'
        error_details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorSummary:
      type: object
      description: Short error summary included in every failed response.
      properties:
        code:
          type: string
          enum:
            - invalid_argument
            - unauthenticated
            - permission_denied
            - not_found
            - method_not_allowed
            - rate_limited
            - internal_error
          description: Short code from the HTTP status.
          example: invalid_argument
        message:
          type: string
          description: Same as the top-level `message`.
        request_id:
          type: string
          description: >-
            Your `X-Request-Id` header if you sent one, otherwise an ID starting
            `req_`. Quote it when you contact support.
          example: req_5f2c9a1e7b3d4c8a6e0f1b2d
    ErrorDetails:
      type: object
      description: >-
        Included on every failed response, with the same shape for every
        endpoint.
      properties:
        code:
          type: string
          enum:
            - bad_request
            - unauthenticated
            - payment_required
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - validation_error
            - rate_limited
            - server_error
            - not_implemented
            - upstream_error
            - service_unavailable
            - upstream_timeout
          example: validation_error
        message:
          type: string
          example: The amount field is required.
        http_status:
          type: integer
          example: 422
        fields:
          type: object
          description: >-
            Messages per field. When the error isn't about a field, the message
            is under `error`.
          additionalProperties:
            type: array
            items:
              type: string
        retryable:
          type: boolean
          description: '`true` for 409, 429, 500, 502, 503 and 504.'
          example: false
        retry_after:
          type: integer
          nullable: true
          description: Seconds to wait before retrying, from the `Retry-After` header.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Your API key (`yativo_pk_...`) from Developers → API Keys. Send together
        with X-Api-Secret.
    apiSecret:
      type: apiKey
      in: header
      name: X-Api-Secret
      description: Your API secret (`yativo_sk_...`), shown once when the key is created.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.