Payouts - Cancel

POST /payouts/{payout_id}/cancel

Description: Cancel a payout.

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432"
}
'

Request

Authorization (header)

  • api-key (string, required) Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path parameters

  • payout_id (string, required) — The identifier for payout

Body (application/json)

  • payout_id (string, required) — Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response. Required string length: 30 Example: "187282ab-40ef-47a9-9206-5099ba31e432"

Successful Response (200, application/json)

Example:

Response Fields

  • payout_id (string, required) — Unique identifier for the payout. Required string length: 30. Example: "187282ab-40ef-47a9-9206-5099ba31e432"

  • merchant_id (string, required) — Identifier for the merchant account. Maximum length: 255. Example: "merchant_1668273825"

  • amount (integer, required) — Payout amount in the lowest denomination of the currency. Example: 1000

  • currency (enum, required) — Three-letter ISO 4217 currency code. Available options include: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

  • auto_fulfill (boolean, required, default: false) — Set to true to confirm the payout without review. Example: true

  • customer_id (string, required) — Identifier for the customer object. Maximum length: 255. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

  • client_secret (string, required) — Token used for client-side verification.

  • return_url (string, required) — URL to redirect after operation completion. Example: "https://hyperswitch.io"

  • business_country (enum, required) — Business country. Available options include: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US

  • entity_type (enum, required) — Type of entity receiving the payout. Options: Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal

  • recurring (boolean, required, default: false) — Specifies if payout is recurring

  • status (enum, required) — Payout status. Options: success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation

  • profile_id (string, required) — Business profile associated with this payout

  • merchant_order_reference_id (string | null) — Your unique identifier for this payout/order. Max length: 255. Example: "merchant_order_ref_123"

  • connector (string | null) — Connector used for the payout. Example: "wise"

  • payout_type (enum) — Payout type. Options: card, bank, wallet, bank_redirect

  • payout_method_data (object) — Payout method information (e.g., card details shown in example)

  • billing (object) — Billing address/phone/email (see example)

  • customer (object) — Customer details attached to this payment (see example)

  • business_label (string | null) — Business label for this payout. Example: "food"

  • description (string | null) — Payout description. Example: "It's my first payout request"

  • metadata (object) — Up to 50 keys (key names ≤ 40 chars; values ≤ 500 chars)

  • merchant_connector_id (string | null) — Unique identifier of the merchant connector account. Example: "mca_sAD3OZLATetvjLOYhUSy"

  • error_message (string | null) — Error message from connector if any. Example: "Failed while verifying the card"

  • error_code (string | null) — Connector error code. Example: "E0001"

  • created (string | null) — Time when payout was created. Example: "2022-09-10T10:11:12Z"

  • connector_transaction_id (string | null) — Underlying processor's payout resource ID. Example: "S3FC9G9M2MVFDXT5"

  • priority (enum) — Send method for processing payouts. Options: instant, fast, regular, wire, cross_border, internal

  • attempts (object[] | null) — List of attempts (see example)

  • payout_link (object) — Payout link object (see example)

  • email, name, phone, phone_country_code (string | null) — Deprecated (use customer object instead)

  • unified_code (string | null) — (Not live yet) Unified error code across connectors. Example: "UE_000"

  • unified_message (string | null) — (Not live yet) Unified error message. Example: "Invalid card details"

  • payout_method_id (string | null) — Identifier for payout method

Notes

  • The payout_id in both path and body identifies the payout.

  • Deprecated fields: email, name, phone, phone_country_code — prefer using the customer object.

Was this page helpful? Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payouts/payouts--cancel.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payouts/payouts--cancel

Related:

  • Payouts - Update: https://api-reference.hyperswitch.io/v1/payouts/payouts--update

  • Payouts - Fulfill: https://api-reference.hyperswitch.io/v1/payouts/payouts--fulfill

PreviousRouting - EliminationNextPayments - Capture