Перейти к содержимому
ZeroKYC Pay
Начать
ДокиПодключениеТарифыБлогВойтиНачать

Быстрый старт

Создайте первый инвойс с payment_currency=any, отправьте покупателя в hosted-чекоут и получите подписанный вебхук.

Создайте первый инвойс одним REST-запросом, отправьте покупателя в hosted-чекоут и получите подписанный вебхук после подтверждения платежа.

1. Получите тестовые ключи

  1. Зарегистрируйтесь — email, пароль, 2FA. Без KYC.
  2. Подключите кошелёк для нужных активов в разделе Кошельки — ваши ключи, ваши монеты.
  3. Скопируйте ключ pk_test_… в разделе API-ключи.

Не хотите писать код? Установите плагин ZeroKYC для WooCommerce — приём крипты заработает в WordPress без единого API-вызова. Можем настроить всё за вас: под ключ, от $99.

Sandbox-инвойсы симулируются: блокчейн-транзакции не происходит, mock-цепь подтверждает их мгновенно, а контракт API идентичен продакшену — те же эндпоинты, те же payload вебхуков, та же схема подписи. Отличия: sandbox-платежи подтверждаются за секунды (production ждёт реальных подтверждений сети), а платёж можно симулировать мгновенно кнопкой на странице инвойса в кабинете (см. Песочница и тестирование).

В примерах ниже используется продакшен-base-URL https://api.zerokyc-payments.com — он принимает ключи pk_test_… и гоняет их инвойсы по симулированной цепи.

2. Создайте инвойс

Укажите payment_currency: "any", чтобы покупатель сам выбрал монету в чекауте, — один инвойс покрывает все включённые активы:

curl -X POST https://api.zerokyc-payments.com/v1/invoices \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": "49.00",
    "base_currency": "USD",
    "payment_currency": "any",
    "order_id": "order-1042",
    "ttl_minutes": 360,
    "success_url": "https://yourapp.com/paid",
    "webhook_url": "https://yourapp.com/webhooks/zkp",
    "metadata": { "customer_id": "cust_8821" }
  }'

В ответе — по одному платёжному варианту на каждый включённый актив и URL hosted-чекоута:

{
  "id": "inv_9f2k...",
  "status": "pending",
  "order_id": "order-1042",
  "amount": "49.00",
  "base_currency": "USD",
  "expires_at": "2026-09-06T18:20:11Z",
  "checkout_url": "https://app.zerokyc-payments.com/pay/inv_9f2k...",
  "options": [
    { "asset": "USDT", "network": "tron", "amount_crypto": "49.00", "rate": "1.0", "status": "open" },
    { "asset": "BTC",  "network": "bitcoin", "amount_crypto": "0.000524", "rate": "93457.91", "status": "open" },
    { "asset": "TON",  "network": "ton", "amount_crypto": "9.81", "rate": "4.99", "status": "open" },
    { "asset": "ETH",  "network": "ethereum", "amount_crypto": "0.0101", "rate": "2970.29", "status": "open" },
    { "asset": "BNB",  "network": "bsc", "amount_crypto": "0.0815", "rate": "601.22", "status": "open" }
  ]
}

Заметки:

  • amount — это фиат (USD, EUR или RUB) или сумма сразу в активе ("base_currency": "BTC").
  • Передавайте заголовок Idempotency-Key: повтор того же создания вернёт тот же инвойс, а не дубликат (подробнее).
  • ttl_minutes по умолчанию 360 (6 часов); допустимый диапазон — 10 минут — 72 часа.
  • metadata возвращается в инвойсе и в каждом вебхуке — кладите туда ссылку на клиента или заказ.
  • При ошибках валидации API отвечает единым конвертом ошибок, например {"error": {"code": "invalid_request", "message": "ttl_minutes must be between 10 and 4320", "doc_url": "..."}}.

Все поля запроса и ответа разобраны в справочнике Invoices API.

3. Отправьте покупателя в чекаут

Редиректните на checkout_url. Страница покажет все варианты с суммами в крипте, адрес, QR и живой таймер TTL; статус опрашивается раз в 5 секунд. Белый лейбл и локали RU/EN встроены.

4. Получите вебхук

Когда платёж подтверждён, вам придёт POST payment.confirmed:

{
  "id": "evt_5c1a...",
  "type": "payment.confirmed",
  "created_at": "2026-09-06T14:02:33Z",
  "data": {
    "invoice_id": "inv_9f2k...",
    "order_id": "order-1042",
    "amount": "49.00",
    "base_currency": "USD",
    "option": { "asset": "TON", "network": "ton", "amount_crypto": "9.81", "paid_amount": "9.81" },
    "tx": { "hash": "9d24...", "confirmations": 1, "explorer_url": "https://tonviewer.com/transaction/9d24...", "output_index": 0 },
    "metadata": { "customer_id": "cust_8821" }
  }
}

Ответьте любым 2xx в течение 10 секунд. Каждая доставка подписана — проверяйте подпись, прежде чем доверять payload (следующий шаг); неудачные доставки ретраятся по лесенке 1м → 5м → 30м → 2ч → 12ч (семантика доставки).

5. Проверьте подпись

Таймстемп и подпись ездят в одном заголовке X-ZKP-Signature: t=<unix seconds>,v1=<hex>; HMAC считается по строке "{t}.{raw_body}":

import { createHmac, timingSafeEqual } from "node:crypto";

// X-ZKP-Signature: t=1694007753,v1=ade537fa...
const [t, v1] = Object.fromEntries(
  req.headers["x-zkp-signature"].split(",").map((p) => p.trim().split("=")),
);

const expected = createHmac("sha256", WEBHOOK_SECRET)
  .update(`${t}.${req.rawBody}`)
  .digest("hex");

const ok = timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));
if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(400).end();

Полные примеры для Node, PHP и Python: проверка HMAC.

Что дальше