zerohash B.V. (the EU entity)
The following steps should be followed if you're onboarding a Customer to zerohash B.V. (the EU entity)

Base URL Change
For EU API calls, use the following base URL: https://api.zerohash.eu

Context

The Single API Call Payouts API lets platforms initiate a compliant stablecoin (or crypto) payout in a single API call. Rather than making four sequential calls to onboard participants, link an external account, and submit a payment, POST /payouts handles all of this in one request.

Participant Roles

Role	Description	Supported types	Example `participant_code`
Platform	The zerohash partner submitting the API request. Must have a signed MSA contract with zerohash.	n/a	`PLAT01`
Payor	The entity or individual submitting payouts on behalf of the Ultimate Payor. Pre-registered via POST /participants/entity/new with zerohash and referenced by `participant_code` on every request.	`entity`, `individual`	`PAYOR1`
Ultimate Payor	The entity or individual whose funds are being sent. zerohash creates and manages this participant internally.	`entity`, `individual`	`UPAYR1`
Beneficiary	The entity or individual receiving the payout.	`entity`, `individual`	`BENEF1`

Account Models

The account_model field controls how participants are treated from a regulatory and compliance perspective. Your zerohash account must be configured for a given account model before it can be used.

Model	Description
`fully_disclosed`	The Ultimate Payor is a legal zerohash customer, signs zerohash T&Cs, and is subject to KYB/KYC. The Payor does not put this activity within their own licenses.
`omnibus`	The Payor is a licensed money service business that puts this activity within their own licenses and is the legal zerohash customer. The Ultimate Payor is not a direct zerohash customer.

Pass the account model on every POST /payouts request:

{
  "account_model": "fully_disclosed",
  ...
}

Fund Float Account

You will fund their float account by sending fiat to the mutually decided-upon bank account. Here are the account details:

- participant_code: 00SCXM

