Інтеграція платіжного шлюзу онлайн-казино: технічний чекліст

Інтеграція шлюзу готова, коли оператор може пояснити, що сталося з грошима гравця після перерваного запиту, повторного сповіщення або затриманої виплати. Успішний виклик API — лише частина цього підтвердження. Практичний результат роботи — узгоджений контракт взаємодії постачальника платіжних послуг (PSP), гаманця гравця, фінансового обліку та працівників, які розбирають винятки.

Цей чекліст призначений для інженерів, керівників платіжного напряму та фінансових команд, які готують інтеграцію казино. Почніть з узгоджених юридичної особи, мерчант-акаунта, ринків, валют і способів оплати. Підтримку депозитів і виплат перевіряйте окремо: доступність однієї операції не підтверджує можливість іншої. Зафіксуйте продукт провайдера та версію API, порядок списання після авторизації, доступ до звітності й контакти для ескалації. Сам по собі технічний доступ не означає дозволу обробляти платежі для азартних ігор.

Документація провайдера нижче слугує конкретним прикладом поведінки інтеграції, а не рекомендацією чи підтвердженням допустимості підключення. Для кожного підтримуваного способу оплати зберіть звичайний депозит, звичайну виплату та щонайменше один сценарій відновлення з відповідними ідентифікаторами операцій провайдера й проводками. Визначте цей обсяг робіт разом з інтеграцією платежів і перевірки особи до розроблення конектора.

Депозити: визначте підтвердження, що дозволяє зарахування

Створіть і надійно збережіть запис депозиту до надсилання запиту провайдеру. Надайте логічному запиту гравця постійний ID, а кожній зовнішній спробі — окремий ідентифікатор. Збережіть суму, валюту, гравця, бренд, мерчант-акаунт і заплановану операцію. Сервер має визначати ці значення на підставі дозволеного запиту: передані браузером ID гаманця чи сума не є довіреним розпорядженням зарахувати гроші.

Узгодьте, яке саме підтвердження провайдера дозволяє зарахування в гаманець для цього способу оплати й порядку списання. Повернення на сторінку успішної оплати таким підтвердженням не є. Зіставляйте автентифіковану серверну подію або достовірну відповідь провайдера про статус з очікуваними спробою, акаунтом, сумою та валютою. Якщо підтримується часткова авторизація, не можна зараховувати всю запитану суму на підставі авторизації меншої суми. Вирішіть, чи приймаєте ви частковий платіж, чи скасовуєте його, та відобразіть фактично прийняту суму.

Записуйте прийнятий факт платежу й відповідну проводку атомарно або використовуйте передавання зі збереженням даних і можливістю повторної обробки, якщо окремі сервіси не дозволяють виконати єдину транзакцію. Цей механізм має розпізнавати вже зафіксовану проводку після збою. Дві копії однієї події, що задовольняє умови зарахування, повинні створювати одне зарахування. Подальший збій списання, повернення або оскарження платежу — новий фінансовий факт зі своїм порядком обробки, а не привід переписати попередню історію.

Наприклад, гравець закрив платіжну сторінку, не повернувшись у казино. Якщо надійшло дійсне підтвердження й умови зарахування виконано, депозит усе одно потрібно обробити. І навпаки: переконливий екран успішної оплати без потрібного підтвердження не має створювати доступні для витрачання кошти.

Виплати: резервуйте кошти до відправлення

Виведення коштів починається з дозволеного запиту та резерву в обліку, який вилучає суму з доступного балансу гравця. Зафіксуйте резерв до того, як стане можливою відправка зовнішньої виплати. Інакше гравець може витратити ті самі кошти, поки провайдер обробляє переказ. Резерв і запис виплати мають бути пов’язані постійним ідентифікатором виведення.

Прив’яжіть до цього запису погоджені реквізити одержувача, суму, валюту та гравця. Повторне відправлення не повинно непомітно змінювати одержувача. Повторно перевіряйте необхідні умови на етапі, визначеному політикою оператора, і забезпечте послідовне виконання переходу, який дозволяє відправлення: паралельні обробники не мають ініціювати два перекази.

