PA Payments API (1.0.0)

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:

  • Authentication: Authorization: Bearer <tenant_api_key> for every /v1 route (see securitySchemes.bearerAuth). Health probes and the docs portal are unauthenticated.
  • Money: integer minor units (cents) + ISO 4217 alpha-3 currency.
  • Identifiers: type-safe prefixed UUIDs (pay_…, mer_…, pin_…, pout_…, tn_…, key_…).
  • Idempotency: mutating requests take an 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.
  • Errors: RFC 7807 application/problem+json with stable PA code values; PSP error codes are never exposed.
  • Rate limiting: every authenticated request consumes a sliding-window slot (default 100 rpm per tenant+endpoint); over-limit returns 429 rate_limited with Retry-After.
  • Interactive reference: 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.
  • Guides: the same /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):

  1. Get your keys — the PA operator hands over the integration package: the tenant API key (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.
  2. Create the first payment — mount the Secure Fields SDK in the deposit page (iframe capture → single-use 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.
  3. Stand up the webhook receiver — verify 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).
  4. Walk the onboarding checklist — the Onboarding Checklist guide details every integration step and the go-live criteria.
  5. Go live — request the production base URL 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.

Handover Package

Приветствуем! Вы получили доступ к платформе платежей 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.


1. Ключи доступа — шаблон (заполняет Оператор PA)

⚠️ Секреты выдаются ровно один раз. Значения передаются по защищённому каналу и показываются единожды — сразу сохраните их в свой 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)

2. Что вы получаете

Артефакт Где получить Назначение
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 модель выплат, статус поверхности

3. Ваша интеграция — 6 шагов

Нумерация ниже — маршрут казино «от виджета до go-live». В чек-листе шаги детализированы своей нумерацией К1–К6; в скобках — куда смотреть за деталями.

К1. Подключить SDK iframe (frontend) — [чек-лист §5/К1]

<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).

К2. Поднять webhook receiver (backend) — [чек-лист §5/К4]

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.

К3. Sandbox-платёж (backend) — [чек-лист §5/К2–К3]

Два вызова с 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.

К4. Redirect — 3DS / hosted page PSP — [чек-лист §5/К5]

Если ответ содержит next_action: {"type": "redirect", "redirect_url": "…", "method": "GET"} — переведите игрока по redirect_url. Возврат игрока на сайт — не результат: финальный статус приходит webhook'ом (К2) и/или через GET /v1/payments/{id}.

К5. Возвраты (refunds) — Payments API (RU)

POST /v1/refunds
Idempotency-Key: <uuid>
{"payment_id": "pay_…", "amount": 1050, "reason": "requested_by_customer"}

Частичные возвраты суммируются с контролем не-превышения AUTHORIZED-суммы; статусы PARTIALLY_REFUNDED → REFUNDED приходят webhook'ом (событие payment.refunded, К2). Полный цикл возвратов подтверждён acceptance-прогоном.

К6. Go-live — [чек-лист §6]

Запросите у Оператора production base URL и production ключи (tenant API key + whs_-секрет production MID) и пройдите go-live чек-лист §6 (7 пунктов: полный цикл, HMAC, идемпотентность, PCI-гигиена, ротации ключей, production MID ENABLED, мониторинг).

4. Правила безопасности (обязательные)

  1. PCI: PAN/CVV вводятся только в SDK iframe и уходят напрямую в capture-поверхность; ваш backend и PA видят только vault_token/pin_ и маскированные метаданные. PAN/CVV — никогда в логи, БД, аудит (acceptance: 0 PAN).
  2. HMAC-верификация обязательна: PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, whs_секрет))> над сырым телом, сравнение timing-safe; без валидной подписи — не обрабатывать (401). Дедуп по PA-Event-Id (= event_id payload, UUIDv7).
  3. Секреты — не в git, не в логах, не в URL; хранение — secret store. Ротация: tenant-ключ POST /v1/tenants/{id}/rotate-key (новый сразу, старый 24 ч grace), webhook-секрет POST /v1/merchants/{id}/rotate-webhook-secret (grace 7 дней, dual-verify).
  4. Идемпотентность обязательна: Idempotency-Key: <uuid> на каждый POST; повтор с тем же ключом возвращает сохранённый результат (Idempotent-Replayed: true), тот же ключ с другим телом → 422 idempotency_key_reuse. Webhook-replay по PA-Event-Id не должен дублировать зачисление игроку.

5. Ограничения текущего релиза

Ограничение Суть Когда снимается
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

6. TL;DR (English)

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.

Приложение — полные ссылки

  • Глоссарий терминов (PA, PSP, MID, PURC, S2S, HPP, 3DS, PCI DSS, vault token, webhook…): Термінологія — что означает каждый термин для казино.
  • Модели интеграции и PCI DSS scope: Integration models — SDK iframe (рекомендовано) / hosted payment page PSP — redirect (redirect_hpp) / почему S2S raw card не предоставляется.
  • Выплаты: Payouts — Phase 2 — модель approval-gate и статус поверхности.
  • Чек-лист онбординга казино (RU Часть I + EN Part II): Onboarding Checklist — детальные шаги К1–К6 / C1–C6, предусловия §2, go-live §6, эскалация §7.
  • API-доки: Payments API (RU) · SDK + Webhooks (RU) · Field Reference · OpenAPI: /docs/openapi.json — референс /docs (Redocly) и Swagger UI /docs/swagger-ui на вашем base URL (раздел 1).
  • Live-примеры и тестовые карты: выдаёт Оператор вместе с SDK-пакетом (раздел «Что вы получаете»); тестовые карты для sandbox — 4111 1111 1111 1111 (12/30, CVC 123), 5555 5555 5555 4444 (MC), 4000 0000 0000 0002 (3DS).

1. Ключи доступа — шаблон (заполняет Оператор PA)

⚠️ Секреты выдаются ровно один раз. Значения передаются по защищённому каналу и показываются единожды — сразу сохраните их в свой 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)

2. Что вы получаете

Артефакт Где получить Назначение
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 модель выплат, статус поверхности

3. Ваша интеграция — 6 шагов

Нумерация ниже — маршрут казино «от виджета до go-live». В чек-листе шаги детализированы своей нумерацией К1–К6; в скобках — куда смотреть за деталями.

К1. Подключить SDK iframe (frontend) — [чек-лист §5/К1]

<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).

К2. Поднять webhook receiver (backend) — [чек-лист §5/К4]

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.

К3. Sandbox-платёж (backend) — [чек-лист §5/К2–К3]

Два вызова с 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.

К4. Redirect — 3DS / hosted page PSP — [чек-лист §5/К5]

Если ответ содержит next_action: {"type": "redirect", "redirect_url": "…", "method": "GET"} — переведите игрока по redirect_url. Возврат игрока на сайт — не результат: финальный статус приходит webhook'ом (К2) и/или через GET /v1/payments/{id}.

К5. Возвраты (refunds) — Payments API (RU)

POST /v1/refunds
Idempotency-Key: <uuid>
{"payment_id": "pay_…", "amount": 1050, "reason": "requested_by_customer"}

Частичные возвраты суммируются с контролем не-превышения AUTHORIZED-суммы; статусы PARTIALLY_REFUNDED → REFUNDED приходят webhook'ом (событие payment.refunded, К2). Полный цикл возвратов подтверждён acceptance-прогоном.

К6. Go-live — [чек-лист §6]

Запросите у Оператора production base URL и production ключи (tenant API key + whs_-секрет production MID) и пройдите go-live чек-лист §6 (7 пунктов: полный цикл, HMAC, идемпотентность, PCI-гигиена, ротации ключей, production MID ENABLED, мониторинг).

4. Правила безопасности (обязательные)

  1. PCI: PAN/CVV вводятся только в SDK iframe и уходят напрямую в capture-поверхность; ваш backend и PA видят только vault_token/pin_ и маскированные метаданные. PAN/CVV — никогда в логи, БД, аудит (acceptance: 0 PAN).
  2. HMAC-верификация обязательна: PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, whs_секрет))> над сырым телом, сравнение timing-safe; без валидной подписи — не обрабатывать (401). Дедуп по PA-Event-Id (= event_id payload, UUIDv7).
  3. Секреты — не в git, не в логах, не в URL; хранение — secret store. Ротация: tenant-ключ POST /v1/tenants/{id}/rotate-key (новый сразу, старый 24 ч grace), webhook-секрет POST /v1/merchants/{id}/rotate-webhook-secret (grace 7 дней, dual-verify).
  4. Идемпотентность обязательна: Idempotency-Key: <uuid> на каждый POST; повтор с тем же ключом возвращает сохранённый результат (Idempotent-Replayed: true), тот же ключ с другим телом → 422 idempotency_key_reuse. Webhook-replay по PA-Event-Id не должен дублировать зачисление игроку.

