Payment webhooks

Production outbound payment webhook delivery is planned and is not currently available. There is no supported merchant webhook registration endpoint, published payment-event schema, delivery-retry contract, or SDK verification method to configure today.

Read payment state today#

Your backend can poll GET /v1/invoices/:id or list GET /v1/invoices using HMAC authentication. Single results are under data; lists use data.items and data.page. Invoice states are Issued, Paid, and Canceled.

  1. Store the numeric invoice ID against your own customer/order record when issuance is confirmed.
  2. Read invoice state with bounded backoff. Lists can lag the chain; use individual strong reads when reconciling a known ID.
  3. Treat Paid and verified settlement evidence as the payment outcome. An issued invoice, submission hash, or 202 pending result is not proof of payment.
  4. Record processed payments durably before applying an accounting update, so repeated polling cannot credit the same payment twice.

Your application owns its customer mapping and ledger crediting. Cleared does not automatically credit a platform's internal customer balance. Use raw-unit amounts and actual settled fees for reconciliation; do not rely solely on partial dashboard/MCP totals. See payments and exports.

Intended future workflow#

The planned workflow is for Cleared to deliver a confirmed payment event to your backend, which verifies it, matches the invoice, and records the payment once. Event IDs, payload/signature formats, registration, retry schedules, ordering guarantees, and delivery visibility are not an executable API contract yet. Discuss production requirements before depending on delivery.

Existing email-provider callback#

POST /v1/webhooks/resend is an inbound email-provider callback, not an outbound merchant payment webhook. It updates invoice email-delivery state. It uses the provider's Svix headers (svix-id, svix-timestamp, svix-signature) and the exact raw body, rather than Cleared API-key HMAC.

When configured and enabled, verified callbacks return { received: true, outcome }. Missing/invalid signature headers return 400; disabled processing returns 503; configuration failures can return 500. Unknown provider-message events can be ignored. This route is for the provider integration, not for merchants to submit payment confirmations. An email being delivered or opened does not mean an invoice was paid.