Skip to content

Webhook reference: x402.payment.*

POST
/webhooks/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.

Media typeapplication/json
object
event
required

settled: the payment confirmed on chain. failed: it will not settle. credited (balance mode): the payment, less the fee, is on the account balance.

string
Allowed values: x402.payment.settled x402.payment.failed x402.payment.credited
data
required
object
id
required
string format: uuid
status
required

credited (balance mode only): confirmed and credited to the account balance.

string
Allowed values: submitted confirmed credited failed
accountId
required

Account the payment belongs to.

string format: uuid
payoutMode
required

wallet: paid to a verified merchant wallet. balance (Base): paid to the account’s settlement address and credited to its balance.

string
Allowed values: wallet balance
origin
required

facilitator: settled through /x402/settle. chain: a transfer to the settlement address that did not go through /x402/settle.

string
Allowed values: facilitator chain
network
required

CAIP-2 network id.

string
asset
required

Token contract.

string
amount
required

Atomic units of asset.

string
payer
required
string
payTo
required
string
transaction
required

Transaction hash. Empty until the settlement is broadcast.

string
errorReason
required

Set when status is failed.

string
nullable
fee
required

Cryptonly fee, atomic units of feeCurrency. 0 within the free tier.

string
feeCurrency
required

Own wallet: USDC, charged to the x402 credits. Balance mode: the settled asset, deducted at credit.

string
nullable
resourceUrl
required

resource.url from the payment.

string
nullable
resourceId
required
string format: uuid
nullable
createdAt
required
string format: date-time
confirmedAt
required
string format: date-time
nullable
creditedAt
required
string format: date-time
nullable
timestamp
required

ISO 8601 timestamp when Cryptonly signed and sent the webhook.

string

Examples

Exampledefault

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"
}

Reference endpoint acknowledged.

Request validation failed (e.g. missing or malformed body / query).

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example

{
"code": "exceptions.auth.invalidApiKey",
"message": "Invalid or missing API key"
}

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

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

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

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.

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example

{
"code": "exceptions.auth.invalidApiKey",
"message": "Invalid or missing API key"
}

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json
object
code
required

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.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example

{
"code": "exceptions.auth.invalidApiKey",
"message": "Invalid or missing API key"
}