Payouts - Create
POST https://sandbox.hyperswitch.io/payouts/create
Example request (cURL)
curl --request POST \
--url https://sandbox.hyperswitch.io/payouts/create \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data @- <<EOF
{
"amount": 1,
"currency": "AED",
"merchant_order_reference_id": "merchant_order_ref_123",
"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>"
},
"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>"
}
}
EOFExample response (200)
Authorizations
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.
Request body (application/json) — fields
amount (integer, required) The payout amount in the lowest denomination of the currency (e.g., cents for USD). Required range: x >= 0.
currency (enum, required) Three-letter ISO 4217 currency code. Examples: AED, USD, EUR, INR, etc. (full list available).
merchant_order_reference_id (string | null) Your unique identifier for this payout/order. Max length 255. Example: "merchant_order_ref_123".
routing (object) Routing configuration for the payout. Example in request.
connector (enum[] | null) Optional list of connectors to attempt, e.g. ["wise", "adyen"].
confirm (boolean | null, default: false) If true, confirms the payout. Recommended flow: Create → Update (if needed) → Confirm.
payout_type (enum) Type of payout. Options: card, bank, wallet, bank_redirect. Mandatory for confirming payout.
payout_method_data (object) Payout method details (e.g., card details). See example request for card fields.
billing (object) Billing address, phone, email. See example request.
auto_fulfill (boolean | null, default: false) Set true to confirm the payout without review.
customer_id (string | null) — deprecated Identifier for customer. Deprecated: use customer object.
customer (object) Customer details; creating this attaches/creates a customer. See example.
return_url (string | null) URL to redirect after operation. Example: "https://hyperswitch.io".
business_country (enum) Business country code (ISO), e.g., AF, US, IN, etc. (full list available).
business_label (string | null) — deprecated Deprecated: use profile_id instead.
description (string | null) Description for the payout. Example: "It's my first payout request".
entity_type (enum) Type of entity receiving payout. Options include: Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal.
recurring (boolean | null, default: false) Whether payout is recurring.
metadata (object) Up to 50 keys; keys up to 40 chars, values up to 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 (enum) Send method for processing payouts. Options: instant, fast, regular, wire, cross_border, internal.
payout_link (boolean | null, default: false) Whether to generate a payout link (cannot be updated later).
payout_link_config (object) Payout link customization. See example request.
session_expiry (integer | null) Client secret expiry in seconds. Example: 900 (15 mins).
email, name, phone, phone_country_code — deprecated Customer fields deprecated in favor of customer object.
payout_method_id (string | null) Identifier for payout method.
browser_info (object) Browser/device info used for 3DS 2.0. See example request.
Response (200 application/json) — notable fields
payout_id (string, required) Unique identifier for the payout. Example: "187282ab-40ef-47a9-9206-5099ba31e432".
merchant_id (string, required) Merchant account identifier inferred from API key.
amount (integer, required) Amount in lowest denomination. Example: 1000.
currency (enum, required) Currency code.
auto_fulfill (boolean, required) True if payout was auto-fulfilled.
customer_id (string, required) Identifier for customer (may be autogenerated).
client_secret (string, required) Token used for client-side verification.
return_url (string, required) Redirect URL after operation.
business_country, entity_type, recurring, status, profile_id (various) Status can be one of: success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation.
merchant_order_reference_id (string | null) Merchant's order reference if provided.
connector (string | null) Connector used for payout. Example: "wise".
payout_type (enum) Payout type: card, bank, wallet, bank_redirect.
payout_method_data (object) Payout method details returned (e.g., card info with last4, expiry).
billing (object) Billing details.
customer (object) Customer attached to the payout.
merchant_connector_id (string | null) Merchant connector account ID. Example: "mca_sAD3OZLATetvjLOYhUSy".
error_message, error_code (string | null) Connector error details if any.
created (string | null) Creation timestamp. Example: "2022-09-10T10:11:12Z".
connector_transaction_id (string | null) Underlying processor's payout resource ID.
priority (enum) Send method used.
attempts (object[] | null) List of attempts with details (status, amount, connector, error info, unified_code/message, etc.).
payout_link (object) If generated, contains payout_link_id and link.
unified_code, unified_message (string | null) Unified error code/message across connectors (not live yet).
payout_method_id (string | null) Identifier for payout method.
If you want any specific fields expanded (for example, full lists of allowed currencies or country codes, or the full schema for routing/payout_method_data/browser_info), tell me which section and I will extract/format it into its own subsection or table.