5. Ограничения текущего релиза

Ограничение Суть Когда снимается
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

6. TL;DR (English)

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.

Приложение — полные ссылки

  • Глоссарий терминов (PA, PSP, MID, PURC, S2S, HPP, 3DS, PCI DSS, vault token, webhook…): Термінологія — что означает каждый термин для казино.
  • Модели интеграции и PCI DSS scope: Integration models — SDK iframe (рекомендовано) / hosted payment page PSP — redirect (redirect_hpp) / почему S2S raw card не предоставляется.
  • Выплаты: Payouts — Phase 2 — модель approval-gate и статус поверхности.
  • Чек-лист онбординга казино (RU Часть I + EN Part II): Onboarding Checklist — детальные шаги К1–К6 / C1–C6, предусловия §2, go-live §6, эскалация §7.
  • API-доки: Payments API (RU) · SDK + Webhooks (RU) · Field Reference · OpenAPI: /docs/openapi.json — референс /docs (Redocly) и Swagger UI /docs/swagger-ui на вашем base URL (раздел 1).
  • Live-примеры и тестовые карты: выдаёт Оператор вместе с SDK-пакетом (раздел «Что вы получаете»); тестовые карты для sandbox — 4111 1111 1111 1111 (12/30, CVC 123), 5555 5555 5555 4444 (MC), 4000 0000 0000 0002 (3DS).

Integration models

Как казино может принимать карточные депозиты через PA, чем модели отличаются и что каждая значит для вашего PCI DSS scope. Ключи и шаги интеграции — Handover Package; детали SDK — SDK + Webhooks и SDK README.

(a) Secure Fields SDK — рекомендуется, доступно сейчас

Рекомендованная модель: iframe-виджет на странице депозита.

Как это работает:

  1. Вы подключаете SDK одним script tag и создаёте контейнер виджета:
  <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.

  1. PAN/CVV игрок вводит внутри iframe, размещённого на origin PA; значения полей недоступны JS казино. Данные карты уходят напрямую в capture-поверхность PA — мимо вашего backend.

  2. Ваш 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.

(b) Hosted payment page PSP (redirect) — доступна для PayAdmit, BTQ Finance и AVGentlements

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 ещё не выданы).

Как это работает:

  1. Ваш backend создаёт платёж без каких-либо карточных данных:
  { "payment_method": { "type": "redirect" } }

(card и instrument_id в redirect-форме запрещены — 422 invalid_request; поля платежа — Field Reference §2.3).

  1. Ответ 201 несёт status: PENDING и next_action: {type: "redirect", redirect_url, method: "GET"} — вы переводите игрока по redirect_url (хостед-страница PSP; возврат игрока — не результат, финал — webhook и/или GET /v1/payments/{id}, шаг К5 чек-листа).

  2. Роутинг: платёж исполняется только на Route Target с capability redirect_hpp=true (PayAdmit hosted-checkout, BTQ Checkout, AVGentlements HPP); если такого маршрута нет — 422 no_eligible_redirect_route ещё до исполнения.

  • Статус: реализовано для PayAdmit и BTQ Finance; AVGentlements — контракт и решение о размещении готовы ( [placement-decision.md] ), включение после выдачи кредов PSP и live-гейта. Раньше модель была roadmap'ом Phase 2; теперь redirect-значение next_action используется и для 3DS challenge, и для hosted page PSP (PayAdmit CARDSHPP, BTQ Checkout, AVGentlements HPP), и создаётся платежом payment_method.type=redirect.
  • BTQ Finance: флоу hosted-страницы. Платформа создаёт платёжный инвойс провайдера, игрок переводится на готовую страницу BTQ Checkout, вводит карту и проходит 3DS там; финал приходит webhook'ом или polling'ом GET /v1/payments/{id} (шаг К5 чек-листа). Тестовые карты BTQ — Field Reference §12.
  • PCI-следствие то же, что у SDK: карта вводится вне вашей среды — и даже вне PA (PA не принимает и не видит PAN в этой модели вовсе: 0 PAN в запросе, ответе, БД и логах).
  • Финал: webhook payment.authorized / payment.failed (подписанный) или polling GET /v1/payments/{id}.

(c) S2S raw card — только для PCI DSS certified мерчантов (модель (d))

Модель «полный server-to-server»: ваш backend принимает номер карты и CVV игрока и пересылает их в платёжный API.

Без сертификации такой путь не предоставляется. Причины — честно:

  1. Ваш PCI DSS scope становится максимальным. Как только PAN проходит через системы казино (приём, буферизация, логи приложений, backends), казино попадает в полный PCI DSS scope — самооценка SAQ D (или A-EP для «только редирект-приёма», что raw-card всё равно не даёт). Это ежегодный аудит, сегментация сети, шифрование хранимых данных и несоизмеримо больший комплаенс-бюджет. Для несертифицированных мерчантов аргумент остаётся в полной силе: собрать карту без SDK iframe — задача модели (b) hosted page PSP (redirect), а не raw-card S2S.
  2. По умолчанию PA принимает карту только от capture-поверхности. raw-card форма (payment_method.card) закрыта двухуровневым fail-closed гейтом и открывается оператором только для мерчанта с собственной сертифицированной PCI DSS средой — см. модель (d) ниже.

(d) H2H (S2S raw card) — по запросу, для PCI DSS certified мерчантов

Статус: по запросу (включение — операторская процедура). Модель для казино, чей 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).

Как это работает:

  1. Ваш backend принимает PAN/CVV игрока в вашем PCI scope и создаёт платёж обычным вызовом 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, каскад, вебхуки, статусы — без нового контракта.

  1. PA транзитом передаёт карту в платёжный процессор: PAN/CVV живут в памяти PA только в момент валидации и диспетча — не сохраняются в PA, не логируются, не попадают в вебхуки/аудит (0 PAN persistence).
  2. Невалидная карта отклоняется на PA (Luhn/expiry/holder/CVC) и никогда не доходит до PSP. На H2H действует отдельный жёсткий rate limit на создания (429 rate_limited + Retry-After) поверх обычного лимита /v1/payments — тот же per-merchant бюджет расходуют и raw-card выплаты: модель одна, поверхность одна.
  3. 3DS-флоу включается опцией 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 — точка транзита без хранения.

3DS в модели (d) — опция authentication_type

По умолчанию raw-card платёж диспетчится в режиме no_three_ds — поведение, существующие запросы не меняются. 3DS включается на запрос:

{
  "payment_method": { "type": "card", "card": { "…": "…" } },
  "authentication_type": "three_ds"
}

Как это работает:

  1. PSP инициирует 3DS-челлендж: PA отвечает 201 со статусом PENDING и next_action: {type: "redirect", redirect_url} — вы переводите игрока на банковскую 3DS-страницу; финал возвращается webhook'ом (payment. authorized/payment.failed) или polling'ом GET /v1/payments/{id}.
  2. Обязательное поле 3DS-набора: session_context.browser.ip_address (parseable IP). Без него запрос с three_ds отклоняется на PA (422 invalid_request, до диспетча): эквайер отклоняет операцию без Client.IPAddress, и honest-поведение — fail-fast на PA, а не зависшая попытка на стороне PSP.
  3. Значение опции — закрытое множество: three_ds | no_three_ds; всё другое → 422 invalid_request. Опция принадлежит raw-card форме: на instrument_id- и redirect-формах она отклоняется (422 invalid_request).
  4. Живой статус на Apcopay-sandbox: three_ds принимается и диспетчится, эквайер запускает челлендж; проекция PENDING+redirect на живом коннекторе Apcopay уточняется (актуальный статус модели — у Оператора; контракт доказан автоматическими e2e-тестами).

