Dolix Pay API — accepting payments

Getting started

1. Open the bot → “Profile” → Dolix Pay → “Connect Dolix Pay”. Anyone can connect.
2. “API and webhooks” → create a key (it is shown only once) and, if you like, set a webhook URL.
3. Or issue invoices by hand: “Create invoice” in the same section, no API needed.

Authentication

A key of the form rsp_live_… is sent in the Authorization: Bearer <key> or X-API-Key: <key> header. We store only a hash of the key; if you lose a key, revoke it in the app and create a new one. Up to 5 keys can be active at the same time.

The limit is 120 requests per minute per key. Above it you get 429 with a Retry-After header.

Create an invoice

{
  "amount": "100",
  "title": "Заказ №104",
  "description": "Два товара",
  "external_id": "ORD-104",
  "payer_telegram_id": "5512340987",
  "lifetime_sec": 86400
}

The Idempotency-Key header works as external_id when the latter is not sent. You cannot pay your own invoice: the merchant cannot be the payer.

{
  "invoice": {
    "id": "210",
    "status": "created",
    "amount": "100",
    "fee": "1",
    "net_amount": "99",
    "currency": "USDT",
    "title": "Заказ №104",
    "description": "Два товара",
    "external_id": "ORD-104",
    "payer_telegram_id": null,
    "pay_url": "https://t.me/<bot>?startapp=serviceOrder_<token>",
    "created_at": "2026-10-04T16:00:00.000Z",
    "expires_at": "2026-10-05T16:00:00.000Z",
    "paid_at": null,
    "payment_method": null,
    "credited": null,
    "network_fee": null
  }
}

Put pay_url on a button in your bot or send it to the payer: the link opens the app on the payment screen. The fee is fixed when the invoice is created and does not change afterwards. After a crypto payment, credited shows how much was actually credited to you in the payment coin, and network_fee shows the network fee that was withheld.

Get, list, cancel

Invoice statuses

payment_method: wallet (from a wallet), crypto (on-chain), sbp (via SBP; an SBP amount is credited with a one-day hold, T+1).

SBP payments are available only to payers who have passed KYC, and they must pay from a personal card in their own name. If the payer's bank sends a full name that does not match KYC, the payment goes to manual review: the invoice is under_review and the money is not credited to you until support decides.

Webhooks

Set the URL in the “API and webhooks” section (https only, a public address) and we will send a POST with JSON.

{
  "id": "evt_91",
  "type": "invoice.paid",
  "created_at": "2026-10-04T16:20:00.000Z",
  "data": { "invoice": { "id": "210", "status": "paid", "external_id": "ORD-104" } }
}

Events: invoice.paid, invoice.under_review, invoice.expired, invoice.cancelled. A delivery may be repeated, so handle events idempotently (by the event id). invoice.paid may arrive hours after invoice.under_review. Rely on invoice.paid.

Respond with any 2xx code within 10 seconds. Otherwise we retry the delivery after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h (8 attempts in total). The “Send test” button in the app sends a ping event.

Verifying the signature

Header X-RSPAY-Signature: t=<unix-seconds>,v1=<hex>, where v1 = HMAC-SHA256(secret, "<t>.<body as received>"). Verify against the raw body and reject requests with a stale t timestamp (for example, older than 5 minutes). The secret is shown in the “API and webhooks” section. The request also carries X-RSPAY-Event (the type) and X-RSPAY-Delivery (the event number).

const crypto = require('crypto');

// rawBody is the request body AS RECEIVED (string/Buffer), not re-serialized JSON
function verify(rawBody, header, secret, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

import hmac, hashlib, re, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
    if not m or abs(time.time() - int(m[1])) > tolerance:
        return False
    signed = m[1].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

Errors

{ "error": { "code": "amount_too_small", "message": "…", "details": { "min_amount": "1" } } }

Funds and security

• The money is credited to your wallet in the coin and network the buyer paid with. Deducted from the amount are the Dolix Pay fee (a percentage, but not less than a per-payment minimum) and, for crypto payments, the network fee for moving the coins to the pooled wallet.
• Every incoming payment goes through an AML check. Until it passes, the money is not credited to you and the invoice is under_review. An address that received unverified coins is no longer issued for payments.
• You withdraw your earnings from the wallet as usual, in any available network; the withdrawal address is checked too.
• Keep the key and the webhook secret on your server. If they end up in the wrong hands, revoke the key and reissue the secret in the app.