- account_group: PLAT01 (replace with your Platform's code)

- account_label: general

- account_type: available

- asset: USD

ℹ️
In Cert, your platform will be pre-funded with Float account funds.

Onboard Payor

⚠️
Approval Required
The Payor PII requirements reflected below require prior approval for your integration. Contact your zerohash representative to begin the review process.

High level requirements

1. Submit entity info (POST /participants/entity/new)
2. Submit entity documents (POST /participants/entity/documents)

Submit Entity Info

Use the POST /participants/entity/new endpoint to pre-register the Payor.

Request Example:

{
  "request_id": "b2c3d4e5-6789-01bc-defg-234567890bcd",
  "entity_name": "Entity B",
  "legal_name": "Entity B B.V.",
  "contact_number": "31201234567",
  "website": "https://entityb.eu",
  "date_established": "2018-03-10",
  "entity_type": "llc",
  "address_one": "Herengracht 100",
  "address_two": "",
  "city": "Amsterdam",
  "postal_code": "1015 BS",
  "jurisdiction_code": "NL",
  "tax_id": "NL861821195B01",
  "id_issuing_authority": "Netherlands",
  "risk_rating": "low",
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1603378501286,
  "signed_timestamp": 1603378501286,
  "submitter_email": "[email protected]",
  "submitter_first_name": "Anna",
  "submitter_last_name": "de Vries",
  "submitter_title": "Compliance Officer",
  "lei_number": "724500XVX2LKTAJ2ML85",
  "chamber_of_commerce_number": "34123456",
  "reason_for_business_relationship": "Provision of digital asset custody and settlement services to entity clients",
  "expected_transaction_volume": 500,
  "expected_transaction_value": 2500000,
  "activity_location": [
    "NL",
    "DE",
    "FR"
  ],
  "source_of_funds": "Operating revenue from business activities",
  "no_persons_with_effective_control_declaration": false,
  "declaration_no_foreseeable_ownership_changes": true,
  "board_members": [
    {
      "first_name": "Johan",
      "last_name": "Bakker",
      "date_of_birth": "1975-04-22",
      "place_of_birth": "Rotterdam, Netherlands"
    }
  ],
  "control_persons": [
    {
      "name": "Johan Bakker",
      "first_name": "Johan",
      "last_name": "Bakker",
      "email": "[email protected]",
      "address_one": "Herengracht 100",
      "city": "Amsterdam",
      "postal_code": "1015 BS",
      "citizenship_code": "NL",
      "country_of_birth": "NL",
      "date_of_birth": "1975-04-22",
      "id_number_type": "passport",
      "id_number": "NL1234567",
      "id_issuing_authority": "Netherlands",
      "role": "Managing Director",
      "ownership_percentage": 0,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1603378501286,
      "control_person": 1,
      "kyc": "pass",
      "kyc_timestamp": 1603378501286
    }
  ],
  "beneficial_owners": [
    {
      "name": "Maria Jansen",
      "first_name": "Maria",
      "middle_name": "Elisabeth",
      "last_name": "Jansen",
      "phone_number": "31612345678",
      "city": "Amsterdam",
      "country": "NL",
      "country_of_birth": "NL",
      "citizenship_code": "NL",
      "date_of_birth": "1980-11-02",
      "tax_id": "123456789",
      "id_number_type": "legal_entity_identifier",
      "id_number": "123456789",
      "id_issuing_authority": "Netherlands",
      "ownership_percentage": 30,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1603378501286,
      "kyc": "pass",
      "kyc_timestamp": 1603378501286
    }
  ],
  "signed_agreements": [
    {
      "type": "fund_auto_convert",
      "region": "eu",
      "signed_timestamp": 1603378501286
    }
  ]
}

The response will contain a participant_code - you will need this in your upcoming POST /participants/entity/documents and the POST /payouts call.

The status of the Payor will be submitted until all required documents are subsequently submitted.

Submit Entity Documents

Use the POST /participants/entity/documents endpoint to attach documents to the Payor:

{
  "participant_code": "PAYOR1",
  "document_type": "lei_certificate",
  "document": "<base64-encoded file>",
  "mime": "application/pdf",
  "file_name": "entity_b_lei_certificate.pdf"
}

Named Document Types

`document_type`	Required For	Notes
`lei_certificate`	`All EU NNPs`	Legal Entity Identifier certificate
`chamber_of_commerce_excerpt`	`All EU NNPs`	Certified Chamber of Commerce (COC) excerpt
`annual_accounts`	`All EU NNPs`	Most recent annual accounts
`power_of_attorney`	Representative authorisation (one of these two)	Accepted forms defined in the integration guide
`board_resolution`	Representative authorisation (one of these two)	Accepted forms defined in the integration guide
`legal_opinion`	Only when `is_complex_structure` = `true` on the entity payload	Not required otherwise

General Document Bucket

supporting_document is a catch-all for everything else - optional, multiple uploads permitted per submission, no content validation enforced, accepted at any point in the submission lifecycle. Pass a free-text document_description field to label what's being uploaded, e.g.:

- "UBO certified ID"
- "Group structure chart — signed by board member"
- "Legal opinion - complex ownership structure"
- "Trust agreement"

Request Examples
Named document type:

{
  "participant_code": "PAYOR1",
  "document_type": "lei_certificate",
  "document": "<base64-encoded file>",
  "mime": "application/pdf",
  "file_name": "entity_b_lei_certificate.pdf"
}

Supporting document (general bucket):

{
  "participant_code": "PAYOR1",
  "document_type": "supporting_document",
  "document_description": "UBO certified ID — Maria Jansen",
  "document": "<base64-encoded file>",
  "mime": "application/pdf",
  "file_name": "ubo_id_maria_jansen.pdf"
}

Response:

// 201
{
  "document_id": "doc_9f13a2b4",
  "participant_code": "PAYOR1",
  "document_type": "lei_certificate",
  "status": "submitted",
  "created_at": "2026-07-31T14:02:00Z"
}

Once the required documents have been created, the Payor will transition to an approved status

Validate Payout Request

Before submitting a live payout via POST /payouts, you can validate your request payload without executing any actions on the backend. Set "validate": true in the request body.
zerohash performs four checks:

- Schema validation - all required fields are present and correctly formatted
- Business logic validation - account model permissibility, required agreements, and other rules
- Address validation - the destination crypto address is not on zerohash's deny-list and is compatible with the specified blockchain network (e.g., a BTC address for a SOL payout is rejected)
- Travel Rule validation - destination crypto address has sufficient travel rule information provided to meet TFR requirements.

The idempotency key may be omitted when validating.

What changes vs. the US example:

Field	US	EU
`jurisdiction_code`	State-level (e.g. `US-IL`)	Country-level only (e.g. `NL`) - no state
`tax_id`	EIN	VAT number
`postal_code`	Conditionally required if `jurisdiction_code` = `US-XX`	`Not conditional on a US jurisdiction - always required for EU addresses`
`lei_number`	Not present	Added - Legal Entity Identifier
`chamber_of_commerce_number`	Not present	Added - Chamber of Commerce (COC) registration number
`reason_for_business_relationship`	Not present	Added
`expected_transaction_volume`	Not present	Added - required for all EU NNPs, not just EDD
`expected_transaction_value`	Not present	Added - required for all EU NNPs, not just EDD
`activity_location`	Not present	Added - countries where the entity is active
`source_of_funds`	Not present	Added - required for all EU NNPs
`signed_agreements[].region`	`"us"`	`"eu"`
Beneficiary identifier (individual)	`tax_id` (SSN/ITIN) or `id_number` + `id_number_type`	`id_number` + `id_number_type`. `tax_id` is not allowed when `id_issuing_authority` is not `US`.
Beneficiary `id_issuing_authority`	`US` or ISO 3166-1 alpha-2	ISO 3166-1 alpha-2 country code (e.g. `FR`)
`beneficiary.external_account.travel_rule`	Not present	Required unless Travel Rule information was already provided through `POST /travel-rule/submit`
`travel_rule.address_belongs_to`	Not present	Always `zh_participant`
EU-only entity fields (`lei_number`, `chamber_of_commerce_number`, and so on)	Not present	Ultimate Payor only. Not accepted for the Beneficiary.

POST /payouts request:

{
  "account_model": "fully_disclosed",
  "validate": true,
  "payor": {
    "participant_code": "PAYOR1",
    "payor": {
      "info": {
        "entity": {
          "onboarding_profile": "payouts_payor_ultimate",
          "legal_name": "Entity B B.V.",
          "contact_number": "+31201234567",
          "address_one": "Herengracht 100",
          "address_two": "Suite 4",
          "city": "Amsterdam",
          "postal_code": "1015 BS",
          "jurisdiction_code": "NL",
          "email": "[email protected]",
          "tax_id": "NL861821195B01",
          "id_issuing_authority": "Netherlands",
          "merchant_category_code": "4511",
          "lei_number": "724500XVX2LKTAJ2ML85",
          "chamber_of_commerce_number": "34123456",
          "reason_for_business_relationship": "Provision of digital asset custody and settlement services to entity clients",
          "expected_transaction_volume": 500,
          "expected_transaction_value": 2500000,
          "activity_location": ["NL", "DE", "FR"],
          "source_of_funds": "Operating revenue from business activities",
          "sanction_screening": "pass",
          "sanction_screening_timestamp": 1603378501286,
          "signed_agreements": [
            {
              "type": "user_agreement",
              "region": "eu",
              "signed_timestamp": 1603378501286
            }
          ]
        }
      }
    }
  },
  "beneficiary": {
    "info": {
      "individual": {
        "onboarding_profile": "payouts_beneficiary",
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+33612345678",
        "date_of_birth": "1985-09-02",
        "address_one": "123 Rue de Rivoli",
        "city": "Paris",
        "postal_code": "75001",
        "jurisdiction_code": "FR",
        "citizenship_code": "FR",
        "id_number_type": "passport",
        "id_number": "12AB34567",
        "id_issuing_authority": "FR"
      }
    },
    "external_account": {
      "info": {
        "network": "SOL",
        "crypto_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "supported_symbols": ["USDC"]
      },
      "travel_rule": {
        "address_belongs_to": "zh_participant",
        "address_owner_type": "individual",
        "wallet_type": "self_custody",
        "wallet_proof_of_ownership": {
          "document": "<base64-encoded document>",
          "mime": "application/pdf"
        }
      }
    }
  },
  "payment": {
    "asset": "USDC.SOL",
    "quoted_asset": "USD",
    "total": "100.00",
    "description": "Contractor payout"
  },
  "metadata": {
    "client_ref": "your-internal-ref-id",
    "campaign": "weekly-contractor-payout"
  }
}

Responses:

Status	Meaning
`200 {}`	All validations passed. Your live request will succeed.
`400`	One or more validations failed. See errors array for details.

// 400 — schema validation failure
{
  "errors": ["zip format is not valid"]
}

// 400 — unexpected field
{
  "errors": ["unexpected field: network_fee_notional"]
}

[Recommended] Whitelist a self-custody receiving wallet's Travel Rule information

Proof of ownership is required for self-custody wallets above the Travel Rule threshold. zerohash manually reviews each submission, which can take up to 2 days, so it is recommended that you submit it well before you plan to initiate the payout. Until the review is approved, payouts to that wallet are limited to €1,000 every 12 hours.

Request - POST /travel-rule/submit

{
  "participant_code": "BENEF1",
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "address_belongs_to": "zh_participant",
  "address_owner_type": "individual",
  "wallet_type": "self_custody",
  "wallet_proof_of_ownership": {
    "document": "<base64-encoded document>",
    "mime": "application/pdf"
  }
}

Warning: Skip this step for Exchange wallets. Their Travel Rule information is retained only briefly and does not require manual review, so submission during POST /payouts is sufficient. Find more information on Travel Rule here.

At any time, you can confirm a wallet's Travel Rule information availability through GET /travel-rule/state-approval

Request - GET /travel-rule/state-approval

{
  "intention_action": "withdrawal",
  "participant_code": "BENEF1",
  "wallet_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "asset": "USDC.SOL",
  "crypto_amount": "100"
}

intention_action (required): deposit or withdrawal. For a payout, set to withdrawal
participant_code (withdrawal only): 6 uppercase alphanumeric characters. For a payout, use the beneficiary’s code.
wallet_address (withdrawal only): non-empty string. Should match beneficiary.external_account.crypto_address

Response - GET /travel-rule/state-approval

{
  "message": {
    "status": "action_required",
    "status_reasons": ["proof_of_ownership"]
  }
}

Other GET /travel-rule/state-approval responses:

`status`	`status_reasons`	Meaning
`allowed`	not returned	Travel Rule checks have passed
`action_required`	`["info_required"]`	Owner identity information, or the hosting VASP, is needed. Send it with `POST /travel-rule/submit`.
`action_required`	`["proof_of_ownership"]`	A self-custody wallet needs `wallet_proof_of_ownership`
`processing`	not returned	Information has been received and is under review
`blocked`	not returned	The transfer was rejected and can’t go ahead
`unknown`	not returned	The status couldn’t be determined

Initiate Payout - New Participants

Use this pattern when submitting a payout for participants that have not been previously onboarded with zerohash. Provide full PII inline for the Ultimate Payor and Beneficiary. zerohash creates the corresponding participant_code values automatically.

For now - only entity types are supported for the Ultimate Payor. For the Beneficiary, both entity and individual are currently supported

Request - Individual Beneficiary:

{
  "account_model": "fully_disclosed",
  "payor": {
    "participant_code": "PAYOR1",
    "payor": {
      "info": {
        "entity": {
          "onboarding_profile": "payouts_payor_ultimate",
          "legal_name": "Entity B B.V.",
          "contact_number": "+31201234567",
          "address_one": "Herengracht 100",
          "address_two": "Suite 4",
          "city": "Amsterdam",
          "postal_code": "1015 BS",
          "jurisdiction_code": "NL",
          "email": "[email protected]",
          "tax_id": "NL861821195B01",
          "id_issuing_authority": "Netherlands",
          "merchant_category_code": "4511",
          "lei_number": "724500XVX2LKTAJ2ML85",
          "chamber_of_commerce_number": "34123456",
          "reason_for_business_relationship": "Provision of digital asset custody and settlement services to entity clients",
          "expected_transaction_volume": 500,
          "expected_transaction_value": 2500000,
          "activity_location": ["NL", "DE", "FR"],
          "source_of_funds": "Operating revenue from business activities",
          "sanction_screening": "pass",
          "sanction_screening_timestamp": 1603378501286,
          "signed_agreements": [
            {
              "type": "user_agreement",
              "region": "eu",
              "signed_timestamp": 1603378501286
            }
          ]
        }
      }
    }
  },
  "beneficiary": {
    "info": {
      "individual": {
        "onboarding_profile": "payouts_beneficiary",
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+33612345678",
        "date_of_birth": "1985-09-02",
        "address_one": "123 Rue de Rivoli",
        "city": "Paris",
        "postal_code": "75001",
        "jurisdiction_code": "FR",
        "citizenship_code": "FR",
        "id_number_type": "passport",
        "id_number": "12AB38567",
        "id_issuing_authority": "FR"
      }
    },
    "external_account": {
      "info": {
        "network": "SOL",
        "crypto_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "supported_symbols": ["USDC"]
      },
      "travel_rule": {
        "address_belongs_to": "zh_participant",
        "address_owner_type": "individual",
        "wallet_type": "hosted",
        "casp_did": "did:ethr:0x9a4b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"
      }
    }
  },
  "payment": {
    "asset": "USDC.SOL",
    "quoted_asset": "USD",
    "total": "100.00",
    "description": "Contractor payout"
  },
  "metadata": {
    "client_ref": "your-internal-ref-id",
    "campaign": "weekly-contractor-payout"
  }
}

Notes:

In the EU, Travel Rule information must be provided for the Beneficiary's receiving wallet before a payout can be initiated. Learn more about Travel Rule Requirements here.
- travel_rule.address_belongs_to must always be set to "zh_participant" for EU Single API Call Payouts.
For the Ultimate Payor entity (EU NNP): jurisdiction_code is country-level only (no state), tax_id is the VAT number, and lei_number, chamber_of_commerce_number, reason_for_business_relationship, expected_transaction_volume, expected_transaction_value, activity_location, and source_of_funds are added.

Request - Entity Beneficiary:

{
  "account_model": "fully_disclosed",
  "payor": {
    "participant_code": "PAYOR1",
    "payor": {
      "info": {
        "entity": {
          "onboarding_profile": "payouts_payor_ultimate",
          "legal_name": "Entity B B.V.",
          "contact_number": "+31201234567",
          "address_one": "Herengracht 100",
          "address_two": "Suite 4",
          "city": "Amsterdam",
          "postal_code": "1015 BS",
          "jurisdiction_code": "NL",
          "email": "[email protected]",
          "tax_id": "NL861821195B01",
          "id_issuing_authority": "Netherlands",
          "merchant_category_code": "4511",
          "lei_number": "724500XVX2LKTAJ2ML85",
          "chamber_of_commerce_number": "34123456",
          "reason_for_business_relationship": "Provision of digital asset custody and settlement services to entity clients",
          "expected_transaction_volume": 500,
          "expected_transaction_value": 2500000,
          "activity_location": ["NL", "DE", "FR"],
          "source_of_funds": "Operating revenue from business activities",
          "sanction_screening": "pass",
          "sanction_screening_timestamp": 1603378501286,
          "signed_agreements": [
            {
              "type": "user_agreement",
              "region": "eu",
              "signed_timestamp": 1603378501286
            }
          ]
        }
      }
    }
  },
  "beneficiary": {
    "info": {
      "entity": {
        "onboarding_profile": "payouts_beneficiary",
        "legal_name": "Entreprise Martin SAS",
        "contact_number": "+33140123456",
        "address_one": "45 Avenue des Champs-Élysées",
        "city": "Paris",
        "postal_code": "75008",
        "jurisdiction_code": "FR",
        "email": "[email protected]",
        "tax_id": "FR40303265045",
        "id_issuing_authority": "FR",
        "sanction_screening": "pass",
        "sanction_screening_timestamp": 1603378501286
      }
    },
    "external_account": {
      "info": {
        "network": "SOL",
        "crypto_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "supported_symbols": ["USDC"]
      },
      "travel_rule": {
        "address_belongs_to": "zh_participant",
        "address_owner_type": "business",
        "wallet_type": "hosted",
        "casp_did": "did:ethr:0x9a4b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"
      }
    }
  },
  "payment": {
    "asset": "USDC.SOL",
    "quoted_asset": "USD",
    "total": "100.00",
    "description": "Contractor payout"
  },
  "metadata": {
    "client_ref": "your-internal-ref-id",
    "campaign": "weekly-contractor-payout"
  }
}

Response:

 {
  "idempotency_key": "your-idempotency-key",
  "payout_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending"
}

Initiate Payout - Existing Participants

📘
No jurisdictional changes with the Existing Participants flow.

If the Ultimate Payor, Beneficiary, and/or external account have already been onboarded in a previous payout, you can reference them by ID instead of re-submitting full PII. Mix and match - any combination of inline PII and reference IDs is supported.

Object	Reference Field
Ultimate Payor	`payor.payor.participant_code`
Beneficiary	`beneficiary.participant_code`
Beneficiary external account	`beneficiary.external_account.external_account_id`

Request:

{
  "account_model": "fully_disclosed",
  "payor": {
    "participant_code": "PAYOR1",
    "payor": {
      "participant_code": "UPAYR1"
    }
  },
  "beneficiary": {
    "participant_code": "BENEF1",
    "external_account": {
      "external_account_id": "ea_3b1d8e4a"
    }
  },
  "payment": {
    "asset": "USDC.SOL",
    "quoted_asset": "USD",
    "total": "100.00",
    "description": "Contractor payout"
  },
  "metadata": {
    "client_ref": "your-internal-ref-id",
    "campaign": "weekly-contractor-payout"
  }
}

Response:

// 202
{
  "idempotency_key": "your-idempotency-key",
  "payout_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending"
}

Travel Rule

When you reference an existing external_account_id, you don’t resubmit the wallet’s PII, but the Travel Rule data requirement depends on the wallet type:

Self-custody wallets: If you already provided sufficient Travel Rule information for this payout in a previous payout, or through POST /travel-rule/submit, you don’t need to send it again. Remember that proof of ownership (wallet_proof_of_ownership) determines how much you can send:
- Proof of ownership provided and approved: You can send self-custody payouts of any amount to that wallet.
- Proof of ownership not provided, or submitted but not yet approved: Self-custody payouts are limited to €1,000 every 12 hours until it is approved.
Exchange (hosted) wallets: zerohash keeps this data only for a short time. Submit it immediately before each payout, either through POST /travel-rule/submit or in the travel_rule object of POST /payouts.

Idempotency

POST /payouts is idempotent. Supply an Idempotency-Key header with each request.

- Same key + same payload → zerohash returns the original response and does not initiate a duplicate payout.
- Same key + different payload → zerohash returns 400.

The idempotency key is included on all webhook events, GET responses, and reports. You can also query by it directly: GET /payouts?idempotency_key=your-key.

Query Payout

You can query a Payout record via the GET /payouts endpoint.

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",
  "failure_reason": null,
  "resources": {
    "payor": {
      "participant_code": "PAYOR1",
      "payor": {
        "participant_code": "ORIG01",
        "status": "approved"
      }
    },
    "beneficiary": {
      "participant_code": "BENEF1",
      "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...",
          "destination_tag": ""
        },
        "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.00",
      "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.00",
        "network_fee_quantity": "0.00"
      },
      "created_at": "2026-05-06T12:01:30Z",
      "updated_at": "2026-05-06T12:01:45Z"
    }
  },
  "account_model": "fully_disclosed"
}

