Крипто-казино
Torrent Gear
Як працюють API-платежів у провайдерів
Платіжний API - це контракт між вашим додатком і провайдером, який перетворює «створити оплату», «підтвердити 3DS», «повернути кошти», «виплатити клієнту» і «отримати статус» в надійні, повторювані виклики. Під капотом - десятки правил: токенізація, idempotency, вебхуки, антифрод, черги, SLA і аудит. Нижче - практична карта того, як це влаштовано у більшості провайдерів.
Базова модель: які сутності є майже завжди
Payment/Charge - спроба списання (authorize + capture або відразу purchase).
Payment Method - картка (PAN/token), банківський рахунок/alias, гаманець, локальний метод.
Customer - сутність клієнта/платника (іноді необов'язкова).
Payout/Transfer - вихідний платіж клієнту/мерчанту.
Refund/Reversal - повернення до початкового платежу (closed-loop).
Webhook Event - асинхронне повідомлення про статус.
Dispute/Chargeback - суперечка по платіжній мережі (для карт).
Order/Invoice - бізнес-контекст навколо платежу.
Автентифікація та безпека
API-ключі/OAuth 2. 0/mTLS - для сервер-к-сервера.
Клієнтські токени - одноразові токени для фронтенда (щоб не світити секрети).
Токенізація карт - PAN йде в провайдера; ви зберігаєте тільки токен.
PCI DSS - якщо ви бачите PAN, ви в зоні PCI; краще уникати і використовувати хостед-поля/SDK.
HMAC підпис вебхуків - перевірка, що подія прийшла від провайдера.
Двозонна архітектура - публічний фронт (JS/SDK) і приватний бекенд (ключі, risk-логіка).
Idempotency, черги та узгодженість
Idempotency-Key в заголовку: повтор запиту (при таймауті) не створює дублікат.
Outbox/Saga у вас: щоб «відправив платіж → записав в леджер → дочекався вебхука» було узгоджено.
Ретраї з backoff - тільки для тимчасових помилок. Матриця retryable/non-retryable - обов'язкова.
Типові ендпоінти (схеми і флоу)
1) Карти (Visa/Mastercard та ін.)
POST/payments - створити платіж ('amount','currency','payment _ method _ token','capture'= false/true).
POST /payments/{id}/confirm — шаг 3-D Secure 2 (challenge/redirect result).
POST/payments/{ id }/capture - захоплення після авторизації (частковий/повний).
POST/payments/{ id }/refund - повернення (частинами, до суми вихідного).
GET /payments/{id} — статус (authorized, captured, failed, requires_action).
3-D Secure / SCA: провайдер поверне'requires _ action'+'client _ secret '/URL для challenge. Після підтвердження клієнтом фронт поверне результат на ваш бекенд → ви смикаєте '/confirm'.
2) A2A / Open Banking (Pay by Bank)
POST/payments → відповідь з'redirect _ url'в банк клієнта.
Клієнт авторизується у банку → webhook'payment. succeeded/failed`.
GET/payments/{ id} - фінальний статус (часто тільки асинхронно).
3) Локальні методи (PIX, PayID, FPX, iDEAL тощо)
POST/payments → отримаєте'qr _ code '/' deeplink '/' copy _ code'.
Показуєте користувачеві, чекаєте webhook про зарахування.
Таймаути і TTL на код - частина контракту.
4) Виплати (payouts)
POST /payouts (`amount`, `currency`, `destination_token` или `card_token`/`bank_alias`).
GET /payouts/{id} — статусы (`queued`, `sent`, `paid`, `failed`).
Вебхукі'payout. paid/failed'- джерело правди.
Закрита петля: переважно виплачувати на джерело (reversal) до альтернатив.
Вебхуки: «Джерело істини»
Події: `payment. pending/authorized/captured/failed`, `payment. requires_action`, `refund. succeeded`, `payout. paid`, `dispute. created'і т.д.
Доставка: з ретраями, підписана HMAC, часто «як мінімум один раз» → тримайте ідемпотентність обробника.
Best practice: обробляти вебхук → оновити леджер → відповісти 2xx. Будь-яка бізнес-логіка після - асинхронно.
Обробка помилок і статусів
HTTP-коди: «2xx» успіх; «4xx» помилка клієнта (валідація, фрод/відмова банку, невірний токен); «5xx» - провайдер.
Причини відмов: `insufficient_funds`, `do_not_honor`, `stolen_card`, `limit_exceeded`, `risk_decline`, `bank_unavailable`.
Вікна повторів: для 3DS - не можна нескінченно ретраїти; для A2A - діють TTL редиректу/коду; для payouts - backoff.
Антифрод і ризик
Device-fingerprinting і поведінкові дані - через JS/SDK провайдера або ваш власний шар.
Списки: BIN-ризик, чорні/білі списки методів/ASN/країн.
Регульовані гейти: ліміти на нові інструменти, «cool-off», velocity, RG/AML-порогові перевірки.
Політики: 'pass/step-up/hold/block'на основі скорингу + правил.
Особливості по рейках
Карти: авторизація vs кліринг (можливий зсув суми), 3DS2, повернення по вихідній операції, спори/чарджбеки.
A2A/Open Banking: редирект/consent-флоу, високий апрув, низька вартість; все асинхронно і сильно залежить від банку.
Локальні швидкі: QR/alias, миттєвий вебхук, TTL і сувора згірка.
OCT/Push-to-Card (виплати на картку): потрібні токени карти, підтримка Fast Funds у емітента, без 3DS.
Версіонування та сумісність
Версії API: '/v1', «дата-версії» в заголовку або фічефлаги.
Backwards-compatible зміни: тільки неруйнівні поля.
Депрекації: графік виведення старих версій, міграційні гайди, дублікат вебхуків на час міграції.
Спостережуваність і SLA
Метрики: p95 часу авторизації/виплати, approve rate по BIN/банку/методу, частка ретраїв, вебхукі-лаг.
Логи: кореляція по'request _ id','idempotency _ key','payment _ id'.
Алерти: сплеск відмов по конкретному банку/країні, зростання таймаутів, дублікати подій.
Згортання та фінанси
Леджер: подвійний запис, незмінні журнали, статуси'authorized/captured/refunded'.
Тристороннє згортання: ваш леджер ↔ вебхукі ↔ звіти провайдера/банку.
Референси: зберігайте'provider _ reference','network _ reference','payout _ reference'- це рятує саппорт.
Sandbox, сертифікація та прод
Sandbox: тестові токени/карти/банки, симуляція 3DS/редиректів, «кнопки» для статусів вебхука.
Тест-кейси: успіх/відмова, 3DS challenge, таймаут провайдера, дублікат вебхука, частковий capture/refund, скасування редиректу, payout fail.
Go-live: ключі прод, домени вебхуків, IP-allowlist, включити антифрод, задати ліміти і алерти.
Міні-приклади (схематично)
Створити платіж (карта)
POST /v1/payments
{
"amount": 9232, "currency": "EUR", "payment_method_token": "pm_tok_123", "capture": true, "metadata": {"order_id": "ORD-1001"}
}
→ 200 { "id": "pay_abc", "status": "requires_action", "next_action": {"type":"redirect", "url":"..."} }Вебхук про успішне зарахування
POST /webhooks
{
"type": "payment. captured", "data": {"id":"pay_abc","amount":9232,"currency":"EUR","metadata":{"order_id":"ORD-1001"}}
}Виплата (payout)
POST /v1/payouts
{
"amount": 5000, "currency": "EUR", "destination_token": "dest_tok_456", "metadata": {"user_id":"u_77"}
}Чек-лист впровадження
1. Архітектура ключів: серверні секрети окремо, клієнтські - одноразові.
2. Idempotency: в кожному write-виклику + ідемпотентні обробники вебхуків.
3. Вебхуки: підпис HMAC, ретраї, черга завдань, моніторинг лагів.
4. 3DS/SCA і редиректи: обробка відмін/таймаутів, повторна спроба френдлі-UX.
5. Антифрод/ліміти: velocity, нові реквізити, чорні списки, RG/AML-пороги.
6. Леджер і згоряння: подвійний запис, тристороння звірка, алерти аномалій.
7. Оркестрація: запасний провайдер, правила роутингу по BIN/країні/сумі.
8. Моніторинг: дашборди approve rate/p95/ретраї, алерти за банками/методами.
9. Юридично/PCI: токенізація, політика повернень, закрита петля payouts.
10. План деградації: kill-switch каналу, черги, ручний режим для критичних операцій.
Часті помилки
Зберігання PAN на своїй стороні без PCI і токенізації.
Відсутність idempotency → дублі платежів/виплат при таймаутах.
Логіка на синхронних відповідях без урахування вебхуків.
Один провайдер на ринок, без fallback/каскадів.
Немає обробки скасування 3DS/редиректу → втрачені кошики.
Слабке згортання → «завислі» і «втрачені» транзакції.
Відсутність чітких SLA і алертів → проблему бачить клієнт, а не ви.
Mini-FAQ
Що надійніше: синхронний статус або вебхук?
Вебхук - джерело істини; синхронна відповідь - лише «прийнято/потрібна дія».
Можна обійтися без 3DS?
Залежить від регуляції/ризику. В EC/UK - SCA обов'язкова; для high-risk краще step-up.
Як підвищити approve rate?
Оркестрація по BIN/банку/методу, локальні рейки, розумні ретраї, коректні дескриптори, антифрод з низьким FPR.
Чому payout «не миттєвий»?
Залежить від рейок (ОСТ/А2А/локальні), банку одержувача і лімітів. Давайте чесне вікно SLA і статус-стрім.
API-платежів - це не тільки «створити платіж». Це дисципліна: безпечна аутентифікація → токенізація → idempotency → асинхронні вебхуки → леджер і згоряння → антифрод/AML → оркестрація і моніторинг. Побудуйте процес за цією схемою, тримайте запасні канали і прозорий UX - і ваш платіжний шар буде швидким, передбачуваним і стійким до збоїв банків і провайдерів.