Payouts - Confirm

POST /payouts/{payout_id}/confirm

Confirm a payout previously created. Use this endpoint to provide payout method data, routing, and other required fields to process the payout.

cURL
curl --request POST \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id}/confirm \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data @- <<EOF
{
  "client_secret": "<string>",
  "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"],
  "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>"
  },
  "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

Authorization

  • api-key (header, required) Use the API key created under your merchant account from the HyperSwitch dashboard. This key authenticates requests from your merchant server only. Do not expose it on websites or mobile apps.

Path Parameters

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

Request Body (application/json)

Fields (high level):

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

  • merchant_order_reference_id (string | null) — merchant's unique ID for this payout (max 255 chars).

  • amount (integer | null) — amount in the lowest denomination of the currency (x >= 0).

  • currency (enum) — three-letter ISO 4217 currency code (e.g., "USD", "AED").

  • routing (object) — routing config (e.g., type: "single", data with connector & merchant_connector_id).

  • connector (enum[] | null) — optional list of preferred connectors (e.g., ["wise","adyen"]).

  • payout_type (enum) — required payout type: card, bank, wallet, bank_redirect.

  • payout_method_data (object) — payout method-specific data (card, bank, etc.).

  • billing (object) — billing address, phone, email.

  • auto_fulfill (boolean | null, default: false) — set true to confirm without review.

  • customer_id (string | null, deprecated) and customer (object) — use customer object to create/attach a customer.

  • return_url (string | null) — redirect URL after operation.

  • business_country (enum) — business country code.

  • business_label (string | null, deprecated) — deprecated; use profile_id.

  • description (string | null) — description for the payout.

  • entity_type (enum) — recipient entity type (Individual, Company, etc.).

  • recurring (boolean | null, default: false) — whether payout is recurring.

  • metadata (object) — up to 50 keys (key max 40 chars, value max 500 chars).

  • payout_token (string | null) — reference to stored payout method.

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

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

  • payout_link (boolean | null, default: false) — whether to generate a payout link (set at Create time).

  • payout_link_config (object) — custom config when payout_link is used.

  • session_expiry (integer | null) — expiry for client_secret in seconds (e.g., 900).

  • email, name, phone, phone_country_code (deprecated) — use customer object instead.

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

  • browser_info (object) — browser details for 3DS 2.0 flows.

(For nested objects such as routing, payout_method_data, billing, customer, browser_info — include fields shown in the sample request.)

Successful Response (200, application/json)

Example response:

Response Fields (selected)

  • payout_id (string) — unique payout identifier.

  • merchant_id (string) — merchant account identifier (inferred from api-key).

  • amount (integer) — payout amount (lowest currency denomination).

  • currency (string) — ISO 4217 currency code.

  • auto_fulfill (boolean) — whether payout was auto-fulfilled.

  • customer_id (string) — customer identifier.

  • client_secret (string) — token for client side verification.

  • status (enum) — payout status (e.g., success, failed, cancelled, initiated, pending, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation).

  • connector (string | null) — connector used for the payout.

  • payout_type (string) — card, bank, wallet, bank_redirect.

  • merchant_connector_id (string | null) — merchant connector account id.

  • error_message / error_code — connector-level error details where applicable.

  • created (date-time) — payout creation timestamp.

  • attempts (array) — list of connector attempts with details.

  • payout_link (object) — link details if a payout link was generated.

  • unified_code / unified_message — cross-connector unified error code/message (not live yet).

(See the sample response above for nested object structure and additional fields.)

Notes / Hints

  • client_secret is required for client-side verification flows.

  • Use the customer object instead of the deprecated email/name/phone fields.

  • payout_link must be requested during Create; it cannot be enabled during Update.

If you need the full list of allowed currency or country codes shown in the original docs, they are included in the request/response field descriptions above.

PreviousProfile - Connector Accounts ListNextRouting - Create