Выплата по raw-card в модели (d) — receiver_card

Для 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).
  • БЕЗ CVV — честно: CVV для зачисления (credit) не нужен — PSP-флоу выплаты («добавить карту получателя» / WITHDRAWAL) принимает карту без CVV (зачисление работает без CVV). Блок receiver_card поля CVC не имеет; прислать его нельзя — контракт отвергнет неизвестное поле громко.
  • Гейт: тот же двухуровневый H2H (PA_H2H_ENABLED + merchants.h2h_enabled) — receiver-форма несёт PAN в среду PA, это та же H2H-семантика («свой checkout мерчанта»); выключенный гейт → 422 h2h_not_enabled. Отдельно выплаты должны быть включены (payouts_enabled).
  • Валидация до диспетча: Luhn/expiry/holder (тот же валидатор, что у депозита, минус CVC); невалидная карта отклоняется на PA и никогда не попадает в запись выплаты.
  • 0 PAN в PA: в записи выплаты сохраняется только МАСКИРОВАННЫЙ снапшот — brand + last4 + срок (тот же класс данных, что у instrument-выплаты); PAN/holder в БД, логах, аудите и вебхуках отсутствуют.
  • Статус: выплата создаётся в AWAITING_APPROVAL (операторский gate); реальный диспетч в PSP — Phase 2, для receiver-выплаты платёжно-системный вызов состоится после его реализации и одобрения оператором.
  • customer_reference на этой форме обязателен (нет инструмента, из которого он обычно берётся).
  • Rate limit: raw-card выплаты расходуют тот же per-merchant H2H-бюджет, что и raw-card депозиты (превышение → 429 rate_limited).

Управление набором PSP

Базовый набор платёжных провайдеров (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 — не меняется

Связанные материалы

(a) Secure Fields SDK — рекомендуется, доступно сейчас

Рекомендованная модель: iframe-виджет на странице депозита.

Как это работает:

  1. Вы подключаете SDK одним script tag и создаёте контейнер виджета:
  <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.

  1. PAN/CVV игрок вводит внутри iframe, размещённого на origin PA; значения полей недоступны JS казино. Данные карты уходят напрямую в capture-поверхность PA — мимо вашего backend.

  2. Ваш 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.

(b) Hosted payment page PSP (redirect) — доступна для PayAdmit, BTQ Finance и AVGentlements

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 ещё не выданы).

Как это работает:

  1. Ваш backend создаёт платёж без каких-либо карточных данных:
  { "payment_method": { "type": "redirect" } }

(card и instrument_id в redirect-форме запрещены — 422 invalid_request; поля платежа — Field Reference §2.3).

  1. Ответ 201 несёт status: PENDING и next_action: {type: "redirect", redirect_url, method: "GET"} — вы переводите игрока по redirect_url (хостед-страница PSP; возврат игрока — не результат, финал — webhook и/или GET /v1/payments/{id}, шаг К5 чек-листа).

  2. Роутинг: платёж исполняется только на Route Target с capability redirect_hpp=true (PayAdmit hosted-checkout, BTQ Checkout, AVGentlements HPP); если такого маршрута нет — 422 no_eligible_redirect_route ещё до исполнения.

  • Статус: реализовано для PayAdmit и BTQ Finance; AVGentlements — контракт и решение о размещении готовы ( [placement-decision.md] ), включение после выдачи кредов PSP и live-гейта. Раньше модель была roadmap'ом Phase 2; теперь redirect-значение next_action используется и для 3DS challenge, и для hosted page PSP (PayAdmit CARDSHPP, BTQ Checkout, AVGentlements HPP), и создаётся платежом payment_method.type=redirect.
  • BTQ Finance: флоу hosted-страницы. Платформа создаёт платёжный инвойс провайдера, игрок переводится на готовую страницу BTQ Checkout, вводит карту и проходит 3DS там; финал приходит webhook'ом или polling'ом GET /v1/payments/{id} (шаг К5 чек-листа). Тестовые карты BTQ — Field Reference §12.
  • PCI-следствие то же, что у SDK: карта вводится вне вашей среды — и даже вне PA (PA не принимает и не видит PAN в этой модели вовсе: 0 PAN в запросе, ответе, БД и логах).
  • Финал: webhook payment.authorized / payment.failed (подписанный) или polling GET /v1/payments/{id}.

(c) S2S raw card — только для PCI DSS certified мерчантов (модель (d))

Модель «полный server-to-server»: ваш backend принимает номер карты и CVV игрока и пересылает их в платёжный API.

Без сертификации такой путь не предоставляется. Причины — честно:

  1. Ваш PCI DSS scope становится максимальным. Как только PAN проходит через системы казино (приём, буферизация, логи приложений, backends), казино попадает в полный PCI DSS scope — самооценка SAQ D (или A-EP для «только редирект-приёма», что raw-card всё равно не даёт). Это ежегодный аудит, сегментация сети, шифрование хранимых данных и несоизмеримо больший комплаенс-бюджет. Для несертифицированных мерчантов аргумент остаётся в полной силе: собрать карту без SDK iframe — задача модели (b) hosted page PSP (redirect), а не raw-card S2S.
  2. По умолчанию PA принимает карту только от capture-поверхности. raw-card форма (payment_method.card) закрыта двухуровневым fail-closed гейтом и открывается оператором только для мерчанта с собственной сертифицированной PCI DSS средой — см. модель (d) ниже.

(d) H2H (S2S raw card) — по запросу, для PCI DSS certified мерчантов

Статус: по запросу (включение — операторская процедура). Модель для казино, чей 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).

Как это работает:

  1. Ваш backend принимает PAN/CVV игрока в вашем PCI scope и создаёт платёж обычным вызовом 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, каскад, вебхуки, статусы — без нового контракта.

  1. PA транзитом передаёт карту в платёжный процессор: PAN/CVV живут в памяти PA только в момент валидации и диспетча — не сохраняются в PA, не логируются, не попадают в вебхуки/аудит (0 PAN persistence).
  2. Невалидная карта отклоняется на PA (Luhn/expiry/holder/CVC) и никогда не доходит до PSP. На H2H действует отдельный жёсткий rate limit на создания (429 rate_limited + Retry-After) поверх обычного лимита /v1/payments — тот же per-merchant бюджет расходуют и raw-card выплаты: модель одна, поверхность одна.
  3. 3DS-флоу включается опцией 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 — точка транзита без хранения.

3DS в модели (d) — опция authentication_type

По умолчанию raw-card платёж диспетчится в режиме no_three_ds — поведение, существующие запросы не меняются. 3DS включается на запрос:

{
  "payment_method": { "type": "card", "card": { "…": "…" } },
  "authentication_type": "three_ds"
}

Как это работает:

  1. PSP инициирует 3DS-челлендж: PA отвечает 201 со статусом PENDING и next_action: {type: "redirect", redirect_url} — вы переводите игрока на банковскую 3DS-страницу; финал возвращается webhook'ом (payment. authorized/payment.failed) или polling'ом GET /v1/payments/{id}.
  2. Обязательное поле 3DS-набора: session_context.browser.ip_address (parseable IP). Без него запрос с three_ds отклоняется на PA (422 invalid_request, до диспетча): эквайер отклоняет операцию без Client.IPAddress, и honest-поведение — fail-fast на PA, а не зависшая попытка на стороне PSP.
  3. Значение опции — закрытое множество: three_ds | no_three_ds; всё другое → 422 invalid_request. Опция принадлежит raw-card форме: на instrument_id- и redirect-формах она отклоняется (422 invalid_request).
  4. Живой статус на Apcopay-sandbox: three_ds принимается и диспетчится, эквайер запускает челлендж; проекция PENDING+redirect на живом коннекторе Apcopay уточняется (актуальный статус модели — у Оператора; контракт доказан автоматическими e2e-тестами).

Выплата по raw-card в модели (d) — receiver_card

