Skip to content
CryptonlyCryptonlyCryptonly

x402 payments and webhooks

Payments

Section titled “Payments”

The Payments tab lists every payment. You can search by transaction hash, filter by endpoint, date, payer or recipient, and export the list as CSV.

Payments table with the date, endpoint, amount, status, payer and transaction of eight payments on Base and Solana, filters on top and Export CSV at the bottom.Payments table with the date, endpoint, amount, status, payer and transaction of eight payments on Base and Solana, filters on top and Export CSV at the bottom.

Click a payment to see its amount, fee, status history and on-chain transaction.

Payment details: 0.01 USDC on Base, confirmed, Cryptonly fee 0.0025 USDC paid from x402 credits, the status history, the /v1/weather/:city endpoint and the on-chain transaction, payer and recipient.Payment details: 0.01 USDC on Base, confirmed, Cryptonly fee 0.0025 USDC paid from x402 credits, the status history, the /v1/weather/:city endpoint and the on-chain transaction, payer and recipient.

The API returns the same data from GET /x402/settlements and GET /x402/settlements/{id}, with the x402 key from the quickstart.

Statuses

Section titled “Statuses”
StatusMeaning
submittedSent to the network, waiting for confirmation.
confirmedFinal on-chain: after 10 blocks on Base, or about 13 seconds on Solana. The fee is charged at this point.
creditedCryptonly balance only: added to your balance, minus the fee.
failedThe payment didn’t go through. No fee is charged.

Webhooks

Section titled “Webhooks”

Add an https URL under Settings → Webhooks to get notified about payments.

Open webhook settings
Webhook URL card with the endpoint URL https://api.acme.com/webhooks/cryptonly.Webhook URL card with the endpoint URL https://api.acme.com/webhooks/cryptonly.
EventWhen
x402.payment.settledThe payment is confirmed on-chain.
x402.payment.failedThe payment didn’t go through.
x402.payment.creditedCryptonly balance only: the payment, minus the fee, is on your balance. Direct transfers to your settlement address send only this event.

Webhooks are signed and retried like every Cryptonly webhook. Check the x-webhook-signature header as shown in Verify a webhook.

The body contains the payment, in the same shape as GET /x402/settlements/{id}:

{
  "event": "x402.payment.settled",
  "data": {
    "id": "0b6e4d8a-3c1f-4a2e-9d7b-5f8c2e1a6b30",
    "status": "confirmed",
    "accountId": "4f1c9a2e-7b3d-4e8f-a6c5-2d9b8e7f1a03",
    "payoutMode": "wallet",
    "origin": "facilitator",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000",
    "payer": "0x93f3a1c5e7b9d2f4a6c8e0b2d4f6a8c0e2b42e2e",
    "payTo": "0x7a3B5e9C1d2F4a6b8C0e2D4f6A8b0C2d4E6f8A1b",
    "transaction": "0x27ca1b5b9ccb3e8d006a5230de9bda23ff91edc794d4f56410560830b4c7a1e3",
    "errorReason": null,
    "fee": "2500",
    "feeCurrency": "USDC_BASE",
    "resourceUrl": "https://api.acme.com/v1/weather/:city",
    "resourceId": "9d2c4b6a-1e3f-4a5b-8c7d-0e9f1a2b3c4d",
    "createdAt": "2026-10-22T17:07:12.000Z",
    "confirmedAt": "2026-10-22T17:07:34.000Z",
    "creditedAt": null
  },
  "timestamp": "2026-10-22T17:07:35.000Z"
}

amount and fee are in the token’s smallest unit. USDC has 6 decimals, so 10000 is 0.01 USDC.

Section titled “Related pages”
Verify a webhookSignature check in Node.js, Python, Go, PHP and Java
List settlementsAPI reference for x402 payments