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_idfromPOST /quotes(withresource: 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.
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.
The currency from which the amount is deducted from your source balance.
The currency in which the beneficiary receives the payout. The currency code is in ISO 4217 format.
The amount you intend to send, in the smallest unit of the source currency (e.g. 1000 equates to $10.00 in USD).
Exactly one of source_amount or destination_amount must be provided (not both).
The amount the beneficiary will receive, in the smallest unit of the destination currency (e.g. cents for USD, paisa for INR).
Exactly one of source_amount or destination_amount must be provided (not both).
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. 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.
An optional invoice reference for this payout.
A unique client-generated identifier for this payout request. If a payout with the same request_id already exists for your business, the API returns a 409 Conflict response. Use this to safely retry payout creation without risk of creating duplicates. You can look up the existing payout using GET /v1/payouts?request_id=<your_request_id>.
List of document IDs to attach to the payout.
[ "doc_5JU9yv0lGSUP", "doc_678a5aa9SKkEr" ]
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. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
{ "invoice_ref": "INV-2026-001", "project": "Alpha" }
- CreatePayoutWithoutQuoteRequest
- CreatePayoutWithQuoteRequest
- Payout without quote (no quote_id)
- Payout with quote (quote_id present)
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": "PYR002",
"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"
}
}'Payout created successfully
The status of the payout.
The amount the beneficiary will receive, expressed in the smallest unit of the specified currency (e.g., cents for USD, paisa for INR). For example, 1000 represents $10.00 in USD. The actual currency is determined by the currency field. Note: "cents" is used generically to denote the minimal currency unit, not necessarily USD.
The currency code in ISO 4217 format. For example, USD.
The amount you intend to send, also specified in the smallest unit of the selected currency. For example, 1000 equates to $10.00 in USD. The currency field determines which currency is used. As with destination_amount, "cents" is a placeholder for the minimal unit, not specifically USD.
The currency code in ISO 4217 format. For example, USD.
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.
Timestamp representing when the payout was created
Timestamp representing when the payout was last updated
(Optional) Unique Transaction Reference for the payout. This is a unique identifier assigned by the bank to track the transaction.
The client-provided unique identifier for this payout request. Can be used to look up the payout via GET /v1/payouts?request_id=<your_request_id>.
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. swift is used for international transfers.
The invoice reference provided when the payout was created.
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. |
PAYOUT_REJECTED | Payout was rejected by the bank. Please reach out to support. (default fallback) |
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. |
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.
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).
The identifier of the quote this payout was created against. null for payouts that were not created from a quote.
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.
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. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
{ "invoice_ref": "INV-2026-001", "project": "Alpha" }
{ "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": [ { … } ], "notes": { "invoice_ref": "INV-2026-001", "project": "Alpha" } }