Skip to main content
POST
Create a payout with payout_method_data (including raw card details) or a saved payout_method_id.

Customer creation

Create the customer with POST /customers, then pass its ID as customer.id or customer_id. A customer ID is required for every payout create request. Unknown IDs return CustomerNotFound (HTTP 404). Inline customer attributes are ignored. The customer association is fixed at creation. Update and confirm use the stored ID and ignore supplied IDs. Payout links require the top-level customer_id.

External-vault card payouts

Use a card saved during a payment. Provide a unique payout_id, the saved payout_method_id, and the card owner’s customer_id or customer.id. Set confirm=true, auto_fulfill=true, payout_type=card, and recurring=false. These values apply when omitted for external-vault payouts. Send the request from your server; no separate confirmation call is required. For this flow, use the saved payout_method_id instead of inline payout_method_data. Do not send vault tokens or credentials.

Retry handling

After a timeout, retrieve the payout using its payout_id before submitting another request. Do not create a new payout ID to retry the same payout. Creating a payout with an existing payout_id returns a duplicate-payout error. Use merchant_order_reference_id for reconciliation, not retry protection.

Authorizations

api-key
string
header
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.

Body

application/json
amount
integer<int64>
required

The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,

Required range: x >= 0
currency
enum<string>
required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options:
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
merchant_order_reference_id
string | null

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Maximum string length: 255
Example:

"merchant_order_ref_123"

routing
object
connector
enum<string>[] | null

This field allows the merchant to manually select a connector with which the payout can go through.

Available options:
adyen,
adyenplatform,
checkout,
cybersource,
deutschebank,
ebanx,
gigadat,
gotyme_sanlam,
loonio,
mifinity,
nomupay,
nuvei,
payone,
paypal,
stripe,
truelayer,
trustly,
wise,
worldpay,
worldpayxml,
envoy,
itaubank,
santander
Example:
confirm
boolean | null
default:false

This field is used when merchant wants to confirm the payout, thus useful for the payout Confirm request. Ideally merchants should Create a payout, Update it (if required), then Confirm it.

Example:

true

payout_type
enum<string> | null

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Available options:
card,
bank,
wallet,
bank_redirect
payout_method_data
object

The payout method information required for carrying out a payout

source_bank_data
object
billing
object | null
auto_fulfill
boolean | null
default:false

Set to true to confirm the payout without review, no further action required

Example:

true

customer_id
string | null
deprecated

Existing customer ID used at creation. Ignored on update and confirm. Deprecated: Use customer.id instead.

Maximum string length: 255
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

customer
object | null

Passing this object creates a new customer or attaches an existing customer to the payment

return_url
string | null

The URL to redirect after the completion of the operation

Example:

"https://hyperswitch.io"

business_country
enum<string> | null
Available options:
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
business_label
string | null
deprecated

Business label of the merchant for this payout. Deprecated: Use profile_id instead.

Example:

"food"

description
string | null

A description of the payout

Example:

"It's my first payout request"

billing_descriptor
object | null

Billing descriptor information for a payout.

entity_type
enum<string> | null

Type of entity to whom the payout is being carried out to, select from the given list of options

Available options:
Individual,
Company,
NonProfit,
PublicSector,
NaturalPerson,
lowercase,
Personal
recurring
boolean | null
default:false

Specifies whether or not the payout request is recurring

metadata
object | null

Legacy vendor/individual details in metadata are a compatibility fallback for Stripe. Explicit sender_details takes precedence and is never merged with that identity. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

funds_transfer_type
enum<string> | null

The category of funds transfer to use when processing a payout.

Available options:
account_to_account,
funds_transfer,
cross_border_money_transfer,
peer_to_peer,
staged_digital_wallet_transfer,
funds_disbursement,
loyalty_payments,
payroll_and_pension_disbursements,
online_gambling,
mastercard_person_to_person,
mastercard_transfer_to_own_account,
mastercard_business_disbursement,
mastercard_business_to_business,
mastercard_gaming_repay
purpose
enum<string> | null

The purpose for which a payout is being carried out.

Available options:
donations,
education,
emergency_need,
expatriation,
family_support,
financial_services,
gifts,
income,
insurance,
investment,
it_services,
leisure,
loan_payment,
medical_treatment,
pension,
royalties,
savings,
travel_and_tourism,
other
sender_details
object

Details of the party providing the funds.

payout_token
string | null

Provide a reference to a stored payout method, used to process the payout.

Example:

"187282ab-40ef-47a9-9206-5099ba31e432"

profile_id
string | null

The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.

priority
enum<string> | null

The send method which will be required for processing payouts, check options for better understanding.

Available options:
instant,
fast,
regular,
wire,
cross_border,
internal

Whether to get the payout link (if applicable). Merchant need to specify this during the Payout Create, this field can not be updated during Payout Update.

Example:

true

Custom payout link config for the particular payout, if payout link is to be generated.

session_expiry
integer<int32> | null

Lifetime of the payout link in seconds, for example 900 for 15 minutes.

Required range: x >= 0
Example:

900

email
string | null
deprecated

Ignored. Deprecated: Manage customer details through the Customers API.

Maximum string length: 255
Example:

"johntest@test.com"

name
string | null
deprecated

