Payouts - Fulfill

POST /payouts/{payout_id}/fulfill

Confirm (fulfill) a payout.

Request

Headers

  • Content-Type: application/json

  • api-key: <api-key> (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"

Example (cURL)

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

Response

Status: 200 OK Content-Type: application/json Description: Payout fulfilled

Example response

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 (e.g., cents for USD). Example: 1000

  • currency (enum, required) — Three-letter ISO 4217 currency code. Example: AED See full list of supported currencies in the expandable section below.

  • 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. Max length: 255. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

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

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

  • business_country (enum, required) — Business country code. See full list in the expandable section below.

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

  • recurring (boolean, required, default:false) — Whether the payout is recurring.

  • status (enum, required) — Payout status. Options include 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) — Merchant's unique ID for reconciliation. Max length: 255.

  • connector (string|null) — Connector used for the payout (e.g., "wise").

  • payout_type (enum) — One of card, bank, wallet, bank_redirect.

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

  • billing (object) — Billing address/phone/email object.

  • customer (object) — Customer details (id, name, email, phone, phone_country_code).

  • business_label (string|null) — Merchant business label (e.g., "food").

  • description (string|null) — Description of the payout.

  • metadata (object) — Up to 50 keys; keys up to 40 chars, values up to 500 chars.

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

  • error_message (string|null) — Connector error message, if any.

  • error_code (string|null) — Connector error code, if any.

  • created (string|null) — Time when payout was created.

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

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

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

  • payout_link (object) — Payout link details.

  • 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.

  • unified_message (string|null) — (Not live yet) Unified error message across connectors.

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

Supported currencies (ISO 4217)

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

Supported business countries (ISO 3166-1 alpha-2)

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

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

Related: Payouts - Cancel, Payouts - Confirm

PreviousPayment Method - CreateNextPayments - Update Intent