Get Started
Essentials
API Reference
- Payments
- Payment Methods
- Customers
- Mandates
- Refunds
- Disputes
- Organization
- Merchant Account
- Business Profile
- API Key
- Merchant Connector Account
- Payouts
- Event
- GSM (Global Status Mapping)
- Poll
- Blocklist
- Routing
- Relay
- Schemas
Payouts - List
curl --request GET \
--url https://sandbox.hyperswitch.io/payouts/list \
--header 'api-key: <api-key>'{
"size": 1,
"data": [
{
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_id": "merchant_1668273825",
"amount": 1000,
"currency": "AED",
"connector": "wise",
"payout_type": "card",
"payout_method_data": {
"card": {
"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>",
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe"
}
},
"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"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"auto_fulfill": true,
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1"
},
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"return_url": "https://hyperswitch.io",
"business_country": "AF",
"business_label": "food",
"description": "It's my first payout request",
"entity_type": "Individual",
"recurring": false,
"metadata": {},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"status": "success",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"profile_id": "<string>",
"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": "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>"
}
],
"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.
Query Parameters
The identifier for customer
A cursor for use in pagination, fetch the next list after some object
A cursor for use in pagination, fetch the previous list before some object
limit on the number of objects to return
The time at which payout is created
The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).
Response
The number of payouts included in the list
x > 0The list of payouts response objects
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.
30This is an identifier for the merchant account. This is inferred from the API key provided during the request
255The 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.,
The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.
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, CLP, CNY, COP, CRC, 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, 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
The identifier for the customer object. If not provided the customer ID will be autogenerated.
255It's a token used for client side verification.
The URL to redirect after the completion of the operation
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
The connector used for the payout
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 The payout method information for response
Masked payout method details for card payout method
Card expiry month
Card expiry year
Card holder name
Issuer of the card
Indicates the card network.
Visa, Mastercard, AmericanExpress, JCB, DinersClub, Discover, CartesBancaires, UnionPay, Interac, RuPay, Maestro 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
Address details
The address city
50AF, 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 address
200The second line of the address
50The third line of the address
50The zip/postal code for the address
50The address state
The first name for the address
255The last name for the address
255Details of customer attached to this payment
The identifier for the customer.
1 - 64The customer's name
255The customer's email address
255The customer's phone number
10The country code for the customer's phone number
2Business label of the merchant for this payout
A description of the payout
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
If there was an error while calling the connector the error message is received here
If there was an error while calling the connectors the code is received here
Time when the payout was created
Underlying processor's payout resource ID
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
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.,
The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.
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, CLP, CNY, COP, CRC, 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, 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 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, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, boleto, bca_bank_transfer, bni_va, bri_va, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eps, 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, paypal, paze, pix, pay_safe_card, przelewy24, prompt_pay, pse, red_compra, red_pagos, samsung_pay, sepa, sofort, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, 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 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(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector
1024Customer's email. Deprecated: Use customer object instead.
255Customer's name. Deprecated: Use customer object instead.
255Customer's phone. Deprecated: Use customer object instead.
255Customer's phone country code. Deprecated: Use customer object instead.
255(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(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector
1024Identifier for payout method
The total number of available payouts for given constraints
curl --request GET \
--url https://sandbox.hyperswitch.io/payouts/list \
--header 'api-key: <api-key>'{
"size": 1,
"data": [
{
"payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
"merchant_id": "merchant_1668273825",
"amount": 1000,
"currency": "AED",
"connector": "wise",
"payout_type": "card",
"payout_method_data": {
"card": {
"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>",
"card_exp_month": "01",
"card_exp_year": "2026",
"card_holder_name": "John Doe"
}
},
"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"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"auto_fulfill": true,
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1"
},
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"return_url": "https://hyperswitch.io",
"business_country": "AF",
"business_label": "food",
"description": "It's my first payout request",
"entity_type": "Individual",
"recurring": false,
"metadata": {},
"merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
"status": "success",
"error_message": "Failed while verifying the card",
"error_code": "E0001",
"profile_id": "<string>",
"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": "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>"
}
],
"total_count": 123
}