Payouts - Update

Update an existing payout.

Endpoint POST /payouts/{payout_id}

cURL Example

curl
curl --request POST \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data @- <<EOF
{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "authipay",
      "merchant_connector_id": "<string>"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "confirm": false,
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "<string>",
      "expiry_year": "<string>",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>"
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "<string>",
  "priority": "instant",
  "payout_link": false,
  "payout_link_config": {
    "logo": "https://hyperswitch.io/favicon.ico",
    "merchant_name": "Hyperswitch",
    "theme": "#4285F4",
    "payout_link_id": "pm_collect_link_2bdacf398vwzq5n422S1",
    "enabled_payment_methods": "[{\"payment_method\": \"bank_transfer\", \"payment_method_types\": [\"ach\", \"bacs\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "[email protected]",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "<string>",
  "browser_info": {
    "color_depth": 1,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "<string>",
    "screen_height": 1,
    "screen_width": 1,
    "time_zone": 123,
    "ip_address": "<string>",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "<string>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  }
}
EOF

Successful Response (200)

Authorization

Header: api-key (string) — required

Use the API key created under your merchant account from the HyperSwitch dashboard. Do not expose this key in client-side code or mobile apps.

Path Parameters

  • payout_id (string) — required The identifier for the payout.

Request Body (application/json)

Fields (only shown with brief descriptions and examples):

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

  • amount (integer | null) Payout amount in the lowest currency denomination (e.g., cents). Required range: x >= 0. Example: 1000

  • currency (string enum) Three-letter ISO 4217 currency code. Example options: AED, USD, EUR, ... (full list supported)

  • routing (object) Routing configuration (type/data). Example shown in request body.

  • connector (string[] | null) Manually select connectors the payout can use. Example: ["wise", "adyen"]

  • confirm (boolean | null) — default: false Set to true to confirm the payout.

  • payout_type (string enum) Type of payout. Options: card, bank, wallet, bank_redirect

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

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

  • auto_fulfill (boolean | null) — default: false Set to true to confirm the payout without review.

  • customer_id (string | null) — deprecated (use customer object) Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

  • customer (object) Customer object to create or attach a customer.

  • client_secret (string | null) Token for client-side verification.

  • return_url (string | null) Redirect URL after operation. Example: "https://hyperswitch.io"

  • business_country (string enum) Two-letter country code (full list supported)

  • business_label (string | null) — deprecated (use profile_id) Example: "food"

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

  • entity_type (string enum) Entity type options: Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal

  • recurring (boolean | null) — default: false

  • metadata (object) Up to 50 keys, key names <= 40 chars, values <= 500 chars.

  • payout_token (string | null) Reference to stored payout method. Example: "187282ab-40ef-47a9-9206-5099ba31e432"

  • profile_id (string | null) Business profile to use for this payout.

  • priority (string enum) Send method options: instant, fast, regular, wire, cross_border, internal

  • payout_link (boolean | null) — default: false Whether to get a payout link. Must be specified during Create; cannot be updated here.

  • payout_link_config (object) Custom config when generating a payout link (logo, merchant_name, theme, etc.)

  • session_expiry (integer | null) Client secret expiry in seconds (e.g., 900)

  • email / name / phone / phone_country_code — deprecated (use customer object)

  • payout_method_id (string | null) Identifier for payout method

  • browser_info (object) Browser data used for 3DS 2.0

(See example request body above for full structure and field examples.)

Response (200 — application/json)

Returns the updated payout object. Key fields include:

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

  • merchant_id (string) — required Merchant account identifier.

  • amount (integer) — required

  • currency (string) — required

  • auto_fulfill (boolean) — required

  • customer_id (string) — required

  • client_secret (string) — required

  • return_url (string) — required

  • business_country (string) — required

  • entity_type (string) — required

  • recurring (boolean) — required

  • status (string enum) — required 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)

  • merchant_order_reference_id (string | null)

  • connector (string | null)

  • payout_type (string)

  • payout_method_data (object)

  • billing (object)

  • customer (object)

  • business_label (string | null)

  • description (string | null)

  • metadata (object)

  • merchant_connector_id (string | null)

  • error_message (string | null)

  • error_code (string | null)

  • created (string | null)

  • connector_transaction_id (string | null)

  • priority (string)

  • attempts (array of objects)

  • payout_link (object)

  • unified_code / unified_message (string | null)

  • payout_method_id (string | null)

(See the full response example above for complete output.)

Was this page helpful?

  • Yes / No

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

Related:

  • Payouts - Create: https://api-reference.hyperswitch.io/v1/payouts/payouts--create

  • Payouts - Cancel: https://api-reference.hyperswitch.io/v1/payouts/payouts--cancel

Responses are generated using AI and may contain mistakes.

PreviousRouting - RetrieveNextSetup Instructions