curl --request POST \
--url https://sandbox.hyperswitch.io/payouts/create \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"amount": 1000,
"auto_fulfill": true,
"confirm": true,
"connector": [
"cybersource"
],
"currency": "USD",
"customer_id": "cus_external_vault_123",
"entity_type": "Individual",
"merchant_order_reference_id": "merchant_payout_1001",
"payout_id": "payout_proxy_merchant_1001",
"payout_method_id": "pm_external_vault_123",
"payout_type": "card",
"profile_id": "pro_external_vault_123",
"recurring": false
}
'{
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_id": "merchant_1668273825",
"amount": 1000,
"currency": "AED",
"auto_fulfill": true,
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"return_url": "https://hyperswitch.io",
"business_country": "AF",
"entity_type": "Individual",
"recurring": false,
"status": "success",
"profile_id": "<string>",
"merchant_order_reference_id": "merchant_order_ref_123",
"connector": "wise",
"payout_type": "card",
"payout_method_data": {
"card": {
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe",
"card_issuer": "<string>",
"card_network": "Visa",
"card_type": "<string>",
"card_issuing_country": "<string>",
"bank_code": "<string>",
"last4": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>"
}
},
"source_bank_data": {
"card": {
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe",
"card_issuer": "<string>",
"card_network": "Visa",
"card_type": "<string>",
"card_issuing_country": "<string>",
"bank_code": "<string>",
"last4": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>"
}
},
"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>"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"customer_document_details": {
"document_type": "cpf",
"document_number": "12345678911"
}
},
"business_label": "food",
"description": "It's my first payout request",
"billing_descriptor": {
"reference": "<string>",
"statement_descriptor": "<string>"
},
"metadata": {},
"funds_transfer_type": "account_to_account",
"purpose": "donations",
"sender_details": {
"type": "individual",
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-31",
"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"
},
"email": "john.doe@example.com",
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"reference_id": "<string>",
"source_of_funds": "credit"
},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"frm_message": {
"frm_name": "<string>",
"frm_transaction_id": "<string>",
"frm_transaction_type": "<string>",
"frm_status": "<string>",
"frm_score": 123,
"frm_reason": null,
"frm_error": "<string>"
},
"created": "2022-09-10T10:11:12Z",
"connector_transaction_id": "S3FC9G9M2MVFDXT5",
"connector_eligibility_reference_id": "8ad8bf30-5789-52be-a80a-72908abf5f9d",
"priority": "instant",
"attempts": [
{
"attempt_id": "<string>",
"status": "success",
"amount": 6583,
"currency": "AED",
"connector": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"payment_method": "card",
"payout_method_type": "ach",
"connector_transaction_id": "<string>",
"cancellation_reason": "<string>",
"unified_code": "UE_000",
"unified_message": "Invalid card details"
}
],
"payout_link": {
"payout_link_id": "<string>",
"link": "<string>"
},
"email": "johntest@test.com",
"name": "John Test",
"phone": "9123456789",
"phone_country_code": "+1",
"unified_code": "UE_000",
"unified_message": "Invalid card details",
"payout_method_id": "<string>"
}Payouts - Create
curl --request POST \
--url https://sandbox.hyperswitch.io/payouts/create \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"amount": 1000,
"auto_fulfill": true,
"confirm": true,
"connector": [
"cybersource"
],
"currency": "USD",
"customer_id": "cus_external_vault_123",
"entity_type": "Individual",
"merchant_order_reference_id": "merchant_payout_1001",
"payout_id": "payout_proxy_merchant_1001",
"payout_method_id": "pm_external_vault_123",
"payout_type": "card",
"profile_id": "pro_external_vault_123",
"recurring": false
}
'{
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_id": "merchant_1668273825",
"amount": 1000,
"currency": "AED",
"auto_fulfill": true,
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"return_url": "https://hyperswitch.io",
"business_country": "AF",
"entity_type": "Individual",
"recurring": false,
"status": "success",
"profile_id": "<string>",
"merchant_order_reference_id": "merchant_order_ref_123",
"connector": "wise",
"payout_type": "card",
"payout_method_data": {
"card": {
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe",
"card_issuer": "<string>",
"card_network": "Visa",
"card_type": "<string>",
"card_issuing_country": "<string>",
"bank_code": "<string>",
"last4": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>"
}
},
"source_bank_data": {
"card": {
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe",
"card_issuer": "<string>",
"card_network": "Visa",
"card_type": "<string>",
"card_issuing_country": "<string>",
"bank_code": "<string>",
"last4": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>"
}
},
"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>"
},
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1",
"customer_document_details": {
"document_type": "cpf",
"document_number": "12345678911"
}
},
"business_label": "food",
"description": "It's my first payout request",
"billing_descriptor": {
"reference": "<string>",
"statement_descriptor": "<string>"
},
"metadata": {},
"funds_transfer_type": "account_to_account",
"purpose": "donations",
"sender_details": {
"type": "individual",
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-31",
"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"
},
"email": "john.doe@example.com",
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"reference_id": "<string>",
"source_of_funds": "credit"
},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"frm_message": {
"frm_name": "<string>",
"frm_transaction_id": "<string>",
"frm_transaction_type": "<string>",
"frm_status": "<string>",
"frm_score": 123,
"frm_reason": null,
"frm_error": "<string>"
},
"created": "2022-09-10T10:11:12Z",
"connector_transaction_id": "S3FC9G9M2MVFDXT5",
"connector_eligibility_reference_id": "8ad8bf30-5789-52be-a80a-72908abf5f9d",
"priority": "instant",
"attempts": [
{
"attempt_id": "<string>",
"status": "success",
"amount": 6583,
"currency": "AED",
"connector": "<string>",
"error_code": "<string>",
"error_message": "<string>",
"payment_method": "card",
"payout_method_type": "ach",
"connector_transaction_id": "<string>",
"cancellation_reason": "<string>",
"unified_code": "UE_000",
"unified_message": "Invalid card details"
}
],
"payout_link": {
"payout_link_id": "<string>",
"link": "<string>"
},
"email": "johntest@test.com",
"name": "John Test",
"phone": "9123456789",
"phone_country_code": "+1",
"unified_code": "UE_000",
"unified_message": "Invalid card details",
"payout_method_id": "<string>"
}payout_method_data (including raw card details) or a saved payout_method_id.
Customer creation
Create the customer withPOST /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 uniquepayout_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 itspayout_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
Body
The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
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 This field allows the merchant to manually select a connector with which the payout can go through.
adyen, adyenplatform, checkout, cybersource, deutschebank, ebanx, gigadat, gotyme_sanlam, loonio, mifinity, nomupay, nuvei, payone, paypal, stripe, truelayer, trustly, wise, worldpay, worldpayxml, envoy, itaubank, santander ["wise", "adyen"]
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.
card, bank, wallet, bank_redirect 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 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.
The category of funds transfer to use when processing a payout.
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 The purpose for which a payout is being carried out.
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 Response
Payout created
The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
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 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 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.
card, bank, wallet, bank_redirect The category of funds transfer to use when processing a payout.
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 The purpose for which a payout is being carried out.
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 Was this page helpful?