Payouts - Retrieve

Retrieve details for a payout.

Endpoint GET https://sandbox.hyperswitch.io/payouts/{payout_id}

Authentication Header: api-key (string, required) Use the API key created under your merchant account from the HyperSwitch dashboard. Do not expose this key on a website or embed it in a mobile application.

cURL example

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

Response (200 application/json) — example

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

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: fields (summary)

payout_id (string, required) — Unique identifier for the payout. Required string length: 30. Example: "187282ab-40ef-47a9-9206-5099ba31e432"
merchant_id (string, required) — Identifier for the merchant account. Max length: 255. Example: "merchant_1668273825"
amount (integer, required) — Amount in the lowest denomination (e.g., cents). Example: 1000
currency (enum, required) — ISO 4217 currency code. Examples: "USD", "EUR". (Full list available in the reference.)
auto_fulfill (boolean, required, default:false) — Set to true to confirm the payout without review. Example: true
customer_id (string, required) — Identifier for the customer object. Max length: 255. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"
client_secret (string, required) — Token used for client side verification.
return_url (string, required) — URL to redirect after completion. Example: "https://hyperswitch.io"
business_country (enum, required) — Business country (ISO 3166-1 alpha-2). (Full list available in the reference.)
entity_type (enum, required) — Entity type receiving the payout. Options include "Individual", "Company", "NonProfit", etc.
recurring (boolean, required, default:false) — Whether the payout is recurring.
status (enum, required) — Payout status. Options include "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) — Business profile associated with this payout.
merchant_order_reference_id (string | null) — Merchant's unique identifier for the payout. Max length: 255.
connector (string | null) — Connector used for the payout (example: "wise").
payout_type (enum) — Payout type (required when confirming payouts). Options: "card", "bank", "wallet", "bank_redirect".
payout_method_data (object) — Payout method details (e.g., card attributes included in example).
billing (object) — Billing information (address, phone, email).
customer (object) — Customer details attached to the payout (id, name, email, phone, phone_country_code).
business_label (string | null) — Business label for this payout (example: "food").
description (string | null) — Description of the payout.
metadata (object) — Up to 50 keys; key names up to 40 chars and values up to 500 chars.
merchant_connector_id (string | null) — Merchant connector account ID.
error_message (string | null) — Connector error message if any.
error_code (string | null) — Connector error code if any.
created (string | null) — Time when the payout was created.
connector_transaction_id (string | null) — Underlying processor's payout resource ID.
priority (enum) — Send method for processing payouts. Options: "instant", "fast", "regular", "wire", "cross_border", "internal".
attempts (object[] | null) — List of attempts with details (attempt_id, status, amount, currency, connector, error_code, error_message, payment_method, payout_method_type, connector_transaction_id, cancellation_reason, unified_code, unified_message).
payout_link (object) — Payout link information (payout_link_id, link).
email, name, phone, phone_country_code (string | null) — Deprecated: use the customer object instead.
unified_code (string | null) — Unified error code across connectors (field not live yet).
unified_message (string | null) — Unified error message across connectors (field not live yet).
payout_method_id (string | null) — Identifier for payout method.

Good afternoon