Is this API non-custodial?

Yes — architecture, not policy. Payments settle on-chain directly to the wallet address on your invoice; Zyrvix never holds, pools, or forwards customer funds. There is no withdrawal step and no minimum payout. The platform fee comes from a separate prepaid balance you top up yourself — pricing at /pricing.

Which cryptocurrencies does it support?

Gram (formerly Toncoin/TON) — the native coin of the TON network. One deliberately chosen chain: sub-cent network fees and finality in seconds, which is what makes small and mid-size checkout payments practical. Additional networks are on the roadmap; the API's currency field is already explicit on every invoice. See the full rebrand story at /accept-gram-payments.

Do I have to build a checkout UI?

No. Every invoice response includes a hosted payment page — a QR code, address, memo, live status, and an optional redirect back to your site. Building your own UI on the raw API is equally supported; webhooks behave identically either way.

How do I test the integration without real funds?

With a sandbox API key (sk_test_ prefix). Sandbox invoices skip billing and blockchain monitoring; you resolve them by simulating any of the four terminal outcomes, and the same signed webhooks fire with an is_sandbox flag.

How are webhooks secured?

Each delivery is signed: an HMAC-SHA256 digest of the timestamp and the raw body, sent as a signature header. Verify with a constant-time comparison and reject stale timestamps to block replays. A unique delivery ID deduplicates retries. The docs include a reference implementation in six languages.

What happens if my server misses a webhook?

Deliveries retry five times with front-loaded backoff before being marked dead — and your data is never stranded: the invoice list is the source of truth. Reconcile any gap by listing paid invoices or fetching a single invoice by ID.

The crypto checkout API that settles to your own wallet

One POST creates an invoice with a hosted payment page; a signed webhook confirms payment. Non-custodial end to end — funds move from your customer's wallet to yours, in Gram (formerly Toncoin/TON) on the TON network. Zyrvix never holds them.

Get your API key Read the API docs

Settlement in Gram (formerly Toncoin/TON) on the TON network — sub-cent network fees, seconds to finality. See current pricing

Create an invoice

curl -X POST https://api.zyrvix.com/invoices \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "5.5",
    "success_url": "https://yourshop.com/order/123/thank-you"
  }'

201 Created

{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "5.5",
  "currency": "GRAM",
  "memo": "AB3XP7Q",
  "status": "pending",
  "expires_at": "2026-06-14T12:30:00Z",
  "hosted_payment_url": "https://pay.zyrvix.com/550e8400-e29b-41d4-a716-446655440000"
}

The invoice.paid webhook it produces

X-Event-Id:    3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Event-Type:  invoice.paid
X-Timestamp:   1749902700
X-Signature:   a3f9b2c1d4e5...

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "invoice.paid",
  "created_at": "2026-06-14T12:05:00Z",
  "data": {
    "invoice": {
      "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid",
      "initiated_by": "automatic",
      "blockchain_metadata": { "tx_hash": "..." }
    }
  }
}

A payment API that behaves like the rest of your stack

01
Plain REST + JSON
Bearer-key auth, predictable resource routes, and a single stable error envelope (error.code / message / details) with documented codes. No SDK required, no platform lock-in — any language that can send HTTPS.
02
Idempotency built in
POST /invoices requires an Idempotency-Key you generate; retrying after a timeout returns the original invoice instead of double-charging. Replaying a key with a different payload returns an explicit 409 conflict — never a silent discard.
03
HMAC-signed webhooks
Every delivery carries a signature header and a timestamp binding, so replay attempts fail your own check. Retries are front-loaded, and a permanent 4xx rejection is respected — never retried into the ground.
04
Hosted pay page included, optional
Every invoice returns a hosted payment page — QR code, wallet address, memo, live status, expiry countdown, and a redirect back to your site. Or ignore it and build your own checkout on the same API; webhooks fire identically either way.
05
Non-custodial by architecture
Payments go on-chain straight to your registered wallet. There is no gateway balance, no withdrawal step, no threshold, and no counterparty custody risk to reason about.