Для 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).
  • БЕЗ CVV — честно: CVV для зачисления (credit) не нужен — PSP-флоу выплаты («добавить карту получателя» / WITHDRAWAL) принимает карту без CVV (зачисление работает без CVV). Блок receiver_card поля CVC не имеет; прислать его нельзя — контракт отвергнет неизвестное поле громко.
  • Гейт: тот же двухуровневый H2H (PA_H2H_ENABLED + merchants.h2h_enabled) — receiver-форма несёт PAN в среду PA, это та же H2H-семантика («свой checkout мерчанта»); выключенный гейт → 422 h2h_not_enabled. Отдельно выплаты должны быть включены (payouts_enabled).
  • Валидация до диспетча: Luhn/expiry/holder (тот же валидатор, что у депозита, минус CVC); невалидная карта отклоняется на PA и никогда не попадает в запись выплаты.
  • 0 PAN в PA: в записи выплаты сохраняется только МАСКИРОВАННЫЙ снапшот — brand + last4 + срок (тот же класс данных, что у instrument-выплаты); PAN/holder в БД, логах, аудите и вебхуках отсутствуют.
  • Статус: выплата создаётся в AWAITING_APPROVAL (операторский gate); реальный диспетч в PSP — Phase 2, для receiver-выплаты платёжно-системный вызов состоится после его реализации и одобрения оператором.
  • customer_reference на этой форме обязателен (нет инструмента, из которого он обычно берётся).
  • Rate limit: raw-card выплаты расходуют тот же per-merchant H2H-бюджет, что и raw-card депозиты (превышение → 429 rate_limited).

Управление набором PSP

Базовый набор платёжных провайдеров (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 — не меняется

Связанные материалы

SDK + Webhooks

Контракт токенизации карты и платёжных инструментов: Secure Fields SDK (browser-capture через POST /v1/sdk/capture, publishable key — см. §4). Связанные гайды: Field Reference (поля платежа), Integration models (модели интеграции и PCI scope), SDK README (быстрый старт), Термінологія.

1. Общая схема (PCI boundary)

┌──────────────────────────── казино (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-тестами платформы):

  1. PAN/CVV никогда не попадают в PA — ни в app DB, ни в логи, ни в audit details, ни в error messages, ни в тела запросов PA API (схема запроса не содержит карточных полей вовсе).
  2. Единственное, что PA хранит о карте: vault token reference (явное PCI-исключение — ссылка на PAN в vault) + маскированные метаданные из ответа vault (brand, last4, expiry). Первых цифр PAN PA не хранит: masked view — ****<last4>.
  3. Vault token — credential: не возвращается ни одним API, не пишется в логи/аудит.
  4. Инструмент принадлежит tenant + merchant: cross-merchant переиспользование запрещено (422 instrument_merchant_mismatch).
  5. Single-use:vault token регистрируется как инструмент ровно один раз (уникальный индекс (tenant_id, vault_token_ref)), инструмент потребляется первым платежом атомарно с созданием платежа (одна транзакция: crash не может оставить «потраченный» инструмент без платежа). Одноразовость — семантика ПЛАТЁЖА, не выплаты: выплата (payout) использует инструмент как приёмник (receiver) и НЕ потребляет его — депозит потратил pin_… (ACTIVE → USED), выплата по тому же pin_… валидна (payout-to-deposit-card, см. Payouts guide).

2. PaymentInstrument API

Аутентификация — та же, что для всех операций API: Authorization: Bearer <tenant_api_key>; rate limiting применяется (route pattern /v1/payment-instruments).

2.1 POST /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:

  1. проверяет скоуп merchant ↔ tenant (422 unknown_merchant);
  2. запрашивает у capture-поверхности только маскированные метаданные токена (span vault_retrieve_card несёт vault_token_fingerprint, не токен);
  3. создаёт PaymentInstrument (PA token pin_...) и аудит-событие регистрации в одной транзакции (details: merchant_id, brand, exp_month/year, customer_reference, vault_token_fingerprint — БЕЗ токена и карточных данных);
  4. закрывает idempotency-ключ сохранённым результатом (201 или stored problem).

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.

2.2 GET /v1/payment-instruments/{id} — masked view

Тот же проекция, что в 201; статус отражает жизненный цикл (ACTIVE/USED/DEACTIVATED). Чужой/несуществующий id — одинаковый 404 instrument_not_found (без утечки существования). vault_token_ref в проекции отсутствует на уровне структуры (unit-тест фиксирует отсутствие поля в сериализации).

2.3 Использование в платежах

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.

2.4 Webhook казино

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):

  • at-least-once + дедуп: событие хранится ровно один раз (UNIQUE event_id); каждая попытка (в т.ч. retry) переотправляет ТЕ ЖЕ байты payload'а → одна и та же подпись (при неизменном секрете); получатель дедуплицирует по event_id;
  • **эмиссия на переход состояния **: событие уникально на переход — UNIQUE (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): это не эмиссия нового факта, а явное действие оператора;
  • секрет не хранится в outbox: webhook_secret берётся из конфигурации merchant'а в момент доставки;
  • dead-letter: после исчерпания бюджета попыток строка получает 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 — терминальное неисполнение.

2.5 Ротация webhook-секрета

POST /v1/merchants/{id}/rotate-webhook-secret — ротация подписывающего секрета без остановки доставки. Тело не требуется (секрет генерирует PA).

  • Новый секрет (whs_...) генерируется сервер-сайд и возвращается ровно один раз (webhook_secret), как при регистрации; он становится активным немедленно — все доставки подписываются уже НОВЫМ секретом (delivery_after_rotation инвариант worker'а: секрет берётся из конфигурации merchant'а в момент доставки).
  • Заменённый секрет переезжает в grace-слот: 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.
  • Повторная регистрация endpoint'а (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-ключа.

3. Secure Fields SDK (pa-sdk/)

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();

Контракт безопасности:

  1. iframe создаётся с sandbox="allow-scripts allow-forms" (БЕЗ allow-same-origin) — фрейм имеет opaque origin, не имеет доступа к DOM/storage родителя, родитель не читает DOM фрейма: casino JS не имеет DOM-доступа к значениям полей (security invariant — см. §1 «PCI boundary»).
  2. Обмен — только postMessage с проверкой origin в обе стороны; namespace pa-secure-fields; токен валидируется по форме до вызова onToken.
  3. PAN/CVV уходят из фрейма напрямую в 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 не нужен).
  4. Формат возвращаемого токена: непрозрачная строка [A-Za-z0-9_-]{8,255} (dev-схема vtok_<brand>_<last4>-<uuid>, capture-поверхность — pm_...).
  5. Коды ошибок capture-шага: 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.

4. Capture-поверхность (куда уходят PAN/CVV)

Режим 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).

5. Ограничения MVP

  • Инструмент в MVP одноразовый (single-use): потребляется ПЛАТЁЖОМ; выплата использует инструмент как приёмник и НЕ потребляет его — депозит-потреблённый (USED) pin_… остаётся валидным получателем выплаты (payout-to-deposit-card — Payouts guide).
  • Reusable instruments (single_use=false), provider tokens, verify/deactivate endpoints и расширенный жизненный цикл — следующие этапы roadmap.
  • CVV-in-cascade (retrieve CVC из vault для попытки B) — вне MVP.

1. Общая схема (PCI boundary)

┌──────────────────────────── казино (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-тестами платформы):

  1. PAN/CVV никогда не попадают в PA — ни в app DB, ни в логи, ни в audit details, ни в error messages, ни в тела запросов PA API (схема запроса не содержит карточных полей вовсе).
  2. Единственное, что PA хранит о карте: vault token reference (явное PCI-исключение — ссылка на PAN в vault) + маскированные метаданные из ответа vault (brand, last4, expiry). Первых цифр PAN PA не хранит: masked view — ****<last4>.
  3. Vault token — credential: не возвращается ни одним API, не пишется в логи/аудит.
  4. Инструмент принадлежит tenant + merchant: cross-merchant переиспользование запрещено (422 instrument_merchant_mismatch).
  5. Single-use:vault token регистрируется как инструмент ровно один раз (уникальный индекс (tenant_id, vault_token_ref)), инструмент потребляется первым платежом атомарно с созданием платежа (одна транзакция: crash не может оставить «потраченный» инструмент без платежа). Одноразовость — семантика ПЛАТЁЖА, не выплаты: выплата (payout) использует инструмент как приёмник (receiver) и НЕ потребляет его — депозит потратил pin_… (ACTIVE → USED), выплата по тому же pin_… валидна (payout-to-deposit-card, см. Payouts guide).

2. PaymentInstrument API

