# Cancel a payout

Cancel a payout that has not yet reached a stage where it can no longer be stopped. A payout with `status: queued` can be cancelled at any time while it waits for the balance to cover it. Nothing is reversed, because no funds were held.

Endpoint: PATCH /payouts/{id}/cancel
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `id` (string, required)
    The unique identifier of the payout to cancel. Starts with `payout_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payout_`; a well-formed ID that doesn't match a payout on your account returns `404`.

## Response 200:

  - `200` (unknown)
    Payout cancelled successfully

## Response 200 fields (application/json):

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

  - `status` (string)
    The status of the payout.
    Example: 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 | null)
    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_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)
    How fees for this payout are collected.
    Example: merchant

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

## Response 400:

  - `400` (unknown)
    Bad request

## Response 404:

  - `404` (unknown)
    Payout not found

## Response 404 fields (application/json):

  - `error` (string)
    Enum: "Not found"

  - `message` (string)
    Entity not found
    Enum: "Entity not found"