Webhook reference: x402.payment.*
Reference schema for x402 settlement events Cryptonly POSTs to the webhook URL set in the account’s x402 settings. Each delivery has an x-webhook-signature header (HMAC-SHA256 over the raw JSON body with the account signing key). This route exists for documentation only.
Required scope: x402.list.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
settled: the payment confirmed on chain. failed: it will not settle. credited (balance mode): the payment, less the fee, is on the account balance.
object
credited (balance mode only): confirmed and credited to the account balance.
Account the payment belongs to.
wallet: paid to a verified merchant wallet. balance (Base): paid to the account’s settlement address and credited to its balance.
facilitator: settled through /x402/settle. chain: a transfer to the settlement address that did not go through /x402/settle.
CAIP-2 network id.
Token contract.
Atomic units of asset.
Transaction hash. Empty until the settlement is broadcast.
Set when status is failed.
Cryptonly fee, atomic units of feeCurrency. 0 within the free tier.
Own wallet: USDC, charged to the x402 credits. Balance mode: the settled asset, deducted at credit.
resource.url from the payment.
ISO 8601 timestamp when Cryptonly signed and sent the webhook.
Examples
Sample x402.payment.credited payload
{ "event": "x402.payment.credited", "data": { "id": "019a0000-0000-7000-8000-000000000001", "status": "credited", "accountId": "019a0000-0000-7000-8000-0000000000aa", "payoutMode": "balance", "origin": "facilitator", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66", "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C", "transaction": "0xabababababababababababababababababababababababababababababababab", "errorReason": null, "fee": "2500", "feeCurrency": "USDC_BASE", "resourceUrl": "https://api.example.com/weather", "resourceId": "019a0000-0000-7000-8000-0000000000bb", "createdAt": "2026-01-01T12:00:00.000Z", "confirmedAt": "2026-01-01T12:00:22.000Z", "creditedAt": "2026-01-01T12:00:22.000Z" }, "timestamp": "2026-01-01T12:00:23.000Z"}Responses
Section titled “Responses”Reference endpoint acknowledged.
Request validation failed (e.g. missing or malformed body / query).
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope), or the organization has been blocked; contact support@cryptonly.net (exceptions.tenant.blocked).
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}Unexpected server error. Safe to retry idempotent operations after a backoff.
object
Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.
Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.
Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.
object
Example
{ "code": "exceptions.auth.invalidApiKey", "message": "Invalid or missing API key"}