Обзор

PayCA отправляет вебхуки при каждом изменении статуса картхолдера. Это позволяет вашей системе реагировать на события в реальном времени без необходимости опрашивать API.

Регистрация вебхука

curl -s -X POST "$PAYCA_BASE_URL/v1/webhooks" \
  -H 'Content-Type: application/json' \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "url": "https://your-domain.com/webhooks/cardholder",
    "type": "cardholder"
  }'
  • url — HTTPS-эндпоинт на вашей стороне, куда будут отправляться вебхуки.
  • type — тип вебхука. Для картхолдеров используйте "cardholder".

Формат payload

При каждом изменении статуса картхолдера на ваш URL отправляется POST-запрос со следующим JSON-телом:

{
  "cardholderId": "1ff17026-f9d7-4870-8d48-daee288edd0a",
  "status": "pass_audit",
  "previousStatus": "under_review",
  "description": "",
  "timestamp": "2026-03-25T12:45:00Z"
}

Поля

Поле Тип Описание
cardholderId string (UUID) Идентификатор картхолдера.
status string Новый статус картхолдера.
previousStatus string Предыдущий статус картхолдера.
description string Причина отклонения (заполняется при rejected_by_admin и reject).
timestamp string (ISO 8601) Время изменения статуса.

Статусы

Картхолдер может находиться в одном из следующих статусов:

Статус Значение
pending_review Создан, ожидает первичного одобрения администратором PayCA.
rejected_by_admin Отклонён администратором PayCA (см. description).
wait_audit Отправлен провайдеру, ожидает ответа провайдера.
under_review Провайдер начал проверку.
pending_approval Провайдер одобрил, ожидает повторного подтверждения администратором PayCA.
pass_audit Полностью одобрен — можно выпускать карту.
reject Отклонён провайдером (см. description и statusFlowLocation).
submission_failed Не удалось отправить картхолдера провайдеру (например, ошибка API). Администратор может повторить отправку.

Переходы и вебхуки

Картхолдер создаётся в статусе pending_review (без вебхука). Дальнейшие переходы вызывают вебхук на ваш URL.

pending_review ─┬─→ rejected_by_admin
                └─→ (одобрение админом — отправка провайдеру)
                       │
                       ├─→ wait_audit / under_review
                       │      │
                       │      ├─→ pending_approval ─┬─→ pass_audit
                       │      │                     ├─→ rejected_by_admin
                       │      │                     └─→ reject
                       │      └─→ reject
                       │
                       └─→ submission_failed
                              │
                              └─[retry]─→ wait_audit → ...
Переход Когда отправляется
pending_review → rejected_by_admin Администратор PayCA отклонил картхолдера.
pending_review → wait_audit / under_review / pending_approval Администратор одобрил, отправили провайдеру; конкретный статус зависит от ответа провайдера.
pending_review → submission_failed Не удалось отправить запрос провайдеру; ошибка в description.
wait_audit → under_review Провайдер начал ручную проверку.
wait_audit / under_review → pending_approval Провайдер одобрил, ожидаем второе подтверждение от PayCA.
wait_audit / under_review → reject Провайдер отклонил (причина в description).
pending_approval → pass_audit Администратор PayCA подтвердил одобрение — можно выпускать карту.
pending_approval → rejected_by_admin Администратор PayCA отказал на финальном шаге.
submission_failed → wait_audit Администратор перезапустил отправку.

Поле previousStatus всегда содержит статус непосредственно перед этим вебхуком. Опирайтесь на пару (status, previousStatus), а не на конкретный путь, — последовательность шагов может варьироваться в зависимости от провайдера.

Примеры вебхуков

Одобрение администратором PayCA

{
  "cardholderId": "1ff17026-f9d7-4870-8d48-daee288edd0a",
  "status": "wait_audit",
  "previousStatus": "pending_review",
  "description": "",
  "timestamp": "2026-03-25T10:35:00Z"
}

Успешное прохождение аудита провайдера

{
  "cardholderId": "1ff17026-f9d7-4870-8d48-daee288edd0a",
  "status": "pass_audit",
  "previousStatus": "under_review",
  "description": "",
  "timestamp": "2026-03-25T12:45:00Z"
}

Действие: картхолдер одобрен, можно выпускать карту через POST /v1/cards.

Отклонение провайдером

{
  "cardholderId": "1ff17026-f9d7-4870-8d48-daee288edd0a",
  "status": "reject",
  "previousStatus": "under_review",
  "description": "Document verification failed: ID photo is unclear",
  "timestamp": "2026-03-25T14:00:00Z"
}

Отклонение администратором PayCA

{
  "cardholderId": "1ff17026-f9d7-4870-8d48-daee288edd0a",
  "status": "rejected_by_admin",
  "previousStatus": "pending_review",
  "description": "Incomplete personal data",
  "timestamp": "2026-03-25T11:00:00Z"
}

Рекомендации по обработке

  1. Отвечайте HTTP 200 — PayCA ожидает успешный ответ. При ошибке доставка будет повторена.
  2. Идемпотентность — один и тот же вебхук может быть доставлен повторно. Используйте cardholderId + status + timestamp для дедупликации.
  3. Реагируйте на pass_audit — это сигнал, что можно выпускать карту для данного картхолдера.
  4. Логируйте reject и rejected_by_admin — поле description содержит причину отказа, которую можно показать пользователю.

Аутентификация

Все запросы к API требуют два заголовка:

x-client-id: <ваш-client-id>
x-client-secret: <ваш-client-secret>

Базовый URL: https://api.actisas.ee