# Create a payout

Sends money from the payment account balance to one of its beneficiaries, at the price of a locked quote.
Pick a quote whose rail the beneficiary supports: a `upi` quote needs a beneficiary with a UPI ID, and a
bank rail such as `imps` or `neft` needs a bank account in the destination currency.
Always read `status` in the response. The call returns `201` for every payout it creates:
- `in_progress`
 - the payout is being processed. Its source amount has moved from
`available`
 to

`on_hold`
. The amount leaves the account when the payout succeeds, and goes back to
`available`
 when

the payout fails or is cancelled.
- `action_required`
 - Glomo needs more information before the payout can continue. Nothing is held yet.

The amount moves to
`on_hold`
 when the payout continues to
`in_progress`
.
- `failed`
 - the payout could not start, for example because a compliance check could not complete.

Nothing is held.
- `cancelled`
 - rare. The quote expired while the payout was being created, and
`error_code`
 is

`QUOTE_EXPIRED`
.

A `failed` or `cancelled` payout has used its quote and its `request_id`. To try again, lock a new quote
and send a new `request_id`.
One transaction runs on a payment account at a time. A payout sent while another transaction on the same
account is in progress returns `409` and does nothing. Retry it with the same `request_id`.
If you send a `request_id` that this account already used, you get the original payout back with `201`,
in its current status, and the rest of the body is ignored. To follow a payout to a final status, use the
[payout webhooks](/platform/webhooks/payout).

Endpoint: POST /payment-accounts/{payment_account_id}/payouts
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `payment_account_id` (string, required)
    The ID of a payment account you own. Starts with `pacct_`.

## Request fields (application/json):

  - `quote_id` (string, required)
    A quote locked on this payment account, before its `expires_at`. One quote pays one payout.
    Example: quote_6ab5a2d4Wc7Nh

  - `beneficiary_id` (string, required)
    An `active` beneficiary of this payment account.
    Example: bene_6ab5a1c9gflRf

  - `purpose_code` (string, required)
    The reason for the payout. Payment account payouts accept these codes only:
| Code | Purpose |
|  --- | --- |
| `S0023` | Transfer to my own overseas account |
| `S1301` | Family support or living expenses |
| `S1302` | Gift to family or friend |
| `S1303` | Donation to charity |
| `S0305` | Education: tuition and student expenses |
| `S0304` | Medical treatment |
| `S0306` | Travel or holiday |
| `S0001` | Investments: stocks and securities |
| `S0005` | Investments: property or real estate |
| `S0601` | Insurance premium |
| `S1306` | Tax payment |
    Enum: "S0023", "S1301", "S1302", "S1303", "S0305", "S0304", "S0306", "S0001", "S0005", "S0601", "S1306"

  - `request_id` (string, required)
    Your unique ID for this payout, up to 64 characters, unique on the payment account. If you send the same `request_id` again on the same account, you get the original payout back and no second payout is made.
    Example: acme-po-0001

  - `notes` (object)
    Your own key-value pairs. A few key names are reserved, and a body that uses one returns `400` naming the key.
    Example: {"channel":"mobile_app"}

## Response 201:

  - `201` (unknown)
    Payout created, or the original payout for a repeated `request_id`

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier for the payout.
    Example: payout_DdWp_HUbOnlg

  - `status` (string)
    The status of the payout.
- `pending_approval`
 — the payout is waiting for a reviewer on your account to approve it. Only

used when payout approval is turned on for your account.
- `queued`
 — the payout is waiting for enough balance to cover it. It moves on once funds arrive, or

fails with
`QUEUE_EXPIRED`
 if they do not arrive in time.
- `in_progress`
 — the payout has been accepted and is being processed or reviewed.
- `action_required`
 — Glomo needs more information before the payout can proceed. Respond to the

open RFI to continue.
- `success`
 — the beneficiary has been paid. Terminal.
- `failed`
 — the payout could not be completed; see