Поки результат зовнішньої операції невідомий, кошти повинні залишатися недоступними. Після зафіксованого завершення виплати погасіть резерв; вивільняйте його лише за наявності підтвердження, що дозволяє цю дію. Повернення після завершення потребує нової проводки: не можна вдруге вивільнити вже погашений резерв. Локальний тайм-аут, натискання оператором кнопки скасування чи очікуваний час надходження не доводять, що кошти не було відправлено. Якщо повернений переказ містить утримання або конвертацію валюти, обліковуйте підтверджені суми, а не відновлюйте початкову суму за припущенням.

Терміни провайдера потрібно зіставляти уважно. У життєвому циклі переказу сервісу виплат Adyen booked означає списання коштів з балансового рахунку й не є остаточним статусом: згодом переказ може завершитися невдало або повернутися. Цей приклад стосується конкретного продукту, а не всіх схем виплат казино. Отримайте рівнозначні підтвердження у свого провайдера, зокрема ідентифікатор відстеження, з яким підтримка зможе розслідувати ненадходження коштів одержувачу.

Розділяйте доступ до API, автентифікацію картки та перевірки гравця

Тут три різні питання: чи має сервер право звертатися до провайдера, чи пройшов платіжний інструмент потрібну автентифікацію та чи дозволено гравцеві виконати цю операцію? Ключ API відповідає на перше. Автентифікація в емітента відповідає на інше питання. Ні те, ні інше не замінює перевірку гравця, обмеження акаунта чи контроль виведення коштів в оператора.

Реалізуйте фактичний контракт автентифікації API провайдера. Наприклад, Adyen документує варіанти з ключем API та Basic-автентифікацією. Серверні секрети не повинні потрапляти в браузерний код, логи й вивантаження для підтримки. Розділяйте тестові та робочі облікові дані й мерчант-акаунти; обмежуйте доступ до секретів та адміністративних змін тими працівниками й сервісами, яким він потрібен. Ротація має охоплювати розгортання, перевірку й видалення попередніх облікових даних, а також план відновлення для вже надісланих запитів.

Свідомо обирайте спосіб обробки платіжних даних. Компоненти, розміщені у провайдера, або токенізація можуть зменшити обсяг даних у вашій системі, але передавання обробки підряднику не знімає всієї відповідальності. Роз’яснення PCI SSC щодо аутсорсингу зазначає, що мерчанти залишаються відповідальними за захист платіжних даних третьою стороною та мають уточнювати обов’язки з підтвердження відповідності в організації, яка керує їхньою програмою відповідності. Визначте реальну сферу застосування вимог з еквайром або платіжною системою; не можна оголошувати інтеграцію відповідною вимогам лише тому, що їм відповідає провайдер.

Докази приймання — дозволений виклик від потрібного сервісу й акаунта, відмова за несанкціонованого доступу та документована межа обробки платіжних даних і секретів. Не копіюйте чутливі дані запитів у систему налагодження лише задля зручності тестування.

Вебхуки: перевірка, збереження, підтвердження отримання й обробка

Перевірка має відповідати документованому алгоритму конкретного типу вебхука. Не вигадуйте універсальну перевірку підпису. Документація Adyen щодо HMAC розрізняє стандартні сповіщення з підписом за вибраними полями та інші типи вебхуків з підписом за початковим тілом запиту. У другому випадку десеріалізація й повторна серіалізація тіла до перевірки можуть змінити підписані байти. Використовуйте належний підтримуваний механізм перевірки й тестові зразки, сформовані провайдером.

Автентичне повідомлення спочатку збережіть у журналі вхідних подій зі стійким зберіганням даних, потім підтвердьте отримання в потрібному провайдеру форматі, а зміну фінансового стану обробляйте окремо. Рекомендації Adyen щодо обробки описують це розділення та попереджають, що повторні сповіщення можуть відрізнятися датою події або деталями. Успішне підтвердження отримання має означати, що інтеграція зможе відновити повідомлення після перезапуску; воно не обов’язково означає, що гаманець уже оновлено.

Дійсного підпису недостатньо для дозволу на проводку в гаманці. Зіставте мерчант-акаунт і середовище, ідентифікатор провайдера, операцію, суму та валюту з відомим платежем. Відхиляйте невідповідні події або поміщайте їх у карантин до того, як вони зможуть вплинути на баланс гравця. Зберігайте достатньо захищених свідчень для розслідування. Автентична подія з невідомим ідентифікатором потребує призначеного відповідального за розбір, а не здогадки про те, якому гравцеві вона належить.