Аутентификация — та же, что для всех операций API: Authorization: Bearer <tenant_api_key>; rate limiting применяется (route pattern /v1/payment-instruments).

2.1 POST /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:

  1. проверяет скоуп merchant ↔ tenant (422 unknown_merchant);
  2. запрашивает у capture-поверхности только маскированные метаданные токена (span vault_retrieve_card несёт vault_token_fingerprint, не токен);
  3. создаёт PaymentInstrument (PA token pin_...) и аудит-событие регистрации в одной транзакции (details: merchant_id, brand, exp_month/year, customer_reference, vault_token_fingerprint — БЕЗ токена и карточных данных);
  4. закрывает idempotency-ключ сохранённым результатом (201 или stored problem).

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.

2.2 GET /v1/payment-instruments/{id} — masked view

Тот же проекция, что в 201; статус отражает жизненный цикл (ACTIVE/USED/DEACTIVATED). Чужой/несуществующий id — одинаковый 404 instrument_not_found (без утечки существования). vault_token_ref в проекции отсутствует на уровне структуры (unit-тест фиксирует отсутствие поля в сериализации).

2.3 Использование в платежах

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.

2.4 Webhook казино

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):

  • at-least-once + дедуп: событие хранится ровно один раз (UNIQUE event_id); каждая попытка (в т.ч. retry) переотправляет ТЕ ЖЕ байты payload'а → одна и та же подпись (при неизменном секрете); получатель дедуплицирует по event_id;
  • **эмиссия на переход состояния **: событие уникально на переход — UNIQUE (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): это не эмиссия нового факта, а явное действие оператора;
  • секрет не хранится в outbox: webhook_secret берётся из конфигурации merchant'а в момент доставки;
  • dead-letter: после исчерпания бюджета попыток строка получает 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 — терминальное неисполнение.

2.5 Ротация webhook-секрета

POST /v1/merchants/{id}/rotate-webhook-secret — ротация подписывающего секрета без остановки доставки. Тело не требуется (секрет генерирует PA).

  • Новый секрет (whs_...) генерируется сервер-сайд и возвращается ровно один раз (webhook_secret), как при регистрации; он становится активным немедленно — все доставки подписываются уже НОВЫМ секретом (delivery_after_rotation инвариант worker'а: секрет берётся из конфигурации merchant'а в момент доставки).
  • Заменённый секрет переезжает в grace-слот: 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.
  • Повторная регистрация endpoint'а (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-ключа.

3. Secure Fields SDK (pa-sdk/)

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();

Контракт безопасности:

  1. iframe создаётся с sandbox="allow-scripts allow-forms" (БЕЗ allow-same-origin) — фрейм имеет opaque origin, не имеет доступа к DOM/storage родителя, родитель не читает DOM фрейма: casino JS не имеет DOM-доступа к значениям полей (security invariant — см. §1 «PCI boundary»).
  2. Обмен — только postMessage с проверкой origin в обе стороны; namespace pa-secure-fields; токен валидируется по форме до вызова onToken.
  3. PAN/CVV уходят из фрейма напрямую в 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 не нужен).
  4. Формат возвращаемого токена: непрозрачная строка [A-Za-z0-9_-]{8,255} (dev-схема vtok_<brand>_<last4>-<uuid>, capture-поверхность — pm_...).
  5. Коды ошибок capture-шага: 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.

4. Capture-поверхность (куда уходят PAN/CVV)

Режим 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).

5. Ограничения MVP

  • Инструмент в MVP одноразовый (single-use): потребляется ПЛАТЁЖОМ; выплата использует инструмент как приёмник и НЕ потребляет его — депозит-потреблённый (USED) pin_… остаётся валидным получателем выплаты (payout-to-deposit-card — Payouts guide).
  • Reusable instruments (single_use=false), provider tokens, verify/deactivate endpoints и расширенный жизненный цикл — следующие этапы roadmap.
  • CVV-in-cascade (retrieve CVC из vault для попытки B) — вне MVP.

Field Reference

Справочник полей создания платежа (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.

Правила форм:

  • 0 PAN по определению: ни запрос, ни ответ, ни БД, ни логи PA не содержат карточных данных — карта живёт только на хостед-странице PSP.
  • Не гейтится H2H: redirect-форма доступна независимо от 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 чек-листа).
  • Каскад останавливается на открытом hosted-флоу: попытка одна, повторного диспатча нет (anti-double-charge); продление/закрытие — sync-воркером и reconciliation'ом (как у 3DS).
  • Модель интеграции — Integration models §(b).

3. capture_method

Значение Семантика Комментарий
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 (без попыток исполнения).

3.1 next_action → collect_data: досбор данных игрока

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-процессором платежа;
  • клиент собирает эти поля у игрока — через Secure Fields SDK (гайд SDK + Webhooks) или последующей формой на своей стороне — и создаёт новый платёж (POST /v1/payments) либо повторяет confirm-вызов, передав запрошенные данные;
  • в текущем MVP-флоу (Apcopay S2S / PayAdmit) платформа отвечает none/redirect/wait; collect_data зарезервирован контрактом заранее — клиент интеграции должен уметь обрабатывать это значение так же, как redirect: не считать его финалом и не кредитовать игрока до финального статуса.

Пример: {"type": "collect_data", "required_fields": ["email", "phone"]} — соберите у игрока email и телефон и повторите создание платежа, передав их в блоке customer (§4).

4. customer — данные игрока

Свободная форма сохраняется целиком (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 видит контекст игрока.

5. billing_address

Проецируется в 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, …). Читается роутингом

Две независимые причины заполнять:

  1. Роутинг (country-filter): Route Target со страновым фильтром обслуживает только платежи с совпадающим billing-страновым кодом; платёж без страны страново-фильтрованный target никогда не матчит — если в приоритете остались только такие target, это 422 no_eligible_route. Валютный eligibility без страны работает, но список маршрутов может быть уже ожидаемого.
  2. PSP-биллинг: Apcopay DEPOSIT-профиль требует адрес (addressLine1, city, countryCode, postalCode) — без блока billing_address платёж уходит без billing-данных и коннектор может отвергнуть его на своей валидации.

6. risk_context / session_context

Оба блока свободной формы: сохраняются с платежём, на 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/таймстампы/тексты про эту пробу не задевают; хранятся поля после пробы как есть.

7. metadata и order_reference

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 и прочие обычные метаданные пробу не задевают.

8. Write-only поля: PaymentResponse НЕ эхоит контекст

Ответ (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).

9. Сводка ошибок по полям

Код 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 (здесь не дублируются):

  • Webhooks — подписанные события платежей и выплат, контракт доставки (at-least-once, retry 1м/5м/30м/2h → DEAD), статусы доставки DELIVERED/PENDING/DEAD, ручной re-send.
  • Sandbox — среды (prod/sandbox), mock-vault и self-describing vault tokens, тестовые карты.
  • Payouts Guide — поля выплаты (instrument_id / receiver_card), статусы, лимиты, самоподтверждение.
  • Merchant Portal / Merchant Onboarding — self-service мерчанта: статистика, список платежей, CSV-экспорт, журнал доставок, ротации ключей и webhook-секрета, управление набором PSP.

Payouts Guide

Как казино выплачивает выигрыши игрокам через 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 — см. раздел ниже.
  • Вкладка «Payouts» в /portal — таблица выплат со статус-бейджами, форма создания и авто-обновление статусов каждые 15 секунд, пока есть выплаты в не-финальном статусе.

Fail-closed гейт: payouts_enabled

Выплаты выключены по умолчанию на ДВУХ уровнях, и мерчантская поверхность проходит, только когда включены ОБА (fail-closed по каждому):

  1. Тенант-уровень — домен выплат включён для всего тенанта Оператором.
  2. Merchant-уровень — выплаты включены для ВАШЕГО мерчанта; собственную поверхность мерчант включить не может (403 forbidden) — это операторское решение (AML/fraud review, условия договора).

Пока гейты выключены, каждый merchant-payout-endpoint отвечает 422 payouts_not_enabled — запросите включение у Оператора (нужны оба уровня: домен тенанта + ваш мерчант).

Модель выплат

