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

Песочница и тестирование

Как работают pk_test-ключи и симулированная цепь, симуляция платежей из кабинета и end-to-end тест обработчика вебхуков.

Песочница позволяет прогнать всю интеграцию — инвойс, чекаут, вебхуки, проверку подписи — без единой реальной транзакции.

Как устроена песочница

  • Ключ pk_test_… помечает каждый создаваемый им инвойс как sandbox.
  • Sandbox-инвойсы ездят по симулированной цепи: контракт (эндпоинты, payload, подписи, статусы) байт-в-байт идентичен продакшену, но платежи подтверждаются за секунды и блокчейн не участвует.
  • Данные полностью изолированы: тестовые ключи видят только sandbox-инвойсы и события; live-ключи — никогда. Идемпотентные ключи скоупятся по режиму, так что одна и та же строка безопасна в обоих.
  • Лимиты в песочнице ниже: 10 созданий инвойсов и 90 чтений в минуту.

Base URL: продакшен-API https://api.zerokyc-payments.com принимает ключи pk_test_… напрямую — это и есть рекомендуемая песочница. Live-ключи на том же API проводят реальные платежи.

Симуляция платежей

Откройте инвойс в кабинете (Инвойсы → инвойс) и нажмите Симулировать платёж: mock-цепь фабрикует совпадающую транзакцию и сразу запускает детекцию — статус перевернётся в confirmed, а вам придут настоящие вебхуки payment.detected → payment.confirmed, подписанные ровно как в продакшене.

Другие состояния:

  • underpaid — API симуляции принимает произвольный amount; значение ниже необходимого даст настоящий вебхук payment.underpaid (вызывается из вашей консольной сессии, например из devtools браузера: POST /console/v1/mock/simulate-payment).
  • expired — создайте инвойс с ttl_minutes: 10 (минимум) и подождите, либо на время разработки проверьте обработчик сфабрикованным payload.

Тестирование обработчика вебхуков

  1. Тестовое событие эндпоинта. В разделе Вебхуки добавите эндпоинт и нажмите Отправить тестовое событие — в течение секунд придёт подписанный webhook.test. Если он отображается доставленным, значит URL, TLS и правило «быстрый 2xx» работают.
  2. Локальный приёмник. В разработке удобно печатать всё, что мы присылаем:
# receiver.py — минимальный приёмник вебхуков для локальных тестов
from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["Content-Length"]))
        print("path:", self.path)
        for h in ("X-ZKP-Signature", "X-ZKP-Event-Id", "X-ZKP-Event-Type"):
            print(f"{h}: {self.headers[h]}")
        print("body:", body.decode())
        self.send_response(200); self.end_headers()

HTTPServer(("0.0.0.0", 9000), H).serve_forever()

API должен доставлять вебхуки по HTTPS — для локальной разработки используйте туннель (cloudflared, ngrok). Проверяйте подпись и в тестах: непроверяющий обработчик в тесте почти всегда остаётся непроверяющим и в продакшене.

  1. Полный цикл. Создайте sandbox-инвойс → Симулировать платёж → убедитесь, что обработчик проверил подпись, дедуплицировал по event.id и отреагировал только на payment.confirmed.

Переход в live

  • Выпустите ключ pk_live_… в кабинете (API-ключи); выпуск live-ключей требует TOTP-подтверждения — ключ показывается один раз, храните его в секрет-менеджере.
  • Интеграция остаётся на том же https://api.zerokyc-payments.com; меняется только ключ.
  • Не отключайте проверку подписи вебхуков — live-события отличаются от sandbox только таймингом (реальные подтверждения занимают время своей сети).
  • Обрабатывайте 429/Retry-After и конверт ошибок: Ошибки, Лимиты и идемпотентность.
  • Перед включением реального трафика прогоните end-to-end один небольшой live-инвойс.