Webhooks

📘
No jurisdictional changes regarding webhook events and payloads.

All payout lifecycle events use payload_type: payout.status_updated. After a successful POST /payouts events are emitted in the following sequence. The payout_id and idempotency_key are present on every event.

Event Sequence

#	`sub_status`	Payout `status`
1	null (initial)	`pending`
2	`payor.payor.submitted`	`pending`
3	`payor.payor.approved`	`pending`
3a	`payor.payor.rejected`	`rejected`
4	`beneficiary.submitted`	`pending`
5	`beneficiary.approved`	`pending`
5a	`beneficiary.pending_approval`	`pending`
5b	`beneficiary.rejected`	`rejected`
6	`beneficiary.external_account.submitted`	`pending`
7	`beneficiary.external_account.approved`	`pending`
7a	`beneficiary.external_account.rejected`	`rejected`
8	`payment.submitted`	`pending`
9	`payment.processing`(only for high-value payouts)	`pending`
10	`payment.posted`	`pending`
11	`payment.settled`	`completed`
11a	`payment.failed`	`failed`

Event payloads

Payout pending (initial)

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": null,
  "previous_sub_status": null,
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": null } },
    "beneficiary": {
      "participant_code": null,
      "status": null,
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Ultimate Payor submitted

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "payor.payor.submitted",
  "previous_sub_status": null,
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "submitted", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": null,
      "status": null,
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Ultimate Payor approved

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "payor.payor.approved",
  "previous_sub_status": "payor.payor.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": null,
      "status": null,
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Ultimate Payor rejected

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "rejected",
  "sub_status": "payor.payor.rejected",
  "previous_sub_status": null,
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "rejected", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": null,
      "status": null,
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary submitted

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "beneficiary.submitted",
  "previous_sub_status": "payor.payor.approved",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "submitted",
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary approved

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "beneficiary.approved",
  "previous_sub_status": "beneficiary.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary pending approval

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "beneficiary.pending_approval",
  "previous_sub_status": "beneficiary.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "pending_approval",
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary rejected

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "rejected",
  "sub_status": "beneficiary.rejected",
  "previous_sub_status": "beneficiary.pending_approval",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "rejected",
      "external_account": {
        "external_account_id": null,
        "status": null,
        "details": { "crypto_address": null }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary external account submitted

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "beneficiary.external_account.submitted",
  "previous_sub_status": "beneficiary.approved",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "submitted",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary external account approved

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "beneficiary.external_account.approved",
  "previous_sub_status": "beneficiary.external_account.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Beneficiary external account rejected

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "rejected",
  "sub_status": "beneficiary.external_account.rejected",
  "previous_sub_status": "beneficiary.external_account.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "status": "approved", "participant_code": "UPAYR1" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": { "external_account_id": "ea_xyz789", "status": "rejected" }
    },
    "payment": {
      "payment_id": null,
      "status": null,
      "rate": "1.00",
      "destination_amount": "100.00",
      "payment_details": { "on_chain_transaction_id": null }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": null
}

Payment submitted

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "payment.submitted",
  "previous_sub_status": "beneficiary.external_account.approved",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "participant_code": "UPAYR1", "status": "approved" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": "pmt_abc123",
      "description": "Contractor payout",
      "asset": "USDC",
      "quoted_asset": "USD",
      "total": "100.00",
      "rate": "1.00",
      "destination_amount": "100.00",
      "status": "submitted",
      "network": "SOL",
      "payment_details": {
        "withdrawal_request_id": null,
        "trade_id": "tr_abc123",
        "on_chain_transaction_id": null,
        "network_fee_notional": null,
        "network_fee_quantity": null
      }
    }
  },
  "timestamp": "2026-05-06T12:06:00Z",
  "failure_reason": null
}