Payout в PA — это отдельный домен с собственным жизненным циклом, а не «отрицательный платёж»:

  1. Создание. Выплата создаётся по инструменту игрока (instrument_id; PAN/CVV-полезная нагрузка отклоняется). Запрос идемпотентен.
  2. Approval gate — шлюз операторского одобрения. Свежесозданная выплата не диспатчится автоматически: она останавливается в состоянии AWAITING_APPROVAL и ждёт решения оператора платформы (approve / decline / cancel). Это fail-closed модель: выплата без одобрения не уйдёт в PSP.
  • next_action маркирует это как {type: "approval", resource, allowed_actions} — внешнему наблюдателю видно, что ресурс ждёт операторского решения.
  • Статус выплаты мерчант видит в /portal («Payouts») и через GET /v1/merchants/{id}/payouts/{payout_id}; вкладка обновляется автоматически.
  1. Dispatch — Phase 2 (операторская часть). После одобрения (APPROVED) выплата диспатчится в PSP — PROCESSING → COMPLETED (или FAILED_TECHNICAL / DECLINED). Диспетч в PSP пока НЕ реализован (Phase 2): мерчант видит честный статус APPROVED («одобрено, ждёт исполнения») без обещаний о движении денег до включения Phase 2.
  2. Лимиты. Пре-флайт лимиты выплат (: single / merchant в день / игрок в день) резервируются атомарно с созданием; отмена и отказ освобождают резерв. Конфигурация лимитов — на стороне Оператора.

Лимиты выплат

Каждая выплата проходит пре-флайт проверку лимитов до создания записи: превышение отклоняется — 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.

Откуда instrument_id для выплаты

У выплаты два рабочих пути получения pin_…, оба опираются на одно и то же правило: инструмент потребляется только ПЛАТЁЖОМ (депозитом), сама выплата инструмент НЕ потребляет.

  1. Вывод на карту депозита (payout-to-deposit-card) — индустриальный стандарт iGaming: игрок выводит выигрыш на ту же карту, с которой пополнялся (AML-чистый контур «та же карта игрока»; так же устроен PayAdmit WITHDRAWAL — cardPanId, «повторно вводить данные карты не нужно»). Используйте тот же pin_…, что ушёл в депозит: платёж перевёл инструмент в USED, но для выплаты он остаётся валидным получателем — статус USED для payout-получателя нормален. Повторные выплаты по тому же pin_… тоже допустимы: риск контролирует операторский approval gate и пре-флайт лимиты, а не одноразовость инструмента.
  2. Свежий capture (вывод на другую карту) — если игрок хочет получить выигрыш на карту, которой не пополнялся: проведите новый Secure Fields capture → 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).

Raw-card получатель: receiver_card

