# Mock update a payout status

Drives one of your payouts to a chosen status without any real money moving, so you can exercise your
webhook handling and reconciliation against statuses that are otherwise hard to reach on demand. The
target must be one of `pending`, `queued`, `success`, `failed`, `action_required` or `cancelled`. This
endpoint is not available in production.
The transition must be legal from the payout's current status — the same transition rules apply as in
production, so this cannot force a payout into a state it could not reach for real. An illegal
transition returns `400` with `State change not allowed` rather than quietly doing nothing, so that
error usually means the payout is not in the state you assumed.

Endpoint: PATCH /payouts/mock
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `id` (string)
    The `id` of the payout to update, as returned when you created it. A payout that does not exist, or belongs to another account, returns `404`.
    Example: payout_E602dMzgjpDC

  - `status` (string)
    The state to move the payout to. These are sandbox transition targets, not the values the payout's
`status` field returns:
- `pending` — accepts the payout for processing. It then reads as `in_progress`. On an account with
payout queueing, a payout that isn't `queued` yet is queued instead. A `queued` payout moves on only
if your balance covers it.
- `queued` — puts the payout in the payout queue. Only on an account with payout queueing.
- `success` — pays the payout out.
- `failed` — fails the payout.
- `action_required` — moves the payout to `action_required`.
- `cancelled` — cancels the payout.

A transition the payout's current status does not allow returns a `400`.
    Enum: "pending", "queued", "success", "failed", "action_required", "cancelled"

## Response 200:

  - `200` (unknown)
    Payout updated 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.
- `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 | 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