Усувайте дублікати з урахуванням ідентифікатора та змісту подій у провайдера. Повторна авторизація відрізняється від подальшого списання, повернення або поверненої виплати. Деякі повторні події містять оновлені суттєві деталі, хоча не повинні створювати нової проводки. Відновлюйте хронологію за доступними порядковими номерами, часовими мітками провайдера та правилами переходів; самого порядку надходження недостатньо. Ротація ключів перевірки має зберігати можливість приймати легітимні затримані сповіщення згідно з документованими правилами провайдера.

Обліковуйте фінансові факти окремо від виконання API-запиту

Один прапорець paid не пояснює передавання запиту, рішення провайдера, проводку в гаманці та розрахунки. Обліковуйте ці виміри окремо й зберігайте початковий статус провайдера поряд з його локальним тлумаченням. Наведені нижче позначення описують внутрішню модель, а не універсальні коди статусів PSP.

• Підготовлено або надіслано: існує зовнішня спроба із зафіксованим перебігом відправлення. Статус «підготовлено» не доводить відсутності відправлення, якщо процес аварійно завершився на межі мережевого виклику.
• Потрібна дія або очікується результат: не завершено додаткову автентифікацію чи асинхронну обробку. Показуйте чесний статус очікування, не створюючи автоматично ще один платіж.
• Результат невідомий: запит міг дійти до провайдера, але інтеграція не має вирішального підтвердження. Призначте відновлення, а не вважайте це відмовою.
• Підтвердження провайдера та результат в обліку: зберігайте обидва факти. Платіж, підтверджений для зарахування, без відповідної проводки потребує виправлення; локальна проводка не доводить завершення розрахунків.
• Подальше коригування: списання, повернення, повернення виплати та оскарження платежу мають власні ідентифікатори, суми й наслідки. Зберігайте послідовність, не зводячи її до останнього статусу.

Коди результатів платежу Adyen показують, чому ця відмінність важлива: Received і Pending є проміжними, а Authorised за ручного списання ще може потребувати capture. Явно визначте момент зарахування в гаманець для погодженого способу оплати. Авторизація не обіцяє незворотного завершення розрахунків.

Напишіть тести переходів для суперечливих і затриманих підтверджень. Застаріла подія очікування не повинна стирати підтверджене списання. Пізніша дійсна зворотна операція має залишатися видимою, навіть якщо клієнтський інтерфейс і далі показує початковий депозит.

Ідемпотентність потребує захисту з обох боків

Захистіть три межі: повторний запит гравця, зовнішній виклик провайдера та локальну фінансову проводку. На першій прив’яжіть ідентифікатор ідемпотентності до однієї дозволеної операції та незмінних даних запиту. Повторне використання ідентифікатора з іншою сумою, валютою або одержувачем має завершуватися відмовою, а не повертати успішну відповідь від іншої операції.

На межі провайдера зберігайте ключ разом з точною спробою до відправлення. Дотримуйтеся умов повторів, сфери дії та строку зберігання, встановлених провайдером. Документація Adyen щодо ідемпотентності задає сферу дії на рівні акаунта й обмеження між регіональними кінцевими точками, а також сигнал transient-error для повторів. Ключ — механізм захисту від дублювання в межах певного контракту, а не вічна глобальна гарантія. Якщо поза межами цього контракту безпека вже не підтверджена, розслідуйте початкову спробу замість непомітного створення нового ключа.

На межі обліку забезпечте унікальність ідентифікатора проводки для відповідної фінансової операції. Код застосунку, який спочатку перевіряє наявність запису, а потім вставляє його, сам по собі вразливий до гонки; сховище зі стійким збереженням даних має відхиляти дублікати. Для справді окремих списань, повернень і повернених виплат використовуйте окремі ідентифікатори. Загальне правило «не більше однієї події на платіж» відкине законні фінансові зміни.

Перевірте збій між фіксацією проводки та позначенням вхідної події як обробленої. Під час повторної обробки потрібно розпізнати вже наявну проводку. Якщо гаманець розміщено в іншому сервісі, його контракт приймання потребує такого самого захисту. Результатом має бути відновлювана обробка з одним передбаченим фінансовим ефектом, а не твердження про доставку повідомлень мережею рівно один раз. Архітектура гаманця та обліку транзакцій є частиною контракту інтеграції.

Відновлюйте втрачений результат без нового платежу

