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

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

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

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

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

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

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

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"
}'

В ответе — по одному платёжному варианту на каждый включённый актив и 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://pay.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" }
]
}

Заметки:

  • amount — это фиат (USD, EUR или RUB) или сумма сразу в активе ("base_currency": "BTC").
  • Передавайте заголовок Idempotency-Key: повтор того же создания вернёт тот же инвойс, а не дубликат.
  • ttl_minutes по умолчанию 360 (6 часов); допустимый диапазон — 10 минут — 72 часа.

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",
  "asset": "TON",
  "network": "ton",
  "amount_paid": "9.81",
  "tx_hash": "9d24...",
  "status": "confirmed"
}
}

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

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

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

const expected = createHmac("sha256", WEBHOOK_SECRET)
  .update(`${req.headers["x-zkp-timestamp"]}.${req.rawBody}`)
  .digest("hex");

const ok = timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(req.headers["x-zkp-signature"], "hex"),
);
if (!ok) return res.status(400).end();

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

Что дальше