Payment processing

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "payment.processing",
  "previous_sub_status": "payment.submitted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "participant_code": "UPAYR1", "status": "approved" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": "pmt_abc123",
      "description": "Contractor payout",
      "asset": "USDC",
      "quoted_asset": "USD",
      "total": "100.00",
      "rate": "1.00",
      "destination_amount": "100.00",
      "status": "processing",
      "network": "SOL",
      "payment_details": {
        "withdrawal_request_id": null,
        "trade_id": "tr_abc123",
        "on_chain_transaction_id": null,
        "network_fee_notional": null,
        "network_fee_quantity": null
      }
    }
  },
  "timestamp": "2026-05-06T12:06:00Z",
  "failure_reason": null
}

Payment posted

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "pending",
  "sub_status": "payment.posted",
  "previous_sub_status": "payment.processing", 
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "participant_code": "UPAYR1", "status": "approved" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": "pmt_abc123",
      "description": "Contractor payout",
      "asset": "USDC",
      "quoted_asset": "USD",
      "total": "100.00",
      "rate": "1.00",
      "destination_amount": "100.00",
      "status": "posted",
      "network": "SOL",
      "payment_details": {
        "withdrawal_request_id": "wr_xyz456",
        "trade_id": "tr_abc123",
        "on_chain_transaction_id": null,
        "network_fee_notional": null,
        "network_fee_quantity": null
      }
    }
  },
  "timestamp": "2026-05-06T12:07:15Z",
  "failure_reason": null
}

