Create a new payout

API reference

Create a new payout

Request

Create a payout in one of two ways:

Payout without quote — specify the beneficiary, currencies and amount inline. Fees and the FX rate are determined at creation time (CreatePayoutWithoutQuoteRequest).
Payout with quote — pass a quote_id from POST /quotes (with resource: payout) to settle against a locked rate and fee breakdown. The currencies, amount and payment rail are derived from the quote and must not be sent (CreatePayoutWithQuoteRequest).

The request variant is selected by the presence of quote_id. If payout queueing is enabled on your account, every payout is accepted with status: queued, including one that the balance in the source currency already covers, and a payout the balance does not cover is accepted instead of rejected. Glomo releases it automatically once the balance covers the amount plus fees. Fees and the FX rate are fixed at creation and honoured when the payout is released. Without payout queueing, a short balance is rejected at creation.

Security

JWT

Bodyapplication/jsonrequired

One of:

Create a payout without a quote by specifying the beneficiary, currencies and amount. Fees and the FX rate are determined at creation time. Use this variant when you have not pre-generated a quote. To create a payout against a locked quote instead, see CreatePayoutWithQuoteRequest.

purpose_codestringrequired

Why you are sending this payout, as a code from a fixed set: see Payout purpose codes. This is not free text. Pass a listed code exactly, for example S0802; matching is exact and case-sensitive. Payouts and payins use different sets, so a payin code such as P1401 is rejected here. An unrecognised code is rejected with 400 Bad Request.

INR payouts on a local rail (neft, imps, rtgs, upi) accept only a subset of the payout codes. A code outside that subset is rejected with 400 Bad Request, with a message saying the code is not valid for the selected payment rail.

Example:"S0802"

beneficiary_idstringrequired

The unique identifier for the beneficiary.

Example:"bene_5JU9yv0lGSUP"

source_currencystring, (iso-4217)required

The currency of the balance the payout is paid from, as an ISO 4217 code from the list above. Any other value returns 400 with a message containing Source currency is not supported.

Enum:"USD""EUR""GBP""AED""SGD""AUD"

Example:"USD"

destination_currencystring, (iso-4217)required

The currency in which the beneficiary receives the payout. The currency code is in ISO 4217 format.

Enum:"USD""EUR""GBP""AED""SGD""AUD""INR"

Example:"INR"

source_amountinteger, >= 1

The amount you intend to send, in the smallest unit of source_currency (cents for USD). 100000 is $1,000.00 when source_currency is USD. Exactly one of source_amount or destination_amount must be provided (not both).

Example:100000

destination_amountinteger, >= 1

The amount the beneficiary will receive, in the smallest unit of destination_currency (paise for INR, cents for USD). 8235000 is ₹82,350.00 when destination_currency is INR. Exactly one of source_amount or destination_amount must be provided (not both).

Example:8235000

payment_railstring

The payment rail to use for this payout. Each local rail serves one corridor and is only available when destination_currency matches it: 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 and is available on any corridor. The rail must be eligible for the beneficiary and the amount must fall inside the rail's limits. Defaults to swift if omitted; a local rail is not selected automatically.

Default:"swift"

Enum:"upi""rtgs""neft""imps""ipp""fts""sepa""fps""npp""swift"

Example:"neft"

invoice_numberstring, <= 50 characters

An optional invoice reference for this payout, up to 50 characters. It is returned on the payout as invoice_number. A longer value returns 400 with a message containing Invoice number must be 50 characters or less.

Example:"INV-2026-001"

request_idstring, <= 64 characters

Your unique identifier for this payout, at most 64 characters, used to reject duplicates. If a payout with the same request_id already exists on your account, the request is rejected with 409 Conflict and the message Record already exists; no second payout is created and the existing payout is not returned. Look it up with GET /v1/payouts?request_id=<your_request_id>. A value longer than 64 characters is rejected with 400.

Example:"req-7f3a9c20"

documentsArray of strings

List of document IDs to attach to the payout.

Example:

[
  "doc_5JU9yv0lGSUP",
  "doc_678a5aa9SKkEr"
]