How do I add a crypto checkout to my website?

1
Customer clicks "Pay"
They click the pay button on your site or app.
2
Create the invoice
Your backend calls POST /invoices with your Idempotency-Key and gets back an invoice ID, a memo, and a hosted payment page URL.
3
Send the customer to pay
Redirect to the hosted payment page, or render your own UI from the response fields.
4
The network confirms
Your customer pays from any TON wallet; the network confirms in seconds.
5
Fulfill on the webhook
Your endpoint receives the signed invoice.paid webhook. Verify the signature, then fulfill the order — never rely on the redirect alone as the payment signal.

Every invoice moves through one lifecycle: pending, then paid, canceled, or expired. An expired invoice that later receives payment can still be reconciled — see the full invoice lifecycle in the docs.

How do crypto payment webhooks work here?

Each delivery is signed: an HMAC-SHA256 digest of the timestamp and the raw request body, sent as a signature header. A signature check alone does not prevent replay, so the reference implementation below also rejects stale timestamps.

Verify the signature and reject replays

# Verification pseudocode:
# 1. reject if abs(now - X-Timestamp) > 300 seconds (replay protection)
# 2. message = X-Timestamp + "." + raw_body_string
# 3. signature = HMAC-SHA256(secret, message).hexdigest()
# 4. compare signature with X-Signature (constant-time compare)

Five event types cover the full lifecycle: invoice.paid, invoice.expired, invoice.canceled, invoice.underpaid, and balance.low. Every delivery also carries a unique delivery ID for deduplicating retries on your side.

A failed delivery retries five times with a front-loaded backoff — seconds, then minutes — before being marked dead, about 13 minutes worst case.

A dead delivery never strands an order: the invoice list is always the source of truth. Reconcile any gap with the docs.

Test the full flow without spending anything

Sandbox keys use the sk_test_ prefix and behave identically to live keys — same request and response shapes, but no fee is charged and there's no blockchain dependency to wait on. You drive the outcome yourself.

Resolve a sandbox invoice to any outcome

curl -X POST https://api.zyrvix.com/sandbox/invoices/550e8400-e29b-41d4-a716-446655440000/simulate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome": "paid"}'

The outcome is one of paid, underpaid, expired, or canceled — all four terminal states, so your webhook handler's full branching logic is exercisable in CI. Sandbox fires the same webhook events, with an is_sandbox flag on every payload, and a separate sandbox webhook URL and secret configurable independently of your live ones.

Create a sandbox key

Custodial processor, platform SDK, or a plain API?

Three different shapes of solution for the same underlying question — where does custody sit, and how much of the integration is already built for you.

Custodial processor

Aggregates your funds in a gateway balance with withdrawal thresholds and KYC tiers. Integration means managing the provider's account lifecycle as well as your own.

TON Pay (platform SDK)

Also non-custodial. Built first for checkout inside Telegram Mini Apps via its own JavaScript/React SDK — a strong first-party choice if your business already lives there.

Zyrvix

A plain REST API, signed webhooks, and a hosted page for your own website or app, outside Telegram, today. No balance to manage, no platform dependency, works from any backend language, sandbox-first.

See the full comparison of custodial processors, TON Pay, and Zyrvix.

Verifiable, not just claimed

Open, public API documentation — every claim on this page is one click from its reference.
An auditable invoice status ledger — every transition recorded with a timestamp and its initiator.
A deterministic error contract — stable, machine-readable codes and documented rate limits.
Non-custodial architecture as a security property — no pooled funds to breach or freeze.

Crypto checkout API — FAQ

Ship a crypto checkout this afternoon

Create a sandbox key and get your first simulated invoice.paid webhook in minutes. Go live later by switching the key prefix — same API, same code.

Get your API key Read the docs

Simple percentage pricing — see current rates.

Last updated July 22, 2026

The crypto checkout API that settles to your own wallet

A payment API that behaves like the rest of your stack

Plain REST + JSON

Idempotency built in

HMAC-signed webhooks

Hosted pay page included, optional

Non-custodial by architecture