Payment settled

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "completed",
  "sub_status": "payment.settled",
  "previous_sub_status": "payment.posted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "participant_code": "UPAYR1", "status": "approved" }},
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": "pmt_abc123",
      "description": "Contractor payout",
      "asset": "USDC",
      "quoted_asset": "USD",
      "total": "100.00",
      "rate": "1.00",
      "destination_amount": "100.00",
      "status": "settled",
      "network": "SOL",
      "payment_details": {
        "withdrawal_request_id": "wr_xyz456",
        "trade_id": "tr_abc123",
        "on_chain_transaction_id": "0xabc123...",
        "network_fee_notional": "0.01",
        "network_fee_quantity": "0.0000000384712"
      }
    }
  },
  "timestamp": "2026-05-06T12:08:45Z",
  "failure_reason": null
}

Payment failed

{
  "payout_id": "payout_abc123",
  "idempotency_key": "your-idempotency-key",
  "created_at": "2026-05-06T12:00:00Z",
  "updated_at": "2026-05-06T12:01:45Z",
  "status": "failed",
  "sub_status": "payment.failed",
  "previous_sub_status": "payment.posted",
  "resources": {
    "payor": { "participant_code": "PAYOR1", "payor": { "participant_code": "UPAYR1", "status": "approved" } },
    "beneficiary": {
      "participant_code": "BENEF1",
      "status": "approved",
      "external_account": {
        "external_account_id": "ea_xyz789",
        "status": "approved",
        "details": { "crypto_address": "ab123..." }
      }
    },
    "payment": {
      "payment_id": "pmt_abc123",
      "status": "failed",
      "payment_details": { "on_chain_transaction_id": "0xabc123..." }
    }
  },
  "timestamp": "2026-05-06T12:01:30Z",
  "failure_reason": "on_chain_transaction_failed"
}