Для мерчанта с включённым 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`.

Onboarding Checklist

Короткий чек-лист, который проводит казино от получения доступов до go-live. Детальные примеры кода и контракты — в Handover Package, SDK + Webhooks и Field Reference; здесь только последовательность шагов и критерии готовности.

Предусловия (казино)

  • HTTPS endpoint webhook-receiver'а (в dev допустим http, в production — HTTPS обязателен);
  • backend, способный делать вызовы PA API и принимать подписанные webhook'и;
  • страница депозита (frontend) для подключения SDK;
  • тестовые карты — выдаёт Оператор (см. раздел Sandbox справочника /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 и ключи, пройти чек-лист ниже —

Go-live чек-лист

Отметка: [О] — Оператор PA, [К] — Казино.

  • [О/К] Sandbox-платёж доведён до финального успешного статуса (AUTHORIZED/CAPTURED) — полный цикл.
  • [К] Верификация PA-Webhook-Signature (HMAC-SHA256 по сырому телу) работает на receiver'е — все типы событий: payment.authorized / payment.captured / payment.refunded / payment.failed (и при включённых выплатах — payout.*).
  • [К] Идемпотентность: replay Idempotency-Key возвращает сохранённый результат (Idempotent-Replayed: true); тот же ключ с другим телом → 422 idempotency_key_reuse; webhook-replay по PA-Event-Id не дублирует зачисление.
  • [К] PCI-гигиена: PAN/CVV отсутствуют в логах казино (SDK iframe — PAN уходит только в capture-поверхность); в логах только pin_/pay_ и маскированные метаданные.
  • [О] Production ключи: ротация tenant key и webhook-секрета выполнена; raw-значения переданы в secret store казино.
  • [О] Production MID ENABLED (Оператор).
  • [О/К] Мониторинг: uptime receiver'а (казино), контакт-лист эскалации заполнен, журнал доставок доступен Оператору.

Диагностика казино

  • GET /v1/merchants/{id}/webhooks/deliveries?payment_id=… — журнал доставок своих платежей (также вкладка Events and Logs в /portal);
  • GET /v1/payments/{id} — состояние платежа;
  • /healthz — живость PA.

Предусловия (казино)

  • HTTPS endpoint webhook-receiver'а (в dev допустим http, в production — HTTPS обязателен);
  • backend, способный делать вызовы PA API и принимать подписанные webhook'и;
  • страница депозита (frontend) для подключения SDK;
  • тестовые карты — выдаёт Оператор (см. раздел Sandbox справочника /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 и ключи, пройти чек-лист ниже —

Go-live чек-лист

Отметка: [О] — Оператор PA, [К] — Казино.

  • [О/К] Sandbox-платёж доведён до финального успешного статуса (AUTHORIZED/CAPTURED) — полный цикл.
  • [К] Верификация PA-Webhook-Signature (HMAC-SHA256 по сырому телу) работает на receiver'е — все типы событий: payment.authorized / payment.captured / payment.refunded / payment.failed (и при включённых выплатах — payout.*).
  • [К] Идемпотентность: replay Idempotency-Key возвращает сохранённый результат (Idempotent-Replayed: true); тот же ключ с другим телом → 422 idempotency_key_reuse; webhook-replay по PA-Event-Id не дублирует зачисление.
  • [К] PCI-гигиена: PAN/CVV отсутствуют в логах казино (SDK iframe — PAN уходит только в capture-поверхность); в логах только pin_/pay_ и маскированные метаданные.
  • [О] Production ключи: ротация tenant key и webhook-секрета выполнена; raw-значения переданы в secret store казино.
  • [О] Production MID ENABLED (Оператор).
  • [О/К] Мониторинг: uptime receiver'а (казино), контакт-лист эскалации заполнен, журнал доставок доступен Оператору.

Диагностика казино

  • 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 маршрута

Связанные материалы

Errors

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.

Error format

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.

Card declines are not HTTP errors

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);
  • the terminal payment.failed webhook announces the same outcome (see Webhooks).

Decline classes

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.

Problem codes

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.

Payments

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

Refunds

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

Payment instruments

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

Secure Fields capture

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

Merchant payouts

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.

Merchant portal — PSP enablement

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

Webhooks

Signed payment events delivered by the outbox worker + delivery log.

Event envelope

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.

Delivery headers

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.

Signature verification (pseudocode)

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
 });

Delivery guarantees

  • At-least-once + dedup. The event is enqueued into the delivery outbox in the SAME database transaction as the payment status change — either both persist or neither. Every retry redelivers the exact same payload bytes: the signature and PA-Event-Id are stable across attempts; dedup by PA-Event-Id.
  • One event per transition. An event is unique per payment + event type + announced status: the receiver sees every terminal fact exactly once, and different transitions of one payment (AUTHORIZED → PARTIALLY_REFUNDED → REFUNDED) carry their own events.
  • Retry ladder. A non-2xx answer or a timeout is retried after 60 s, 300 s, 1800 s and 7200 s — a budget of 5 attempts per event; after that the delivery is marked DEAD (dead-letter — the payment itself is unaffected). Answer 2xx quickly: the delivery timeout is 5 s by default.
  • Delivery status ≠ payment status. 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.

Webhook secret rotation

POST /v1/merchants/{id}/rotate-webhook-secret re-keys deliveries without downtime:

  • the new secret (whs_…) is shown exactly once and becomes active immediately — every delivery after the rotation is signed with the NEW secret;
  • the replaced secret stays valid until 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;
  • rollout: deploy dual-verify → rotate → confirm old-secret verifications stop arriving.

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

Sandbox and production environments: base URLs, mock-vault behavior, test cards and how to get keys.

Environments

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.

Sandbox behavior

  • The sandbox runs the mock execution engine: every well-formed payment reaches a terminal status locally (no PSP round-trip), so the whole flow — instruments, payments, refunds, webhooks, delivery log — is exercisable end-to-end.
  • The sandbox does not impose amount limits (the mock engine authorizes any well-formed amount); rate limits apply as in production (sliding window per key + endpoint, default 100 requests/min, over-limit → 429 rate_limited with Retry-After).
  • The webhook outbox works for real: register an HTTPS endpoint and the sandbox delivers the same signed events with the same retry ladder (see Webhooks).
  • The webhook secret and the tenant API key are environment-specific — sandbox keys never work against production and vice versa.

Self-describing vault tokens (mock vault)

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.

Test cards

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.

Getting keys

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).

Payments

Payment lifecycle (create, read). Status machine: PENDING → AUTHORIZED → CAPTURED → PARTIALLY_REFUNDED → REFUNDED; FAILED; UNKNOWN_PENDING_SYNC.

Transaction statuses

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.

Create a payment

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.

Authorizations:
bearerAuth
header Parameters
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. 201 for a successful creation) and body, with header Idempotent-Replayed: true (a fresh execution answers false; no new domain event is written). Same key + different body is a 422 idempotency_key_reuse; a stored deterministic 4xx problem replays as the same problem. TTL 24h.

Request Body schema: application/json
required
merchant_id
required
string

Merchant of this tenant (mer_…). A merchant outside the tenant of the Bearer key → 422 unknown_merchant.

amount
required
integer >= 1

Positive integer in minor units (cents); 0 or negative → 422 invalid_request.

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 422 no_eligible_route without starting an attempt.

object

Payment method selection — three MUTUALLY EXCLUSIVE families: (1) the saved-card instrument (instrument_id, the Secure Fields SDK model), (2) the raw card H2H form (card, model (d) — ONLY for PCI DSS certified merchants after the operator enablement: 422 h2h_not_enabled otherwise), or (3) a HOSTED (PAN-free) form. Carrying both card and instrument_id → 422 invalid_request; carrying card/instrument inside a hosted form → 422 invalid_request. Each method opens its OWN PSP checkout page (BASIC_CARD only cards, APPLEPAY only Apple Pay, GOOGLEPAY only Google Pay, OPENBANKING only open banking) — the wallet button never appears on the card page. Apple Pay / Google Pay are available for RETURNING customers only: with the contractual threshold std_min_deposits a wallet payment whose customer has fewer SUCCESSFUL deposits than the threshold answers 422 wallet_unavailable_for_first_deposit BEFORE the idempotency claim (no payment/attempt, no PSP call); metadata.deposit_stream=redep is the explicit override. The card values are TRANSIT data: validated, mapped into the processor dispatch and dropped — never persisted, logged, audited or echoed.

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 (segment IS NULL) answers — an unknown label never turns a configured merchant into a legacy-order merchant. Absent / null / blank = the default cascade. Shape: at most 64 characters of [a-z0-9_-] (the alphabet of the PSP-callback path segments), 422 invalid_request otherwise — refused BEFORE the idempotency claim and any PSP call. The value is a routing label, never customer data: it is traced (routing cascade decision) and fixed on the attempt (attempts.routing_segment), never echoed by the payments API. Part of the idempotency fingerprint when present.

capture_method
string
Default: "automatic"
enum: "automatic" "manual"

automatic (default) — sale model: the PSP dispatch is PURC, so PA AUTHORIZED already means the provider captured the money (provider_status COMPLETED). manual — authorize-only; the capture endpoint is NOT part of the public API surface, and Route Targets are capability-filtered: a target without the manual-capture capability never serves the request (422 no_eligible_route when nothing remains; the pilot merchant routes are configured automatic only).

object

Customer context (identity/contact); risk fields belong to risk_context. Must be a JSON object (or absent/null) — any other JSON type → 422 invalid_request. FREE-FORM and WRITE-ONLY: the object is stored verbatim and projected to the PSP connector call, but the payment response NEVER echoes it (see PaymentResponse; the merchant portal Transaction Details / CSV report are the read surface).

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 browser block, which is projected into the PSP browser_info of the dispatch (the Apcopay DirectConnect PURC requires UserAgent/TimeZone; absent context → the dispatch carries no browser data).

object

Billing address; free-form and write-only (never echoed by the payment response). Two consumers: (1) the routing country filter — country_code/country scopes Route Target selection, and a payment WITHOUT a country never matches a country-filtered target (an all-filtered cascade → 422 no_eligible_route); (2) the PSP billing projection (address.line1 etc. — the Apcopay S2S DEPOSIT profile requires addressLine1, city, countryCode, postalCode).

object

Free-form client metadata (e.g. order_id); stored with the payment, WRITE-ONLY: never echoed by the payment response. Convention: the external order reference belongs in metadata.order_reference — that key surfaces in the merchant portal (Order Reference column, free-text search q, CSV report).

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 browser_info.ip_address. The Apcopay live DirectConnect PURC rejects a payment without Client.IPAddress (pspid: 0, "Missing Client.IPAddress" → FAILED_TECHNICAL cascade). Resolution order: session_context.browser.ip_address → customer.ip_address/customer.ip → this field → the socket/X-Forwarded-For peer (only when PA_RATE_LIMIT_TRUST_XFF=1). Validated as IPv4/IPv6; blank is ignored, malformed → 422 invalid_request. Deliberately NOT part of the idempotency fingerprint: the IP is a dispatch hint, not the payment identity. (I-8b): for server-to-server (non-3DS) dispatches the missing browser_info fields are completed with the synthetic server-side set (user_agent "PA/1.0 (server-side H2H)", accept_header/language/time_zone/color_depth/screen size/java_enabled), because Apcopay also requires the BrowserDetails block ("Missing BrowserDetails" otherwise). Explicit session_context.browser values always win; three_ds dispatches never get synthetic data.

Responses

Response Headers
Idempotent-Replayed
string
enum: "true" "false"

false on a fresh execution, true on a replay of the stored result (present on every response of this idempotent POST).

Response Schema: application/json
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 (type discriminator): what the client should do next. none — nothing to do; wait carries retry_after_secs (synchronize later); redirect carries the hosted-page URL (3DS / hosted payment page); collect_data asks the client to gather additional data from the player; approval marks an operator action (payout gate).

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>

Request samples

Content type
application/json
{
  • "merchant_id": "string",
  • "amount": 1050,
  • "currency": "EUR",
  • "payment_method": {
    • "type": "card",
    • "instrument_id": "pin_01900000-0000-7000-8000-000000000001",
    • "card": {
      }
    },
  • "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"
}

Response samples

Content type
application/json
{
  • "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
  • "status": "PENDING",
  • "amount": 1050,
  • "currency": "EUR",
  • "capture_method": "automatic",
  • "next_action": {
    • "type": "none"
    },
  • "attempts_summary": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Fetch a payment

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).

Authorizations:
bearerAuth
path Parameters
id
required
string

Payment id (pay_…).

Responses

Response Headers
Retry-After
integer

Seconds the client should wait before retrying.

Response Schema: application/json
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 (type discriminator): what the client should do next. none — nothing to do; wait carries retry_after_secs (synchronize later); redirect carries the hosted-page URL (3DS / hosted payment page); collect_data asks the client to gather additional data from the player; approval marks an operator action (payout gate).

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>

Response samples

Content type
application/json
{
  • "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
  • "status": "PENDING",
  • "amount": 1050,
  • "currency": "EUR",
  • "capture_method": "automatic",
  • "next_action": {
    • "type": "none"
    },
  • "attempts_summary": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Payment Instruments

Card instrument registration from single-use vault tokens (Secure Fields capture surface). No PAN/CVV ever reaches the backend API.

Register a payment instrument from a single-use vault token

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.

Authorizations:
bearerAuth
header Parameters
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. 201 for a successful creation) and body, with header Idempotent-Replayed: true (a fresh execution answers false; no new domain event is written). Same key + different body is a 422 idempotency_key_reuse; a stored deterministic 4xx problem replays as the same problem. TTL 24h.

Request Body schema: application/json
required
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).

Responses

Response Headers
Idempotent-Replayed
string
enum: "true" "false"

false on a fresh execution, true on a replay of the stored result (present on every response of this idempotent POST).

Response Schema: application/json
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.

Request samples

Content type
application/json
{
  • "merchant_id": "string",
  • "vault_token": "string",
  • "customer_reference": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Fetch a payment instrument (masked view)

Returns masked card metadata only (masked PAN ****<last4>, brand, optional expiry) and the instrument lifecycle status. No vault token is ever returned.

Authorizations:
bearerAuth
path Parameters
id
required
string

Payment instrument id (pin_…).

Responses

Response Schema: application/json
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.

Response samples

Content type
application/json
{
  • "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"
}

Refunds

Idempotent refunds of authorized/captured payments.

Create a refund

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.

Authorizations:
bearerAuth
header Parameters
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. 201 for a successful creation) and body, with header Idempotent-Replayed: true (a fresh execution answers false; no new domain event is written). Same key + different body is a 422 idempotency_key_reuse; a stored deterministic 4xx problem replays as the same problem. TTL 24h.

Request Body schema: application/json
required
payment_id
required
string
amount
required
integer >= 1

Minor units; must not exceed the remaining refundable amount.

reason
string

Responses

Response Headers
Idempotent-Replayed
string
enum: "true" "false"

false on a fresh execution, true on a replay of the stored result (present on every response of this idempotent POST).

Response Schema: application/json
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.

Request samples

Content type
application/json
{
  • "payment_id": "pay_01900000-0000-7000-8000-00000000000a",
  • "amount": 1,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "refund_id": "string",
  • "payment_id": "string",
  • "amount": 0,
  • "currency": "string",
  • "status": "PENDING",
  • "payment_status": "AUTHORIZED"
}

Merchant Payouts

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.

Create a payout for this merchant

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Merchant id (mer_…).

header Parameters
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. 201 for a successful creation) and body, with header Idempotent-Replayed: true (a fresh execution answers false; no new domain event is written). Same key + different body is a 422 idempotency_key_reuse; a stored deterministic 4xx problem replays as the same problem. TTL 24h.

Request Body schema: application/json
required
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 422 unknown_instrument. Payout instrument policy: the receiver accepts status ACTIVE or USED — an instrument a deposit already consumed (USED) stays a valid payout receiver, and the payout does NOT consume the instrument (repeated payouts to the same pin_… are valid; the operator approval gate and the payout limits own the risk). A DEACTIVATED instrument is 422 instrument_not_payout_eligible. Mutually exclusive with receiver_card.

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_card form (no instrument ownership context to default from). Validated by the shared validator: ≤ 255 characters, restricted charset, Luhn PAN probe.

receiver
object

Masked receiver metadata; PAN/CVV keys are rejected with 422 invalid_request (receiver must not contain card data fields (PAN/CVV)).

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 merchants.h2h_enabled, any off level → 422 h2h_not_enabled, checked BEFORE validation) and validated fail-fast (Luhn/expiry/holder). NO CVV field by contract: a credit needs none (the PSP add_card/WITHDRAWAL flow accepts the card without CVV); a sent card_cvc is rejected loudly (unknown field). Transit discipline: the payout record receives the MASKED snapshot (brand + last4 + expiry) — PAN/holder never enter storage; raw-card payouts draw from the SAME per-merchant H2H rate-limit bucket as raw-card deposits (429 rate_limited + Retry-After on excess). The PSP dispatch itself stays Phase 2: the payout lands in AWAITING_APPROVAL with the masked snapshot.

Responses

Response Headers
Idempotent-Replayed
string
enum: "true" "false"

false on a fresh execution, true on a replay of the stored result (present on every response of this idempotent POST).

Response Schema: application/json
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: AWAITING_APPROVAL (manual gate), APPROVED (auto-approve policy — decision fixed, PSP dispatch pending), DECLINED, CANCELLED. CREATED is the domain-level initial state (validation and pre-flight limits passed) that a created payout leaves immediately — creation maps it straight onto AWAITING_APPROVAL / APPROVED. PROCESSING and UNKNOWN_PENDING_SYNC (as well as COMPLETED / FAILED_TECHNICAL) become reachable only after the Phase-2 PSP dispatch; UNKNOWN_PENDING_SYNC syncs first.

amount
required
integer
currency
required
string
customer_reference
required
string
object or object or object or object or object (NextAction)

Typed union (type discriminator): what the client should do next. none — nothing to do; wait carries retry_after_secs (synchronize later); redirect carries the hosted-page URL (3DS / hosted payment page); collect_data asks the client to gather additional data from the player; approval marks an operator action (payout gate).

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>

Request samples

Content type
application/json
{
  • "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"
    }
}

Response samples

Content type
application/json
{
  • "payout_id": "string",
  • "status": "CREATED",
  • "amount": 0,
  • "currency": "string",
  • "customer_reference": "string",
  • "next_action": {
    • "type": "none"
    },
  • "attempts_summary": [
    • {
      }
    ],
  • "approval_decisions": [
    • {
      }
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

List this merchant's payouts

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Merchant id (mer_…).

query Parameters
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).

Responses

Response Schema: application/json
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)

Response samples

Content type
application/json
{
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "status": "CREATED",
  • "payouts": [
    • {
      }
    ]
}

Read one of this merchant's payouts

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Merchant id (mer_…).

id
required
string

Payout id (pout_…).

Responses

Response Schema: application/json
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: AWAITING_APPROVAL (manual gate), APPROVED (auto-approve policy — decision fixed, PSP dispatch pending), DECLINED, CANCELLED. CREATED is the domain-level initial state (validation and pre-flight limits passed) that a created payout leaves immediately — creation maps it straight onto AWAITING_APPROVAL / APPROVED. PROCESSING and UNKNOWN_PENDING_SYNC (as well as COMPLETED / FAILED_TECHNICAL) become reachable only after the Phase-2 PSP dispatch; UNKNOWN_PENDING_SYNC syncs first.

amount
required
integer
currency
required
string
customer_reference
required
string
object or object or object or object or object (NextAction)

Typed union (type discriminator): what the client should do next. none — nothing to do; wait carries retry_after_secs (synchronize later); redirect carries the hosted-page URL (3DS / hosted payment page); collect_data asks the client to gather additional data from the player; approval marks an operator action (payout gate).

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>

Response samples

Content type
application/json
{
  • "payout_id": "string",
  • "status": "CREATED",
  • "amount": 0,
  • "currency": "string",
  • "customer_reference": "string",
  • "next_action": {
    • "type": "none"
    },
  • "attempts_summary": [
    • {
      }
    ],
  • "approval_decisions": [
    • {
      }
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Cancel this merchant's payout request

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).

Authorizations:
bearerAuth
path Parameters
id
required
string

Merchant id (mer_…).

id
required
string

Payout id (pout_…).

header Parameters
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. 201 for a successful creation) and body, with header Idempotent-Replayed: true (a fresh execution answers false; no new domain event is written). Same key + different body is a 422 idempotency_key_reuse; a stored deterministic 4xx problem replays as the same problem. TTL 24h.

Request Body schema: application/json
optional
reason
string

Responses

Response Schema: application/json
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: AWAITING_APPROVAL (manual gate), APPROVED (auto-approve policy — decision fixed, PSP dispatch pending), DECLINED, CANCELLED. CREATED is the domain-level initial state (validation and pre-flight limits passed) that a created payout leaves immediately — creation maps it straight onto AWAITING_APPROVAL / APPROVED. PROCESSING and UNKNOWN_PENDING_SYNC (as well as COMPLETED / FAILED_TECHNICAL) become reachable only after the Phase-2 PSP dispatch; UNKNOWN_PENDING_SYNC syncs first.

amount
required
integer
currency
required
string
customer_reference
required
string
object or object or object or object or object (NextAction)

Typed union (type discriminator): what the client should do next. none — nothing to do; wait carries retry_after_secs (synchronize later); redirect carries the hosted-page URL (3DS / hosted payment page); collect_data asks the client to gather additional data from the player; approval marks an operator action (payout gate).

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>

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "payout_id": "string",
  • "status": "CREATED",
  • "amount": 0,
  • "currency": "string",
  • "customer_reference": "string",
  • "next_action": {
    • "type": "none"
    },
  • "attempts_summary": [
    • {
      }
    ],
  • "approval_decisions": [
    • {
      }
    ],
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}