notesobject or null(Notes)

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. 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"
}

curl -i -X POST \
  https://api.glomopay.com/api/v1/payouts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "purpose_code": "S0802",
    "beneficiary_id": "bene_a1b2c3d4e5",
    "source_currency": "USD",
    "destination_currency": "INR",
    "source_amount": 100000,
    "payment_rail": "neft",
    "invoice_number": "INV-2026-001",
    "request_id": "req-7f3a9c20",
    "documents": [
      "doc_11aa22bb33"
    ],
    "notes": {
      "internal_ref": "batch-42"
    }
  }'

Responses

Payout created successfully

Bodyapplication/json

idstringread-only

The unique identifier for the payout.

Example:"payout_DdWp_HUbOnlg"

statusstringread-only

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"

Example:"success"

destination_amountnumber, >= 1

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_currencystring, (iso-4217)

The currency code in ISO 4217 format. For example, USD.

Example:"USD"

source_amountnumber, >= 1

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_currencystring, (iso-4217)

The currency code in ISO 4217 format. For example, USD.

Example:"USD"

beneficiary_idstring

The unique identifier of the beneficiary the payout is sent to.

Example:"bene_5JU9yv0lGSUP"

documentsArray of objects(AttachedDocument)

The attached documents for the payout.

purpose_codestring

Purpose code of this payout, from the fixed set of payout purpose codes.

Example:"S0017"

mid_market_rateobjectread-only

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.

feesobjectread-only

The fees applied to this payout

created_atstring, (date-time)read-only

When the payout was created, as an ISO 8601 date-time in UTC.

Example:"2021-06-01T12:00:00Z"

updated_atstring, (date-time)read-only

When the payout was last updated, as an ISO 8601 date-time in UTC.

Example:"2021-06-01T12:00:00Z"

utrstring or nullread-only

(Optional) Unique Transaction Reference for the payout. This is a unique identifier assigned by the bank to track the transaction.

Example:"AXISN52024112000001234"

request_idstring or null, <= 64 charactersread-only

The request_id you sent when creating this payout, at most 64 characters; null if you sent none. Look the payout up with GET /v1/payouts?request_id=<your_request_id>.

Example:"your-internal-id"

payment_railstring or nullread-only

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"

Example:"swift"

invoice_numberstring or null, <= 50 charactersread-only

The invoice reference sent when the payout was created, up to 50 characters. null when none was sent.

Example:"INV-2026-001"

fee_collection_modestringread-only

How fees for this payout are collected.

Example:"merchant"

error_codestring or nullread-only

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"

Example:null

error_descriptionstring or nullread-only

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_descriptionstring or nullread-only

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_idstring or nullread-only

The identifier of the quote this payout was created against. null for payouts that were not created from a quote.

Example:"quote_3m4n5o6p7q"

taxesArray of objectsread-only

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.

estimated_credit_datestring or null, (date)read-only

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"

notesobject or null(Notes)

Example:

{
  "invoice_ref": "INV-2026-001",
  "project": "Alpha"
}

Response

{
  "id": "payout_DdWp_HUbOnlg",
  "status": "success",
  "destination_amount": 1000,
  "destination_currency": "USD",
  "source_amount": 1000,
  "source_currency": "USD",
  "beneficiary_id": "bene_5JU9yv0lGSUP",
  "documents": [
    { … }
  ],
  "purpose_code": "S0017",
  "mid_market_rate": {
    "currency": "USD",
    "rate": 1.17
  },
  "fees": {
    "fx_fee": { … },
    "txn_fee": { … }
  },
  "created_at": "2021-06-01T12:00:00Z",
  "updated_at": "2021-06-01T12:00:00Z",
  "utr": "AXISN52024112000001234",
  "request_id": "your-internal-id",
  "payment_rail": "swift",
  "invoice_number": "INV-2026-001",
  "fee_collection_mode": "merchant",
  "error_code": null,
  "error_description": null,
  "customer_error_description": null,
  "quote_id": "quote_3m4n5o6p7q",
  "taxes": [
    { … }
  ],
  "estimated_credit_date": "2026-06-05",
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}