API v1 · Sandbox · Webhooks

Arzan Pay API для Kaspi Pay: сайт, CRM, POS, Telegram и внутренние системы.

Base URL: https://pay.arzan.cloud/api. Аутентификация через X-API-Key или Authorization: Bearer <api_key>. Лимит публичного API: 60 req/min. Для тестов используйте is_sandbox=true, чтобы не отправлять реальный счет в Kaspi.

OpenAPI spec Postman collection Node.js example PHP example Python example Webhook signature example

Quick Start

curl -X POST https://pay.arzan.cloud/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "phone_number": "77011234567",
    "description": "Order #1042",
    "external_order_id": "order_1042",
    "is_sandbox": true
  }'

Go Live Checklist

1. Sandbox

Создайте тестовый счет, получите `invoice.id`, проверьте список счетов и отмену.

2. Webhook

Создайте endpoint, сохраните `secret`, проверьте `X-Webhook-Signature` на raw body.

3. Live

Уберите `is_sandbox`, используйте `external_order_id`, не создавайте live-счета в healthcheck.

Endpoints

МетодПутьСтатусОписание
POST/organizations/verifyliveПроверить API key и организацию.
GET/v1/meliveТекущий мерчант и capabilities.
POST/v1/invoicesliveСоздать sandbox или реальный Kaspi-счет.
GET/v1/invoicesliveСписок счетов с pagination и фильтрами.
GET/v1/invoices/{id}liveПолучить счет.
POST/v1/invoices/{id}/cancelliveОтменить pending/processing счет через Kaspi remote cancel.
POST/v1/invoices/status/checkliveПроверить статусы через Kaspi remote details / QR status.
POST/v1/qrliveСоздать sandbox или реальный Kaspi QR.
POST/v1/invoices/{id}/refundliveСоздать возврат по оплаченному счету через Kaspi return.
GET/POST/v1/refundsliveСписок и создание возвратов по оплаченным счетам/QR.
GET/v1/kaspi/sessionliveМониторинг Kaspi-сессии: last success, last error, статус.
POST/v1/sandbox/invoices/{id}/simulateliveПесочница: paid, canceled, failed, pending без реального Kaspi.
GET/POST/v1/webhooksliveНастройка webhook endpoint.
GET/POST/v1/webhook-deliveriesliveИстория доставок и retry webhook delivery.
GET/v1/audit-logsliveAudit log платежных действий.
GET/v1/jobsliveОчередь jobs/retry/dead-letter статусов.
POST/v1/webhooks/{id}/testliveТестовая доставка webhook.
GET/POST/v1/subscriptionsmvpПодписки и очередь автосчетов.
GET/POST/v1/catalogmvpКаталог и очередь синхронизации.

Webhook Signature

Каждый webhook подписывается заголовком X-Webhook-Signature: sha256=<hex>. Подпись считается как HMAC-SHA256 от raw body с использованием webhook secret. 

const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex')

Idempotency

Для create/refund endpoint'ов передавайте Idempotency-Key. Повторный запрос с тем же ключом вернет сохраненный response и не создаст дубль. Также external_order_id уникален внутри мерчанта.

Интеграции

Tilda

Форма Tilda отправляет webhook на ваш bridge, bridge создает Arzan Pay invoice и получает статус через webhook.

WooCommerce

Payment gateway создает invoice на checkout, webhook переводит order в processing/completed.

Telegram

Бот спрашивает сумму и телефон, создает счет, webhook отправляет сообщение об оплате.

Bitrix24

Робот сделки вызывает bridge, invoice id сохраняется в пользовательское поле, webhook двигает сделку.

CRM/POS

Используйте `external_order_id`, чтобы связать чек или заказ с Arzan Pay invoice.

Внутренние системы

OpenAPI и Postman collection подходят для быстрой генерации клиента.

Ошибки

400invalid_phone, invalid_amountПроверьте формат телефона и сумму.
401api_key_required, invalid_api_keyПередайте корректный API key.
404invoice_not_found, webhook_not_foundОбъект не найден.
409kaspi_not_connected, invoice_not_cancelableНужно подключить Kaspi или изменить действие.
422validation_errorТело запроса не прошло бизнес-валидацию.
429rate_limit_exceededИспользуйте `Retry-After`.
502kaspi_invoice_failedKaspi не принял создание счета.