ZEzerohash
Payouts

Retrieve payout state

Changed on

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

get/payouts

Request

  • Base URL
    https://api.cert.zerohash.com
  • Auth
    API key in header X-SCX-API-KEY and API key in header X-SCX-PASSPHRASE

Query parameters

payout_idstring uuid
Example:f47ac10b-58cc-4372-a567-0e02b2c3d479

Public-facing payout identifier returned by POST /payouts (202 acknowledgement) and emitted on payout.status_updated webhooks. Mutually exclusive with idempotency_key.

idempotency_keystring
Example:client-supplied-uuid

The Idempotency-Key value the caller supplied on the original POST /payouts submission. Useful for reconciliation when the POST response was lost mid-flight and the caller is unsure whether a payout was created. Mutually exclusive with payout_id.

Headers

X-SCX-SIGNEDstring required

HMAC-SHA256 signature of the request, base64-encoded. See the Authentication guide for the exact signing formula.

X-SCX-TIMESTAMPstring required
Example:1678901234

Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.

Response

Current state of the payout.

payout_idstring uuid required
idempotency_keystring required
status'pending' | 'completed' | 'rejected' | 'failed' required
sub_statusstring 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.processing, payment.posted, payment.settled, payment.failed. payment.processing is emitted only for high-value payouts.

previous_sub_statusstring nullable

Null on the initial pending state.

created_atstring date-time required
updated_atstring 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' | 'external_account_creation_failed' | 'beneficiary_rejected' | 'ultimate_payor_rejected' | 'beneficiary_not_approved' | 'ultimate_payor_not_approved' | 'conflict_recovery_failed' | 'insufficient_balance' | 'temporarily_unavailable' | 'rejected_by_rules' | 'compliance_risk' | 'jurisdiction_not_allowed' nullable

Machine-readable failure code, present (non-null) on terminal *.rejected / payment.failed states.

account_model'omnibus' | 'fully_disclosed' required

Echo of the account_model supplied at submit time. Immutable per payout.

Example response

{
  "payout_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "idempotency_key": "client-supplied-uuid",
  "status": "completed",
  "sub_status": "payment.settled",
  "previous_sub_status": "payment.posted",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "resources": {
    "payor": {
      "participant_code": "PAYOR1",
      "payor": {
        "participant_code": "ORIG01",
        "status": "approved"
      }
    },
    "beneficiary": {
      "participant_code": "PART_7e2a4f9c",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_3b1d8e4a",
        "account_nickname": "Max's USDC wallet",
        "status": "approved",
        "details": {
          "network": "SOL",
          "supported_symbols": [
            "USDC"
          ],
          "crypto_address": "ab123..."
        },
        "created_at": "2026-05-06T12:01:00Z",
        "updated_at": "2026-05-06T12:01:20Z"
      }
    },
    "payment": {
      "payment_id": "pmt_4c9d2e10",
      "network": "SOL",
      "asset": "USDC",
      "quoted_asset": "USD",
      "total": "100.00",
      "rate": "1",
      "destination_amount": "100.00",
      "status": "posted",
      "description": "Monthly payout",
      "payment_details": {
        "withdrawal_request_id": "wr_uuid_xyz",
        "trade_id": "tr_uuid_qrs",
        "on_chain_transaction_id": "0xabc123...",
        "network_fee_notional": "0.01",
        "network_fee_quantity": "0.0000000384712"
      },
      "created_at": "2026-05-06T12:01:30Z",
      "updated_at": "2026-05-06T12:01:45Z"
    }
  },
  "account_model": "omnibus"
}

Changes

  • 47cf70ae701cRevision changes
    • warning

      added the new compliance_risk enum value to the response property for the response status

    • warning

      added the new conflict_recovery_failed enum value to the response property for the response status

    • warning

      added the new external_account_creation_failed enum value to the response property for the response status

    • warning

      added the new insufficient_balance enum value to the response property for the response status

    • warning

      added the new jurisdiction_not_allowed enum value to the response property for the response status

    • warning

      added the new rejected_by_rules enum value to the response property for the response status

    • warning

      added the new temporarily_unavailable enum value to the response property for the response status