Submit or validate a payout

post

https://api.cert.zerohash.com/payouts

Single endpoint that drives the full payout lifecycle. The optional validate body field switches between two modes:

validate: true — runs the full pre-flight pipeline (schema, business-logic, address-validity and Travel Rule checks) with no side effects. Returns 200 OK with body {} on success, 400 Bad Request with errors[] on any validation failure (including a destination address that still needs Travel Rule information), 403 Forbidden with { error: true, message } if a payout party (beneficiary or ultimate payor) is not eligible under zerohash rules (e.g. not in an allowed jurisdiction) or the destination address is blocked by the Travel Rule compliance check, or 422 Unprocessable Entity with errors[] if the payout asset is currently depegged or the destination address is under Travel Rule review. Nothing is persisted; no beneficiary, external account, or payment is created, and no Travel Rule information is submitted in validate mode. The Idempotency-Key header is not required and is ignored if supplied.
validate: false or omitted (submit) — runs the same validation pipeline (same 400 / 403 / 422 rejections, nothing persisted), submits any beneficiary.external_account.travel_rule information the destination address still needs, then executes the payout. Requires the Idempotency-Key header. On success returns 202 Accepted with a slim { idempotency_key, payout_id, status } body; full resource state is retrieved via GET /payouts or observed on payout.status_updated webhooks. The (platform_code, Idempotency-Key) pair is unique: replaying the same key with the canonical-JSON-equivalent body returns the original 202 echo-back; replaying with a different body returns 400. A rejected request does not consume the key.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Payout payload. See PostPayoutsRequest for field-level rules.

Payout submission or pre-flight validation. When validate: true, zerohash runs the full validation pipeline (schema, business-logic, and address-validity checks) and returns 200 with an empty body on success or 400/422 on failure — nothing is persisted. When validate is omitted or false, the request is idempotent (require Idempotency-Key header) and on success returns 202 with a slim acknowledgement.

validate

boolean

Defaults to false

When true, runs the full validation pipeline with no side effects (nothing persisted, no downstream resource creation). When omitted or false, zerohash executes the payout.

payor

object

required

Top-level payor — the participant directly debited for the payout. Must be pre-onboarded via POST /participants/entity/new and referenced here by participant_code. The top-level payor is not onboarded inline. An optional nested payor represents the upstream originator (e.g., the merchant's customer), which MAY be inline-onboarded via PayorBlock.

beneficiary

required

Beneficiary block — the participant receiving the funds. Exactly one of participant_code (references an existing approved beneficiary) or info (inline entity/individual data to be onboarded by zerohash) must be supplied. external_account is always required and identifies the destination wallet.

In the EU regulatory context an inline beneficiary (info) is accepted only for a wallet the beneficiary owns: external_account must be inline (info) and carry travel_rule with address_belongs_to set to zh_participant, address_owner_type matching the beneficiary (business for an entity, individual for an individual), and no individual_pii, business_pii or wallet_proof_of_ownership; any other combination is rejected with 400. The Travel Rule check then runs once the beneficiary is onboarded, right before the payment is submitted; if the address is not allowed, the payout ends in payment.failed with a travel_rule_* failure reason. To pay out to a third-party wallet, or to send a proof of ownership, reference an onboarded beneficiary by participant_code.

payment

object

required

account_model

string

enum

required

Compliance setup applied to this payout. Required. Determines which party is treated as zerohash's legal customer for this transaction and which signed_agreements coverage is required:

omnibus — the top-level Payor is the legal customer. The Payor's onboarded signed_agreements must include user_agreement.
fully_disclosed — the Ultimate Payor (nested payor.payor) is the legal customer. The inline payor.payor.info.signed_agreements must include user_agreement.

Validated on submission (schema and signed-agreements checks). Echoed on GET /payouts. Immutable per payout — replays of the same Idempotency-Key with a different value return HTTP 400 payload-mismatch.

Allowed:

metadata

object

Caller-supplied free-form key-value pairs attached to the payout, supplied on the POST /payouts request body. Write-only: metadata is NOT returned on the POST /payouts response, NOT returned on GET /payouts, and NOT included on any payout.status_updated webhook. It is retained internally and is part of the idempotency body hash — replays with the same Idempotency-Key but different metadata return HTTP 400 payload-mismatch.

Limits: maximum 50 keys per object; each key 1–40 UTF-8 characters; each value 0–500 UTF-8 characters; strings only (no nested objects, arrays, numbers, booleans, or null values).

Caller responsibility — NO PII: Do NOT place sensitive data — government IDs, full names tied to financial data, account numbers, dates of birth, home addresses, crypto addresses, or any other PII — in metadata values. zerohash treats metadata as opaque.

Headers

X-SCX-SIGNED

string

required

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

X-SCX-TIMESTAMP

string

required

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

Idempotency-Key

string

Caller-supplied idempotency key (stable across retries of the same logical operation). Required when validate is omitted or false. Ignored in validate mode. zerohash stores a SHA-256 hash of the canonicalized JSON body alongside this key; a replay with the same key but a different body returns HTTP 400.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Validate-mode success (only returned when validate: true). All three validation tiers passed. Body is intentionally empty.

202Submit-mode success. The payout has been accepted and is now pending. Asynchronous processing continues; observe state changes via payout.status_updated webhooks or GET /payouts. Returned only when validate is omitted or false.

400Validation failure. A schema, business-logic, or address-validity check failed, OR an Idempotency-Key was reused with a different request body. Body uses the standard errors[] envelope. Nothing is persisted.

404Not Found

500Internal Server Error

503Service Unavailable