v1

latestOpenAPI 3.0.02026-07-26168846732.2 KB

Payouts

Payouts - Retrieve

get/payouts/{payout_id}

Path parameters

payout_idstring required

The identifier for payout

Query parameters

force_syncboolean nullable

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

Response

Payout retrieved

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

merchant_idstring required

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

merchant_order_reference_idstring nullable

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.

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

currency'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' required

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

connectorstring nullable

The connector used for the payout

payout_type'card' | 'bank' | 'wallet' | 'bank_redirect'

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.

auto_fulfillboolean required

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

customer_idstring required

The identifier for the customer object. If not provided the customer ID will be autogenerated. Deprecated: Use the customer object instead.

client_secretstring required

It's a token used for client side verification.

return_urlstring required

The URL to redirect after the completion of the operation

business_country'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' required

business_labelstring nullable

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

descriptionstring nullable

A description of the payout

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

recurringboolean required

Specifies whether or not the payout request is recurring

metadataobject nullable

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_idstring nullable

Unique identifier of the merchant connector account

error_messagestring nullable

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

error_codestring nullable

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

profile_idstring required

The business profile that is associated with this payout

createdstring date-time nullable

Time when the payout was created

connector_transaction_idstring nullable

Underlying processor's payout resource ID

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

emailstring nullable

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

namestring nullable

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

phonestring nullable

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

phone_country_codestring nullable

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

unified_codestring nullable

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

unified_messagestring nullable

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

payout_method_idstring nullable

Identifier for payout method

Example response

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "connector": "wise",
  "payout_method_data": {
    "card": {
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "source_bank_data": {
    "card": {
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "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"
    }
  },
  "auto_fulfill": true,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_label": "food",
  "description": "It's my first payout request",
  "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",
  "attempts": [
    {
      "amount": 6583,
      "unified_code": "UE_000",
      "unified_message": "Invalid card details"
    }
  ],
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details"
}