Payouts - Retrieve - Hyperswitch

Get Started

Essentials

API Reference

Admin API based

GET

payouts

{payout_id}

curl --request GET \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id} \
  --header 'api-key: <api-key>'

{
  "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>"
}

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.

Path Parameters

payout_id

string

required

The identifier for payout

Query Parameters

force_sync

boolean | null

Sync with the connector to get the payout details (defaults to false)

Response

200

application/json

Payout retrieved

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 length: 255

Example:

"merchant_1668273825"

amount

integer

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 currency code in uppercase. Eg: 'USD' for the United States Dollar.

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

The identifier for the customer object. If not provided the customer ID will be autogenerated.

Maximum length: 255

Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

client_secret

string

required

It's a token used for client side verification.

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,

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

connector

string | null

The connector used for the payout

Example:

"wise"

payout_type

enum<string>

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

payout_method_data

object

The payout method information for response

billing

object

billing.address

object

Address details

billing.phone

object

billing.email

string | null

customer

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example:

"food"

description

string | null

A description of the payout

Example:

"It's my first payout request"

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.

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"

created

string | 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"

priority

enum<string>

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

attempts.attempt_id

string

required

Unique identifier for the attempt

attempts.status

enum<string>

required

Available options:

success,

failed,

cancelled,

initiated,

expired,

reversed,

pending,

ineligible,

requires_creation,

requires_confirmation,

requires_payout_method_data,

requires_fulfillment,

requires_vendor_account_creation

attempts.amount

integer

required

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.,

Example:

6583

attempts.currency

enum<string>

The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.

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

attempts.connector

string | null

The connector used for the payout

attempts.error_code

string | null

Connector's error code in case of failures

attempts.error_message

string | null

Connector's error message in case of failures

attempts.payment_method

enum<string>

Available options:

card,

bank,

wallet

attempts.payout_method_type

enum<string>

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Available options:

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,

eft,

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,

sepa_bank_transfer,

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,

instant_bank_transfer

attempts.connector_transaction_id

string | null

A unique identifier for a payout provided by the connector

attempts.cancellation_reason

string | null

If the payout was cancelled the reason provided here

attempts.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 length: 255

Example:

"UE_000"

attempts.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 length: 1024

Example:

"Invalid card details"

payout_link

object

string | null

deprecated

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

Maximum length: 255

Example:

"johntest@test.com"

name

string | null

deprecated

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

Maximum length: 255

Example:

"John Test"

phone

string | null

deprecated

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

Maximum length: 255

Example:

"9123456789"

phone_country_code

string | null

deprecated

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

Maximum 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 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 length: 1024

Example:

"Invalid card details"

payout_method_id

string | null

Identifier for payout method

Payouts - Confirm Payouts - List

curl --request GET \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id} \
  --header 'api-key: <api-key>'

{
  "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>"
}