Розгляньмо спробу депозиту A. Провайдер приймає її, але відповідь губиться. Браузер повторює запит, а обробник перезапускається до надходження вебхука. Жодна з цих подій не доводить відмови. Зберігайте зв’язок логічного депозиту з A та не допускайте відправлення другої спроби, поки результат A не з’ясовано.

1. Відновіть збережену спробу, дані запиту та ключ ідемпотентності провайдера. Зберігайте невизначеність, якщо процес не може довести, чи перетнув запит межу мережевого виклику.
2. Отримайте достовірні дані провайдера про статус або скористайтеся документованим механізмом повторного відправлення тієї самої спроби, якщо його умови це дозволяють. Фіксуйте кожну дію з відновлення та кожну відповідь.
3. Спрямовуйте підтвердження, що задовольняє умови обробки, у той самий шлях перевірки й створення проводок, що й звичайні події. Пізній вебхук і відновлена відповідь API мають приводити до одного фінансового ефекту.
4. Ескалуйте нерозв’язані випадки, зазначаючи тривалість очікування, ідентифікатори та відповідального. Відсутність запису в одній відповіді на запит або одному звіті не доводить невдачі, якщо контракт провайдера не робить такий результат вирішальним саме для цієї операції.

Застосовуйте той самий підхід до виплат, зберігаючи резерв коштів. Зміна провайдера чи створення нового ключа, поки перший переказ ще може завершитися, здатні подвоїти зовнішній платіж. План відновлення має визначати, коли дозволена нова спроба та яке підтвердження закриває попередню. Ширші рішення щодо маршрутизації належать до архітектури оркестрації платежів і відновлення.

Схема нижче показує спрощений шлях депозиту. У робочій системі запити, сповіщення й відновлення можуть відбуватися окремими каналами. Під час виведення коштів також потрібен резерв до відправлення; не можна просто скопіювати показаний порядок.

Підтвердьте зв’язок гаманця з розрахунками провайдера

Підтвердьте чотири зв’язки: прийняту операцію провайдера з проводкою в обліку гравця; коригування з початковою операцією; операції, включені до розрахунків, з розрахунковим пакетом провайдера; пакет — з фактично отриманими грошима. Для виплат потрібні відповідні записи зовнішнього переказу та руху коштів. Звіряйте за юридичною особою, мерчант-акаунтом, валютою та фінансовим періодом, а не за одним лічильником успішних операцій.

Зберігайте внутрішні ідентифікатори й ідентифікатори провайдера, тип операції, точні суми, валюту, дати проводок та ідентифікатори пакетів. На межі API використовуйте передбачене провайдером представлення суми, а всередині — точне грошове представлення. До відправлення перевіряйте валюту й правила суми для способу оплати; відхиляйте непідтримувані значення замість прихованого округлення. Не вгадуйте масштаб десяткових розрядів за відображеною сумою. Часові пояси, межі розрахункових періодів і доступність звітів визначають, чи є розбіжність очікуваним часовим зсувом, чи винятком.

Звіт Adyen Settlement details — приклад підтвердження на рівні транзакцій, що містить валюти й суми до та після утримань, ідентифікатори та поля комісій. Комісію можуть зазначати загальною сумою або компонентами. Зіставте фактичний формат звіту з обліком, щоб не враховувати витрати двічі. Такий звіт описує власну сферу розрахунків; він не стає автоматично повним відображенням усіх витрат бізнесу чи грошових надходжень за зовнішніми розрахунками.

Корисні класи винятків: підтверджені депозити без зарахувань, повторні проводки, незіставлені повернення, резерви виплат із нез’ясованим результатом і розрахункові суми, що не збігаються з рухом грошей після документованих коригувань. Для кожного випадку призначте відповідального, зафіксуйте тривалість очікування, підтвердження та наступну дію. Виправляйте через дозволені проводки або повторюваний шлях їх створення, зберігаючи початкові свідчення. Не редагуйте баланс гравця вручну заради гарного денного підсумку.

Застосовуйте контроль ризиків, зберігаючи фінансову історію

Визначте правила оператора щодо допуску акаунта, належності платіжного інструмента, лімітів операцій, схвалення виведення та обмежених акаунтів на відповідних ринках. Інтеграція має застосовувати потрібні рішення на сервері на узгоджених етапах. Ця стаття не встановлює єдиного глобального правила KYC чи законного строку зберігання даних.

