Обзор

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 → rejected_by_admin
pending_review → wait_audit → under_review → pass_audit
                                            → reject

Вебхук отправляется при каждом переходе между статусами.

Переход Описание
pending_review → wait_audit Администратор PayCA одобрил картхолдера, отправлен в провайдер.
wait_audit → under_review Провайдер начал проверку.
under_review → pass_audit Провайдер одобрил — можно выпускать карту.
under_review → reject Провайдер отклонил (причина в description).
pending_review → rejected_by_admin Администратор PayCA отклонил (причина в description).

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

Одобрение администратором 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