Download OpenAPI specification:
Public payments API of the PA Core payment aggregation platform.
The API exposes the PA model only (payments, refunds, payment instruments, payouts, merchant onboarding, audit trail, webhook delivery log, tenant key lifecycle). PSP/connector concepts never cross this boundary.
Conventions:
Authorization: Bearer <tenant_api_key> for every /v1 route (see securitySchemes.bearerAuth). Health probes and the docs portal are unauthenticated.pay_…, mer_…, pin_…, pout_…, tn_…, key_…).Idempotency-Key header; a retry with the same key and body replays the stored result (Idempotent-Replayed: true), a reused key with a different body is rejected with 422 idempotency_key_reuse.application/problem+json with stable PA code values; PSP error codes are never exposed.429 rate_limited with Retry-After.GET /docs (branded Redocly reference page) served by the same API instance; GET /docs/swagger-ui is the try-it-out console (Swagger UI); this document is GET /docs/openapi.json./docs reference page renders the integration guides INSIDE the sidebar «Guides» group — Handover Package, Integration models, SDK README, SDK + Webhooks (Secure Fields), Secure Fields (EN), Field Reference, Payouts Guide, Onboarding Checklist, Термінологія (glossary) — plus the standalone reference sections Errors, Webhooks and Sandbox; /docs is the single documentation entry point, the raw markdown surface stays at GET /portal/docs/{doc}.Getting started (10 minutes, sandbox):
Authorization: Bearer, shown exactly once), your merchant id, the webhook secret (shown exactly once at webhook registration) and the Secure Fields captureUrl. The package contents are listed in the Handover Package guide.vault_token), register the instrument (POST /v1/payment-instruments), create the payment (POST /v1/payments with an Idempotency-Key); for hosted-page PSPs use payment_method.type = redirect and follow next_action.redirect_url. Sandbox base URL: https://sandbox.playpulse.tech.PA-Webhook-Signature (v1= + HMAC-SHA256 over the raw body), dedup by PA-Event-Id, answer 2xx fast (the Webhooks reference has the full contract and a receiver example).https://payments.playpulse.tech and production keys from the operator; production keys are issued separately from sandbox keys.Merchant portal: https://sandbox.playpulse.tech/portal (sandbox) · https://payments.playpulse.tech/portal (production) — dashboard statistics, payments list, CSV report, webhook delivery health and self-service rotations.
RU documentation of the contract lives in the repository under docs/api/ (Russian); this spec is the EN-facing reference for external merchants.
Merchant view: this page renders the MERCHANT-relevant endpoints only — the operator surfaces (admin console, PSP portal, ops tooling, audit trail, merchant onboarding, tenant keys, payouts) are part of the platform contract served by GET /docs/openapi.json and are intentionally omitted from this reference. The «Guides» group carries the integration documents; «Field Reference» details every field of POST /v1/payments.
Приветствуем! Вы получили доступ к платформе платежей PA: приём карточных депозитов (токенизация → платёж → подписанные webhooks → возвраты) через Payments API и Secure Fields SDK. Эта страница — самодостаточная точка входа: ключи, артефакты, 6 шагов интеграции, правила безопасности и ограничения текущего релиза. Детали каждого шага — в чек-листе онбординга казино (RU + EN).
Состояние платформы подтверждено полномочным acceptance-прогоном: платежи до AUTHORIZED
(Apcopay, saved-card tokenise → PURC CardToken), возвраты полный цикл
(PARTIALLY_REFUNDED/REFUNDED), webhooks exactly-once (дедуп переходов),
идемпотентность (422 idempotency_key_reuse), PCI: 0 PAN в логах/БД.
Поддержка (контакты заполняет Оператор при выдаче доступов): L1 — вопросы интеграции (), L2 — Оператор PA, дежурный (), L3 — PSP PayAdmit/Apcopay (___). Эскалация — чек-лист §7.
⚠️ Секреты выдаются ровно один раз. Значения передаются по защищённому каналу и показываются единожды — сразу сохраните их в свой secret store. Повторный показ невозможен; замена — только ротация через API (§4, правило 3).
| Параметр | Значение | Комментарий |
|---|---|---|
| Production base URL | https://payments.playpulse.tech |
Основной прод-адрес. TLS-сертификат Let's Encrypt, валиден до 2026-12-23, автопродление. Production ключи (tenant API key + whs_-секрет production MID) выдаются Оператором отдельно от sandbox-ключей — разделение сред |
| Sandbox base URL | https://sandbox.playpulse.tech |
Изолированный sandbox-инстанс. TLS-сертификат Let's Encrypt, валиден до 2026-12-27, автопродление |
| Tenant API key (Bearer) | ___ |
Заголовок Authorization: Bearer <key> на каждый вызов PA API; raw-значение показывается один раз |
| Merchant ID | ___ (mer_…) |
Ваш профиль мерчанта в PA (валюты, маршрутизация, webhook) |
| Webhook secret | ___ (whs_…) |
Для проверки подписи PA-Webhook-Signature; показывается ОДИН раз при регистрации endpoint'а |
| captureUrl (для SDK) | ___ |
Выдаёт Оператор вместе с SDK-пакетом (значение captureUrl для PASecureFields.mount) |
| Артефакт | Где получить | Назначение |
|---|---|---|
| SDK frontend | https://<pa-origin>/pa-sdk/secure-fields.js (выдаёт Оператор в SDK-пакете) |
drop-in виджет: iframe-форма карты, onToken(vaultToken); без сборки |
| SDK iframe-страница | https://<pa-origin>/pa-sdk/secure-fields-frame.html |
размещается на origin PA; логику не менять |
| Демо-казино (эталон receiver'а) | SDK-пакет (demo/ — demo.html + server.js) |
рабочий frontend + backend + webhook receiver одним процессом |
| Payments API (RU) | гайд SDK + Webhooks + референс /docs |
/v1/payments, /v1/refunds, идемпотентность, ротация ключей |
| SDK + webhook контракт (RU) | гайд SDK + Webhooks | инструменты, HMAC v1, дедуп PA-Event-Id, ротация webhook-секрета |
| OpenAPI (EN) + референс | /docs/openapi.json · Redocly: /docs · Swagger UI: /docs/swagger-ui — всё на вашем base URL (раздел 1; корень / ведёт на /docs) |
машинная схема API |
| Чек-лист онбординга (RU + EN) | гайд Onboarding Checklist | детальные шаги К1–К6 / C1–C6, go-live §6, эскалация §7 |
| Field Reference | гайд Field Reference | все поля POST /v1/payments: типы, обязательность, ошибки |
| SDK README | гайд SDK README | «как это работает за 30 секунд» + локальный smoke |
| Глоссарий | гайд Термінологія | PA, PSP, MID, PURC, S2S, HPP, 3DS, PCI DSS, vault token… |
| Integration models | гайд Integration models | SDK / hosted page / S2S — модели и PCI DSS scope |
| Payouts | гайд Payouts — Phase 2 | модель выплат, статус поверхности |
Нумерация ниже — маршрут казино «от виджета до go-live». В чек-листе шаги детализированы своей нумерацией К1–К6; в скобках — куда смотреть за деталями.
<script src="https://<pa-origin>/pa-sdk/secure-fields.js"></script>
<div id="pa-card"></div>
<script>
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<pa-origin>/pa-sdk/secure-fields-frame.html',
captureUrl: '<из секции 1>', // выдаёт Оператор
onToken: (r) => {
// r.vaultToken — single-use vault token → сразу на СВОЙ backend
fetch('/my/api/deposit', { method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ vault_token: r.vaultToken, amount_cents: 1500 }) });
},
onError: (e) => showError(e.code, e.message),
});
</script>
Инварианты: iframe — opaque origin (JS казино не видит значения полей); vault_token —
одноразовый, не в URL/логи/localStorage. Тестовые карты PSP-sandbox выдаёт Оператор (чек-лист О6).
Endpoint регистрирует Оператор (секрет whs_… — §1). Receiver обязан: верифицировать
PA-Webhook-Signature (HMAC-SHA256 по сырому телу), дедуплицировать по
PA-Event-Id и отвечать 2xx быстро. Эталонный Node/Express receiver — в
чек-листе §5/К4; полный контракт доставки
(at-least-once, retry 1м/5м/30м/2h → DEAD после 5 попыток, ротация секрета с grace
7 дней и dual-verify) — раздел Webhooks справочника /docs.
Два вызова с Idempotency-Key (uuid) и Authorization: Bearer <tenant API key>:
POST /v1/payment-instruments
Idempotency-Key: <uuid>
{"merchant_id": "mer_…", "vault_token": "<из К1>", "customer_reference": "usr_123"}
→ 201 {"instrument_id": "pin_…", "card_meta": {"masked_pan": "****1111", …}}
POST /v1/payments
Idempotency-Key: <uuid>
{"merchant_id": "mer_…", "amount": 1500, "currency": "EUR",
"payment_method": {"type": "card", "instrument_id": "pin_…"}, "capture_method": "automatic"}
→ 201 {"payment_id": "pay_…", "status": "PENDING"|"AUTHORIZED"|"FAILED", …}
Инструмент одноразовый (повтор → 422 instrument_not_active); PENDING → опрашивайте
GET /v1/payments/{id} (Retry-After); replay Idempotency-Key возвращает сохранённый
результат, тот же ключ с другим телом → 422 idempotency_key_reuse.
Если ответ содержит next_action: {"type": "redirect", "redirect_url": "…", "method": "GET"} —
переведите игрока по redirect_url. Возврат игрока на сайт — не результат: финальный
статус приходит webhook'ом (К2) и/или через GET /v1/payments/{id}.
POST /v1/refunds
Idempotency-Key: <uuid>
{"payment_id": "pay_…", "amount": 1050, "reason": "requested_by_customer"}
Частичные возвраты суммируются с контролем не-превышения AUTHORIZED-суммы; статусы
PARTIALLY_REFUNDED → REFUNDED приходят webhook'ом (событие payment.refunded, К2).
Полный цикл возвратов подтверждён acceptance-прогоном.
Запросите у Оператора production base URL и production ключи (tenant API key + whs_-секрет
production MID) и пройдите go-live чек-лист §6 (7 пунктов: полный цикл, HMAC, идемпотентность,
PCI-гигиена, ротации ключей, production MID ENABLED, мониторинг).
vault_token/pin_ и маскированные метаданные. PAN/CVV —
никогда в логи, БД, аудит (acceptance: 0 PAN).PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, whs_секрет))> над сырым телом, сравнение timing-safe; без валидной подписи — не
обрабатывать (401). Дедуп по PA-Event-Id (= event_id payload, UUIDv7).POST /v1/tenants/{id}/rotate-key (новый сразу, старый 24 ч grace),
webhook-секрет POST /v1/merchants/{id}/rotate-webhook-secret (grace 7 дней, dual-verify).Idempotency-Key: <uuid> на каждый POST; повтор с тем же
ключом возвращает сохранённый результат (Idempotent-Replayed: true), тот же ключ с другим
телом → 422 idempotency_key_reuse. Webhook-replay по PA-Event-Id не должен дублировать
зачисление игроку.| Ограничение | Суть | Когда снимается |
|---|---|---|
| Production MID | Prod URL жив: https://payments.playpulse.tech. Production MID у PSP — в оформлении на стороне PSP; production ключи выдаются отдельно от sandbox |
у PSP |
| 3DS | PayAdmit — hosted HPP в их среде (в пилоте demo 502); Apcopay — NotSupported в MVP |
отдельный этап roadmap |
| Выплаты | Выплаты мерчанта доступны (POST /v1/merchants/{id}/payouts, гайд Payouts; включаются Оператором). PSP-диспетч выплат — следующий этап |
Phase 2 |
| KYC | Не входит в MVP — средствами казино/партнёров | вне скоупа PA |
Welcome — you get sandbox API access, the Secure Fields SDK and signed webhooks. Integration in
6 steps: K1 mount the SDK iframe (onToken(vaultToken) → send straight to your backend);
K2 run a webhook receiver — verify PA-Webhook-Signature (v1=<hex HMAC-SHA256> over the
raw body), dedup by PA-Event-Id, reply 2xx fast; K3 exchange the vault token
(POST /v1/payment-instruments → pin_…) and create the payment (POST /v1/payments with
Idempotency-Key on the sandbox base URL from section 1); K4 follow
next_action.redirect (3DS / hosted page) — the final status arrives via webhook and/or
GET /v1/payments/{id}; K5 refunds via POST /v1/refunds (partial refunds supported,
PARTIALLY_REFUNDED → REFUNDED); K6 go-live — request the production URL and keys from the
Operator and pass the go-live checklist. Security: PAN/CVV never leave the SDK iframe; HMAC
verification and idempotency are mandatory; keep secrets out of git and logs.
Limits: production URL is live (https://payments.playpulse.tech) — production MID
at the PSP is pending with the PSP, production keys are issued separately from sandbox,
3DS limited (PayAdmit hosted HPP / Apcopay NotSupported in MVP), payouts = Phase 2, no KYC in MVP.
Details: onboarding checklist, English Part II.
redirect_hpp) / почему S2S raw card не предоставляется./docs (Redocly) и Swagger UI
/docs/swagger-ui на вашем base URL (раздел 1).4111 1111 1111 1111 (12/30, CVC 123), 5555 5555 5555 4444 (MC),
4000 0000 0000 0002 (3DS).⚠️ Секреты выдаются ровно один раз. Значения передаются по защищённому каналу и показываются единожды — сразу сохраните их в свой secret store. Повторный показ невозможен; замена — только ротация через API (§4, правило 3).
| Параметр | Значение | Комментарий |
|---|---|---|
| Production base URL | https://payments.playpulse.tech |
Основной прод-адрес. TLS-сертификат Let's Encrypt, валиден до 2026-12-23, автопродление. Production ключи (tenant API key + whs_-секрет production MID) выдаются Оператором отдельно от sandbox-ключей — разделение сред |
| Sandbox base URL | https://sandbox.playpulse.tech |
Изолированный sandbox-инстанс. TLS-сертификат Let's Encrypt, валиден до 2026-12-27, автопродление |
| Tenant API key (Bearer) | ___ |
Заголовок Authorization: Bearer <key> на каждый вызов PA API; raw-значение показывается один раз |
| Merchant ID | ___ (mer_…) |
Ваш профиль мерчанта в PA (валюты, маршрутизация, webhook) |
| Webhook secret | ___ (whs_…) |
Для проверки подписи PA-Webhook-Signature; показывается ОДИН раз при регистрации endpoint'а |
| captureUrl (для SDK) | ___ |
Выдаёт Оператор вместе с SDK-пакетом (значение captureUrl для PASecureFields.mount) |
| Артефакт | Где получить | Назначение |
|---|---|---|
| SDK frontend | https://<pa-origin>/pa-sdk/secure-fields.js (выдаёт Оператор в SDK-пакете) |
drop-in виджет: iframe-форма карты, onToken(vaultToken); без сборки |
| SDK iframe-страница | https://<pa-origin>/pa-sdk/secure-fields-frame.html |
размещается на origin PA; логику не менять |
| Демо-казино (эталон receiver'а) | SDK-пакет (demo/ — demo.html + server.js) |
рабочий frontend + backend + webhook receiver одним процессом |
| Payments API (RU) | гайд SDK + Webhooks + референс /docs |
/v1/payments, /v1/refunds, идемпотентность, ротация ключей |
| SDK + webhook контракт (RU) | гайд SDK + Webhooks | инструменты, HMAC v1, дедуп PA-Event-Id, ротация webhook-секрета |
| OpenAPI (EN) + референс | /docs/openapi.json · Redocly: /docs · Swagger UI: /docs/swagger-ui — всё на вашем base URL (раздел 1; корень / ведёт на /docs) |
машинная схема API |
| Чек-лист онбординга (RU + EN) | гайд Onboarding Checklist | детальные шаги К1–К6 / C1–C6, go-live §6, эскалация §7 |
| Field Reference | гайд Field Reference | все поля POST /v1/payments: типы, обязательность, ошибки |
| SDK README | гайд SDK README | «как это работает за 30 секунд» + локальный smoke |
| Глоссарий | гайд Термінологія | PA, PSP, MID, PURC, S2S, HPP, 3DS, PCI DSS, vault token… |
| Integration models | гайд Integration models | SDK / hosted page / S2S — модели и PCI DSS scope |
| Payouts | гайд Payouts — Phase 2 | модель выплат, статус поверхности |
Нумерация ниже — маршрут казино «от виджета до go-live». В чек-листе шаги детализированы своей нумерацией К1–К6; в скобках — куда смотреть за деталями.
<script src="https://<pa-origin>/pa-sdk/secure-fields.js"></script>
<div id="pa-card"></div>
<script>
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<pa-origin>/pa-sdk/secure-fields-frame.html',
captureUrl: '<из секции 1>', // выдаёт Оператор
onToken: (r) => {
// r.vaultToken — single-use vault token → сразу на СВОЙ backend
fetch('/my/api/deposit', { method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ vault_token: r.vaultToken, amount_cents: 1500 }) });
},
onError: (e) => showError(e.code, e.message),
});
</script>
Инварианты: iframe — opaque origin (JS казино не видит значения полей); vault_token —
одноразовый, не в URL/логи/localStorage. Тестовые карты PSP-sandbox выдаёт Оператор (чек-лист О6).
Endpoint регистрирует Оператор (секрет whs_… — §1). Receiver обязан: верифицировать
PA-Webhook-Signature (HMAC-SHA256 по сырому телу), дедуплицировать по
PA-Event-Id и отвечать 2xx быстро. Эталонный Node/Express receiver — в
чек-листе §5/К4; полный контракт доставки
(at-least-once, retry 1м/5м/30м/2h → DEAD после 5 попыток, ротация секрета с grace
7 дней и dual-verify) — раздел Webhooks справочника /docs.
Два вызова с Idempotency-Key (uuid) и Authorization: Bearer <tenant API key>:
POST /v1/payment-instruments
Idempotency-Key: <uuid>
{"merchant_id": "mer_…", "vault_token": "<из К1>", "customer_reference": "usr_123"}
→ 201 {"instrument_id": "pin_…", "card_meta": {"masked_pan": "****1111", …}}
POST /v1/payments
Idempotency-Key: <uuid>
{"merchant_id": "mer_…", "amount": 1500, "currency": "EUR",
"payment_method": {"type": "card", "instrument_id": "pin_…"}, "capture_method": "automatic"}
→ 201 {"payment_id": "pay_…", "status": "PENDING"|"AUTHORIZED"|"FAILED", …}
Инструмент одноразовый (повтор → 422 instrument_not_active); PENDING → опрашивайте
GET /v1/payments/{id} (Retry-After); replay Idempotency-Key возвращает сохранённый
результат, тот же ключ с другим телом → 422 idempotency_key_reuse.
Если ответ содержит next_action: {"type": "redirect", "redirect_url": "…", "method": "GET"} —
переведите игрока по redirect_url. Возврат игрока на сайт — не результат: финальный
статус приходит webhook'ом (К2) и/или через GET /v1/payments/{id}.
POST /v1/refunds
Idempotency-Key: <uuid>
{"payment_id": "pay_…", "amount": 1050, "reason": "requested_by_customer"}
Частичные возвраты суммируются с контролем не-превышения AUTHORIZED-суммы; статусы
PARTIALLY_REFUNDED → REFUNDED приходят webhook'ом (событие payment.refunded, К2).
Полный цикл возвратов подтверждён acceptance-прогоном.
Запросите у Оператора production base URL и production ключи (tenant API key + whs_-секрет
production MID) и пройдите go-live чек-лист §6 (7 пунктов: полный цикл, HMAC, идемпотентность,
PCI-гигиена, ротации ключей, production MID ENABLED, мониторинг).
vault_token/pin_ и маскированные метаданные. PAN/CVV —
никогда в логи, БД, аудит (acceptance: 0 PAN).PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, whs_секрет))> над сырым телом, сравнение timing-safe; без валидной подписи — не
обрабатывать (401). Дедуп по PA-Event-Id (= event_id payload, UUIDv7).POST /v1/tenants/{id}/rotate-key (новый сразу, старый 24 ч grace),
webhook-секрет POST /v1/merchants/{id}/rotate-webhook-secret (grace 7 дней, dual-verify).Idempotency-Key: <uuid> на каждый POST; повтор с тем же
ключом возвращает сохранённый результат (Idempotent-Replayed: true), тот же ключ с другим
телом → 422 idempotency_key_reuse. Webhook-replay по PA-Event-Id не должен дублировать
зачисление игроку.| Ограничение | Суть | Когда снимается |
|---|---|---|
| Production MID | Prod URL жив: https://payments.playpulse.tech. Production MID у PSP — в оформлении на стороне PSP; production ключи выдаются отдельно от sandbox |
у PSP |
| 3DS | PayAdmit — hosted HPP в их среде (в пилоте demo 502); Apcopay — NotSupported в MVP |
отдельный этап roadmap |
| Выплаты | Выплаты мерчанта доступны (POST /v1/merchants/{id}/payouts, гайд Payouts; включаются Оператором). PSP-диспетч выплат — следующий этап |
Phase 2 |
| KYC | Не входит в MVP — средствами казино/партнёров | вне скоупа PA |
Welcome — you get sandbox API access, the Secure Fields SDK and signed webhooks. Integration in
6 steps: K1 mount the SDK iframe (onToken(vaultToken) → send straight to your backend);
K2 run a webhook receiver — verify PA-Webhook-Signature (v1=<hex HMAC-SHA256> over the
raw body), dedup by PA-Event-Id, reply 2xx fast; K3 exchange the vault token
(POST /v1/payment-instruments → pin_…) and create the payment (POST /v1/payments with
Idempotency-Key on the sandbox base URL from section 1); K4 follow
next_action.redirect (3DS / hosted page) — the final status arrives via webhook and/or
GET /v1/payments/{id}; K5 refunds via POST /v1/refunds (partial refunds supported,
PARTIALLY_REFUNDED → REFUNDED); K6 go-live — request the production URL and keys from the
Operator and pass the go-live checklist. Security: PAN/CVV never leave the SDK iframe; HMAC
verification and idempotency are mandatory; keep secrets out of git and logs.
Limits: production URL is live (https://payments.playpulse.tech) — production MID
at the PSP is pending with the PSP, production keys are issued separately from sandbox,
3DS limited (PayAdmit hosted HPP / Apcopay NotSupported in MVP), payouts = Phase 2, no KYC in MVP.
Details: onboarding checklist, English Part II.
redirect_hpp) / почему S2S raw card не предоставляется./docs (Redocly) и Swagger UI
/docs/swagger-ui на вашем base URL (раздел 1).4111 1111 1111 1111 (12/30, CVC 123), 5555 5555 5555 4444 (MC),
4000 0000 0000 0002 (3DS).Как казино может принимать карточные депозиты через PA, чем модели отличаются и что каждая значит для вашего PCI DSS scope. Ключи и шаги интеграции — Handover Package; детали SDK — SDK + Webhooks и SDK README.
Рекомендованная модель: iframe-виджет на странице депозита.
Как это работает:
<script src="https://<pa-origin>/pa-sdk/secure-fields.js"></script>
<div id="pa-card"></div>
<script>
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<pa-origin>/pa-sdk/secure-fields-frame.html',
captureUrl: '<выдаёт Оператор>',
publishableKey: 'pk_...', // публичный ключ мерчанта
onToken: (r) => {
// r.vaultToken — single-use vault token → сразу на СВОЙ backend
fetch('/my/api/deposit', { method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ vault_token: r.vaultToken, amount_cents: 1500 }) });
},
onError: (e) => showError(e.code, e.message),
});
</script>
Минимальный рабочий пример (включая локальный smoke) — SDK README.
PAN/CVV игрок вводит внутри iframe, размещённого на origin PA; значения полей недоступны JS казино. Данные карты уходят напрямую в capture-поверхность PA — мимо вашего backend.
Ваш backend получает только vault_token, обменивает его на
pin_…-инструмент (POST /v1/payment-instruments) и создаёт платёж
(POST /v1/payments).
PCI DSS следствие: казино ВНЕ PCI DSS scope. PAN/CVV ни на секунду не попадают в системы казино (ни в DOM, ни в backend, ни в логи) — ваша среда не хранит и не обрабатывает карточные данные, и самооценка по минимальной форме остаётся тривиальной. Это главный аргумент, почему SDK — рекомендованный путь.
Модель поддерживает и сохранённые карты: одна регистрация инструмента = один платёж в MVP (single-use), повторный депозит — новый vault token.
Redirect-модель «как у PayAdmit HPP»: игрок перенаправляется на хостед-страницу
оплаты на стороне PSP, вводит карту там, 3DS проходит на странице автоматически
и финал возвращается webhook'ом/статусом. Хостед-страница размещена у PSP —
своя страница PA не требуется. Провайдеры модели: PayAdmit (hosted
checkout), BTQ Finance (BTQ Checkout — готовая платёжная страница,
карточный сервис payment_card_<валюта>_hpp, валюта в нижнем регистре,
например payment_card_eur_hpp) и AVGentlements (avgent — та же
продуктовая линия, что PayAdmit; контракт —
[docs/integrations/avgent/hpp-flow.md] ;
подключение — после live-гейта, креды PSP ещё не выданы).
Как это работает:
{ "payment_method": { "type": "redirect" } }
(card и instrument_id в redirect-форме запрещены — 422 invalid_request;
поля платежа — Field Reference §2.3).
Ответ 201 несёт status: PENDING и next_action: {type: "redirect", redirect_url, method: "GET"} — вы переводите игрока по redirect_url
(хостед-страница PSP; возврат игрока — не результат, финал — webhook и/или
GET /v1/payments/{id}, шаг К5 чек-листа).
Роутинг: платёж исполняется только на Route Target с capability
redirect_hpp=true (PayAdmit hosted-checkout, BTQ Checkout, AVGentlements
HPP); если такого маршрута нет — 422 no_eligible_redirect_route ещё до
исполнения.
next_action используется и
для 3DS challenge, и для hosted page PSP (PayAdmit CARDSHPP, BTQ
Checkout, AVGentlements HPP), и создаётся платежом
payment_method.type=redirect.GET /v1/payments/{id} (шаг К5 чек-листа).
Тестовые карты BTQ — Field Reference §12.payment.authorized / payment.failed (подписанный) или
polling GET /v1/payments/{id}.Модель «полный server-to-server»: ваш backend принимает номер карты и CVV игрока и пересылает их в платёжный API.
Без сертификации такой путь не предоставляется. Причины — честно:
payment_method.card) закрыта двухуровневым fail-closed
гейтом и открывается оператором только для мерчанта с собственной
сертифицированной PCI DSS средой — см. модель (d) ниже.Статус: по запросу (включение — операторская процедура). Модель для казино, чей backend уже находится в полном PCI DSS scope (собственная сертифицированная среда, актуальный AoC) и принимает карту на своём собственном checkout'е: raw card отправляется напрямую в Payments API server-to-server, без SDK и payment page.
Провайдеры модели (d): BTQ Finance — включённый S2S-провайдер. Его флоу
показывает, как модель устроена изнутри: платформа создаёт у провайдера
платёжный инвойс, затем исполняет card-gate sale с картой игрока; провайдер
запускает 3DS-челлендж (redirect на банковскую страницу) или обрабатывает
операцию напрямую, и финальный статус платформа получает callback'ом
провайдера или статус-опросом (промежуточный PENDING — нормальное состояние,
см. Field Reference §12).
Как это работает:
POST /v1/payments — raw-card вариант блока
payment_method (поля — Field Reference §2): {
"payment_method": {
"type": "card",
"card": {
"card_number": "4500000000004454",
"card_exp_month": 12,
"card_exp_year": 2029,
"card_holder_name": "John Doe",
"card_cvc": "123"
}
}
}
card и instrument_id взаимоисключимы. Ресурс тот же: idempotency,
каскад, вебхуки, статусы — без нового контракта.
429 rate_limited + Retry-After) поверх обычного лимита
/v1/payments — тот же per-merchant бюджет расходуют и raw-card
выплаты: модель одна, поверхность одна.authentication_type и возвращается
существующим контрактом: next_action: {type: "redirect", redirect_url} — финал webhook'ом или GET /v1/payments/{id} (шаг К5
чек-листа). Подробности — ниже, «3DS в модели (d)».Включение — только оператором (Admin API), fail-closed по умолчанию:
per-merchant флаг merchants.h2h_enabled + deployment kill-switch
PA_H2H_ENABLED — оба по умолчанию false. Контрактное условие включения —
актуальный PCI DSS AoC мерчанта (Attestation of Compliance): факт включения
фиксируется аудит-событием с AoC-референсом; отключение — мгновенный rollback
(флаг, без технического окна).
PCI DSS следствие: полный scope казино — как и до интеграции. Для сертифицированного мерчанта модель не меняет его сертификационный status: PAN и так проходит в его среде. Ответственность за антифрод, chargeback и обработку PAN в своей среде — на мерчанте; PA — точка транзита без хранения.
По умолчанию raw-card платёж диспетчится в режиме no_three_ds — поведение, существующие запросы не меняются. 3DS включается на запрос:
{
"payment_method": { "type": "card", "card": { "…": "…" } },
"authentication_type": "three_ds"
}
Как это работает:
201 со статусом PENDING и
next_action: {type: "redirect", redirect_url} — вы переводите игрока на
банковскую 3DS-страницу; финал возвращается webhook'ом (payment. authorized/payment.failed) или polling'ом GET /v1/payments/{id}.session_context.browser.ip_address
(parseable IP). Без него запрос с three_ds отклоняется на PA (422 invalid_request, до диспетча): эквайер отклоняет операцию без
Client.IPAddress, и honest-поведение — fail-fast на
PA, а не зависшая попытка на стороне PSP.three_ds | no_three_ds; всё
другое → 422 invalid_request. Опция принадлежит raw-card форме: на
instrument_id- и redirect-формах она отклоняется (422 invalid_request).three_ds принимается и диспетчится,
эквайер запускает челлендж; проекция PENDING+redirect на живом коннекторе
Apcopay уточняется (актуальный статус модели — у Оператора; контракт
доказан автоматическими e2e-тестами).Для PCI DSS certified мерчанта выплата может идти на карту, переданную inline — без предварительной регистрации инструмента:
POST /v1/merchants/{id}/payouts
{
"receiver_card": {
"card_number": "4500000000004454",
"card_exp_month": 12,
"card_exp_year": 2029,
"card_holder_name": "John Doe"
},
"amount": 2500,
"currency": "EUR",
"customer_reference": "usr_123"
}
Правила формы:
receiver_card и instrument_id взаимоисключимы (оба → 422 invalid_request; ни одного — тоже 422).receiver_card поля CVC не имеет; прислать его нельзя — контракт
отвергнет неизвестное поле громко.PA_H2H_ENABLED +
merchants.h2h_enabled) — receiver-форма несёт PAN в среду PA, это та же
H2H-семантика («свой checkout мерчанта»); выключенный гейт → 422 h2h_not_enabled. Отдельно выплаты должны быть включены
(payouts_enabled).AWAITING_APPROVAL (операторский gate);
реальный диспетч в PSP — Phase 2, для receiver-выплаты
платёжно-системный вызов состоится после его реализации и одобрения
оператором.customer_reference на этой форме обязателен (нет инструмента, из
которого он обычно берётся).429 rate_limited).Базовый набор платёжных провайдеров (PSP) настраивает Оператор; мерчант
управляет его включением для себя на вкладке Integration → Платёжные
провайдеры портала (или GET/PUT /v1/merchants/{id}/providers — см. Field Reference §13):
выключенный провайдер перестаёт обслуживать НОВЫЕ платежи мерчанта,
уже начатые завершаются как обычно. Провайдеры каждой модели выше
(PayAdmit, BTQ Finance, Apcopay) появляются в этом списке после
операторского подключения.
| Модель | Статус | Кто видит PAN/CVV | PCI DSS scope казино |
|---|---|---|---|
| Secure Fields SDK (iframe) | доступна | iframe на origin PA | вне scope |
| Hosted payment page PSP (redirect) | доступна для PayAdmit и BTQ Finance (redirect_hpp) |
страница PSP (PA карту не видит) | вне scope |
| S2S raw card | не предоставляется без сертификации; certified — модель (d) | backend казино | SAQ D / A-EP — полный scope |
| H2H (модель (d)) | по запросу, для PCI DSS certified (AoC + операторский гейт) | backend казино (уже в scope) | полный scope — не меняется |
next_action;Рекомендованная модель: iframe-виджет на странице депозита.
Как это работает:
<script src="https://<pa-origin>/pa-sdk/secure-fields.js"></script>
<div id="pa-card"></div>
<script>
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<pa-origin>/pa-sdk/secure-fields-frame.html',
captureUrl: '<выдаёт Оператор>',
publishableKey: 'pk_...', // публичный ключ мерчанта
onToken: (r) => {
// r.vaultToken — single-use vault token → сразу на СВОЙ backend
fetch('/my/api/deposit', { method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ vault_token: r.vaultToken, amount_cents: 1500 }) });
},
onError: (e) => showError(e.code, e.message),
});
</script>
Минимальный рабочий пример (включая локальный smoke) — SDK README.
PAN/CVV игрок вводит внутри iframe, размещённого на origin PA; значения полей недоступны JS казино. Данные карты уходят напрямую в capture-поверхность PA — мимо вашего backend.
Ваш backend получает только vault_token, обменивает его на
pin_…-инструмент (POST /v1/payment-instruments) и создаёт платёж
(POST /v1/payments).
PCI DSS следствие: казино ВНЕ PCI DSS scope. PAN/CVV ни на секунду не попадают в системы казино (ни в DOM, ни в backend, ни в логи) — ваша среда не хранит и не обрабатывает карточные данные, и самооценка по минимальной форме остаётся тривиальной. Это главный аргумент, почему SDK — рекомендованный путь.
Модель поддерживает и сохранённые карты: одна регистрация инструмента = один платёж в MVP (single-use), повторный депозит — новый vault token.
Redirect-модель «как у PayAdmit HPP»: игрок перенаправляется на хостед-страницу
оплаты на стороне PSP, вводит карту там, 3DS проходит на странице автоматически
и финал возвращается webhook'ом/статусом. Хостед-страница размещена у PSP —
своя страница PA не требуется. Провайдеры модели: PayAdmit (hosted
checkout), BTQ Finance (BTQ Checkout — готовая платёжная страница,
карточный сервис payment_card_<валюта>_hpp, валюта в нижнем регистре,
например payment_card_eur_hpp) и AVGentlements (avgent — та же
продуктовая линия, что PayAdmit; контракт —
[docs/integrations/avgent/hpp-flow.md] ;
подключение — после live-гейта, креды PSP ещё не выданы).
Как это работает:
{ "payment_method": { "type": "redirect" } }
(card и instrument_id в redirect-форме запрещены — 422 invalid_request;
поля платежа — Field Reference §2.3).
Ответ 201 несёт status: PENDING и next_action: {type: "redirect", redirect_url, method: "GET"} — вы переводите игрока по redirect_url
(хостед-страница PSP; возврат игрока — не результат, финал — webhook и/или
GET /v1/payments/{id}, шаг К5 чек-листа).
Роутинг: платёж исполняется только на Route Target с capability
redirect_hpp=true (PayAdmit hosted-checkout, BTQ Checkout, AVGentlements
HPP); если такого маршрута нет — 422 no_eligible_redirect_route ещё до
исполнения.
next_action используется и
для 3DS challenge, и для hosted page PSP (PayAdmit CARDSHPP, BTQ
Checkout, AVGentlements HPP), и создаётся платежом
payment_method.type=redirect.GET /v1/payments/{id} (шаг К5 чек-листа).
Тестовые карты BTQ — Field Reference §12.payment.authorized / payment.failed (подписанный) или
polling GET /v1/payments/{id}.Модель «полный server-to-server»: ваш backend принимает номер карты и CVV игрока и пересылает их в платёжный API.
Без сертификации такой путь не предоставляется. Причины — честно:
payment_method.card) закрыта двухуровневым fail-closed
гейтом и открывается оператором только для мерчанта с собственной
сертифицированной PCI DSS средой — см. модель (d) ниже.Статус: по запросу (включение — операторская процедура). Модель для казино, чей backend уже находится в полном PCI DSS scope (собственная сертифицированная среда, актуальный AoC) и принимает карту на своём собственном checkout'е: raw card отправляется напрямую в Payments API server-to-server, без SDK и payment page.
Провайдеры модели (d): BTQ Finance — включённый S2S-провайдер. Его флоу
показывает, как модель устроена изнутри: платформа создаёт у провайдера
платёжный инвойс, затем исполняет card-gate sale с картой игрока; провайдер
запускает 3DS-челлендж (redirect на банковскую страницу) или обрабатывает
операцию напрямую, и финальный статус платформа получает callback'ом
провайдера или статус-опросом (промежуточный PENDING — нормальное состояние,
см. Field Reference §12).
Как это работает:
POST /v1/payments — raw-card вариант блока
payment_method (поля — Field Reference §2): {
"payment_method": {
"type": "card",
"card": {
"card_number": "4500000000004454",
"card_exp_month": 12,
"card_exp_year": 2029,
"card_holder_name": "John Doe",
"card_cvc": "123"
}
}
}
card и instrument_id взаимоисключимы. Ресурс тот же: idempotency,
каскад, вебхуки, статусы — без нового контракта.
429 rate_limited + Retry-After) поверх обычного лимита
/v1/payments — тот же per-merchant бюджет расходуют и raw-card
выплаты: модель одна, поверхность одна.authentication_type и возвращается
существующим контрактом: next_action: {type: "redirect", redirect_url} — финал webhook'ом или GET /v1/payments/{id} (шаг К5
чек-листа). Подробности — ниже, «3DS в модели (d)».Включение — только оператором (Admin API), fail-closed по умолчанию:
per-merchant флаг merchants.h2h_enabled + deployment kill-switch
PA_H2H_ENABLED — оба по умолчанию false. Контрактное условие включения —
актуальный PCI DSS AoC мерчанта (Attestation of Compliance): факт включения
фиксируется аудит-событием с AoC-референсом; отключение — мгновенный rollback
(флаг, без технического окна).
PCI DSS следствие: полный scope казино — как и до интеграции. Для сертифицированного мерчанта модель не меняет его сертификационный status: PAN и так проходит в его среде. Ответственность за антифрод, chargeback и обработку PAN в своей среде — на мерчанте; PA — точка транзита без хранения.
По умолчанию raw-card платёж диспетчится в режиме no_three_ds — поведение, существующие запросы не меняются. 3DS включается на запрос:
{
"payment_method": { "type": "card", "card": { "…": "…" } },
"authentication_type": "three_ds"
}
Как это работает:
201 со статусом PENDING и
next_action: {type: "redirect", redirect_url} — вы переводите игрока на
банковскую 3DS-страницу; финал возвращается webhook'ом (payment. authorized/payment.failed) или polling'ом GET /v1/payments/{id}.session_context.browser.ip_address
(parseable IP). Без него запрос с three_ds отклоняется на PA (422 invalid_request, до диспетча): эквайер отклоняет операцию без
Client.IPAddress, и honest-поведение — fail-fast на
PA, а не зависшая попытка на стороне PSP.three_ds | no_three_ds; всё
другое → 422 invalid_request. Опция принадлежит raw-card форме: на
instrument_id- и redirect-формах она отклоняется (422 invalid_request).three_ds принимается и диспетчится,
эквайер запускает челлендж; проекция PENDING+redirect на живом коннекторе
Apcopay уточняется (актуальный статус модели — у Оператора; контракт
доказан автоматическими e2e-тестами).Для PCI DSS certified мерчанта выплата может идти на карту, переданную inline — без предварительной регистрации инструмента:
POST /v1/merchants/{id}/payouts
{
"receiver_card": {
"card_number": "4500000000004454",
"card_exp_month": 12,
"card_exp_year": 2029,
"card_holder_name": "John Doe"
},
"amount": 2500,
"currency": "EUR",
"customer_reference": "usr_123"
}
Правила формы:
receiver_card и instrument_id взаимоисключимы (оба → 422 invalid_request; ни одного — тоже 422).receiver_card поля CVC не имеет; прислать его нельзя — контракт
отвергнет неизвестное поле громко.PA_H2H_ENABLED +
merchants.h2h_enabled) — receiver-форма несёт PAN в среду PA, это та же
H2H-семантика («свой checkout мерчанта»); выключенный гейт → 422 h2h_not_enabled. Отдельно выплаты должны быть включены
(payouts_enabled).AWAITING_APPROVAL (операторский gate);
реальный диспетч в PSP — Phase 2, для receiver-выплаты
платёжно-системный вызов состоится после его реализации и одобрения
оператором.customer_reference на этой форме обязателен (нет инструмента, из
которого он обычно берётся).429 rate_limited).Базовый набор платёжных провайдеров (PSP) настраивает Оператор; мерчант
управляет его включением для себя на вкладке Integration → Платёжные
провайдеры портала (или GET/PUT /v1/merchants/{id}/providers — см. Field Reference §13):
выключенный провайдер перестаёт обслуживать НОВЫЕ платежи мерчанта,
уже начатые завершаются как обычно. Провайдеры каждой модели выше
(PayAdmit, BTQ Finance, Apcopay) появляются в этом списке после
операторского подключения.
| Модель | Статус | Кто видит PAN/CVV | PCI DSS scope казино |
|---|---|---|---|
| Secure Fields SDK (iframe) | доступна | iframe на origin PA | вне scope |
| Hosted payment page PSP (redirect) | доступна для PayAdmit и BTQ Finance (redirect_hpp) |
страница PSP (PA карту не видит) | вне scope |
| S2S raw card | не предоставляется без сертификации; certified — модель (d) | backend казино | SAQ D / A-EP — полный scope |
| H2H (модель (d)) | по запросу, для PCI DSS certified (AoC + операторский гейт) | backend казино (уже в scope) | полный scope — не меняется |
next_action;Контракт токенизации карты и платёжных инструментов: Secure Fields SDK
(browser-capture через POST /v1/sdk/capture, publishable key — см. §4). Связанные гайды: Field Reference
(поля платежа), Integration models (модели интеграции
и PCI scope), SDK README (быстрый старт), Термінологія.
┌──────────────────────────── казино (frontend) ───────────────────────────┐
│ страница депозита │
│ └── PA Secure Fields SDK → <iframe sandbox> (origin PA) │
│ └── PAN/CVV: ввод и ОТПРАВКА НАПРЯМУЮ в capture-поверхность │
│ POST /v1/sdk/capture — МИНУЯ casino backend │
└───────────────┬──────────────────────────────────────────────────────────┘
│ TLS; PA — транзит (без записи PAN/CVV) → PSP vault
│ только single-use vault token (postMessage)
▼
casino backend ── POST /v1/payment-instruments {vault_token} ──▶ PA API
│ │
│ PA ── masked meta ─┘
│ (brand/last4 от vault)
└── POST /v1/payments {payment_instrument_id} ──▶ PA API
│
cascade engine │
casino backend ◀── подписанный webhook (HMAC-SHA256) ────┘
Инварианты (каждый из них проверен автоматическими e2e-тестами платформы):
****<last4>.tenant + merchant: cross-merchant переиспользование запрещено
(422 instrument_merchant_mismatch).(tenant_id, vault_token_ref)), инструмент потребляется первым платежом атомарно с
созданием платежа (одна транзакция: crash не может оставить «потраченный» инструмент без
платежа). Одноразовость — семантика ПЛАТЁЖА, не выплаты: выплата (payout)
использует инструмент как приёмник (receiver) и НЕ потребляет его — депозит потратил
pin_… (ACTIVE → USED), выплата по тому же pin_… валидна (payout-to-deposit-card,
см. Payouts guide).Аутентификация — та же, что для всех операций API: Authorization: Bearer <tenant_api_key>;
rate limiting применяется (route pattern /v1/payment-instruments).
Заголовок Idempotency-Key обязателен (контракт идемпотентности — pa-payments-api.md §3).
{
"merchant_id": "mer_...", // скоуп тенанта
"vault_token": "pm_...", // single-use vault token от capture-поверхности
"customer_reference": "usr_123" // опционально, игрок казино
}
Правила обработки: схема запроса не содержит карточных полей — PAN/CVV физически не могут быть приняты (неизвестные поля игнорируются парсером и не сохраняются). PA:
unknown_merchant);vault_retrieve_card несёт vault_token_fingerprint, не токен);PaymentInstrument (PA token pin_...) и аудит-событие регистрации
в одной транзакции (details: merchant_id, brand, exp_month/year, customer_reference,
vault_token_fingerprint — БЕЗ токена и карточных данных);customer_reference: опциональное поле — свободный текст, в котором
карточные данные могли бы попасть в записи PA, поэтому его форма ограничена (общий валидатор PA;
тот же применяется на /v1/payouts для customer_reference и в /v1/payments для
customer.reference_id): длина ≤ 255 символов; opaque-charset [A-Za-z0-9_.@-] (без пробелов,
/?# и прочей пунктуации); Luhn-валидная 13–19-значная последовательность (PAN-проба) отвергается.
PAN-проба применяется и к форматированным PAN: разделители [._@-] между группами
цифр снимаются, и Luhn-валидная 13–19-значная последовательность в «схлопнутом» значении
отвергается (форматированный PAN = PAN по PCI DSS; легитимные референсы с сепараторами —
INV-2024-001 — проходят). customer.reference_id в /v1/payments валидируется независимо от
JSON-типа: строка — как есть; JSON-число — в канонической десятичной записи тем же
валидатором (PAN цифрами как число → 422); null — отсутствие опционального поля; прочие
типы → 422 invalid_request (customer.reference_id must be a string).
Нарушение → 422 invalid_request; сообщение называет ограничение, но не эхоит значение.
Проверка выполняется ДО вызова vault и до создания idempotency-ключа.
Ответ 201 Created (masked view):
{
"instrument_id": "pin_...",
"merchant_id": "mer_...",
"status": "ACTIVE",
"card_meta": {"masked_pan": "****4242", "brand": "VISA", "exp_month": "08", "exp_year": "2028"},
"customer_reference": "usr_123",
"created_at": "2026-09-20T12:00:00Z"
}
Коды ошибок:
| Код | HTTP | Причина | Класс |
|---|---|---|---|
invalid_request |
400/422 | пустой/длинный (>255) vault_token, недопустимый charset (только [A-Za-z0-9_.:-] — без /?# и пробелов), кривой merchant_id; нарушения контракта customer_reference |
детерминированный |
idempotency_key_required |
400 | нет Idempotency-Key |
детерминированный |
idempotency_key_reuse |
422 | тот же ключ с другим телом | детерминированный |
idempotency_in_flight |
409 | оригинал ещё выполняется (Retry-After) |
— |
unknown_merchant |
422 | merchant не в тенанте | детерминированный |
vault_token_unknown |
422 | capture-поверхность не знает токен (потрачен/чужой) | детерминированный |
vault_unavailable |
502 | vault недоступен/отверг ключ/невалидный ответ (детали — только в логах PA) | транзиентный |
vault_token_already_registered |
409 | токен уже зарегистрирован другим инструментом | детерминированный |
Идемпотентность классов: детерминированные коды сохраняются в
idempotency-записи и реплеятся тем же ключом (повтор возвращает сохранённый результат). Транзиентный
vault_unavailable НЕ сохраняется: claim ключа освобождается, и повтор тем же ключом начинает
новую попытку доставки (новый вызов vault → возможен 201), а не реплей запиненной 502 на TTL.
Тот же проекция, что в 201; статус отражает жизненный цикл (ACTIVE/USED/DEACTIVATED).
Чужой/несуществующий id — одинаковый 404 instrument_not_found (без утечки существования).
vault_token_ref в проекции отсутствует на уровне структуры (unit-тест фиксирует отсутствие
поля в сериализации).
POST /v1/payments принимает payment_method.instrument_id (= pin_...):
{
"merchant_id": "mer_...",
"amount": 1500,
"currency": "EUR",
"payment_method": {"type": "card", "instrument_id": "pin_..."},
"capture_method": "automatic"
}
Валидация (до создания Payment, в транзакции idempotency-ключа):
| Код | HTTP | Причина |
|---|---|---|
unknown_instrument |
422 | нет такого pin_ в тенанте |
instrument_merchant_mismatch |
422 | инструмент другого merchant'а тенанта |
instrument_not_active |
422 | уже использован (USED) или деактивирован |
При успехе: инструмент атомарно переводится ACTIVE → USED той же транзакцией, что создаёт
Payment (single-use), instrument_id фиксируется на Payment/Attempt-журнале; дальше —
обычный cascade.
Endpoint webhook'а регистрирует Оператор (по HTTPS в production) и передаёт казино
webhook_secret (whs_...) — ровно один раз, по защищённому каналу. Казино само
endpoint не регистрирует; URL можно поменять позже через портал (Profile — HTTPS-only).
Доставка: когда платёж этого merchant'а достигает финального статуса, PA
записывает одно событие в транзакционный outbox webhook_deliveries — В ТОЙ ЖЕ
транзакции, что и доменное изменение статуса (паттерн audit-трейла событие не
существует без статуса, статус не коммитится без события). Доставку выполняет асинхронный
worker (crate::webhook_worker): poll PENDING с наступившим next_retry_at → POST
сохранённого payload'а → DELIVERED (2xx) | retry: attempts++,
next_retry_at = now + backoff (лестница 1м/5м/30м/2h) → после 5 неудачных попыток DEAD
(dead-letter, больше не доставляется). Запрос create_payment больше НЕ блокируется
доставкой и не может «упасть» из-за получателя:
{
"event_id": "0197...", // UUIDv7 — ключ дедупликации
"event_type": "payment.authorized",
"created_at": "2026-09-20T12:00:01Z",
"data": {
"payment_id": "pay_...", "merchant_id": "mer_...", "status": "AUTHORIZED",
"amount": 1500, "currency": "EUR", "instrument_id": "pin_...",
"correlation_id": "...", "attempts_summary": [...]
}
}
Заголовки: PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, webhook_secret))>,
PA-Event-Id: <event_id>. Типы: payment.authorized, payment.captured, payment.refunded,
payment.failed (а также async-переходы sync worker'а: UNKNOWN → AUTHORIZED|FAILED —
ARC-PA6-11) и — с события выплат: payout.approved, payout.completed,
payout.declined, payout.cancelled. PENDING/UNKNOWN_PENDING_SYNC не доставляются; для выплат так же молчат AWAITING_APPROVAL (синхронный ответ
создания/решения несёт этот факт), PROCESSING («PSP принял запрос» — НЕ финансовая
финальность, Correction #2) и FAILED_TECHNICAL/UNKNOWN_PENDING_SYNC
(sync-first эскалация, не казино-webhook). Свойства доставки (PG-7):
event_id); каждая
попытка (в т.ч. retry) переотправляет ТЕ ЖЕ байты payload'а → одна и та же подпись
(при неизменном секрете); получатель дедуплицирует по event_id;(payment_id, event_type, data.status) (миграция 0018) и —
UNIQUE (payout_id, event_type, data.status) (миграция 0031; каждая строка outbox
принадлежит ровно одному агрегату: payment_id XOR payout_id). Повторная
эмиссия того же факта (повторный sync-тик, неудачный refund, не изменивший
статус платежа, дублирующая запись состояния) под НОВЫМ event_id — no-op:
казино видит каждый терминальный факт РОВНО ОДИН РАЗ, дедуп получателя по
PA-Event-Id не обязан ловить новые id. Разные переходы одного платежа
(AUTHORIZED → PARTIALLY_REFUNDED → REFUNDED) несут свои события;
retry-доставки не затронуты (at-least-once по event_id сохраняется);POST /v1/merchants/{id}/webhooks/deliveries/{delivery_id}/resend, тело
{"url": "https://…"}). Это НЕ смена webhook-адреса мерчанта: адрес хранится
в target_url НОВОЙ строки outbox (resend_of = исходная), а
merchants.webhook_url не меняется — воркер отправки берёт
COALESCE(target_url, merchants.webhook_url). Payload переотправляется тот же
(факты платежа/выплаты без изменений), подпись — тем же секретом мерчанта, ретраи/dead-letter — обычная лестница, attempts
исходной строки не растёт. Получатель видит НОВЫЙ event_id
(<исходный>:resend:<uuid>): переотправка под старым id была бы проглочена
дедупом PA-Event-Id — ради «доставить ещё раз» она и делается. Переходный
guard (UNIQUE (payment_id|payout_id, event_type, data.status)) на
такие строки не распространяется (resend_of IS NULL, миграция 0050): это не
эмиссия нового факта, а явное действие оператора;webhook_secret берётся из конфигурации merchant'а в
момент доставки;status=DEAD,
last_error хранит класс последней ошибки (status:<HTTP-код>/timeout/connect);/portal, вкладка «Events and Logs») и через
GET /v1/merchants/{id}/webhooks/deliveries?payment_id=pay_... /
GET /v1/webhooks/deliveries?payout_id=po_... (; ровно один из двух
параметров — иначе 400 invalid_request): статус, attempts,
last_error, created_at, delivered_at по каждому событию. добавил
пагинацию (limit ≤ 200, default 25, offset), фильтры
status/event_type/since/until и total по фильтру; строка ручной
переотправки несёт target_url (маскированный: схема+хост+путь, query →
?***) и resend_of.Ошибка доставки НЕ влияет на результат платежа (только лог без тела события).
Тот же конверт и те же заголовки, что у платёжных событий; data несёт факты выплаты
(приёмник — только маскированные метаданные или pin_...-ссылка инструмента, PAN/CVV
в payout-контуре не существуют по построению):
{
"event_id": "0197...",
"event_type": "payout.approved",
"created_at": "2026-10-18T12:00:01Z",
"data": {
"payout_id": "po_...", "merchant_id": "mer_...", "status": "APPROVED",
"amount": 1000, "currency": "EUR", "customer_reference": "player-1",
"instrument_id": "pin_...", "correlation_id": "...",
"attempts_summary": [...]
}
}
Опциональные поля data (появляются только когда применимы): reason — причина
decline/cancel, записанная на гейте; receiver — маскированный снимок приёмника
raw-card-выплаты; retry_of_payout_id — исходная выплата
retry-цепочки. Типы событий: payout.approved — решение гейта
зафиксировано (в т.ч. авто-аппрув-политиками — событие эмиссится в той же транзакции
создания); payout.completed — провайдер-подтверждённая финансовая финальность
(Phase 2); payout.declined / payout.cancelled — терминальное неисполнение.
POST /v1/merchants/{id}/rotate-webhook-secret — ротация подписывающего секрета без
остановки доставки. Тело не требуется (секрет генерирует PA).
whs_...) генерируется сервер-сайд и возвращается ровно один раз
(webhook_secret), как при регистрации; он становится активным немедленно — все
доставки подписываются уже НОВЫМ секретом (delivery_after_rotation инвариант
worker'а: секрет берётся из конфигурации merchant'а в момент доставки).merchants.webhook_secret_prev +
webhook_secret_rotated_at (миграция 0013). В течение grace-окна
(PA_WEBHOOK_SECRET_GRACE_DAYS, по умолчанию 7 дней; окно отсчитывается от
webhook_secret_rotated_at) получатель принимает оба секрета (dual-verify) —
схема rollout'а на стороне казино: обновить верификацию → ротация → убедиться, что
старые проверки больше не приходят.{merchant_id, webhook_url, webhook_secret, old_secret_expires_at, rotated_at};
old_secret_expires_at = rotated_at + grace — момент, после которого старый секрет
обязан отвергаться. Эталонная реализация dual-verify —
pa_api::webhook::verify_event_signature(secret, secret_prev, rotated_at, grace, body, header, now):
активный секрет валиден всегда, предыдущий — только пока now <= rotated_at + grace.POST /v1/merchants/{id}/webhook) сдвигает секрет
по тому же инварианту (предыдущий → grace-слот); вторая ротация выталкивает
предыдущий-предыдущий секрет из окна — в grace живёт ровно один секрет.rotate_webhook_secret в той же транзакции, что и изменение; details
содержат webhook_url, rotated_at, grace_days — секреты в details и логах не
пишутся никогда.404 merchant_not_found (чужой/неизвестный мерчант — tenant-scoping),
409 webhook_not_registered (нет зарегистрированного endpoint'а — сначала
POST /v1/merchants/{id}/webhook), 401 без Bearer-ключа.Drop-in, без сборки: pa-sdk/secure-fields.js + pa-sdk/secure-fields-frame.html.
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<host>/secure-fields-frame.html', // казино хостит статику
captureUrl: 'https://<pa-origin>/v1/sdk/capture', // реальный capture
publishableKey: 'pk_<merchant-uuid>_<digest>', // PUBLIC, из онбординга мерчанта
onToken: (r) => { /* r.vaultToken, r.brand, r.last4 */ },
onError: (e) => { /* e.code, e.message */ },
onReady: () => {},
});
fields.destroy(); fields.isReady(); fields.token();
Контракт безопасности:
sandbox="allow-scripts allow-forms" (БЕЗ allow-same-origin) —
фрейм имеет opaque origin, не имеет доступа к DOM/storage родителя, родитель не читает
DOM фрейма: casino JS не имеет DOM-доступа к значениям полей (security invariant —
см. §1 «PCI boundary»).pa-secure-fields;
токен валидируется по форме до вызова onToken.captureUrl (fetch, X-Publishable-Key +
flat-JSON card_number/cvc/expiry_month/expiry_year/card_holder_name) — единственный
сетевой вызов с карточными данными; в demo-режиме (captureUrl: 'demo') токен mintится
внутри фрейма без сети (PAN остаётся и умирает в iframe; publishable key не нужен).[A-Za-z0-9_-]{8,255}
(dev-схема vtok_<brand>_<last4>-<uuid>, capture-поверхность — pm_...).invalid_publishable_key, origin_not_allowed,
invalid_card, rate_limited, capture_unavailable — полный реестр кодов
в справочнике /docs (раздел «Errors»).onToken возвращает vaultToken — его казино-backend отправляет в
POST /v1/payment-instruments (§2.1). Схема интеграции казино (backend + frontend) —
pa-sdk/README.md.
| Режим | captureUrl |
Что происходит |
|---|---|---|
demo |
demo |
Тестовый double: токен vtok_... mintится в iframe локально (CI/E2E/demo без стенда). Никакой передачи карточных данных. |
| Продакшн (capture через PA) | https://<pa-origin>/v1/sdk/capture |
iframe шлёт PAN/CVV напрямую на capture-endpoint PA → PA токенизирует карту в vault и возвращает vault_token + маскированные метаданные; PA — только транзит: без записи PAN/CVV в БД/логи/аудит. Auth: publishable key мерчанта (X-Publishable-Key, PUBLIC — не секрет); жёсткий per-key rate limit + per-IP окно; HTTPS-only на публичных адресах в production (fail-fast). |
| Прямой vault (post-MVP) | hosted fields провайдера | PAN/CVV уходят напрямую в hosted fields PSP-хранилища → card_reference. Требует отдельной browser-JWE capture-страницы. |
Publishable key (pk_...): derived, без хранения (детерминированный — повторная
выдача даёт то же значение). Не секрет: привязывает capture к мерчанту (и к его
rate-limit-бюджету), прав не даёт — деньги двигает только tenant Bearer.
Конфигурация развёртывания capture-поверхности и webhook-воркера — на стороне
Оператора: для интеграции казино важны только captureUrl и publishable key (§3).
USED) pin_… остаётся валидным получателем выплаты (payout-to-deposit-card —
Payouts guide).single_use=false), provider tokens, verify/deactivate
endpoints и расширенный жизненный цикл — следующие этапы roadmap.┌──────────────────────────── казино (frontend) ───────────────────────────┐
│ страница депозита │
│ └── PA Secure Fields SDK → <iframe sandbox> (origin PA) │
│ └── PAN/CVV: ввод и ОТПРАВКА НАПРЯМУЮ в capture-поверхность │
│ POST /v1/sdk/capture — МИНУЯ casino backend │
└───────────────┬──────────────────────────────────────────────────────────┘
│ TLS; PA — транзит (без записи PAN/CVV) → PSP vault
│ только single-use vault token (postMessage)
▼
casino backend ── POST /v1/payment-instruments {vault_token} ──▶ PA API
│ │
│ PA ── masked meta ─┘
│ (brand/last4 от vault)
└── POST /v1/payments {payment_instrument_id} ──▶ PA API
│
cascade engine │
casino backend ◀── подписанный webhook (HMAC-SHA256) ────┘
Инварианты (каждый из них проверен автоматическими e2e-тестами платформы):
****<last4>.tenant + merchant: cross-merchant переиспользование запрещено
(422 instrument_merchant_mismatch).(tenant_id, vault_token_ref)), инструмент потребляется первым платежом атомарно с
созданием платежа (одна транзакция: crash не может оставить «потраченный» инструмент без
платежа). Одноразовость — семантика ПЛАТЁЖА, не выплаты: выплата (payout)
использует инструмент как приёмник (receiver) и НЕ потребляет его — депозит потратил
pin_… (ACTIVE → USED), выплата по тому же pin_… валидна (payout-to-deposit-card,
см. Payouts guide).Аутентификация — та же, что для всех операций API: Authorization: Bearer <tenant_api_key>;
rate limiting применяется (route pattern /v1/payment-instruments).
Заголовок Idempotency-Key обязателен (контракт идемпотентности — pa-payments-api.md §3).
{
"merchant_id": "mer_...", // скоуп тенанта
"vault_token": "pm_...", // single-use vault token от capture-поверхности
"customer_reference": "usr_123" // опционально, игрок казино
}
Правила обработки: схема запроса не содержит карточных полей — PAN/CVV физически не могут быть приняты (неизвестные поля игнорируются парсером и не сохраняются). PA:
unknown_merchant);vault_retrieve_card несёт vault_token_fingerprint, не токен);PaymentInstrument (PA token pin_...) и аудит-событие регистрации
в одной транзакции (details: merchant_id, brand, exp_month/year, customer_reference,
vault_token_fingerprint — БЕЗ токена и карточных данных);customer_reference: опциональное поле — свободный текст, в котором
карточные данные могли бы попасть в записи PA, поэтому его форма ограничена (общий валидатор PA;
тот же применяется на /v1/payouts для customer_reference и в /v1/payments для
customer.reference_id): длина ≤ 255 символов; opaque-charset [A-Za-z0-9_.@-] (без пробелов,
/?# и прочей пунктуации); Luhn-валидная 13–19-значная последовательность (PAN-проба) отвергается.
PAN-проба применяется и к форматированным PAN: разделители [._@-] между группами
цифр снимаются, и Luhn-валидная 13–19-значная последовательность в «схлопнутом» значении
отвергается (форматированный PAN = PAN по PCI DSS; легитимные референсы с сепараторами —
INV-2024-001 — проходят). customer.reference_id в /v1/payments валидируется независимо от
JSON-типа: строка — как есть; JSON-число — в канонической десятичной записи тем же
валидатором (PAN цифрами как число → 422); null — отсутствие опционального поля; прочие
типы → 422 invalid_request (customer.reference_id must be a string).
Нарушение → 422 invalid_request; сообщение называет ограничение, но не эхоит значение.
Проверка выполняется ДО вызова vault и до создания idempotency-ключа.
Ответ 201 Created (masked view):
{
"instrument_id": "pin_...",
"merchant_id": "mer_...",
"status": "ACTIVE",
"card_meta": {"masked_pan": "****4242", "brand": "VISA", "exp_month": "08", "exp_year": "2028"},
"customer_reference": "usr_123",
"created_at": "2026-09-20T12:00:00Z"
}
Коды ошибок:
| Код | HTTP | Причина | Класс |
|---|---|---|---|
invalid_request |
400/422 | пустой/длинный (>255) vault_token, недопустимый charset (только [A-Za-z0-9_.:-] — без /?# и пробелов), кривой merchant_id; нарушения контракта customer_reference |
детерминированный |
idempotency_key_required |
400 | нет Idempotency-Key |
детерминированный |
idempotency_key_reuse |
422 | тот же ключ с другим телом | детерминированный |
idempotency_in_flight |
409 | оригинал ещё выполняется (Retry-After) |
— |
unknown_merchant |
422 | merchant не в тенанте | детерминированный |
vault_token_unknown |
422 | capture-поверхность не знает токен (потрачен/чужой) | детерминированный |
vault_unavailable |
502 | vault недоступен/отверг ключ/невалидный ответ (детали — только в логах PA) | транзиентный |
vault_token_already_registered |
409 | токен уже зарегистрирован другим инструментом | детерминированный |
Идемпотентность классов: детерминированные коды сохраняются в
idempotency-записи и реплеятся тем же ключом (повтор возвращает сохранённый результат). Транзиентный
vault_unavailable НЕ сохраняется: claim ключа освобождается, и повтор тем же ключом начинает
новую попытку доставки (новый вызов vault → возможен 201), а не реплей запиненной 502 на TTL.
Тот же проекция, что в 201; статус отражает жизненный цикл (ACTIVE/USED/DEACTIVATED).
Чужой/несуществующий id — одинаковый 404 instrument_not_found (без утечки существования).
vault_token_ref в проекции отсутствует на уровне структуры (unit-тест фиксирует отсутствие
поля в сериализации).
POST /v1/payments принимает payment_method.instrument_id (= pin_...):
{
"merchant_id": "mer_...",
"amount": 1500,
"currency": "EUR",
"payment_method": {"type": "card", "instrument_id": "pin_..."},
"capture_method": "automatic"
}
Валидация (до создания Payment, в транзакции idempotency-ключа):
| Код | HTTP | Причина |
|---|---|---|
unknown_instrument |
422 | нет такого pin_ в тенанте |
instrument_merchant_mismatch |
422 | инструмент другого merchant'а тенанта |
instrument_not_active |
422 | уже использован (USED) или деактивирован |
При успехе: инструмент атомарно переводится ACTIVE → USED той же транзакцией, что создаёт
Payment (single-use), instrument_id фиксируется на Payment/Attempt-журнале; дальше —
обычный cascade.
Endpoint webhook'а регистрирует Оператор (по HTTPS в production) и передаёт казино
webhook_secret (whs_...) — ровно один раз, по защищённому каналу. Казино само
endpoint не регистрирует; URL можно поменять позже через портал (Profile — HTTPS-only).
Доставка: когда платёж этого merchant'а достигает финального статуса, PA
записывает одно событие в транзакционный outbox webhook_deliveries — В ТОЙ ЖЕ
транзакции, что и доменное изменение статуса (паттерн audit-трейла событие не
существует без статуса, статус не коммитится без события). Доставку выполняет асинхронный
worker (crate::webhook_worker): poll PENDING с наступившим next_retry_at → POST
сохранённого payload'а → DELIVERED (2xx) | retry: attempts++,
next_retry_at = now + backoff (лестница 1м/5м/30м/2h) → после 5 неудачных попыток DEAD
(dead-letter, больше не доставляется). Запрос create_payment больше НЕ блокируется
доставкой и не может «упасть» из-за получателя:
{
"event_id": "0197...", // UUIDv7 — ключ дедупликации
"event_type": "payment.authorized",
"created_at": "2026-09-20T12:00:01Z",
"data": {
"payment_id": "pay_...", "merchant_id": "mer_...", "status": "AUTHORIZED",
"amount": 1500, "currency": "EUR", "instrument_id": "pin_...",
"correlation_id": "...", "attempts_summary": [...]
}
}
Заголовки: PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, webhook_secret))>,
PA-Event-Id: <event_id>. Типы: payment.authorized, payment.captured, payment.refunded,
payment.failed (а также async-переходы sync worker'а: UNKNOWN → AUTHORIZED|FAILED —
ARC-PA6-11) и — с события выплат: payout.approved, payout.completed,
payout.declined, payout.cancelled. PENDING/UNKNOWN_PENDING_SYNC не доставляются; для выплат так же молчат AWAITING_APPROVAL (синхронный ответ
создания/решения несёт этот факт), PROCESSING («PSP принял запрос» — НЕ финансовая
финальность, Correction #2) и FAILED_TECHNICAL/UNKNOWN_PENDING_SYNC
(sync-first эскалация, не казино-webhook). Свойства доставки (PG-7):
event_id); каждая
попытка (в т.ч. retry) переотправляет ТЕ ЖЕ байты payload'а → одна и та же подпись
(при неизменном секрете); получатель дедуплицирует по event_id;(payment_id, event_type, data.status) (миграция 0018) и —
UNIQUE (payout_id, event_type, data.status) (миграция 0031; каждая строка outbox
принадлежит ровно одному агрегату: payment_id XOR payout_id). Повторная
эмиссия того же факта (повторный sync-тик, неудачный refund, не изменивший
статус платежа, дублирующая запись состояния) под НОВЫМ event_id — no-op:
казино видит каждый терминальный факт РОВНО ОДИН РАЗ, дедуп получателя по
PA-Event-Id не обязан ловить новые id. Разные переходы одного платежа
(AUTHORIZED → PARTIALLY_REFUNDED → REFUNDED) несут свои события;
retry-доставки не затронуты (at-least-once по event_id сохраняется);POST /v1/merchants/{id}/webhooks/deliveries/{delivery_id}/resend, тело
{"url": "https://…"}). Это НЕ смена webhook-адреса мерчанта: адрес хранится
в target_url НОВОЙ строки outbox (resend_of = исходная), а
merchants.webhook_url не меняется — воркер отправки берёт
COALESCE(target_url, merchants.webhook_url). Payload переотправляется тот же
(факты платежа/выплаты без изменений), подпись — тем же секретом мерчанта, ретраи/dead-letter — обычная лестница, attempts
исходной строки не растёт. Получатель видит НОВЫЙ event_id
(<исходный>:resend:<uuid>): переотправка под старым id была бы проглочена
дедупом PA-Event-Id — ради «доставить ещё раз» она и делается. Переходный
guard (UNIQUE (payment_id|payout_id, event_type, data.status)) на
такие строки не распространяется (resend_of IS NULL, миграция 0050): это не
эмиссия нового факта, а явное действие оператора;webhook_secret берётся из конфигурации merchant'а в
момент доставки;status=DEAD,
last_error хранит класс последней ошибки (status:<HTTP-код>/timeout/connect);/portal, вкладка «Events and Logs») и через
GET /v1/merchants/{id}/webhooks/deliveries?payment_id=pay_... /
GET /v1/webhooks/deliveries?payout_id=po_... (; ровно один из двух
параметров — иначе 400 invalid_request): статус, attempts,
last_error, created_at, delivered_at по каждому событию. добавил
пагинацию (limit ≤ 200, default 25, offset), фильтры
status/event_type/since/until и total по фильтру; строка ручной
переотправки несёт target_url (маскированный: схема+хост+путь, query →
?***) и resend_of.Ошибка доставки НЕ влияет на результат платежа (только лог без тела события).
Тот же конверт и те же заголовки, что у платёжных событий; data несёт факты выплаты
(приёмник — только маскированные метаданные или pin_...-ссылка инструмента, PAN/CVV
в payout-контуре не существуют по построению):
{
"event_id": "0197...",
"event_type": "payout.approved",
"created_at": "2026-10-18T12:00:01Z",
"data": {
"payout_id": "po_...", "merchant_id": "mer_...", "status": "APPROVED",
"amount": 1000, "currency": "EUR", "customer_reference": "player-1",
"instrument_id": "pin_...", "correlation_id": "...",
"attempts_summary": [...]
}
}
Опциональные поля data (появляются только когда применимы): reason — причина
decline/cancel, записанная на гейте; receiver — маскированный снимок приёмника
raw-card-выплаты; retry_of_payout_id — исходная выплата
retry-цепочки. Типы событий: payout.approved — решение гейта
зафиксировано (в т.ч. авто-аппрув-политиками — событие эмиссится в той же транзакции
создания); payout.completed — провайдер-подтверждённая финансовая финальность
(Phase 2); payout.declined / payout.cancelled — терминальное неисполнение.
POST /v1/merchants/{id}/rotate-webhook-secret — ротация подписывающего секрета без
остановки доставки. Тело не требуется (секрет генерирует PA).
whs_...) генерируется сервер-сайд и возвращается ровно один раз
(webhook_secret), как при регистрации; он становится активным немедленно — все
доставки подписываются уже НОВЫМ секретом (delivery_after_rotation инвариант
worker'а: секрет берётся из конфигурации merchant'а в момент доставки).merchants.webhook_secret_prev +
webhook_secret_rotated_at (миграция 0013). В течение grace-окна
(PA_WEBHOOK_SECRET_GRACE_DAYS, по умолчанию 7 дней; окно отсчитывается от
webhook_secret_rotated_at) получатель принимает оба секрета (dual-verify) —
схема rollout'а на стороне казино: обновить верификацию → ротация → убедиться, что
старые проверки больше не приходят.{merchant_id, webhook_url, webhook_secret, old_secret_expires_at, rotated_at};
old_secret_expires_at = rotated_at + grace — момент, после которого старый секрет
обязан отвергаться. Эталонная реализация dual-verify —
pa_api::webhook::verify_event_signature(secret, secret_prev, rotated_at, grace, body, header, now):
активный секрет валиден всегда, предыдущий — только пока now <= rotated_at + grace.POST /v1/merchants/{id}/webhook) сдвигает секрет
по тому же инварианту (предыдущий → grace-слот); вторая ротация выталкивает
предыдущий-предыдущий секрет из окна — в grace живёт ровно один секрет.rotate_webhook_secret в той же транзакции, что и изменение; details
содержат webhook_url, rotated_at, grace_days — секреты в details и логах не
пишутся никогда.404 merchant_not_found (чужой/неизвестный мерчант — tenant-scoping),
409 webhook_not_registered (нет зарегистрированного endpoint'а — сначала
POST /v1/merchants/{id}/webhook), 401 без Bearer-ключа.Drop-in, без сборки: pa-sdk/secure-fields.js + pa-sdk/secure-fields-frame.html.
const fields = PASecureFields.mount({
container: '#pa-card',
frameUrl: 'https://<host>/secure-fields-frame.html', // казино хостит статику
captureUrl: 'https://<pa-origin>/v1/sdk/capture', // реальный capture
publishableKey: 'pk_<merchant-uuid>_<digest>', // PUBLIC, из онбординга мерчанта
onToken: (r) => { /* r.vaultToken, r.brand, r.last4 */ },
onError: (e) => { /* e.code, e.message */ },
onReady: () => {},
});
fields.destroy(); fields.isReady(); fields.token();
Контракт безопасности:
sandbox="allow-scripts allow-forms" (БЕЗ allow-same-origin) —
фрейм имеет opaque origin, не имеет доступа к DOM/storage родителя, родитель не читает
DOM фрейма: casino JS не имеет DOM-доступа к значениям полей (security invariant —
см. §1 «PCI boundary»).pa-secure-fields;
токен валидируется по форме до вызова onToken.captureUrl (fetch, X-Publishable-Key +
flat-JSON card_number/cvc/expiry_month/expiry_year/card_holder_name) — единственный
сетевой вызов с карточными данными; в demo-режиме (captureUrl: 'demo') токен mintится
внутри фрейма без сети (PAN остаётся и умирает в iframe; publishable key не нужен).[A-Za-z0-9_-]{8,255}
(dev-схема vtok_<brand>_<last4>-<uuid>, capture-поверхность — pm_...).invalid_publishable_key, origin_not_allowed,
invalid_card, rate_limited, capture_unavailable — полный реестр кодов
в справочнике /docs (раздел «Errors»).onToken возвращает vaultToken — его казино-backend отправляет в
POST /v1/payment-instruments (§2.1). Схема интеграции казино (backend + frontend) —
pa-sdk/README.md.
| Режим | captureUrl |
Что происходит |
|---|---|---|
demo |
demo |
Тестовый double: токен vtok_... mintится в iframe локально (CI/E2E/demo без стенда). Никакой передачи карточных данных. |
| Продакшн (capture через PA) | https://<pa-origin>/v1/sdk/capture |
iframe шлёт PAN/CVV напрямую на capture-endpoint PA → PA токенизирует карту в vault и возвращает vault_token + маскированные метаданные; PA — только транзит: без записи PAN/CVV в БД/логи/аудит. Auth: publishable key мерчанта (X-Publishable-Key, PUBLIC — не секрет); жёсткий per-key rate limit + per-IP окно; HTTPS-only на публичных адресах в production (fail-fast). |
| Прямой vault (post-MVP) | hosted fields провайдера | PAN/CVV уходят напрямую в hosted fields PSP-хранилища → card_reference. Требует отдельной browser-JWE capture-страницы. |
Publishable key (pk_...): derived, без хранения (детерминированный — повторная
выдача даёт то же значение). Не секрет: привязывает capture к мерчанту (и к его
rate-limit-бюджету), прав не даёт — деньги двигает только tenant Bearer.
Конфигурация развёртывания capture-поверхности и webhook-воркера — на стороне
Оператора: для интеграции казино важны только captureUrl и publishable key (§3).
USED) pin_… остаётся валидным получателем выплаты (payout-to-deposit-card —
Payouts guide).single_use=false), provider tokens, verify/deactivate
endpoints и расширенный жизненный цикл — следующие этапы roadmap.Справочник полей создания платежа (POST /v1/payments) для казино-разработчика:
типы, обязательность, ограничения и коды ошибок,
которые платформа отвечает на нарушение каждого правила. Дополнение к гайду
SDK + Webhooks (токенизация → инструмент → платёж), к
Handover Package (ключи и 6 шагов интеграции) и к
чек-листу онбординга. Машиночитаемый контракт —
openapi.json (GET /docs/openapi.json), RU-описание ресурса —
payments-api.md. Модели интеграции (SDK / hosted page /
H2H raw card) — Integration models.
Пример запроса целиком:
{
"merchant_id": "mer_...",
"amount": 1050,
"currency": "EUR",
"payment_method": { "type": "card", "instrument_id": "pin_..." },
"capture_method": "automatic",
"customer": {
"reference_id": "usr_123",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "35712345678"
},
"billing_address": {
"address_line1": "211 Victory st",
"city": "Limassol",
"postal_code": "3011",
"country_code": "CY"
},
"session_context": {
"browser": { "user_agent": "Mozilla/5.0 ...", "time_zone": -120 }
},
"metadata": { "order_reference": "ord-2026-000123" }
}
```--
## 1. Корневые поля
| Поле | Тип | Обязательность | Назначение и ограничения |
|---|---|---|---|
| `merchant_id` | string | да | Ваш мерчант (`mer_…`) в тенанте. Чужой/неизвестный — `422 unknown_merchant` |
| `amount` | integer | да | Положительное число в minor units (центы). `≤ 0` → `422 invalid_request` |
| `currency` | string | да | ISO 4217 alpha-3 (`EUR`, `USD`, …). Валюта участвует в eligibility: ни один Route Target не поддерживает валюту → `422 no_eligible_route` |
| `payment_method` | object | нет¹ | Выбор способа платежа — см. §2. Без `payment_method` платёж создаётся (201), но исполнение не состоится: диспатч коннектора требует `instrument_id` и попытка завершится `FAILED_TECHNICAL` |
| `capture_method` | string | нет (`automatic` по умолчанию) | `automatic` \| `manual` — см. §3 |
| `customer` | object | нет | Данные игрока для PSP — см. §4. Должен быть JSON-объектом (или `null`/отсутствовать); строка/число/массив → `422 invalid_request` |
| `billing_address` | object | нет² | Биллинг-адрес для PSP и роутинга — см. §5 |
| `risk_context` | object | нет | Свободная форма (KYC-флаги, статистика депозитов). Сохраняется; на MVP-роутинг не влияет — см. §6 |
| `session_context` | object | нет | Сессия игрока; блок `browser` проецируется в PSP — см. §6 |
| `metadata` | object | нет | Свободная форма (`additionalProperties: true`); соглашение `metadata.order_reference` — см. §7 |
| `customer_ip` | string | нет | IP плательщика для S2S-диспатча (`browser_info.ip_address`). IPv4/IPv6; пустое значение игнорируется, некорректное → `422 invalid_request`. Приоритет определения IP: `session_context.browser.ip_address` → `customer.ip_address`/`customer.ip` → `customer_ip` → peer-IP сокета (за доверенным прокси). В idempotency-хеш НЕ входит |
| `segment` | string | нет | **** ярлык трафика мерчанта — выбирает сегментный каскад маршрутизации. ≤64 символа `[a-z0-9_-]` (строчные буквы, цифры, `-`, `_`); пустая строка/`null` = default-каскад; иная форма → `422 invalid_request` ДО idempotency-claim и любых вызовов PSP. Если каскада с таким сегментом нет — исполняется default-каскад (не legacy-порядок). В idempotency-хеш входит только при наличии (отсутствие поля сохраняет прежний хеш); значение фиксируется в попытке (`attempts.routing_segment`) и в ответе API не возвращается |
| `authentication_type` | string | нет (`no_three_ds` по умолчанию) | 3DS-режим raw-card формы: `three_ds` \| `no_three_ds`. Только для `payment_method.card`; `three_ds` требует `session_context.browser.ip_address`. Нарушения → `422 invalid_request`. См. §2.2 |
¹ Платёж по карте диспатчится только через инструмент: `payment_method.instrument_id`
обязателен для фактического исполнения card-формы (surface `pin_…` — §2.1).
Исключение — redirect-форма (§2.3): исполнение без инструмента и без карты
(хостед-страница PSP), при наличии Route Target с `redirect_hpp=true`.
² Необязательно по схеме, но строго рекомендован: см. §5 (роутинг по стране и
обязательные поля PSP DEPOSIT-профиля).
Заголовок `Idempotency-Key` обязателен для POST; канонический хеш считается по
разобранной структуре запроса, поэтому тела с разным порядком ключей, но одинаковой
семантикой дают один хеш. Повтор тем же ключом+телом реплеит сохранённый результат;
тот же ключ с другим телом — `422 idempotency_key_reuse`.
## 2. payment_method
Три взаимоисключимые СЕМЕЙСТВА форм: сохранённая карта (`instrument_id`, §2.1),
raw card H2H (`card`, §2.2 — только для PCI DSS certified мерчантов после
операторского включения) и **hosted page** без данных (§2.3: `type` =
`redirect` | `apple_pay` | `google_pay` | `open_banking`). Указать формы
одновременно → `422 invalid_request`.
### 2.1 instrument_id — сохранённая карта (Secure Fields SDK)
| Поле | Значения | Ограничения | Ошибка при нарушении |
|---|---|---|---|
| `type` | `"card"` — единственное поддерживаемое значение | Любое другое значение отклоняется контрактом платформы | `422 unsupported_payment_method` |
| `instrument_id` | `pin_…` — идентификатор из `POST /v1/payment-instruments` | **SINGLE-USE**: регистрируется от single-use vault token (Secure Fields capture), потребляется атомарно с созданием платежа | `422 unknown_instrument` (нет в тенанте), `422 instrument_merchant_mismatch` (инструмент другого мерчанта тенанта), `422 instrument_not_active` (уже использован `USED` или деактивирован) |
Порядок интеграции: карта игрока → Secure Fields SDK → single-use vault token →
`POST /v1/payment-instruments` (`pin_…`) → `payment_method.instrument_id` здесь.
Повторное использование того же `pin_…` для второго платежа невозможно: статус
инструмента становится `USED`, повтор отвечает `422 instrument_not_active` — для
повторного депозита зарегистрируйте новый инструмент от нового vault token
(сохранённые карты — тот же путь: одна регистрация = один платёж).
PAN/CVV в этот запрос не принимаются никогда: поля карты живут только внутри
capture-поверхности (см. гайд [SDK + Webhooks](<#tag/SDK-+-Webhooks>) §1/§4).
### 2.2 card — raw card (H2H, только для PCI DSS certified мерчантов)
Форма `payment_method.card` доступна **только** мерчанту, чей H2H-гейт включён
оператором (per-merchant флаг + deployment kill-switch; см. гайд
[Integration models, модель (d)](<#tag/Integration-models>)).
Выключенный гейт → `422 h2h_not_enabled` на любую card-форму.
| Поле | Тип | Ограничения | Ошибка при нарушении |
|---|---|---|---|
| `card_number` | string | только цифры, 12–19 цифр, Luhn-валидный PAN | `422 invalid_card_number` |
| `card_exp_month` | number \| string | 1–12 | `422 invalid_card_expiry` |
| `card_exp_year` | number \| string | 4-значный год (2000–2199); карта валидна до конца месяца экспирации | `422 invalid_card_expiry`; просроченная карта → `422 card_expired` |
| `card_holder_name` | string | 1–255 символов после trim | `422 invalid_card_holder` |
| `card_cvc` | string | 3–4 цифры | `422 invalid_card_cvc` |
Правила формы:
- **Валидация до диспетча**: невалидная карта отклоняется на PA и никогда не
доходит до PSP (fail-fast до любых вызовов процессора).
- **Транзит, не хранение**: значения карты живут в памяти PA только в момент
валидации и построения вызова процессора. В записи платежа сохраняется
только `payment_method_type: "card"` (без `instrument_id`); PAN/CVV/holder
не появляются в ответе, вебхуках, аудит-логе и БД.
- **Idempotency**: канонический хеш тела включает карту — повтор тем же ключом
требует пересылки тех же card-полей (сохранённый ответ карту не содержит).
- **Rate limit**: на H2H-создания действует отдельный жёсткий per-merchant
бюджет — превышение `429 rate_limited` + `Retry-After` (общий лимит
`/v1/payments` при этом не расходуется). Тот же бюджет расходуют и
raw-card выплаты — поверхность одна.
- **Аутентификация**: только tenant API key (`pa_sk_…`); publishable key
(`pk_…`) на H2H не участвует.
- Экспир-поля принимаются числом (`12`, `2029`) и строкой (`"12"`, `"2029"`) —
канонический хеш от формы написания не зависит.
#### authentication_type — 3DS-режим raw-card запроса (опция, по умолчанию no_three_ds)
Корневое поле запроса (`authentication_type`, НЕ внутри `payment_method`).
Значение — закрытое множество: `three_ds` | `no_three_ds`; любое другое →
`422 invalid_request`.
| Значение | Поведение | Ответ |
|---|---|---|
| нет / `no_three_ds` | поведение без изменений: PSP обрабатывает операцию без 3DS-челленджа | `201 AUTHORIZED` (или финал по обычному каскаду) |
| `three_ds` | PSP инициирует 3DS-челлендж; игрок проходит банковскую 3DS-страницу | `201 PENDING` + `next_action: {type: "redirect", redirect_url}` — финал webhook'ом/`GET` |
Правила опции:
- Принадлежит **только raw-card форме**: на `instrument_id`- и
`redirect`-формах (и без `payment_method`) → `422 invalid_request` — поле
никогда не игнорируется молча.
- `three_ds` требует **`session_context.browser.ip_address`** (parseable IP):
это часть 3DS-набора данных браузера; без него запрос отклоняется на PA
(`422 invalid_request`, до диспетча) — эквайер отклоняет операцию без
`Client.IPAddress`, и честное поведение — fail-fast на PA, а не зависшая
попытка.
- Опция участвует в каноническом idempotency-хеше: повтор тем же ключом — с
тем же значением опции.
- 3DS-финал приходит подписанным webhook'ом или читается `GET
/v1/payments/{id}` (шаг К5 чек-листа); промежуточный `PENDING` — нормальное
состояние челленджа, не ошибка.
### 2.3 Hosted page без данных — redirect | apple_pay | google_pay | open_banking (модель (b), PayAdmit / BTQ Finance / AVGentlements)
Форма без карточных данных: игрок вводит карту или выбирает кошелёк (и проходит
3DS) на **хостед-странице PSP**; PA в этом флоу не видит ни карту, ни
wallet-токен — только редирект и финальный callback/sync.
**Один метод = один отдельный чекаут PSP.** Значение `payment_method.type`
уходит в PSP как `paymentMethod` и открывает СВОЮ страницу чекаута:
`redirect` → `BASIC_CARD` (только карточная форма), `apple_pay` → `APPLEPAY`
(только Apple Pay), `google_pay` → `GOOGLEPAY` (только Google Pay),
`open_banking` → `OPENBANKING` (open banking). Wallet-кнопка **не появляется** на
карточной странице и наоборот: какой метод запросили — тот чекаут игрок и
увидит. PA ничего не рендерит; состав методов на терминале описывается
`capabilities.payment_methods` Route Target (данные, не код).
```json
{ "payment_method": { "type": "redirect" } }
{ "payment_method": { "type": "apple_pay" } }
type |
PSP paymentMethod на проводе |
Смысл |
|---|---|---|
redirect |
BASIC_CARD |
карточная страница PSP |
apple_pay |
APPLEPAY |
кнопка Apple Pay на хостед-странице PSP |
google_pay |
GOOGLEPAY |
кнопка Google Pay на хостед-странице PSP |
open_banking |
OPENBANKING |
open banking (отдельный терминал PSP) |
| Поле | Значения | Ограничения | Ошибка при нарушении |
|---|---|---|---|
type |
redirect | apple_pay | google_pay | open_banking |
Другие поля формы (instrument_id, card) запрещены |
422 invalid_request (перенос карты/инструмента в hosted-форму) |
| — | роутинг | Платёж исполняется только на Route Target с capability redirect_hpp=true (PayAdmit hosted-checkout, BTQ Checkout, AVGentlements HPP) |
422 no_eligible_redirect_route — hosted-маршрута нет (исполнения не было) |
| — | allowlist метода | Route Target объявляет допустимые методы в capabilities.payment_methods (значения PSP: BASIC_CARD / APPLEPAY / GOOGLEPAY / OPENBANKING); поле отсутствует или пусто → принимает любой метод |
422 no_eligible_route — ни один target не объявляет запрошенный метод |
apple_pay / google_pay |
только возвращающиеся игроки | PSP предоставляет Apple/Google Pay только для STD-трафика (у first-time депозитора этих кнопок нет). PA считает стрим из истории: ftd, пока у клиента меньше контрактного порога успешных депозитов |
422 wallet_unavailable_for_first_deposit — «Apple Pay / Google Pay is available for returning customers only». Возвращается до idempotency-claim: payment/attempt не создаются, PSP не вызывается. При пороге 3 клиент с двумя депозитами ещё ftd — wallet ему недоступен |
Wallet-методы доступны только на STD-терминалах; на FTD-терминале объявляется
только BASIC_CARD (данные Route Target, не код). Кнопки Apple/Google Pay
рисует hosted-страница PSP: PA ничего не рендерит и wallet-токен не
обрабатывает; Apple Pay domain association / merchant validation — на стороне
PSP, на стороне PA ничего не требуется.
Если мерчант знает больше PA (первый депозит прошёл мимо платформы), он передаёт
metadata.deposit_stream = "redep" — override переводит платёж на STD-контур и
wallet проходит. Обратный override ("ftd") переводит платёж на FTD-контур
(только карта). Формат запроса при этом не меняется: те же hosted-формы без
card/instrument_id, отличается только type.
Правила форм:
PA_H2H_ENABLED/merchants.h2h_enabled (переносить карточные данные
некуда и нечего — отдельный rate-limit на H2H не применяется, действует
общий лимит /v1/payments).201 + status: PENDING +
next_action: {type: "redirect", redirect_url, method: "GET"} — переведите
игрока по redirect_url (хостед-страница PSP). Возврат игрока — не
результат: финал приходит webhook'ом (payment.authorized /
payment.failed) и/или через GET /v1/payments/{id} (шаг К5
чек-листа).| Значение | Семантика | Комментарий |
|---|---|---|
automatic (default) |
Sale-модель: PSP диспатчит PURC, авторизация и захват — одним вызовом | PA-статус AUTHORIZED = provider_status COMPLETED: деньги уже захвачены PSP, депозит можно зачислять игроку по webhook payment.authorized |
manual |
Authorize-only: платёж останавливается до отдельного захвата | Capture-endpoint в публичном API не экспонирован (/v1/payments/{id}/capture не входит в текущую поверхность). Используйте automatic |
capture_method валидируется по capabilities Route Target: target без поддержки
запрошенного метода отфильтровывается на eligibility. Текущие merchant-роуты пилота
настроены на automatic — запрос manual без способного target отвечает
422 no_eligible_route (без попыток исполнения).
next_action в ответе на POST /v1/payments и в GET /v1/payments/{id} сообщает,
что клиент должен сделать дальше. В текущих live-флоу встречаются значения:
| Значение | Что делать |
|---|---|
none |
Ничего: платёж идёт сам, финал придёт webhook'ом (payment.*) или через GET /v1/payments/{id} |
wait |
Подождать retry_after_secs и опросить GET /v1/payments/{id} (идёт синхронизация статуса) |
redirect |
Перевести игрока по redirect_url (3DS challenge / hosted page PSP); возврат игрока — не результат, финал — webhook/polling — см. шаг К5 чек-листа онбординга |
collect_data |
Контрактный member для PSP-флоу с дополнительным вводом — см. ниже |
collect_data означает, что PSP просит собрать у игрока дополнительные данные,
прежде чем платёж сможет продолжиться:
required_fields — список имён полей, которые PSP просит собрать
(например email, phone); состав определяется PSP-процессором платежа;POST /v1/payments) либо повторяет
confirm-вызов, передав запрошенные данные;none/redirect/wait; collect_data зарезервирован контрактом заранее —
клиент интеграции должен уметь обрабатывать это значение так же, как
redirect: не считать его финалом и не кредитовать игрока до финального
статуса.Пример: {"type": "collect_data", "required_fields": ["email", "phone"]} —
соберите у игрока email и телефон и повторите создание платежа, передав их в
блоке customer (§4).
Свободная форма сохраняется целиком (write-only — см. §8), но эти поля читает
платформа и проецирует в PSP-вызов (billing форка: address.first_name,
address.last_name, email, phone):
| Поле | Тип | Обязательность | Комментарий |
|---|---|---|---|
reference_id |
string | number | нет (рекомендуется) | ID игрока у казино — ownership-контекст инструментов. НЕ PAN: строка или число канонизируется и проходит Luhn-пробу — Luhn-валидная 13–19-значная последовательность (в т.ч. форматированная 4111-1111-1111-1111) отклоняется как кард-данные. Ограничения: ≤255 символов, charset [A-Za-z0-9_.@-]; null = поле отсутствует; другой JSON-тип → 422 invalid_request |
first_name / last_name |
string | да для Apcopay S2S | Имя/фамилия игрока (проецируются в billing.address) |
email |
string | да для Apcopay S2S | Проекция в billing.email и верхнеуровневый email PSP |
phone |
string | object | да для Apcopay S2S | Плоская строка — только цифры, без + (ведущий + допустим и обрезается: "+35712345678" → 35712345678; лучше сразу слать цифры); структурированная форма { "country_code": "357", "number": "12345678" } проецируется verbatim. Без phone коннектор Apcopay S2S отвергает платёж ошибкой missing-required-param (семейство IR_04 форка) — профиль PSP DEPOSIT требует customer.phone наряду с именем и email |
Телефон/имя/email нужны на каждый S2S-платёж (профиль PSP), а не только на
регистрацию инструмента: POST /v1/payment-instruments их не принимает — платёжный
запрос единственное место, где PA видит контекст игрока.
Проецируется в billing.address PSP; коды маппинга PA → PSP:
address_line1→line1, address_line2→line2, city, state, postal_code→zip,
country_code или country→country.
| Поле | Тип | Обязательность | Комментарий |
|---|---|---|---|
address_line1 |
string | да для Apcopay S2S | Строка адреса; PSP DEPOSIT-профиль требует addressLine1 |
address_line2 |
string | нет | Доп. строка |
city |
string | да для Apcopay S2S | |
state |
string | нет | Штат/регион |
postal_code |
string | да для Apcopay S2S | |
country_code (или country) |
string | см. ниже | ISO-2 (CY, MT, …). Читается роутингом |
Две независимые причины заполнять:
422 no_eligible_route. Валютный eligibility без
страны работает, но список маршрутов может быть уже ожидаемого.addressLine1, city, countryCode, postalCode) — без блока
billing_address платёж уходит без billing-данных и коннектор может отвергнуть
его на своей валидации.Оба блока свободной формы: сохраняются с платежём, на MVP-роутинг не влияют (эластичность политик — следующий шаг). Исключение — блок браузера:
session_context.browser проецируется в browser_info PSP-вызова (3DS-данные):
Поле блока browser |
Тип | Комментарий |
|---|---|---|
user_agent |
string | Apcopay DirectConnect PURC требует UserAgent |
time_zone |
number | JS getTimezoneOffset в минутах (минус — восточнее UTC); Apcopay требует TimeZone |
accept_header, language |
string | опционально |
java_enabled, java_script_enabled |
boolean | опционально |
screen_width, screen_height, color_depth |
integer | опционально |
ip_address |
string | IP игрока; должен парситься как IP |
Без session_context.browser платёж диспатчится без browser-данных, и отсутствие
UserAgent/TimeZone — типичная причина отклонения Apcopay PURC: собирайте
блок на клиенте и передавайте всегда.
PAN-проба: в свободных значениях обоих блоков (на любой
глубине вложенности, включая числа) не допускается Luhn-валидная цепочка
13–19 цифр или её «карточный» группированный формат (4111 1111 1111 1111) —
такое значение является кард-данными, и весь запрос отклоняется с
422 invalid_request (сообщение называет поле, но не эхоит значение).
Обычные ID/таймстампы/тексты про эту пробу не задевают; хранятся поля после
пробы как есть.
metadata — свободная форма, сохраняется с платежём. Соглашение платформы:
внешний ID заказа кладите в metadata.order_reference — тогда он появляется
в мерчант-портале (колонка Order Reference списка транзакций, свободный поиск q
и CSV-экспорт report.csv). Передавать его отдельным полем не нужно — отдельного
поля в контракте нет.
metadata.deposit_stream — выбор стрима депозита: "ftd" | "redep". PA сам
определяет стрим по истории игрока (customer.reference_id + число успешных депозитов против
контрактного порога std_min_deposits; дефолт 1 = правило), а этот ключ —
override: он побеждает расчёт PA. Используйте "redep", если ваш учёт FTD расходится с нашим
(первый депозит прошёл мимо PA). Иные значения → 422 invalid_request. Отдельного поля в контракте
нет — только metadata. Порог задаётся оператором в договоре (admin API
PUT /v1/merchants/{id}/std-min-deposits, pa-admin-onboarding-api.md §2.7), мерчанту его менять
не нужно и нельзя. Диапазон порога — целое 1..=2147483647: не-целое или отсутствующее значение
при обновлении → 400 invalid_request (отказ парсера тела), целое вне диапазона (< 1 или
> i32::MAX) → 422 invalid_request. Подробно, включая wallet-ограничение и доказательную базу, —
§2.3 и pa-admin-onboarding-api.md §2.7.
Служебные ключи PA: metadata — контейнер мерчанта; PA-owned служебные ключи (например
pa_hosted_payment_method, которым PA передаёт выбранный PSP-метод внутри диспатча) — внутренняя
деталь PA: мерчант их не передаёт, а merchant-metadata на диспатч в PSP не переносится. Ключи с
префиксом pa_ зарезервированы за PA.
PAN-проба: как и risk_context/session_context, значения
metadata сканируются на входе — Luhn-валидная цепочка 13–19 цифр (или её
группированный формат) в любом вложенном значении → 422 invalid_request.
Внешние ID заказов вида INV-2024-001 и прочие обычные метаданные пробу не
задевают.
Ответ (201 creation и GET /v1/payments/{id}) — проекция логического платежа:
{
"payment_id": "pay_...",
"status": "AUTHORIZED",
"amount": 1050,
"currency": "EUR",
"capture_method": "automatic",
"attempts_summary": [ ... ],
"created_at": "2026-09-20T12:00:00Z"
}
Поля customer, billing_address, metadata, risk_context, session_context
— write-only: они не возвращаются в ответе Payments API. Это дисциплина
данных платформы: маскированные/чувствительные контексты не гуляют по публичному
API. Доступ к ним — мерчант-портал: Transaction Details
(GET /v1/merchants/{id}/payments/{payment_id} возвращает metadata и customer
verbatim) и CSV-экспорт (report.csv).
| Код | HTTP | Когда |
|---|---|---|
unsupported_payment_method |
422 | payment_method.type ∉ card | redirect | apple_pay | google_pay | open_banking |
invalid_request (hosted-форма) |
422 | hosted-форма (redirect/apple_pay/google_pay/open_banking) с переносом card или instrument_id (hosted-форма не принимает данные карты) |
wallet_unavailable_for_first_deposit |
422 | payment_method.type = apple_pay | google_pay, а стрим клиента = ftd (успешных депозитов меньше контрактного порога std_min_deposits, дефолт 1: Apple/Google Pay доступны только STD-трафику). Ошибка возвращается ДО idempotency-claim: payment/attempt не создаются, PSP не вызывается; текст — «Apple Pay / Google Pay is available for returning customers only». Escape hatch: metadata.deposit_stream=redep |
no_eligible_redirect_route |
422 | payment_method.type=redirect, но ни один Route Target с capability redirect_hpp не поддерживает валюту/capture_method/страну — hosted-маршрута нет |
unknown_instrument |
422 | pin_… нет в тенанте |
instrument_merchant_mismatch |
422 | инструмент другого мерчанта тенанта |
instrument_not_active |
422 | инструмент уже использован (USED) или деактивирован — SINGLE-USE |
h2h_not_enabled |
422 | raw-card форма (payment_method.card) при выключенном H2H-гейте (per-merchant флаг или deployment kill-switch — любой уровень); то же для raw-card получателя выплаты (receiver_card, §11.2) |
invalid_card_number |
422 | card_number: не только цифры, длина вне 12–19, Luhn-fail (депозит card и payout receiver_card) |
invalid_card_expiry |
422 | card_exp_month вне 1–12 или год вне 4-значного окна (депозит и payout) |
card_expired |
422 | месяц/год экспирации карты уже прошли (депозит и payout) |
invalid_card_holder |
422 | card_holder_name пуст (после trim) или длиннее 255 символов (депозит и payout) |
invalid_card_cvc |
422 | card_cvc не 3–4 цифры (только депозит — payout-форма receiver_card поля CVC не имеет) |
invalid_request (authentication_type) |
422 | authentication_type ∉ three_ds | no_three_ds; опция на не-raw-card форме; three_ds без parseable session_context.browser.ip_address |
no_eligible_route |
422 | ни один Route Target не поддерживает валюту/capture_method/страну (пустая country-filter выборка); для H2H — нет target с capability s2s_card; для saved-card инструмента — нет target, способного исполнить instrument dispatch (все объявляют saved_card=false; сообщение «no active route target supports saved-card instrument dispatch…»); для hosted-формы — нет target, чей capabilities.payment_methods содержит запрошенный метод, или нет target с нужным deposit_streams; для redirect — см. no_eligible_redirect_route выше |
unknown_merchant |
422 | merchant_id не в тенанте ключа |
rate_limited |
429 | превышен rate limit (для H2H — отдельный per-merchant бюджет + Retry-After) |
invalid_request |
400/422 | amount ≤ 0, кривая валюта, customer не объект, card + instrument_id одновременно, нарушение формы customer.reference_id (charset/длина/PAN-проба) |
invalid_request (PAN-проба контекста) |
422 | PAN-подобная последовательность (Luhn-валидная цепочка 13–19 цифр или сгруппированный «карточный» формат) внутри свободных JSONB-полей customer / risk_context / session_context / metadata: карта не попадает в PA-записи и на PSP; значение в ошибке не эхоится |
idempotency_key_required |
400 | нет заголовка Idempotency-Key |
idempotency_key_reuse |
422 | тот же ключ с другим телом |
Детерминированные коды сохраняются в idempotency-записи и реплеятся тем же ключом (повтор возвращает сохранённый результат, включая ошибку). Полный список и семафоры — payments-api.md §3.
Смежные поверхности вынесены в отдельные разделы справочника /docs (здесь не дублируются):
DEAD), статусы доставки DELIVERED/PENDING/DEAD, ручной re-send.instrument_id / receiver_card), статусы, лимиты, самоподтверждение.Как казино выплачивает выигрыши игрокам через PA (payout) и что из payout-домена доступно мерчанту прямо сейчас. Приём депозитов — Handover Package; глоссарий — Термінологія.
Мерчантская payout-поверхность открыта (/v1/merchants/{id}/payouts*,
merchant-view справочника /docs, тег «Merchant Payouts») и
/portal-вкладка «Payouts»:
POST /v1/merchants/{id}/payouts: получатель —
инструмент игрока (instrument_id, pin_…, зарегистрированный этим же
мерчантом), сумма в минорных единицах, валюта. Ссылка на игрока
(customer_reference) берётся из инструмента, если не указана явно.
Запрос идемпотентен — обязателен Idempotency-Key.GET /v1/merchants/{id}/payouts (список с фильтром по
статусу) и GET /v1/merchants/{id}/payouts/{payout_id} (детально:
attempts_summary, approval_decisions, next_action).POST /v1/merchants/{id}/payouts/{payout_id}/cancel
— только пока выплата в CREATED/AWAITING_APPROVAL; одобренную
оператором выплату мерчант отменить не может (409 payout_not_cancellable).payout_self_approval, казино само
подтверждает/отклоняет свои выплаты в AWAITING_APPROVAL —
см. раздел ниже./portal — таблица выплат со статус-бейджами,
форма создания и авто-обновление статусов каждые 15 секунд, пока есть
выплаты в не-финальном статусе.Выплаты выключены по умолчанию на ДВУХ уровнях, и мерчантская поверхность проходит, только когда включены ОБА (fail-closed по каждому):
403 forbidden) — это операторское
решение (AML/fraud review, условия договора).Пока гейты выключены, каждый merchant-payout-endpoint отвечает
422 payouts_not_enabled — запросите включение у Оператора (нужны оба
уровня: домен тенанта + ваш мерчант).
Payout в PA — это отдельный домен с собственным жизненным циклом, а не «отрицательный платёж»:
instrument_id;
PAN/CVV-полезная нагрузка отклоняется). Запрос идемпотентен.AWAITING_APPROVAL и ждёт решения оператора платформы
(approve / decline / cancel). Это fail-closed модель: выплата без
одобрения не уйдёт в PSP.next_action маркирует это как
{type: "approval", resource, allowed_actions} — внешнему наблюдателю
видно, что ресурс ждёт операторского решения./portal («Payouts») и через
GET /v1/merchants/{id}/payouts/{payout_id}; вкладка обновляется
автоматически.APPROVED) выплата диспатчится в PSP — PROCESSING → COMPLETED (или
FAILED_TECHNICAL / DECLINED). Диспетч в PSP пока НЕ реализован
(Phase 2): мерчант видит честный статус APPROVED («одобрено, ждёт
исполнения») без обещаний о движении денег до включения Phase 2.Каждая выплата проходит пре-флайт проверку лимитов до создания записи:
превышение отклоняется — 422 limit_exceeded, запись выплаты не создаётся.
Лимиты задаёт Оператор платформы; мерчант их не конфигурирует.
Что ограничивается (календарный день — UTC):
| Лимит | Что считает |
|---|---|
| Single payout | максимум суммы одной выплаты |
| Сумма за день мерчанта | все выплаты мерчанта за день |
| Количество за день мерчанта | все выплаты мерчанта за день |
| Сумма за день на игрока | все выплаты одного игрока за день |
| Количество за день на игрока | все выплаты одного игрока за день |
| MID-дневная | дневной бюджет MID (платёжного терминала, через который идёт выплата) |
При превышении API отвечает 422 limit_exceeded (RFC 7807). Ориентируйтесь
на код limit_exceeded, а не на значения из сообщения: лимиты —
операторская конфигурация, они меняются, и конкретные числа в гайде не
публикуются. Сообщение ошибки называет сработавшее ограничение
(single / мерчант / игрок). Отклонённая по лимиту выплата дневной бюджет
не резервирует и в PSP не уходит.
Fail-closed. Если лимиты для тенанта/мерчанта не настроены вовсе, выплаты
заблокированы: 422 limit_exceeded «payout limits are not configured».
Это сознательная защита, а не ошибка конфигурации на вашей стороне —
запросите настройку у Оператора.
Как запросить увеличение лимита: через Оператора (поддержка платформы). Укажите merchant_id, измерение (single / день / игрок / MID) и желаемый порог с обоснованием — изменение применяется операторской конфигурацией, менять контракт запроса не нужно.
Повтор после отказа по лимиту: запрос с тем же Idempotency-Key вернёт
сохранённый результат — ретрай тем же ключом
не перепроверяет лимит. После согласования лимита используйте новый
Idempotency-Key.
У выплаты два рабочих пути получения pin_…, оба опираются на одно и то же
правило: инструмент потребляется только ПЛАТЁЖОМ (депозитом), сама выплата
инструмент НЕ потребляет.
cardPanId, «повторно вводить данные карты не
нужно»). Используйте тот же pin_…, что ушёл в депозит: платёж
перевёл инструмент в USED, но для выплаты он остаётся валидным
получателем — статус USED для payout-получателя нормален. Повторные
выплаты по тому же pin_… тоже допустимы: риск контролирует
операторский approval gate и пре-флайт лимиты, а не
одноразовость инструмента.POST /v1/payment-instruments → новый pin_… (шаги К1–К2
чеклиста) и создайте выплату по нему —
валиден и статус ACTIVE (инструмент ещё не использован в платеже).Приёмник выплаты принимает инструмент в статусе ACTIVE или USED;
административно деактивированный (DEACTIVATED) → 422 instrument_not_payout_eligible; чужой/неизвестный pin_… → 422 unknown_instrument. Статус инструмента выплата не меняет: после выплаты
USED остаётся USED (новый ПЛАТЁЖ по нему по-прежнему отклоняется —
422 instrument_not_active).
Для мерчанта с включённым H2H-гейтом (PCI DSS certified среда — см. Integration models, модель (d)) доступен третий путь: выплата на карту, переданную inline, без предварительной регистрации инструмента:
POST /v1/merchants/{id}/payouts
{
"receiver_card": {
"card_number": "4500000000004454",
"card_exp_month": 12,
"card_exp_year": 2029,
"card_holder_name": "John Doe"
},
"amount": 2500,
"currency": "EUR",
"customer_reference": "usr_123"
}
```**`receiver_card` ⊕ `instrument_id`** взаимоисключимы (оба → `422
invalid_request`; ни одного — тоже `422`).
- **Без CVV — по дизайну:** CVV для зачисления не нужен (PSP-флоу выплаты
работает с картой без CVV). Присланный `card_cvc` отвергается контрактом
громко — PA никогда не принимает CVV на payout-поверхности.
- **Двойной гейт:** обычный payouts-гейт (`payouts_enabled`) ПЛЮС тот же
двухуровневый H2H-гейт, что у raw-card депозитов (`PA_H2H_ENABLED` +
`merchants.h2h_enabled`) — receiver-форма несёт PAN в PA, это H2H-семантика.
Выключен любой уровень → `422 h2h_not_enabled`.
- **Валидация fail-fast:** Luhn/expiry/holder — невалидная карта отклоняется
на PA (`422 invalid_card_number` / `invalid_card_expiry` / `card_expired` /
`invalid_card_holder`), значение в сообщении не эхоится, запись выплаты не
создаётся.
- **0 PAN в PA:** PA сохраняет только маскированный снапшот (brand + last4 +
срок — тот же класс данных, что у instrument-получателя); PAN/holder/CVC
в БД, логах, аудите и вебхуках отсутствуют. В списке выплат получатель
виден тем же маскированным лейблом (`VISA •••• 4454`).
- **`customer_reference` обязателен** на этой форме (нет инструмента, из
контекста которого он обычно подставляется).
- **Статус и диспетч:** выплата создаётся в `AWAITING_APPROVAL` — операторский
gate тот же; реальный вызов PSP — Phase 2 и для receiver-выплаты
произойдёт только после его реализации и одобрения оператором.
- **Rate limit:** raw-card выплаты расходуют тот же per-merchant H2H-бюджет,
что и raw-card депозиты (`429 rate_limited` + `Retry-After` при
превышении).
## Самоподтверждение выплат мерчантом
По умолчанию решение по выплате — операторское (four-eyes: казино
запрашивает — платформа одобряет). Оператор может передать мерчанту
право подтверждать собственные выплаты — флаг
`merchants.payout_self_approval`, fail-closed (по умолчанию `false`):
- **Кто включает:** только Оператор — `PUT
/v1/merchants/{id}/payout-self-approval` (`{"enabled": true, "reason":
"…"}`, admin-ключ; merchant-ключ → `403`). Каждый toggle аудируется
(`merchant.payout_self_approval`). Мерчант не может включить флаг
себе сам.
- **Что открывается мерчанту:** approve/decline СВОИХ выплат в статусе
`AWAITING_APPROVAL`:
- `POST /v1/merchants/{id}/payouts/{payout_id}/approve` →
`APPROVED` — та же семантика, что у операторского approve:
повторная проверка лимитов в момент решения, approved-снапшот,
запись решения с ролью `merchant` в `approval_decisions[]`;
- `POST /v1/merchants/{id}/payouts/{payout_id}/decline` →
`DECLINED` — резерв лимитов освобождается.
Оба идемпотентны (`Idempotency-Key` обязателен), аудит:
`merchant.payout_approved` / `merchant.payout_declined`.
- **Что НЕ меняется:** PSP-диспетч остаётся Phase 2 операторской части;
фаза исполнения после `APPROVED` не переходит к мерчанту. Флаг не
отменяет лимиты, гейты `payouts_enabled` (tenant + merchant) и
идемпотентность.
- **Пока флаг выключен:** оба эндпоинта отвечают `422
payout_self_approval_not_enabled` — запрашивайте включение у
Оператора. Выплата в любом статусе кроме `AWAITING_APPROVAL`
(финальный, исполнение, ещё `CREATED`) → `409
payout_already_final`; чужая выплата → `404`.
- **В `/portal`:** с флагом на вкладке «Payouts» у выплат
`AWAITING_APPROVAL` появляются кнопки Approve/Decline; без флага —
«Очікує підтвердження оператора» (решение за Оператором).
## Почему это не «Phase 2 целиком»
- **Операторский gate остаётся операторским.** Одобрение и исполнение
(PSP-диспетч) — решения и механика платформы; мерчантской стороне
принадлежат создание запроса, наблюдение статуса и отмена до одобрения.
- **Стабильность контракта.** Схемы payout-домена опубликованы в версионном
контракте (`GET /docs/openapi.json`) с Phase 1 — merchant-эндпоинты
используют те же имена полей и статусы (`PayoutResponse`), интеграция,
написанная под операторский контракт, не ломается.
## Интеграция (минимальный путь)
1. Получите merchant-ключ у Оператора (`POST /v1/merchants/{id}/api-key`
выдаёт оператор) — он и merchant_id.
2. Зарегистрируйте инструмент игрока: SDK capture →
`POST /v1/payment-instruments` → `pin_…` (шаги К1–К2
[чеклиста](<#tag/Onboarding-Checklist>)); сохраните `pin_…` — списка
инструментов API не возвращает. Два пути получения `pin_…` для выплаты —
см. раздел «Откуда instrument_id для выплаты» выше.
3. Дождитесь включения выплат Оператором (`payouts_enabled`).
4. `POST /v1/merchants/{id}/payouts` c `Idempotency-Key` →
`AWAITING_APPROVAL` (201).
5. Опрашивайте статус (`GET …/payouts/{payout_id}`), читайте вкладку
«Payouts» в `/portal` — она обновляется сама, или подписайтесь на
webhook-события выплаты. Отменить —
`…/payouts/{payout_id}/cancel` до одобрения.
## Webhook-события выплаты
Выплаты ходят через ТЕ ЖЕ webhook-доставки, что и платежи (один outbox,
один worker, одна подпись `PA-Webhook-Signature`, дедуп по `event_id` —
см. [SDK + Webhooks](<#tag/SDK-+-Webhooks>)). Поверх создания выплаты
мерчантом PA доставляет:
- `payout.approved` — решение гейта зафиксировано (оператор однородил или
сработала авто-политика; для авто-политик событие уходит сразу в той же
транзакции, что создание);
- `payout.completed` — провайдер-подтверждённая финансовая финальность
(Phase 2, PSP-диспетч);
- `payout.declined` — гейт отклонил выплату (`data.reason` — записанная
причина);
- `payout.cancelled` — выплата отменена до PSP-диспетча (`data.reason`).
Не доставляются: `CREATED`/`AWAITING_APPROVAL` (синхронный ответ
создания/решения несёт этот факт), `PROCESSING` («PSP принял» — не
финансовая финальность), `FAILED_TECHNICAL`/`UNKNOWN_PENDING_SYNC`
(sync-first эскалация). Повторная эмиссия того же факта под новым
`event_id` — no-op (transition-dedup): каждый факт выплаты приходит ровно
один раз. Журнал доставки выплаты: `GET
/v1/webhooks/deliveries?payout_id=po_...`; в `/portal` (вкладка
«Events and Logs») доставки выплат видны в общей ленте мерчанта.
## Связанные материалы
- [Термінологія](<#tag/Terminologiya>) — approval gate, Route Target, webhook;
- [Integration models](<#tag/Integration-models>) — модели приёма депозитов;
- [SDK + Webhooks](<#tag/SDK-+-Webhooks>) — webhook-контракт (тот же канал
доставляет и payout-события —);
- [Field Reference](<#tag/Field-Reference>) — поля платежа и payout-запроса,
`next_action`.
Короткий чек-лист, который проводит казино от получения доступов до go-live. Детальные примеры кода и контракты — в Handover Package, SDK + Webhooks и Field Reference; здесь только последовательность шагов и критерии готовности.
/docs).| Шаг | Действие | Где смотреть |
|---|---|---|
| К1 | Подключить SDK iframe на странице депозита (PASecureFields.mount, onToken(vaultToken)) |
Handover §3/К1, SDK + Webhooks §3 |
| К2 | Обменять vault_token на инструмент: POST /v1/payment-instruments → pin_… |
SDK + Webhooks §2.1 |
| К3 | Создать платёж: POST /v1/payments (с Idempotency-Key) → pay_… |
Field Reference |
| К4 | Принимать webhook'и: верифицировать PA-Webhook-Signature, дедуп по PA-Event-Id, отвечать 2xx |
SDK + Webhooks §2.4 |
| К5 | Обрабатывать next_action.redirect (3DS / hosted page): перевести игрока по redirect_url; финал — webhook/polling, не возврат игрока |
Field Reference §3.1 |
| К6 | Go-live: получить production URL и ключи, пройти чек-лист ниже | — |
Отметка: [О] — Оператор PA, [К] — Казино.
AUTHORIZED/CAPTURED) — полный цикл.PA-Webhook-Signature (HMAC-SHA256 по сырому телу) работает на receiver'е — все типы событий: payment.authorized / payment.captured / payment.refunded / payment.failed (и при включённых выплатах — payout.*).Idempotency-Key возвращает сохранённый результат (Idempotent-Replayed: true); тот же ключ с другим телом → 422 idempotency_key_reuse; webhook-replay по PA-Event-Id не дублирует зачисление.pin_/pay_ и маскированные метаданные.GET /v1/merchants/{id}/webhooks/deliveries?payment_id=… — журнал доставок своих платежей (также вкладка Events and Logs в /portal);GET /v1/payments/{id} — состояние платежа;/healthz — живость PA./docs).| Шаг | Действие | Где смотреть |
|---|---|---|
| К1 | Подключить SDK iframe на странице депозита (PASecureFields.mount, onToken(vaultToken)) |
Handover §3/К1, SDK + Webhooks §3 |
| К2 | Обменять vault_token на инструмент: POST /v1/payment-instruments → pin_… |
SDK + Webhooks §2.1 |
| К3 | Создать платёж: POST /v1/payments (с Idempotency-Key) → pay_… |
Field Reference |
| К4 | Принимать webhook'и: верифицировать PA-Webhook-Signature, дедуп по PA-Event-Id, отвечать 2xx |
SDK + Webhooks §2.4 |
| К5 | Обрабатывать next_action.redirect (3DS / hosted page): перевести игрока по redirect_url; финал — webhook/polling, не возврат игрока |
Field Reference §3.1 |
| К6 | Go-live: получить production URL и ключи, пройти чек-лист ниже | — |
Отметка: [О] — Оператор PA, [К] — Казино.
AUTHORIZED/CAPTURED) — полный цикл.PA-Webhook-Signature (HMAC-SHA256 по сырому телу) работает на receiver'е — все типы событий: payment.authorized / payment.captured / payment.refunded / payment.failed (и при включённых выплатах — payout.*).Idempotency-Key возвращает сохранённый результат (Idempotent-Replayed: true); тот же ключ с другим телом → 422 idempotency_key_reuse; webhook-replay по PA-Event-Id не дублирует зачисление.pin_/pay_ и маскированные метаданные.GET /v1/merchants/{id}/webhooks/deliveries?payment_id=… — журнал доставок своих платежей (также вкладка Events and Logs в /portal);GET /v1/payments/{id} — состояние платежа;/healthz — живость PA.Справочник терминов и сокращений Payments API для казино-разработчика. Каждый термин — «что означает для казино»: где вы с ним столкнётесь при интеграции (см. Handover Package и чек-лист онбординга).
| Термин | Расшифровка | Что означает для казино |
|---|---|---|
| PA | Payment Aggregator — платёжная платформа-агрегатор | Платформа, к которой вы интегрируетесь: Payments API, Secure Fields SDK, webhooks, мерчант-портал |
| PSP | Payment Service Provider — платёжный провайдер | Внешний процессор карточных платежей (PayAdmit, Apcopay). PA направляет платежи на PSP через маршрутизацию; decline'ы и 3DS приходят именно от PSP |
| MID | Merchant Identifier — идентификатор мерчанта у PSP | Ваш аккаунт у конкретного PSP. Создаётся и привязывается Оператором (вы получаете merchant_id в PA, MID — «за кадром»); статус MID определяет, идут ли ваши платежи в проде |
| PURC | Purchase — операция покупки | Основная карточная операция депозита: при capture_method: "automatic" PA диспатчит PURC в PSP — авторизация и захват одним вызовом. Успешный PURC = статус AUTHORIZED = можно кредитовать игрока |
| S2S | Server-to-Server — платёж сервер-сервер | Модель, где ваш backend шлёт платёжный запрос напрямую в API PA (в отличие от redirect-модели). Текущий основной флоу: backend + Secure Fields SDK на фронте |
| HPP | Hosted Payment Page — хостед-страница оплаты | Страница оплаты, размещённая у PSP: игрок перенаправляется на неё (next_action: redirect) и вводит данные там. Модель PA: payment_method: {type: "redirect"} — доступна для PayAdmit, PA карту в этом флоу не видит (см. Integration models) |
| 3DS | 3-D Secure — протокол аутентификации держателя карты | Дополнительное подтверждение платежа игроком (challenge на стороне банка/PSP). Если PSP требует 3DS, платёж отвечает next_action: {type: "redirect"} — игрока надо отправить по redirect_url, финал придёт webhook'ом |
| PCI DSS | Payment Card Industry Data Security Standard | Стандарт безопасности карточных данных. Следствие для вас: PAN/CVV должны вводиться только в SDK iframe — ваш backend остаётся вне PCI DSS scope (см. Integration models) |
| vault token | Одноразовый токен токенизации карты | Единственное, что выходит из SDK iframe вместо PAN/CVV (onToken(vaultToken)). Одноразовый, не хранится в логах/localStorage, обменивается на инструмент через POST /v1/payment-instruments |
| next_action | Поле ответа «что делать дальше» | Инструкция клиенту: none / wait / redirect / collect_data / approval. Семантика каждого значения — Field Reference §3.1 |
| capture | Захват авторизованной суммы | При automatic захват выполняется PSP вместе с авторизацией (sale-модель); при manual платёж ждёт отдельного захвата (в текущем публичном API capture-endpoint не экспонирован — используйте automatic) |
| redirect_url | URL из next_action: redirect |
Адрес, на который надо перевести игрока (3DS challenge / hosted page PSP). Возврат игрока на сайт — не результат платежа: финальный статус приходит webhook'ом и/или GET /v1/payments/{id} |
| webhook | Подписанный HTTP-callback о событии платежа | PA доставляет payment.authorized / payment.captured / payment.refunded / payment.failed на ваш endpoint; верифицируйте PA-Webhook-Signature, дедуплицируйте по PA-Event-Id, отвечайте 2xx |
| Idempotency-Key | Заголовок идемпотентности POST-запросов | Обязателен на каждый POST платежей/возвратов/инструментов. Повтор с тем же ключом возвращает сохранённый результат (не создаёт дубль), тот же ключ с другим телом — 422 idempotency_key_reuse |
| Route Target | Маршрут каскада: MID + приоритет + фильтры | Куда PA направит платёж (какой PSP/MID, в каком порядке). Настраивается Оператором; платёж без подходящего маршрута — 422 no_eligible_route |
| connector | Коннектор PSP внутри PA | Программная интеграция PA с конкретным PSP (apcopay, payadmit). Определяет supported-возможности (3DS, capture-методы, платёжные данные) — capabilities маршрута |
POST /v1/payments;Error model of the PA API: RFC 7807 problem responses, the card-decline taxonomy and the stable error codes of every merchant-facing endpoint group.
Every error answer is RFC 7807 application/problem+json:
{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"code": "no_eligible_route",
"message": "no eligible route target for this payment",
"payment_id": "pay_01a0ec3b7f8c4d5e9a1b2c3d"
}
| Field | Meaning |
|---|---|
type |
RFC 7807 type URI; the stable code field is the discriminator |
title |
HTTP status phrase |
status |
HTTP status code |
code |
Stable PA error code — switch on this value, never on message |
message |
Human-readable explanation; never echoes card data |
payment_id |
Payment reference, when the error is bound to one |
Codes are stable PA values: PSP/processor error codes never cross the API boundary.
A declined card is a payment outcome, not an HTTP error: POST /v1/payments answers 201 (the payment resource exists) and GET /v1/payments/{id} answers 200 — the money outcome travels inside the payment resource:
status = FAILED once every attempt and cascade step is exhausted without an authorization;attempts_summary[] carries one entry per attempt — seq, route_target (provider + MID) and the attempt status (DECLINED_SOFT, DECLINED_HARD, UNKNOWN, FAILED_TECHNICAL or AUTHORIZED);payment.failed webhook announces the same outcome (see Webhooks).Every attempt decline is normalized by the platform into exactly one class; the class — never a raw processor code — drives the retry/cascade/stop decision:
| Decline class | Meaning | Platform behavior | Merchant action |
|---|---|---|---|
SOFT_RETRYABLE |
Retryable decline (insufficient funds, 3DS timeout) | Retry on the same route target, then cascade to the next route target | retry-safe — the same card often succeeds on a later retry |
HARD_CASCADE_ALLOWED |
Final for this attempt; another route may still succeed | Cascade continues on the next route target | final for this attempt — retrying with another card/instrument is possible |
HARD_TERMINAL |
Pointless to continue (stolen card, fraud block, invalid instrument) | The payment stops as FAILED; the cascade does not continue |
final — contact support if the outcome is unexpected |
UNKNOWN |
No result: timeout, connection drop, unparsable answer | Sync first — the cascade is blocked until the outcome is resolved | retry-safe — wait; the payment stays PENDING/UNKNOWN_PENDING_SYNC while syncing |
TECHNICAL |
Platform/infrastructure error without proof of execution | Retry of the same attempt, or cascade by policy | retry-safe |
Unknown processor codes default to UNKNOWN — the safe side: sync before anything else.
Decline Type over the API error codes: soft — the same call may succeed later (retry-safe); hard — the call as submitted is final, something must be fixed first; technical — platform-side, retry-safe.
POST /v1/payments, GET /v1/payments/{id}:
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
invalid_request |
400 / 422 | hard | final — fix the request; a corrected retry is safe |
unsupported_media_type |
415 | hard | final — send Content-Type: application/json |
unknown_merchant |
404 / 422 | hard | final — merchant_id is not in this tenant |
unsupported_payment_method |
422 | hard | final — use card (instrument) or redirect |
unknown_instrument |
422 | hard | final — register the instrument first |
card_expired |
422 | hard | final for the card — capture a new one |
invalid_card_number / invalid_card_expiry / invalid_card_cvc / invalid_card_holder |
422 | hard | final — raw-card (H2H) surface validation |
h2h_not_enabled |
422 | hard | contact support — the raw-card gate is closed for this merchant |
no_eligible_route |
422 | hard | contact support — no eligible route target (routing configuration) |
no_eligible_redirect_route |
422 | hard | contact support — no redirect-capable route for type: redirect |
idempotency_in_flight |
409 | soft | retry-safe — wait Retry-After, then GET the payment |
idempotency_key_reuse |
422 | hard | final — a key is replayable only with the same body; new payment = new key |
payment_not_found |
404 | hard | final — a foreign-tenant payment is a plain 404 |
rate_limited |
429 | soft | retry-safe — honor Retry-After |
internal |
500 | technical | retry-safe — transient; contact support if it persists |
POST /v1/refunds:
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
invalid_request |
400 / 422 | hard | final — fix the request |
refund_exceeds_amount |
422 | hard | final — refunds may not exceed the remaining amount; partial refunds sum up |
invalid_state |
422 | hard | final — check the payment status first (refundable states only) |
payment_not_found |
404 | hard | final |
idempotency_in_flight |
409 | soft | retry-safe — wait Retry-After |
idempotency_key_reuse |
422 | hard | final — new refund = new key |
rate_limited |
429 | soft | retry-safe |
internal |
500 | technical | retry-safe |
POST /v1/payment-instruments, GET /v1/payment-instruments/{id}:
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
invalid_request |
400 / 422 | hard | final — fix the request |
unknown_merchant |
422 | hard | final — merchant_id is not in this tenant |
vault_token_unknown |
422 | hard | final — the vault token was not minted; re-run the Secure Fields capture |
vault_token_already_registered |
409 | hard | final — single use: this token is already an instrument |
idempotency_in_flight |
409 | soft | retry-safe — wait Retry-After |
idempotency_key_reuse |
422 | hard | final |
vault_unavailable |
502 | technical | retry-safe — vault-side outage |
rate_limited |
429 | soft | retry-safe |
internal |
500 | technical | retry-safe |
POST /v1/sdk/capture (browser contour — publishable key):
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
invalid_publishable_key |
401 | hard | final — publishable key missing/unknown |
origin_not_allowed |
403 | hard | final — request origin not on the configured allowlist |
invalid_request |
400 / 422 | hard | final — fix the card payload |
capture_rejected |
422 | hard | final — the capture surface rejected the card |
rate_limited |
429 | soft | retry-safe — per-key/per-IP capture quota |
capture_unavailable |
502 | technical | retry-safe — capture surface unreachable |
POST /v1/merchants/{id}/payouts, GET /v1/merchants/{id}/payouts/{payout_id}, POST /v1/merchants/{id}/payouts/{payout_id}/cancel, POST /v1/merchants/{id}/payouts/{payout_id}/approve, POST /v1/merchants/{id}/payouts/{payout_id}/decline:
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
invalid_request |
400 / 422 | hard | final — fix the request (no PAN/CVV anywhere in the payload) |
payouts_not_enabled |
422 | hard | contact support — the payouts gate is off for this merchant |
unknown_instrument |
422 | hard | final — the source instrument is unknown or belongs to another merchant |
instrument_not_payout_eligible |
422 | hard | final — the instrument is not usable as a payout receiver (status DEACTIVATED; the receiver accepts ACTIVE or USED) |
limit_exceeded |
422 | hard | contact support — payout limit exceeded |
payout_not_found |
404 | hard | final |
idempotency_in_flight |
409 | soft | retry-safe — wait Retry-After |
idempotency_key_reuse |
422 | hard | final |
payout_not_cancellable |
409 | hard | final — the payout is outside the merchant-cancellable range (e.g. already approved) |
payout_already_final |
409 | hard | final — the payout is not awaiting approval (self-approval may only decide an AWAITING_APPROVAL payout) |
payout_self_approval_not_enabled |
422 | hard | contact support — the merchant self-approval flag is off; the operator decides the payout |
invalid_state_transition |
409 | hard | final — approval-gate state matrix violation |
rate_limited |
429 | soft | retry-safe |
internal |
500 | technical | retry-safe |
429 rate_limited applies to every endpoint (sliding window per key + endpoint) and always carries Retry-After.
GET /v1/merchants/{id}/providers, PUT /v1/merchants/{id}/providers/{code}:
| Code | HTTP | Decline Type | Merchant action |
|---|---|---|---|
merchant_not_found |
404 | hard | final — a foreign/unknown merchant (or an unconfigured provider code) is a plain 404 |
provider_locked_by_operator |
403 | hard | final — the operator disabled this PSP for the merchant; the merchant cannot re-enable it, contact support |
operator_locked_is_operator_only |
422 | hard | final — remove the operator-only operator_locked field from the request: the merchant cannot set or clear the operator lock |
rate_limited |
429 | soft | retry-safe — honor Retry-After |
internal |
500 | technical | retry-safe — transient; contact support if it persists |
PA delivers one signed event per terminal payment transition. Event types: payment.authorized, payment.captured, payment.refunded, payment.failed — intermediate states (PENDING, UNKNOWN_PENDING_SYNC) are never delivered.
POST <webhook_url> with Content-Type: application/json — full payment.authorized example:
{
"event_id": "0197f6a2-7f8c-7a10-b3ce-2c1a4e5d6f70",
"event_type": "payment.authorized",
"created_at": "2026-09-28T10:05:00Z",
"data": {
"payment_id": "pay_01a0ec3b7f8c4d5e9a1b2c3d",
"merchant_id": "mer_01a0ec3a1b2c4d5e9a1b2c3d",
"status": "AUTHORIZED",
"amount": 1050,
"currency": "EUR",
"instrument_id": "pin_01a0ec3b1a2b4c5d9a1b2c3d",
"correlation_id": "7c1e4a8f0b3d4e5f9a0b1c2d",
"attempts_summary": [
{
"seq": 1,
"route_target": {
"provider": "apcopay",
"mid": "mid-main"
},
"status": "AUTHORIZED"
}
]
}
}
event_id is a UUIDv7 minted once per state transition; data.attempts_summary is the collapsed attempt journal — the same structure the payment resource carries. data carries no PSP secrets and no card data: the instrument appears by its pin_… id only.
Every delivery — first attempt and every retry — carries:
| Header | Value |
|---|---|
PA-Event-Id |
The payload event_id — the receiver dedup key |
PA-Webhook-Signature |
v1=<hex(HMAC-SHA256(raw_body, webhook_secret))> — lowercase hex over the RAW body bytes |
Content-Type |
application/json |
Given the webhook secret whs_5f3a9c1e7b2d4068ae13d5f70c8b9e42 and the exact body above, the signature header is:
PA-Webhook-Signature: v1=0c4377f83b4194131e88c0d61ca00ef7f7727a52b0cf03a079adf849045c0b5d
Any byte difference (whitespace, key order, re-serialization) produces a different signature — verify the RAW bytes.
Verify before parsing JSON, over the raw request body:
expected = "v1=" + lowercase_hex(HMAC_SHA256(key = webhook_secret, message = raw_body))
provided = header "PA-Webhook-Signature"
ok = constant_time_equals(expected, provided)
if not ok:
respond 401 and do not process the event
Reference receiver (Node/Express):
const crypto = require('crypto');
const seen = new Set(); // production: a durable store (DB/Redis), not memory
app.post('/pa/webhook',
express.raw({ type: '*/*' }), // RAW body — required for the signature
(req, res) => {
const sig = String(req.get('PA-Webhook-Signature') || '');
const expected = 'v1=' + crypto.createHmac('sha256', process.env.PA_WEBHOOK_SECRET)
.update(req.body).digest('hex');
const ok = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return res.sendStatus(401); // wrong signature
const eventId = req.get('PA-Event-Id'); // at-least-once delivery
if (seen.has(eventId)) return res.sendStatus(200);
seen.add(eventId);
const ev = JSON.parse(req.body);
switch (ev.event_type) {
case 'payment.authorized':
case 'payment.captured': creditPlayer(ev.data); break; // credit the deposit
case 'payment.refunded': debitPlayer(ev.data); break;
case 'payment.failed': markFailed(ev.data); break;
}
res.sendStatus(200); // 2xx = delivered, otherwise a retry is scheduled
});
PA-Event-Id are stable across attempts; dedup by PA-Event-Id.AUTHORIZED → PARTIALLY_REFUNDED → REFUNDED) carry their own events.DEAD (dead-letter — the payment itself is unaffected). Answer 2xx quickly: the delivery timeout is 5 s by default.DELIVERED (receiver answered 2xx), PENDING (in the retry ladder), DEAD (budget exhausted) describe the notification only — money operations keep working. Delivery log (merchant-scoped): GET /v1/merchants/{id}/webhooks/deliveries with ?payment_id=… per transaction, or the portal Integration tab.POST /v1/merchants/{id}/rotate-webhook-secret re-keys deliveries without downtime:
whs_…) is shown exactly once and becomes active immediately — every delivery after the rotation is signed with the NEW secret;rotated_at + grace (default 7 days; the answer carries old_secret_expires_at) — during the grace window verify BOTH secrets (dual-verify), after it reject the old one;Dual-verify pseudocode:
ok = constant_time_equals(sig, sign(active_secret, raw_body))
if not ok and now < old_secret_expires_at:
ok = constant_time_equals(sig, sign(previous_secret, raw_body))
Registration: the operator registers the endpoint (POST /v1/merchants/{id}/webhook) and hands over the whs_… secret once; the merchant re-targets the URL itself via PATCH /v1/merchants/{id}/webhook-url (HTTPS-only; a URL change does NOT rotate the secret).
Sandbox and production environments: base URLs, mock-vault behavior, test cards and how to get keys.
| Environment | Base URL | Notes |
|---|---|---|
| Production | https://payments.playpulse.tech |
Live processing; production keys are issued separately from sandbox keys |
| Sandbox | https://sandbox.playpulse.tech |
Isolated instance (own process + own database); the mock engine authorizes every well-formed payment locally |
Both environments serve the same API surface: /docs (this reference), /docs/swagger-ui (try-it-out console), /docs/openapi.json (machine-readable spec), /portal (merchant portal), plus the unauthenticated health probes GET /healthz and GET /ready.
429 rate_limited with Retry-After).The sandbox mock vault accepts self-describing demo tokens vtok_<brand>_<last4>-<suffix> — the token names the card it resolves to (vtok_visa_1111-quickstart → VISA ending 1111). Register an instrument with it:
curl -s -X POST "https://sandbox.playpulse.tech/v1/payment-instruments" \
-H "Authorization: Bearer $KEY" -H "Idempotency-Key: qs-instrument-1" \
-H "Content-Type: application/json" \
-d '{"merchant_id":"mer_...","vault_token":"vtok_visa_1111-quickstart","customer_reference":"player_1"}'
# → {"instrument_id":"pin_...","card_meta":{"masked_pan":"****1111","brand":"VISA"},"status":"ACTIVE"}
The production capture surface (POST /v1/sdk/capture behind the Secure Fields SDK) answers with the same single-use vault-token shape — the backend integration does not change between environments.
The PA sandbox mock vault does not validate card numbers at all — cards exist only as vault tokens. Test card numbers matter when the operator attaches a real PSP sandbox route to your merchant:
| Network | Number | Expiry | CVC | Holder | Expected result |
|---|---|---|---|---|---|
| VISA (3DS frictionless) | 4500000000004454 |
12/30 |
any | Frictionless Processed |
Frictionless 3DS → processed → AUTHORIZED |
| VISA (hosted page) | 4111 1111 1111 1111 |
12/30 |
123 |
any | Hosted-page flow with partial-complete semantics in the PSP sandbox |
| Mastercard | 5555 5555 5555 4444 |
12/30 |
123 |
any | Alternate network |
| VISA (3DS challenge) | 4000 0000 0000 0002 |
12/30 |
123 |
any | 3DS challenge flow |
The holder name drives the 3DS scenario: Frictionless Processed completes the challenge without user interaction.
Sandbox and production credentials are issued by the PA operator through the handover package (see the Handover Package guide): tenant API key (Bearer — shown exactly once), merchant id, webhook secret (whs_… — shown exactly once at webhook registration) and the SDK captureUrl. Production keys are issued separately — go-live re-runs the handover against the production base URL (see the Onboarding Checklist guide).
Payment lifecycle (create, read). Status machine: PENDING → AUTHORIZED → CAPTURED → PARTIALLY_REFUNDED → REFUNDED; FAILED; UNKNOWN_PENDING_SYNC.
Payment resource states (GET /v1/payments/{id}, webhook payloads):
| Status | Meaning | Webhook |
|---|---|---|
PENDING |
No confirmed authorization yet; attempts/cascade in progress | not delivered |
AUTHORIZED |
An attempt is authorized (funds held or captured per PSP policy) | payment.authorized |
CAPTURED |
Capture confirmed (when authorization and capture are separate) | payment.captured |
PARTIALLY_REFUNDED |
Confirmed refunds do not cover the full amount | payment.refunded |
REFUNDED |
Full amount refunded | payment.refunded |
FAILED |
Every attempt/cascade step exhausted without an authorization | payment.failed |
UNKNOWN_PENDING_SYNC |
An attempt has no result and sync is in progress; the payment is NOT failed | not delivered — escalates to reconciliation |
Attempt states (inside attempts_summary[]): PENDING (request in flight), AUTHORIZED, DECLINED_SOFT (retryable decline — same-route retry, then cascade), DECLINED_HARD (final for the attempt — the cascade may continue unless the decline class is terminal), UNKNOWN (no result — sync first, cascade blocked until resolved), FAILED_TECHNICAL (platform/infrastructure error without proof of execution).
The decline class behind a DECLINED_* attempt decides the cascade behavior — the full taxonomy is in the Errors reference. While any attempt is UNKNOWN, no new authorization is started on any route (anti-double-charge invariant); the payment stays UNKNOWN_PENDING_SYNC until sync resolves it.
Idempotent payment creation. The request runs the routing cascade (eligible Route Targets by currency/capture method) through the execution engine; the response is the logical payment of the PA model (attempt journal collapsed into attempts_summary, no PSP internals).
Deterministic client errors (unknown_merchant, no_eligible_route, validation failures) are stored with the idempotency record and are replayed identically on retry with the same key.
Requires the Idempotency-Key header.
| Idempotency-Key required | string [ 1 .. 255 ] characters Client-generated unique key of the operation. A retry with the same key + same body replays the stored result of the original request — the ORIGINAL status code (e.g. |
| merchant_id required | string Merchant of this tenant ( |
| amount required | integer >= 1 Positive integer in minor units (cents); |
| currency required | string ISO 4217 alpha-3. Part of the routing eligibility: when no Route Target of the merchant supports the currency, the payment answers |
object Payment method selection — three MUTUALLY EXCLUSIVE families: (1) the saved-card instrument ( | |
| segment | string or null <= 64 characters ^[a-z0-9_-]+$ the optional ROUTING SEGMENT of the payment — the merchant's traffic label. It selects the SEGMENTED routing cascade of the request's method category; when no cascade carries that segment, the DEFAULT cascade ( |
| capture_method | string Default: "automatic" enum: "automatic" "manual"
|
object Customer context (identity/contact); risk fields belong to | |
| risk_context | object Casino-supplied risk context (KYC flags, deposit statistics). Free-form, stored with the payment, write-only (never echoed). The MVP routing does not consume it; the connector projection is data-minimized. |
object Device/session context of the payment. Free-form, stored, write-only (never echoed); it does not affect the MVP routing — EXCEPT the | |
object Billing address; free-form and write-only (never echoed by the payment response). Two consumers: (1) the routing country filter — | |
object Free-form client metadata (e.g. | |
| authentication_type | string enum: "three_ds" "no_three_ds" the 3DS mode of the H2H raw-card form (payment_method.card) — the PSP runs the 3DS challenge. Default no_three_ds. three_ds: the fork answers requires_customer_action + a typed redirect → PA PENDING + next_action.redirect (the existing projection — no new states). The option belongs to the RAW-CARD form only: on the instrument or redirect form (or without payment_method) it is rejected with 422 invalid_request — never silently ignored. three_ds additionally REQUIRES session_context.browser.ip_address. Participates in the canonical idempotency hash: a replay with the same key must carry the same value. |
| customer_ip | string (I-8): the payer's client IP for the S2S dispatch |
| Idempotent-Replayed | string enum: "true" "false"
|
| payment_id required | string |
| status required | string enum: "PENDING" "AUTHORIZED" "CAPTURED" "PARTIALLY_REFUNDED" "REFUNDED" "FAILED" "UNKNOWN_PENDING_SYNC" PA payment status. |
| amount required | integer |
| currency required | string |
| capture_method required | string enum: "automatic" "manual" |
object or object or object or object or object (NextAction) Typed union ( | |
required | Array of objects Collapsed attempt journal: per-attempt sequence number, the public Route Target projection (provider + MID label only, no PSP secrets) and the attempt status. The decline class is NOT part of the summary — it is carried by the full attempt domain model internally, never by this public projection. |
| created_at required | string <date-time> |
{- "merchant_id": "string",
- "amount": 1050,
- "currency": "EUR",
- "payment_method": {
- "type": "card",
- "instrument_id": "pin_01900000-0000-7000-8000-000000000001",
- "card": {
- "card_number": "4500000000004454",
- "card_exp_month": 12,
- "card_exp_year": 2029,
- "card_holder_name": "John Doe",
- "card_cvc": "123"
}
}, - "segment": "vip-eu",
- "capture_method": "automatic",
- "customer": {
- "reference_id": "usr_123",
- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "phone": "35712345678"
}, - "risk_context": { },
- "session_context": {
- "browser": { }
}, - "billing_address": {
- "address_line1": "string",
- "address_line2": "string",
- "city": "string",
- "state": "string",
- "postal_code": "string",
- "country_code": "string",
- "country": "string"
}, - "metadata": { },
- "authentication_type": "three_ds",
- "customer_ip": "203.0.113.7"
}{- "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
- "status": "PENDING",
- "amount": 1050,
- "currency": "EUR",
- "capture_method": "automatic",
- "next_action": {
- "type": "none"
}, - "attempts_summary": [
- {
- "seq": 0,
- "route_target": {
- "provider": "payadmit",
- "mid": "mid_1"
}, - "status": "PENDING"
}
], - "created_at": "2019-08-24T14:15:22Z"
}Returns the last confirmed state of the payment with the collapsed attempt journal. Fresh reads never call the PSP; while the state is PENDING or UNKNOWN_PENDING_SYNC the response carries next_action and a Retry-After header (synchronization is asynchronous — the source of truth is this GET).
| id required | string Payment id ( |
| Retry-After | integer Seconds the client should wait before retrying. |
| payment_id required | string |
| status required | string enum: "PENDING" "AUTHORIZED" "CAPTURED" "PARTIALLY_REFUNDED" "REFUNDED" "FAILED" "UNKNOWN_PENDING_SYNC" PA payment status. |
| amount required | integer |
| currency required | string |
| capture_method required | string enum: "automatic" "manual" |
object or object or object or object or object (NextAction) Typed union ( | |
required | Array of objects Collapsed attempt journal: per-attempt sequence number, the public Route Target projection (provider + MID label only, no PSP secrets) and the attempt status. The decline class is NOT part of the summary — it is carried by the full attempt domain model internally, never by this public projection. |
| created_at required | string <date-time> |
{- "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
- "status": "PENDING",
- "amount": 1050,
- "currency": "EUR",
- "capture_method": "automatic",
- "next_action": {
- "type": "none"
}, - "attempts_summary": [
- {
- "seq": 0,
- "route_target": {
- "provider": "payadmit",
- "mid": "mid_1"
}, - "status": "PENDING"
}
], - "created_at": "2019-08-24T14:15:22Z"
}Card instrument registration from single-use vault tokens (Secure Fields capture surface). No PAN/CVV ever reaches the backend API.
PCI boundary: the browser-side capture surface (PA Secure Fields SDK → PA Locker) tokenizes PAN/CVV into a single-use vault_token. This endpoint registers the instrument in PA — the request struct carries NO card fields and cannot accept PAN/CVV; PA resolves the masked metadata (masked PAN, brand, expiry) from the vault itself. The vault token is a credential: it is consumed for the metadata lookup and stored as a reference only, never serialized back.
Requires the Idempotency-Key header.
| Idempotency-Key required | string [ 1 .. 255 ] characters Client-generated unique key of the operation. A retry with the same key + same body replays the stored result of the original request — the ORIGINAL status code (e.g. |
| merchant_id required | string |
| vault_token required | string Opaque single-use token from the Secure Fields capture surface (credential — never logged, never serialized back). |
| customer_reference | string Casino-side player reference (ownership context; optional). |
| Idempotent-Replayed | string enum: "true" "false"
|
| instrument_id required | string |
| merchant_id required | string |
| status required | string enum: "ACTIVE" "USED" "EXPIRED" "DEACTIVATED" "PURGED" |
required | object (CardMetaResponse) |
| customer_reference | string |
| created_at required | string <date-time> |
| used_at | string <date-time> First payment usage of the single-use instrument. |
{- "merchant_id": "string",
- "vault_token": "string",
- "customer_reference": "string"
}{- "instrument_id": "pin_01900000-0000-7000-8000-000000000001",
- "merchant_id": "string",
- "status": "ACTIVE",
- "card_meta": {
- "masked_pan": "****4242",
- "brand": "VISA",
- "exp_month": "string",
- "exp_year": "string"
}, - "customer_reference": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "used_at": "2019-08-24T14:15:22Z"
}Returns masked card metadata only (masked PAN ****<last4>, brand, optional expiry) and the instrument lifecycle status. No vault token is ever returned.
| id required | string Payment instrument id ( |
| instrument_id required | string |
| merchant_id required | string |
| status required | string enum: "ACTIVE" "USED" "EXPIRED" "DEACTIVATED" "PURGED" |
required | object (CardMetaResponse) |
| customer_reference | string |
| created_at required | string <date-time> |
| used_at | string <date-time> First payment usage of the single-use instrument. |
{- "instrument_id": "pin_01900000-0000-7000-8000-000000000001",
- "merchant_id": "string",
- "status": "ACTIVE",
- "card_meta": {
- "masked_pan": "****4242",
- "brand": "VISA",
- "exp_month": "string",
- "exp_year": "string"
}, - "customer_reference": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "used_at": "2019-08-24T14:15:22Z"
}Idempotent full or partial refund of a payment in AUTHORIZED / CAPTURED / PARTIALLY_REFUNDED / REFUNDED state. The refund amount never exceeds the remaining refundable amount; the payment status is recomputed (PARTIALLY_REFUNDED → REFUNDED). Requires the Idempotency-Key header.
| Idempotency-Key required | string [ 1 .. 255 ] characters Client-generated unique key of the operation. A retry with the same key + same body replays the stored result of the original request — the ORIGINAL status code (e.g. |
| payment_id required | string |
| amount required | integer >= 1 Minor units; must not exceed the remaining refundable amount. |
| reason | string |
| Idempotent-Replayed | string enum: "true" "false"
|
| refund_id required | string |
| payment_id required | string |
| amount required | integer |
| currency required | string |
| status required | string enum: "PENDING" "SUCCEEDED" "FAILED" Refund status. |
| payment_status required | string enum: "AUTHORIZED" "CAPTURED" "PARTIALLY_REFUNDED" "REFUNDED" "FAILED" Recomputed payment status. |
{- "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
- "amount": 1,
- "reason": "string"
}{- "refund_id": "string",
- "payment_id": "string",
- "amount": 0,
- "currency": "string",
- "status": "PENDING",
- "payment_status": "AUTHORIZED"
}Merchant-facing payouts: the casino creates payouts for its own players, reads their statuses and cancels a request before the operator decision. Every payout enters the platform approval gate — a fresh payout is AWAITING_APPROVAL and waits for the operator approve/decline; the PSP execution (dispatch to the payment provider) is the operator-side Phase 2. The surface is gated fail-closed: the per-merchant payouts_enabled toggle (admin PUT /v1/merchants/{id}/payouts-enabled) or the tenant-level payouts flag must be on, otherwise 422 payouts_not_enabled. the OPERATOR may additionally grant the merchant the self-approval waiver (merchants.payout_self_approval, admin PUT /v1/merchants/{id}/payout-self-approval) — while it is ON the merchant confirms its own AWAITING_APPROVAL payouts (approve/decline, merchant-role decisions, audited merchant.payout_approved / merchant.payout_declined); while it is OFF the surface answers 422 payout_self_approval_not_enabled and the four-eyes discipline stands.
The MERCHANT-facing payout create: the casino requests a payout for its own player. The receiver is a payment instrument OF THIS MERCHANT (pin_…) — an unknown or a sibling merchant's instrument is 422 unknown_instrument; the player reference defaults to the instrument's ownership context when customer_reference is omitted.
The payout enters the SAME approval gate as the operator surface: with the default policy it is created AWAITING_APPROVAL and waits for the operator decision (next_action.type = "approval"). The PSP execution is the operator-side Phase 2.
Fail-closed gate: the surface requires the tenant-level payouts_enabled gate AND the per-merchant payouts_enabled toggle — otherwise 422 payouts_not_enabled.
Authorization: the admin (tenant) Bearer or the merchant-scoped key — a merchant key may only address ITS OWN merchant (a foreign path is a plain 404).
Requires the Idempotency-Key header.
| id required | string Merchant id ( |
| Idempotency-Key required | string [ 1 .. 255 ] characters Client-generated unique key of the operation. A retry with the same key + same body replays the stored result of the original request — the ORIGINAL status code (e.g. |
| instrument_id | string Card-based receiver form: PA instrument of the path merchant. Must reference a payment instrument OF THIS MERCHANT in this tenant — an unknown or a sibling merchant's instrument is |
| amount required | integer >= 1 Amount in minor units. |
| currency required | string ISO 4217 alpha-3 currency. |
| customer_reference | string Casino-side player reference. Optional on the instrument form — defaults to the instrument's ownership context when the instrument carries one (required explicitly otherwise); REQUIRED on the |
| receiver | object Masked receiver metadata; PAN/CVV keys are rejected with |
| risk_context | object Risk context consumed by the payout approval policy; PAN/CVV keys are rejected. |
| retry_of_payout_id | string Original payout when retrying after a confirmed DECLINED (a new payout, not a second financial attempt). |
object the H2H raw-card receiver — the payout CREDITS this card. Gated by the H2H flags (deployment kill-switch + per-merchant |
| Idempotent-Replayed | string enum: "true" "false"
|
| payout_id required | string |
| status required | string enum: "CREATED" "AWAITING_APPROVAL" "APPROVED" "PROCESSING" "COMPLETED" "DECLINED" "FAILED_TECHNICAL" "CANCELLED" "UNKNOWN_PENDING_SYNC" PA payout status. Phase-1 reachable through this API: |
| amount required | integer |
| currency required | string |
| customer_reference required | string |
object or object or object or object or object (NextAction) Typed union ( | |
required | Array of objects |
Array of objects Approval-gate decisions (present after a gate mutation). | |
| version required | integer Optimistic-concurrency version of the aggregate. |
| created_at required | string <date-time> |
{- "instrument_id": "string",
- "amount": 1,
- "currency": "string",
- "customer_reference": "string",
- "receiver": { },
- "risk_context": { },
- "retry_of_payout_id": "string",
- "receiver_card": {
- "card_number": "string",
- "card_exp_month": 0,
- "card_exp_year": 0,
- "card_holder_name": "string"
}
}{- "payout_id": "string",
- "status": "CREATED",
- "amount": 0,
- "currency": "string",
- "customer_reference": "string",
- "next_action": {
- "type": "none"
}, - "attempts_summary": [
- {
- "seq": 0,
- "status": "string"
}
], - "approval_decisions": [
- {
- "decision": "APPROVED",
- "policy_id": "string",
- "actor": "string",
- "role": "string",
- "reason": "string",
- "snapshot_hash": "string",
- "decided_at": "2019-08-24T14:15:22Z"
}
], - "version": 0,
- "created_at": "2019-08-24T14:15:22Z"
}The merchant's own payout list — newest first, filter-scoped total, clamped page (default 50, capped 200). Authorization: the admin (tenant) Bearer or the merchant-scoped key (a foreign merchant path is a plain 404). Fail-closed: 422 payouts_not_enabled while the merchant gate is off.
| id required | string Merchant id ( |
| status | string enum: "CREATED" "AWAITING_APPROVAL" "APPROVED" "PROCESSING" "COMPLETED" "DECLINED" "FAILED_TECHNICAL" "CANCELLED" "UNKNOWN_PENDING_SYNC" Optional payout-status filter (the canonical registry). |
| limit | integer [ 1 .. 200 ] Default: 50 Page size (clamped to 200). |
| offset | integer >= 0 Default: 0 Page offset (0-based). |
| total required | integer Total payouts matching the filter (independent of the page). |
| limit required | integer |
| offset required | integer |
| count required | integer Payouts on this page. |
| status | string enum: "CREATED" "AWAITING_APPROVAL" "APPROVED" "PROCESSING" "COMPLETED" "DECLINED" "FAILED_TECHNICAL" "CANCELLED" "UNKNOWN_PENDING_SYNC" Echoed status filter (absent = no filter). |
required | Array of objects (MerchantPayoutListItem) |
{- "total": 0,
- "limit": 0,
- "offset": 0,
- "count": 0,
- "status": "CREATED",
- "payouts": [
- {
- "payout_id": "string",
- "status": "CREATED",
- "amount": 0,
- "currency": "string",
- "customer_reference": "string",
- "instrument_id": "string",
- "instrument": "string",
- "version": 0,
- "created_at": "2019-08-24T14:15:22Z"
}
]
}The payout state of the merchant's own payout: status, amounts, attempts summary, approval decisions and next_action (approval while the operator gate is active). The payout must belong to the path merchant — a sibling merchant's payout (or a foreign id) is a plain 404 (payout_not_found), never a 403. Fail-closed: 422 payouts_not_enabled while the merchant gate is off.
| id required | string Merchant id ( |
| id required | string Payout id ( |
| payout_id required | string |
| status required | string enum: "CREATED" "AWAITING_APPROVAL" "APPROVED" "PROCESSING" "COMPLETED" "DECLINED" "FAILED_TECHNICAL" "CANCELLED" "UNKNOWN_PENDING_SYNC" PA payout status. Phase-1 reachable through this API: |
| amount required | integer |
| currency required | string |
| customer_reference required | string |
object or object or object or object or object (NextAction) Typed union ( | |
required | Array of objects |
Array of objects Approval-gate decisions (present after a gate mutation). | |
| version required | integer Optimistic-concurrency version of the aggregate. |
| created_at required | string <date-time> |
{- "payout_id": "string",
- "status": "CREATED",
- "amount": 0,
- "currency": "string",
- "customer_reference": "string",
- "next_action": {
- "type": "none"
}, - "attempts_summary": [
- {
- "seq": 0,
- "status": "string"
}
], - "approval_decisions": [
- {
- "decision": "APPROVED",
- "policy_id": "string",
- "actor": "string",
- "role": "string",
- "reason": "string",
- "snapshot_hash": "string",
- "decided_at": "2019-08-24T14:15:22Z"
}
], - "version": 0,
- "created_at": "2019-08-24T14:15:22Z"
}The MERCHANT cancel: the casino withdraws its own payout request while it is still CREATED/AWAITING_APPROVAL — before the operator decision. STRICTLY NARROWER than the operator cancel: an operator-APPROVED payout answers 409 payout_not_cancellable (the execution flow belongs to the operator). The released limit reservations are freed (proven non-execution). Idempotent; empty body allowed (reason optional).
| id required | string Merchant id ( |
| id required | string Payout id ( |
| Idempotency-Key required | string [ 1 .. 255 ] characters Client-generated unique key of the operation. A retry with the same key + same body replays the stored result of the original request — the ORIGINAL status code (e.g. |
| reason | string |
| payout_id required | string |
| status required | string enum: "CREATED" "AWAITING_APPROVAL" "APPROVED" "PROCESSING" "COMPLETED" "DECLINED" "FAILED_TECHNICAL" "CANCELLED" "UNKNOWN_PENDING_SYNC" PA payout status. Phase-1 reachable through this API: |
| amount required | integer |
| currency required | string |
| customer_reference required | string |
object or object or object or object or object (NextAction) Typed union ( | |
required | Array of objects |
Array of objects Approval-gate decisions (present after a gate mutation). | |
| version required | integer Optimistic-concurrency version of the aggregate. |
| created_at required | string <date-time> |
{- "reason": "string"
}{- "payout_id": "string",
- "status": "CREATED",
- "amount": 0,
- "currency": "string",
- "customer_reference": "string",
- "next_action": {
- "type": "none"
}, - "attempts_summary": [
- {
- "seq": 0,
- "status": "string"
}
], - "approval_decisions": [
- {
- "decision": "APPROVED",
- "policy_id": "string",
- "actor": "string",
- "role": "string",
- "reason": "string",
- "snapshot_hash": "string",
- "decided_at": "2019-08-24T14:15:22Z"
}
], - "version": 0,
- "created_at": "2019-08-24T14:15:22Z"
}