`error_code`
. Terminal.
- `cancelled`
 — the payout was stopped before it was paid. Terminal.
    Enum: "pending_approval", "queued", "in_progress", "action_required", "success", "failed", "cancelled"

  - `destination_amount` (number)
    The amount the beneficiary will receive, in the smallest unit of `destination_currency` (paise for INR, cents for USD). `1000` is $10.00 when `destination_currency` is USD.
    Example: 1000

  - `destination_currency` (string)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.
    Example: USD

  - `source_amount` (number)
    The amount you intend to send, in the smallest unit of `source_currency` (cents for USD). `1000` is $10.00 when `source_currency` is USD.
    Example: 1000

  - `source_currency` (string)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.
    Example: USD

  - `beneficiary_id` (string)
    The unique identifier of the beneficiary the payout is sent to.
    Example: bene_5JU9yv0lGSUP

  - `documents` (array)
    The attached documents for the payout.

  - `documents.id` (string)
    The unique identifier for the Document.
    Example: doc_nYUqLpuYQ0M8

  - `documents.type` (string)
    The type of the Document.
    Example: invoice

  - `documents.status` (string)
    Enum: "pending", "uploaded", "rejected", "approved"

  - `documents.rfi_doc_id` (string | null)
    The unique identifier for the RFI Document. This will be `null` if the document is not an RFI Document.
    Example: rfidoc_nYUqLpuYQ0M8

  - `purpose_code` (string)
    Purpose code of this payout, from the fixed set of [payout purpose codes](/payout/purpose-codes).
    Example: S0017

  - `mid_market_rate` (object)
    The mid-market rate at the time of payout creation. The currency represents the destination currency and rate represents the factor of conversion. Example: 1 EUR = 1.17 USD. Rate corresponds to 1.17 and currency is USD.

  - `mid_market_rate.currency` (string | null)
    The destination currency, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` when no rate has been recorded yet.
    Example: USD

  - `mid_market_rate.rate` (number | null)
    Units of the destination currency (`mid_market_rate.currency`) per one unit of `source_currency`. `1.17` with `currency` `USD` on a payout from EUR to USD means 1 EUR = 1.17 USD. `1` when the source and destination currencies are the same. `null` when no rate has been recorded yet.
    Example: 1.17

  - `fees` (object)
    The fees applied to this payout

  - `fees.fx_fee` (object)
    The foreign exchange fees applied to the payout

  - `fees.fx_fee.currency` (string | null)
    The currency of the FX fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` until fees are applied to the payout.
    Example: USD

  - `fees.fx_fee.amount` (integer | null)
    The FX fee, in the smallest unit of this fee's `currency`, which is the payout's `source_currency`. `200` is $2.00 when that currency is USD. `null` until fees are applied to the payout; a zero fee is `0`.
    Example: 200

  - `fees.txn_fee` (object)
    The transaction fees applied to the payout

  - `fees.txn_fee.currency` (string | null)
    The currency of the transaction fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` until fees are applied to the payout.
    Example: USD

  - `fees.txn_fee.amount` (integer | null)
    The transaction fee, in the smallest unit of this fee's `currency`, which is the payout's `source_currency`. `100` is $1.00 when that currency is USD. `null` until fees are applied to the payout; a zero fee is `0`.
    Example: 100

  - `created_at` (string)
    When the payout was created, as an ISO 8601 date-time in UTC.
    Example: 2021-06-01T12:00:00Z

  - `updated_at` (string)
    When the payout was last updated, as an ISO 8601 date-time in UTC.
    Example: 2021-06-01T12:00:00Z

  - `utr` (string | null)
    (Optional) Unique Transaction Reference for the payout. This is a unique identifier assigned by the bank to track the transaction.
    Example: AXISN52024112000001234

  - `request_id` (string)
    The `request_id` you sent. To read a payout again, send the same Create a payout request: you get the payout back in its current status, and no second payout is made.
    Example: acme-po-0001

  - `payment_rail` (string | null)
    The payment rail used to settle this payout. Each local rail serves one corridor: `upi`, `imps`, `neft`, `rtgs` for `INR`; `ipp`, `fts` for `AED`; `sepa` for `EUR`; `fps` for `GBP`; `npp` for `AUD`. `swift` is used for international transfers.
    Enum: "swift", "imps", "neft", "rtgs", "upi", "ipp", "fts", "sepa", "fps", "npp", "null"

  - `invoice_number` (string | null)
    The invoice reference sent when the payout was created, up to 50 characters. `null` when none was sent.
    Example: INV-2026-001

  - `fee_collection_mode` (string)
    When the fees are collected. `immediate` means the fees come out of `source_amount`, as the quote shows.
    Enum: "immediate", "deferred"

  - `error_code` (string | null)
    A machine-readable code describing why the payout failed or was cancelled. `null` unless the
payout is in an error state. The accompanying `error_description` carries the human-readable text.
| Code | Description |
|  --- | --- |
| `QUOTE_EXPIRED` | Quote has expired. Please create a new payout with a valid quote. |
| `QUEUE_EXPIRED` | Payout stayed queued for 30 days because the balance did not cover it. No funds were held. |
| `PAYOUT_REJECTED` | Payout was rejected by the bank. Please reach out to support. (default fallback) |
| `INSUFFICIENT_BALANCE` | The balance no longer covered the payout when it came out of review. No funds were held. |
| `INVALID_BENE_ACCOUNT_NUMBER` | Beneficiary account number is invalid. |
| `INVALID_BENE_ACCOUNT_TYPE` | Beneficiary account type is invalid. |
| `INVALID_BENE_IFSC` | Beneficiary IFSC code is invalid. |
| `INVALID_VPA` | VPA/UPI address is invalid. |
| `INVALID_BENE_NAME` | Beneficiary name is invalid. |
| `INVALID_BENE_ADDRESS` | Beneficiary address or PIN/ZIP code is invalid. |
| `INVALID_BENE_EMAIL` | Beneficiary email is invalid. |
| `INVALID_BENE_CONTACT` | Beneficiary contact/mobile number is invalid. |
| `NAME_MISMATCH` | Remitter and beneficiary names do not match for the selected purpose. |
    Enum: "QUOTE_EXPIRED", "QUEUE_EXPIRED", "PAYOUT_REJECTED", "INSUFFICIENT_BALANCE", "INVALID_BENE_ACCOUNT_NUMBER", "INVALID_BENE_ACCOUNT_TYPE", "INVALID_BENE_IFSC", "INVALID_VPA", "INVALID_BENE_NAME", "INVALID_BENE_ADDRESS", "INVALID_BENE_EMAIL", "INVALID_BENE_CONTACT", "NAME_MISMATCH", "null"

  - `error_description` (string | null)
    A merchant-facing, human-readable description of the error. Operational copy for the merchant. `null` unless the payout is in an error state. See `customer_error_description` for the copy meant for the end-customer.
    Example: null

  - `customer_error_description` (string | null)
    Customer-facing error copy, written for the merchant to relay to their end-customer. Derives from the same `error_code` as `error_description` but targets a different audience. `null` when there is no `error_code`, or when the error code has no customer-facing variant (some codes are merchant-only).
    Example: null

  - `quote_id` (string | null)
    The identifier of the quote this payout was created against. `null` for payouts that were not created from a quote.
    Example: quote_3m4n5o6p7q

  - `taxes` (array)
    Taxes withheld on this payout, deducted from the amount before it reached the beneficiary. Present on repatriation payouts (purpose code `P0001`), where the remitting bank withholds GST on the currency conversion; empty for every other purpose, and empty until the bank has confirmed the payout.

  - `taxes.name` (string)
    The name of the tax withheld.
    Example: GST

  - `taxes.amount` (number)
    The tax amount, in the smallest unit of `currency`. For example, 877 is 8.77 INR.
    Example: 877

  - `taxes.currency` (string)
    The currency the tax was withheld in, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    Example: INR

  - `taxes.bps` (integer)
    The rate the tax was charged at, in basis points. 1800 is 18%.
    Example: 1800

  - `estimated_credit_date` (string | null)
    The date Glomo expects the beneficiary's account to be credited, as an ISO 8601 date (`YYYY-MM-DD`) in IST. Set once, when the payout moves to `in_progress`, and not updated afterwards. It accounts for bank cut-off times, weekends, and settlement holidays for `destination_currency`. It is an estimate, not a guarantee; a `status` of `success` confirms the beneficiary has been paid. `null` until the payout reaches `in_progress`, and stays `null` for payouts that fail or are cancelled before then.
    Example: 2026-06-05

  - `notes` (object | null)
    Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    Example: {"invoice_ref":"INV-2026-001","project":"Alpha"}

  - `payment_account_id` (string)
    The payment account the payout is sent from.
    Example: pacct_6ab59a10Hk3Zq

  - `receipt_ids` (array)
    IDs of the payment receipts that Glomo attached to the payout, such as the bank's confirmation. Empty until a receipt is attached.
    Example: []

## Response 400:

  - `400` (unknown)
    The payout was refused and nothing was created. Examples:
- `code`

`INSUFFICIENT_BALANCE`
 - the
`available`
 balance does not cover the payout.
`message`
 gives

the extra amount needed. The same error is returned when the balance cannot be read for a moment,

so a retry with the same
`request_id`
 is safe.
- `Payment account cannot send money`
 - the account is not
`active`
.
- `Payouts are not available`
 - payouts are not enabled for your account. Contact Glomo.
- `Purpose code S0802 is not allowed for payment account payouts`
 - use a code from the list.
- `Beneficiary verification is pending`
 or
`Beneficiary has been rejected`
 - the beneficiary is not

`active`
.
- `No rails available for this beneficiary`
 - the beneficiary does not support the quote's rail or

destination currency. Pick a quote for a rail it supports. The quote is not used.
- `Quote has expired`
 or
`Quote has already been used`
 - lock a new quote.
- `Fee amount is equal to or higher than the total transaction amount, try increasing the amount`
 -

the fees take the whole amount. Lock a quote for a larger amount.
- A validation message - a required field is missing,
`quote_id`
 does not start with
`quote_`
,

`beneficiary_id`
 does not start with
`bene_`
,
`request_id`
 is longer than 64 characters, or a

`notes`
 key is reserved.

## Response 400 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

## Response 404:

  - `404` (unknown)
    Not found. One of these is true:
- The payment account does not exist or you do not own it.
- The quote does not exist or was locked on another account.
- The beneficiary does not exist, was deleted, or is on another account.

## Response 404 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

## Response 409:

  - `409` (unknown)
    Another transaction on this payment account is in progress, such as another payout being created. Nothing was done. Retry with the same `request_id`.

## Response 409 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

