# Cancel a payout

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

## Path parameters:

  - `id` (string, required)
    The unique identifier of the payout to cancel.

## Response 200 fields (application/json):

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

  - `status` (string)
    The status of the payout.
    Example: cancelled

  - `destination_amount` (number)
    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.
    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, 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.
    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 for the beneficiary.
    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 for why you want to receive this payment
    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 code
    Example: USD

  - `mid_market_rate.rate` (number | null)
    The conversion rate factor
    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)
    The currency code for the FX fee
    Example: USD

  - `fees.fx_fee.amount` (number)
    The amount of the FX fee
    Example: 200

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

  - `fees.txn_fee.currency` (string)
    The currency code for the transaction fee
    Example: USD

  - `fees.txn_fee.amount` (number)
    The amount of the transaction fee
    Example: 100

  - `created_at` (string)
    Timestamp representing when the payout was created
    Example: 2021-06-01T12:00:00Z

  - `updated_at` (string)
    Timestamp representing when the payout was last updated
    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 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>`.
    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`. `swift` is used for international transfers.
    Enum: "swift", "imps", "neft", "rtgs", "upi", "ipp", "fts", "sepa", "fps", null

  - `invoice_number` (string | null)
    The invoice reference provided when the payout was created.
    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. |
| `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. |
    Enum: "QUOTE_EXPIRED", "PAYOUT_REJECTED", "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

## Response 404 fields (application/json):

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

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