API error scenarios

Endpoint	HTTP Status	Scenario	Response
POST /payouts	403	Request carries no API key	{"error": true, "message": "Missing API Key"}
POST /payouts	403	API key lacks the withdraw permissions required to post payouts	{"error": true, "message": "This api key does not have the required withdraw permissions to post payouts."}
POST /payouts	400	Missing required body field	{"errors": ["payor should have required property 'participant_code'"]}
POST /payouts	400	Missing required nested field (examples)	{"errors": ["payment should have required property 'asset'"]}
POST /payouts	400	Wrong field type	{"errors": ["payment.total should be string"]}
POST /payouts	400	signed_timestamp not an integer	{"errors": ["signed_timestamp should be integer"]}
POST /payouts	400	sanction_screening not in enum	{"errors": ["sanction_screening should be equal to one of the allowed values"]}
POST /payouts	400	onboarding_profile not in allowed enum (UP entity)	{"errors": ["onboarding_profile should be equal to one of the allowed values"]}
POST /payouts	400	merchant_category_code not a 4-digit string	{"errors": ["merchant_category_code should match pattern ..."]}
POST /payouts	400	Unknown / extra field anywhere in body	{"errors": ["should NOT have additional properties"]}
POST /payouts	400	validate flag wrong type	{"errors": ["validate should be boolean"]}
POST /payouts	400	payor not exactly one of participant_code or info (both or neither)	{"errors": ["payor must specify exactly one of participant_code or info"]}
POST /payouts	400	beneficiary not exactly one of participant_code or info	{"errors": ["beneficiary must specify exactly one of participant_code or info"]}
POST /payouts	400	beneficiary.info not exactly one of entity or individual	{"errors": ["beneficiary.info must specify exactly one of entity or individual"]}
POST /payouts	400	external_account not exactly one of external_account_id or info	{"errors": ["beneficiary.external_account must specify exactly one of external_account_id or info"]}
POST /payouts	400	External account not approved	External account not approved
POST /payouts	400	External account does not support the payment asset	{"errors": ["external account does not support asset USDC"]}
POST /payouts	400	Platform not enrolled in payouts product	{"errors": ["platform is not enrolled in payouts and cannot onboard payouts profiles"]}
POST /payouts	400	Entity legal_name missing	{"errors": ["entity legal name must be supplied"]}
POST /payouts	400	Entity tax_id missing	{"errors": ["tax_id is required for payouts entity applications"]}
POST /payouts	400	Entity tax_id not a valid US EIN (US jurisdiction)	{"errors": ["invalid us ein format"]}
POST /payouts	400	Entity id_issuing_authority missing	{"errors": ["id_issuing_authority is required for payouts entity applications"]}
POST /payouts	400	Entity address_one missing	{"errors": ["address_one is required for payouts entity applications"]}
POST /payouts	400	Address/city/zip format invalid (examples; PO Box, length, special chars, US zip)	{"errors": ["address_one should not be empty and should not contain PO Box"]}
POST /payouts	400	Entity jurisdiction_code missing	{"errors": ["jurisdiction_code is required"]}
POST /payouts	400	sanction_screening status not explicitly defined / not PASSED / bad timestamp	{"errors": ["sanction_screening status should be explicitly defined"]}
POST /payouts	400	Ultimate Payor entity email missing	{"errors": ["email is required for payouts payor ultimate entity applications"]}
POST /payouts	400	merchant_category_code not a valid 4-digit Mastercard MCC	{"errors": ["invalid merchant_category_code: must be a 4-digit Mastercard MCC"]}
POST /payouts	400	Individual beneficiary first_name missing	{"errors": ["should have required property 'first_name'"]}
POST /payouts	400	Individual beneficiary last_name missing	{"errors": ["last_name should NOT be shorter than 1 characters"]}
POST /payouts	400	Individual beneficiary date_of_birth missing	{"errors": ["date_of_birth is required for payouts beneficiary applications"]}
POST /payouts	400	Individual beneficiary id_issuing_authority not ISO 3166-1 alpha-2	{"errors": ["id_issuing_authority must be a valid ISO 3166-1 alpha-2 country code for payouts beneficiary applications"]}
POST /payouts	400	Float/credit balance insufficient for payout	{"errors": ["insufficient balance"]}
POST /payouts	400	Asset not supported (no asset / not payout-enabled / account symbol mismatch)	{"errors": ["asset is not supported"]}
POST /payouts	400	quoted_asset is not USD	{"errors": ["invalid quoted asset"]}
POST /payouts	400	Resolved account not approved	{"errors": ["account is not approved"]}
POST /payouts	400	Participant (payor) not approved (payments view)	{"errors": ["participant is not approved"]}
POST /payouts	400	Account not found (payments view)	{"errors": ["account not found"]}
POST /payouts	400	Inline crypto address invalid for network or on deny list	{"errors": ["invalid or denied destination address"]}
POST /payouts	400	Inline crypto address is sanctioned	{"errors": ["sanctioned address"]}
POST /payouts	422	Asset is currently depegged (orchestrator depeg gate)	{"errors": ["asset is currently depegged and conversions are halted"]}
POST /payouts	500	Orchestrator/downstream internal error (unmapped)	{"errors": ["internal server error"]}
POST /payouts	400	Travel Rule information is missing or incomplete for the receiving wallet, and the request carries no `travel_rule` data	{"errors": ["travel rule information is required for the beneficiary address; missing: <fields>. Add beneficiary.external_account.travel_rule or submit it via POST /travel-rule/submit"]}
POST /payouts	400	travel_rule object is invalid (for example a missing required field)	{"errors": ["travel_rule should have required property 'wallet_type'"]}
POST /payouts	413	Proof-of-ownership document is too large	{"errors": ["request body is too large; beneficiary.external_account.travel_rule.wallet_proof_of_ownership.document must be at most 3.5 MB once decoded"]}
POST /payouts	422	Travel Rule review for the receiving wallet is in progress, for example after proof of ownership was submitted	{"errors": ["travel rule review in progress for the beneficiary address; submit the payout again once the address is allowed"]}
POST /payouts	403	The receiving wallet is blocked by the Travel Rule check	{"error": true, "message": "the beneficiary address is blocked by the travel rule compliance check"}
POST /payouts	400	Entity `tax_id` not a valid EU VAT number (EU jurisdiction)	`{"errors": ["invalid vat number format"]}`
POST /payouts	400	Individual beneficiary `id_number` or `id_number_type` missing
POST /payouts	400	`casp_did` missing for `wallet_type: hosted`
POST /payouts	400	`casp_did` sent for `wallet_type: self_custody`
POST /payouts	400	`address_belongs_to` is not `zh_participant` (EU)
POST /payouts	400	Self-custody wallet without approved proof of ownership, payout exceeds €1,000 per 12 hours
GET /payouts	403	Request carries no API key	{"error": true, "message": "Missing API Key"}
GET /payouts	400	Neither payout_id nor idempotency_key supplied	{"errors": ["exactly one of payout_id or idempotency_key is required"]}
GET /payouts	400	Both payout_id and idempotency_key supplied	{"errors": ["exactly one of payout_id or idempotency_key is required"]}
GET /payouts	400	payout_id not a valid UUID	{"errors": ["payout_id should match format "uuid""]}
GET /payouts	400	Unknown / extra query field	{"errors": ["should NOT have additional properties"]}
GET /payouts	400	Neither identifier (orchestrator guard)	{"errors": ["either payout_id or idempotency_key is required"]}
GET /payouts	400	Both identifiers (orchestrator guard)	{"errors": ["only one of payout_id or idempotency_key must be provided"]}
GET /payouts	400	payout_id invalid UUID (orchestrator guard)	{"errors": ["payout_id must be a valid UUID"]}
GET /payouts	404	payout_id does not exist	{"errors": ["payout not found"]}
GET /payouts	404	idempotency_key does not exist	{"errors": ["payout not found"]}
GET /payouts	500	Orchestrator/repository internal error	{"errors": ["internal server error"]}