---
title: "Retrieve payout state"
method: GET
path: "/payouts"
tags: ["Payouts"]
---

# Retrieve payout state

`GET /payouts`

Returns the current lifecycle state of a payout. Identify the payout by **exactly one** of `payout_id` or `idempotency_key` — supplying neither or both returns `400 Bad Request`. The response is lifecycle-only (PII-free); full per-resource details are fetched from the existing per-resource endpoints (`GET /participants/{code}`, `GET /payments/external_accounts/{id}`, `GET /payments/{payment_id}`) once the caller has the identifier. All queries are scoped to the caller's `platform_code`; a `payout_id` belonging to another tenant returns `404 Not Found` (indistinguishable from a non-existent payout).

## Query parameters

- `payout_id` string, uuid
- `idempotency_key` string

## Headers

- `X-SCX-SIGNED` string, required
- `X-SCX-TIMESTAMP` string, required

## Response `200`

Current state of the payout.

- GetPayoutsResponse — Lifecycle-only view of a payout. PII (beneficiary natural-person fields, inline payor `info.entity` data, etc.) is NOT returned here — fetch from the per-resource GET endpoints when needed.
  - `payout_id` string, uuid, required
  - `idempotency_key` string, required
  - `status` 'pending' | 'completed' | 'rejected' | 'failed', required
  - `sub_status` string, nullable — Current sub-status (JSON-path notation mirroring the request tree). `null` on the initial pending webhook; non-null on every subsequent transition. One of: `payor.payor.submitted`, `payor.payor.pending_approval`, `payor.payor.approved`, `payor.payor.rejected`, `beneficiary.submitted`, `beneficiary.pending_approval`, `beneficiary.approved`, `beneficiary.rejected`, `beneficiary.external_account.submitted`, `beneficiary.external_account.approved`, `beneficiary.external_account.rejected`, `payment.submitted`, `payment.posted`, `payment.settled`, `payment.failed`.
  - `previous_sub_status` string, nullable — Null on the initial pending state.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required — Timestamp of the most recent sub-status transition. On terminal states (`payment.settled` / `*.rejected` / `payment.failed`) this is effectively the completion time.
  - `failure_reason` 'on_chain_transaction_failed' | 'payment_submission_failed' | 'beneficiary_creation_failed' | 'ultimate_payor_creation_failed' | 'external_account_rejected' | 'beneficiary_rejected' | 'ultimate_payor_rejected' | 'beneficiary_not_approved' | 'ultimate_payor_not_approved', nullable — Machine-readable failure code, present (non-null) on terminal `*.rejected` / `payment.failed` states.
  - `resources` PayoutResources, required — Lifecycle snapshot of the payout's downstream resources. Each sub-object is `null` until the corresponding resource is created. Full PII (beneficiary natural-person fields, the inline payor `info.entity` block) is intentionally NOT surfaced here — call the per-resource GET endpoints when full details are required.
    - `payor` PayoutResourcePayor — Lifecycle view of the payor chain. Top level carries `participant_code` (the onboarded merchant); the nested `payor` (if present) carries the upstream originator's `participant_code` and `status`. Inline `info` blocks are NOT echoed back on GET — fetch the originator via `GET /participants/{participant_code}` when full details are required.
      - `participant_code` string
      - `payor` object
        - `participant_code` string
        - `status` 'submitted' | 'pending_approval' | 'approved' | 'rejected'
    - `beneficiary` PayoutResourceBeneficiary — Beneficiary lifecycle view. Full beneficiary PII (name, DOB, address, ID numbers, etc.) is NOT included here — fetch via `GET /participants/{participant_code}`.
      - `participant_code` string
      - `status` 'submitted' | 'pending_approval' | 'approved' | 'rejected'
      - `external_account` PayoutResourceExternalAccount — External account lifecycle + non-PII details. `crypto_address`, `account_nickname`, and `destination_tag` are returned on GET but NOT on webhooks.
        - `external_account_id` string
        - `account_nickname` string
        - `status` 'submitted' | 'approved' | 'rejected'
        - `details` object
          - `network` string
          - `supported_symbols` string[]
          - `crypto_address` string
          - `destination_tag` string
        - `created_at` string, date-time
        - `updated_at` string, date-time
    - `payment` PayoutResourcePayment — Payment lifecycle + execution details.
      - `payment_id` string
      - `network` string
      - `asset` string
      - `quoted_asset` string
      - `total` string
      - `rate` string — Conversion rate applied to the payout, denominated in `quoted_asset` per unit of `asset`. `1` for 1:1 stablecoin transfers.
      - `destination_amount` string — Quantity of `asset` the beneficiary ultimately receives.
      - `status` 'submitted' | 'posted' | 'settled' | 'failed'
      - `description` string
      - `payment_details` PayoutResourcePaymentDetails — On-chain and zerohash references produced during payment execution. Populated progressively as the payment transitions through `posted` and `settled`.
        - `withdrawal_request_id` string
        - `trade_id` string
        - `on_chain_transaction_id` string — Public on-chain transaction identifier.
        - `network_fee_notional` string — Network fee expressed in `quoted_asset`, decimal string.
        - `network_fee_quantity` string — Network fee in the native asset of the chain, decimal string.
      - `created_at` string, date-time
      - `updated_at` string, date-time
  - `account_model` 'omnibus' | 'fully_disclosed', required — Echo of the `account_model` supplied at submit time. Immutable per payout.

## Other responses

- `400` — Neither or both of `payout_id` / `idempotency_key` were supplied.
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/zerohash/apis/zerohash-api.md) · [All operations](https://skmtc.net/zerohash/apis/zerohash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zerohash/zerohash-api/revisions/8b647d934363/schema)