Platform’s leveraging the Payins endpoints can subscribe to webhooks to receive real-time updates.
Programmatic handling
Use status_reason_code for any branching logic — it is a stable enum that will not change without a deprecation notice. The reason field is human-readable and may be reworded at any time; do not parse it.
Payload schema
| Field | Type | Always present? | Description |
|---|---|---|---|
success | boolean | Yes | true when the payment settled at the quoted amount; false for any failure or partial outcome (including UNDERPAY).OVERPAY returns true |
status_reason_code | string | No | Stable, machine-readable code describing the outcome. |
reason | string | No | Human-readable description of the outcome. Empty when success == true with no special condition. Do not parse — use status_reason_code instead. |
participant_code | string | Yes | End-customer identifier. |
platform_code | string | Yes | Platform participant code. |
fund_asset | string | Yes | Crypto asset the customer paid with. |
rate | string | No | Execution rate applied. Present when the payment executed (success and OVERPAY/UNDERPAY). |
quoted_currency | string | No | Merchant settlement currency. Present when the payment executed. |
source_address | string | Yes | Sending address. |
deposit_address | string | Yes | zerohash receiving address. |
quantity | string | No | Amount paid in fund_asset. Present when a deposit was received. |
notional | string | No | Settled amount in quoted_currency. Present when the payment executed. |
fund_id | string | Yes | Unique payment identifier. |
fund_timestamp | number | No | UNIX nanosecond timestamp of the executed trade. Present when the payment executed. |
deposit_timestamp | number | No | UNIX nanosecond timestamp the on-chain deposit was confirmed. Omitted on expiry events where no deposit was received. |
transaction_id | string | Yes | On-chain transaction hash. Empty when no deposit was received. |
account_label | string | Yes | Merchant account identifier. |
reference_id | string | No | Platform-provided payment ID. |
deposit_intent_id | string | No | Payin session identifier. |
Status reason codes
The table below lists every status_reason_code value that can appear on
the Payins webhook.
status_reason_code | success | When it fires |
|---|---|---|
DEPOSIT_PROCESSED | true | Payment received at the quoted amount and settled to the merchant. |
OVERPAY | true | Customer paid more than the quoted amount. The payment is settled in full; reconcile the surplus against your order. |
UNDERPAY | false | Customer paid less than the quoted amount. The deposited crypto has been returned to the customer's account. |
PAY_ASSET_NOT_SUPPORTED | false | Asset paid with is not enabled on the Payins workflow. |
PAY_ASSET_DEPEGGED | false | Conversions for this stablecoin are temporarily halted. |
PAY_PLATFORM_NOT_ENABLED | false | Your platform is not enabled on the Payins workflow. |
CURRENCY_MISMATCH | false | The asset the customer paid with does not match the asset specified in the quote. |
AMOUNT_BELOW_MINIMUM | false | Deposit was below the configured minimum. |
AMOUNT_ABOVE_MAXIMUM | false | Deposit was above the configured maximum. |
INVALID_AMOUNT_FORMAT | false | Deposit amount could not be parsed. |
PARTICIPANT_NOT_APPROVED | false | Customer was not in an approved KYC state at the time of payment. |
PAYMENT_EXPIRED | false | No deposit was received before the payment quote expired. No on-chain deposit is associated with this event. |
PAYMENT_ARCHIVED | false | A new payment was requested before this one was completed; this payment session has been archived. No on-chain deposit is associated with this event. |
DEPOSIT_WINDOW_EXPIRED | false | Deposit arrived after the payment quote had expired or the payment had already been settled. |
QUARANTINED_DEPOSIT | false | For zerohash compliance reasons, the deposit has not been settled and the crypto has been credited to a zerohash holding account. |
PROCESSING_FAILED | false | An unexpected error occurred while processing the payment. Contact zerohash support if this code persists. |
Example payloads
Successful payment
{
"success": true,
"status_reason_code": "DEPOSIT_PROCESSED",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"rate": "1.00",
"quoted_currency": "USD",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"notional": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"fund_timestamp": 1748534400123456789,
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Overpayment (settled, surplus to customer)
{
"success": true,
"status_reason_code": "OVERPAY",
"reason": "over payment",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"rate": "1.00",
"quoted_currency": "USD",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "110.50",
"notional": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"fund_timestamp": 1748534400123456789,
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Underpayment (returned to customer)
{
"success": false,
"status_reason_code": "UNDERPAY",
"reason": "under payment",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"rate": "1.00",
"quoted_currency": "USD",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "85.00",
"notional": "85.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"fund_timestamp": 1748534400123456789,
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Asset not supported by Payins workflow
{
"success": false,
"status_reason_code": "PAY_ASSET_NOT_SUPPORTED",
"reason": "asset deposited is not supported by the pay workflow",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "DOGE",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "1500.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Asset depegged
{
"success": false,
"status_reason_code": "PAY_ASSET_DEPEGGED",
"reason": "conversions are currently halted",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Platform not enabled for Payins
{
"success": false,
"status_reason_code": "PAY_PLATFORM_NOT_ENABLED",
"reason": "deposit to an account associated with a platform not enabled on the pay workflow",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Currency mismatch
{
"success": false,
"status_reason_code": "CURRENCY_MISMATCH",
"reason": "deposit currency does not match the fund's underlying currency. The deposit has not been converted to fiat and the crypto has been credited to the customer's account",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "ETH",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "0.50000000",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Amount below minimum
{
"success": false,
"status_reason_code": "AMOUNT_BELOW_MINIMUM",
"reason": "deposit below minimum threshold. The deposit has not been converted to fiat and the crypto has been credited to the customer's account",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "0.50",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Amount above maximum
{
"success": false,
"status_reason_code": "AMOUNT_ABOVE_MAXIMUM",
"reason": "deposit above maximum threshold. The deposit has not been converted to fiat and the crypto has been credited to the customer's account",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "500000.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Customer not in approved state
{
"success": false,
"status_reason_code": "PARTICIPANT_NOT_APPROVED",
"reason": "the customer was not in an approved state at the time of deposit. The deposit has not been converted to fiat and the crypto has been credited to the customer's account",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Payment expired (no deposit received)
{
"success": false,
"status_reason_code": "PAYMENT_EXPIRED",
"reason": "payment session has expired.",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USD",
"source_address": "-",
"deposit_address": "-",
"quantity": "0",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Payment archived (superseded by a new request)
{
"success": false,
"status_reason_code": "PAYMENT_ARCHIVED",
"reason": "Payment archived due to a new one being requested before the previous one was completed",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USD",
"source_address": "-",
"deposit_address": "-",
"quantity": "0",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Deposit arrived after the payment window closed
{
"success": false,
"status_reason_code": "DEPOSIT_WINDOW_EXPIRED",
"reason": "deposit window expired or deposit already processed",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}Compliance hold
{
"success": false,
"status_reason_code": "QUARANTINED_DEPOSIT",
"reason": "For Zero Hash Compliance reasons, the deposit has not been converted to fiat and the crypto has been credited to a Zero Hash holding account",
"participant_code": "ABC123",
"platform_code": "PLAT01",
"fund_asset": "USDC",
"source_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
"deposit_address": "0x9f4b6e1a8d2c3f5a7b8c9d0e1f2a3b4c5d6e7f8a",
"quantity": "100.00",
"fund_id": "f0e8d4a2-1c3b-4e5f-9a8b-7c6d5e4f3a2b",
"deposit_timestamp": 1748534399987654321,
"transaction_id": "0x3c2e8d4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"account_label": "merchant-01",
"reference_id": "order-abc-12345",
"deposit_intent_id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d"
}