Зберігайте пропорційні й захищені відомості про рішення: яка версія політики діяла, яке рішення ухвалено, коли та яким сервісом чи уповноваженим працівником. Обмежте доступ до платіжних налаштувань, зміни реквізитів, повернень і ручних коригувань. Перевіряйте авторизацію між брендами та акаунтами гравців, а не лише приймання кінцевою точкою дійсного входу. Архітектура безпеки платформи має визначати ці межі довіри.

Блокування за результатами оцінки ризику не скасовує зовнішнього платежу. Якщо депозит підтверджено після обмеження акаунта, зафіксуйте фінансовий факт і дотримуйтеся схваленого оператором порядку, наприклад контрольованого повернення або обмеження використання коштів. Не можна ігнорувати підтвердження, робити заблоковані кошти доступними для витрачання або вважати початкове списання невдалим. Так само локальна зупинка виплати потребує з’ясування результату зовнішнього переказу до вивільнення резерву.

Надайте підтримці безпечний доступ до статусу, часу та ідентифікаторів з чітким розподілом відповідальності за ескалацію. Доступ до секретів або необмеженої зміни балансу не замінює зручного процесу розслідування.

Ухвалюйте рішення про запуск на підставі перевірок

Виконайте кожен сценарій приймання для конкретної погодженої конфігурації мерчанта й способу оплати. Пакет доказів має містити ідентифікатори запиту та спроби, очищені від чутливих даних підтвердження провайдера, підсумкові проводки, зміни резервів і результат звірки. Визначте очікуваний результат до тесту; успішний код відповіді не є критерієм проходження.

Тести в пісочниці підтверджують функціональну поведінку. Вони не доводять дозволу працювати в промисловому середовищі, правильності робочих облікових даних, наявності реальної розрахункової звітності чи операційної готовності. Якщо провайдер і оператор дозволяють контрольовану перевірку в робочому середовищі, обмежте її підтримуваними юридичними особами, способами оплати й сумами; залучіть до розбору фінансову команду та підтримку. Перед відкриттям ширшого потоку перевірте робочу кінцеву точку вебхуків, ключі, доступ до звітів і відповідальність за попередження.

Визначте, як припиняти приймання нових депозитів чи виплат, зберігаючи обробку наявних спроб, пізніх сповіщень і повернень. Відкат має зберігати записи операцій в очікуванні та завдання, які їх звіряють. Відстежуйте тривалість очікування операцій з невідомим результатом, підтверджені платежі без проводок, завислі резерви й збої обробки вхідних подій; обирайте пороги, що потребують дій, для кожного способу оплати.

Вісім перевірок нижче — мінімальний набір доказів, а не гарантія схвалення чи повноти. Додайте сценарії автентифікації, часткових платежів, списань, повернень і спорів для конкретного способу оплати, якщо фактичний продукт їх підтримує. Запускайте інтеграцію лише з узгодженою відповідальністю за решту винятків і документованим рішенням про те, які нерозв’язані умови блокують новий потік.

• Повторний запит гравця: одночасне надсилання однієї операції створює одну зовнішню спробу; повторне використання її ідентифікатора з іншою сумою чи одержувачем відхиляється.
• Автентичність і належність: неправильний підпис, неправильне середовище чи чужий мерчант-акаунт не можуть зарахувати кошти; автентичний невідомий ідентифікатор спрямовується на розбір з призначеним відповідальним.
• Повторні й затримані події: повторне підтвердження створює одну проводку, а дійсне подальше списання, повернення чи повернення виплати залишається доступним для обробки.
• Втрачена відповідь і перезапуск: прийнятий запит із втраченою відповіддю відновлюється без нового списання чи виплати, зокрема після збою одразу після фіксації проводки.
• Невизначеність виплати: доступні кошти резервуються до відправлення й залишаються недоступними за невідомого результату; підтверджене повернення обліковується за фактичною сумою.
• Фінансова звірка: операції провайдера відповідають проводкам, а розрахункові пакети — руху грошей із документованими строками, комісіями, валютами та коригуваннями.
• Обмеження доступу: недозволені зміни реквізитів, доступ до іншого гравця й операції іншого бренду відхиляються без зміни коштів і надсилання запиту провайдеру.
• Робоча конфігурація та відкат: облікові дані, сповіщення й звіти належать до потрібного акаунта; зупинка нового потоку зберігає відновлення та звірку наявних операцій.