Get Started
Payments Core APIs
Account management APIs
Other APIs
curl --request POST \
--url https://sandbox.hyperswitch.io/payouts/list \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"start_time": "2023-11-07T05:31:56Z",
"currency": "AED",
"entity_type": "Individual",
"end_time": "2023-11-07T05:31:56Z",
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_order_reference_id": "merchant_order_ref_123",
"profile_id": "<string>",
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"limit": 1,
"offset": 1,
"connector": [
"wise",
"adyen"
],
"status": [
"pending",
"failed"
],
"payout_method": [
"bank",
"card"
]
}
'{
"size": 1,
"data": [
{
"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>"
}
},
"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": "[email protected]",
"phone": "9123456789",
"phone_country_code": "+1"
},
"business_label": "food",
"description": "It's my first payout request",
"metadata": {},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"created": "2022-09-10T10:11:12Z",
"connector_transaction_id": "S3FC9G9M2MVFDXT5",
"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": "[email protected]",
"name": "John Test",
"phone": "9123456789",
"phone_country_code": "+1",
"unified_code": "UE_000",
"unified_message": "Invalid card details",
"payout_method_id": "<string>"
}
],
"total_count": 123
}Payouts - List using filters
curl --request POST \
--url https://sandbox.hyperswitch.io/payouts/list \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"start_time": "2023-11-07T05:31:56Z",
"currency": "AED",
"entity_type": "Individual",
"end_time": "2023-11-07T05:31:56Z",
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_order_reference_id": "merchant_order_ref_123",
"profile_id": "<string>",
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"limit": 1,
"offset": 1,
"connector": [
"wise",
"adyen"
],
"status": [
"pending",
"failed"
],
"payout_method": [
"bank",
"card"
]
}
'{
"size": 1,
"data": [
{
"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>"
}
},
"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": "[email protected]",
"phone": "9123456789",
"phone_country_code": "+1"
},
"business_label": "food",
"description": "It's my first payout request",
"metadata": {},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"created": "2022-09-10T10:11:12Z",
"connector_transaction_id": "S3FC9G9M2MVFDXT5",
"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": "[email protected]",
"name": "John Test",
"phone": "9123456789",
"phone_country_code": "+1",
"unified_code": "UE_000",
"unified_message": "Invalid card details",
"payout_method_id": "<string>"
}
],
"total_count": 123
}Authorizations
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
A type representing a range of time for filtering, including a mandatory start time and an optional end time.
The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed
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 Type of entity to whom the payout is being carried out to, select from the given list of options
Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal The end time to filter payments list or to get list of filters. If not passed the default time is now
The identifier for payout
30"187282ab-40ef-47a9-9206-5099ba31e432"
The merchant order reference ID for payout
255"merchant_order_ref_123"
The identifier for business profile
The identifier for customer
"cus_y3oqhf46pyzuxjbcn2giaqnb44"
The limit on the number of objects. The default limit is 10 and max limit is 20
x >= 0The starting point within a list of objects
x >= 0The list of connectors to filter payouts list
adyen, adyenplatform, cybersource, ebanx, gigadat, loonio, nomupay, nuvei, payone, paypal, stripe, wise, worldpay, worldpayxml ["wise", "adyen"]The list of payout status to filter payouts list
success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation ["pending", "failed"]The list of payout methods to filter payouts list
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 ["bank", "card"]Response
Payouts filtered
The number of payouts included in the list
x >= 0The list of payouts response objects
Show child attributes
Show child attributes
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.
30"187282ab-40ef-47a9-9206-5099ba31e432"
This is an identifier for the merchant account. This is inferred from the API key provided during the request
255"merchant_1668273825"
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.,
1000
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 Set to true to confirm the payout without review, no further action required
true
The identifier for the customer object. If not provided the customer ID will be autogenerated.
255"cus_y3oqhf46pyzuxjbcn2giaqnb44"
It's a token used for client side verification.
"pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"
The URL to redirect after the completion of the operation
"https://hyperswitch.io"
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 Type of entity to whom the payout is being carried out to, select from the given list of options
Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal Specifies whether or not the payout request is recurring
success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation The business profile that is associated with this payout
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.
255"merchant_order_ref_123"
The connector used for the payout
"wise"
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 payout method information for response
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
Show child attributes
Show child attributes
Masked payout method details for card payout method
Show child attributes
Show child attributes
Card expiry month
"01"
Card expiry year
"2026"
Card holder name
"John Doe"
Issuer of the card
Indicates the card network.
Visa, Mastercard, AmericanExpress, JCB, DinersClub, Discover, CartesBancaires, UnionPay, Interac, RuPay, Maestro, Star, Pulse, Accel, Nyce Card type, can be either credit or debit
Card issuing country
Code for Card issuing bank
Last 4 digits of the card number
The ISIN of the card
Extended bin of card, contains the first 8 digits of card number
Show child attributes
Show child attributes
Address details
Show child attributes
Show child attributes
The city, district, suburb, town, or village of the address.
50"New York"
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 first line of the street address or P.O. Box.
200"123, King Street"
The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
50"Powelson Avenue"
The third line of the street address, if applicable.
50"Bridgewater"
The zip/postal code for the address
50"08807"
The address state
"New York"
The first name for the address
255"John"
The last name for the address
255"Doe"
The zip/postal code of the origin
50"08807"
Details of customer attached to this payment
Show child attributes
Show child attributes
The identifier for the customer.
1 - 64"cus_y3oqhf46pyzuxjbcn2giaqnb44"
The customer's name
255"John Doe"
The customer's phone number
10"9123456789"
The country code for the customer's phone number
2"+1"
Business label of the merchant for this payout
"food"
A description of the payout
"It's my first payout request"
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.
Unique identifier of the merchant connector account
"mca_sAD3OZLATetvjLOYhUSy"
If there was an error while calling the connector the error message is received here
"Failed while verifying the card"
If there was an error while calling the connectors the code is received here
"E0001"
Time when the payout was created
"2022-09-10T10:11:12Z"
Underlying processor's payout resource ID
"S3FC9G9M2MVFDXT5"
The send method which will be required for processing payouts, check options for better understanding.
instant, fast, regular, wire, cross_border, internal List of attempts
Show child attributes
Show child attributes
Unique identifier for the attempt
success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation The payout attempt amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,
6583
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 The connector used for the payout
Connector's error code in case of failures
Connector's error message in case of failures
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 Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.
ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, paysera, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, bluecode, boleto, bca_bank_transfer, bni_va, breadpay, bri_va, bhn_card_network, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eft, eps, flexiti, fps, evoucher, giropay, givex, google_pay, go_pay, gcash, ideal, interac, indomaret, klarna, kakao_pay, local_bank_redirect, mandiri_va, knet, mb_way, mobile_pay, momo, momo_atm, multibanco, online_banking_thailand, online_banking_czech_republic, online_banking_finland, online_banking_fpx, online_banking_poland, online_banking_slovakia, oxxo, pago_efectivo, permata_bank_transfer, open_banking_uk, pay_bright, payjustnow, paypal, paze, pix, pay_safe_card, przelewy24, prompt_pay, pse, red_compra, red_pagos, samsung_pay, sepa, sepa_bank_transfer, sepa_guarenteed_debit, skrill, sofort, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, upi_qr, vipps, viet_qr, venmo, walley, we_chat_pay, seven_eleven, lawson, mini_stop, family_mart, seicomart, pay_easy, local_bank_transfer, mifinity, open_banking_pis, direct_carrier_billing, instant_bank_transfer, instant_bank_transfer_finland, instant_bank_transfer_poland, revolut_pay, indonesian_bank_transfer, open_banking A unique identifier for a payout provided by the connector
If the payout was cancelled the reason provided here
(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector
255"UE_000"
(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector
1024"Invalid card details"
Customer's email. Deprecated: Use customer object instead.
255Customer's name. Deprecated: Use customer object instead.
255"John Test"
Customer's phone. Deprecated: Use customer object instead.
255"9123456789"
Customer's phone country code. Deprecated: Use customer object instead.
255"+1"
(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector
255"UE_000"
(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector
1024"Invalid card details"
Identifier for payout method
The total number of available payouts for given constraints
Was this page helpful?