Ignored. Deprecated: Manage customer details through the Customers API.

Maximum string length: 255
Example:

"John Test"

phone
string | null
deprecated

Ignored. Deprecated: Manage customer details through the Customers API.

Maximum string length: 255
Example:

"9123456789"

phone_country_code
string | null
deprecated

Ignored. Deprecated: Manage customer details through the Customers API.

Maximum string length: 255
Example:

"+1"

payout_method_id
string | null

Saved payment-method identifier, resolved internally for normal payouts and to vault tokens for proxy payouts.

browser_info
object | null

Browser information to be used for 3DS 2.0

Response

Payout created

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"

merchant_id
string
required

This is an identifier for the merchant account. This is inferred from the API key provided during the request

Maximum string length: 255
Example:

"merchant_1668273825"

amount
integer<int64>
required

The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,

Example:

1000

currency
enum<string>
required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options:
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
default:false
required

Set to true to confirm the payout without review, no further action required

Example:

true

customer_id
string
required
deprecated

Attached customer ID, if any. Deprecated: Use customer.id instead.

Maximum string length: 255
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

client_secret
string
required

Legacy client secret retained for compatibility. Payout execution requires an API key.

Example:

"pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"

return_url
string
required

The URL to redirect after the completion of the operation

Example:

"https://hyperswitch.io"

business_country
enum<string>
required
Available options:
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<string>
required

Type of entity to whom the payout is being carried out to, select from the given list of options

Available options:
Individual,
Company,
NonProfit,
PublicSector,
NaturalPerson,
lowercase,
Personal
recurring
boolean
default:false
required

Specifies whether or not the payout request is recurring

status
enum<string>
required
Available options:
success,
failed,
cancelled,
initiated,
expired,
reversed,
pending,
ineligible,
not_permitted,
requires_creation,
requires_confirmation,
requires_payout_method_data,
requires_fulfillment,
requires_vendor_account_creation
profile_id
string
required

The business profile that is associated with this payout

merchant_order_reference_id
string | null

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Maximum string length: 255
Example:

"merchant_order_ref_123"

connector
string | null

The connector used for the payout

Example:

"wise"

payout_type
enum<string> | null

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Available options:
card,
bank,
wallet,
bank_redirect
payout_method_data
object

The payout method information for response

source_bank_data
object

The payout method information for response

billing
object | null
customer
object | null

Details of customer attached to this payment

business_label
string | null
deprecated

Business label of the merchant for this payout. Deprecated: Use profile_id instead.

Example:

"food"

description
string | null

A description of the payout

Example:

"It's my first payout request"

billing_descriptor
object | null

Billing descriptor information for a payout.

metadata
object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

funds_transfer_type
enum<string> | null

The category of funds transfer to use when processing a payout.

Available options:
account_to_account,
funds_transfer,
cross_border_money_transfer,
peer_to_peer,
staged_digital_wallet_transfer,
funds_disbursement,
loyalty_payments,
payroll_and_pension_disbursements,
online_gambling,
mastercard_person_to_person,
mastercard_transfer_to_own_account,
mastercard_business_disbursement,
mastercard_business_to_business,
mastercard_gaming_repay
purpose
enum<string> | null

The purpose for which a payout is being carried out.

Available options:
donations,
education,
emergency_need,
expatriation,
family_support,
financial_services,
gifts,
income,
insurance,
investment,
it_services,
leisure,
loan_payment,
medical_treatment,
pension,
royalties,
savings,
travel_and_tourism,
other
sender_details
object

Details of the party providing the funds.

merchant_connector_id
string | null

Unique identifier of the merchant connector account

Example:

"mca_sAD3OZLATetvjLOYhUSy"

error_message
string | null

If there was an error while calling the connector the error message is received here

Example:

"Failed while verifying the card"

error_code
string | null

If there was an error while calling the connectors the code is received here

Example:

"E0001"

frm_message
object | null

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

created
string<date-time> | null

Time when the payout was created

Example:

"2022-09-10T10:11:12Z"

connector_transaction_id
string | null

Underlying processor's payout resource ID

Example:

"S3FC9G9M2MVFDXT5"

connector_eligibility_reference_id
string | null

Underlying processor's reference ID for the payout eligibility check

Example:

"8ad8bf30-5789-52be-a80a-72908abf5f9d"

priority
enum<string> | null

The send method which will be required for processing payouts, check options for better understanding.

Available options:
instant,
fast,
regular,
wire,
cross_border,
internal
attempts
object[] | null

List of attempts

email
string | null
deprecated

Customer's email. Deprecated: Use customer object instead.

Maximum string length: 255
Example:

"johntest@test.com"

name
string | null
deprecated

Customer's name. Deprecated: Use customer object instead.

Maximum string length: 255
Example:

"John Test"

phone
string | null
deprecated

Customer's phone. Deprecated: Use customer object instead.

Maximum string length: 255
Example:

"9123456789"

phone_country_code
string | null
deprecated

Customer's phone country code. Deprecated: Use customer object instead.

Maximum string length: 255
Example:

"+1"

unified_code
string | null

(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector

Maximum string length: 255
Example:

"UE_000"

unified_message
string | null

(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector

Maximum string length: 1024
Example:

"Invalid card details"

payout_method_id
string | null

Identifier for payout method