Шар оркестрації платежів — це софт між вашим checkout і платіжними провайдерами. Він тримає всі рішення про платіж, крім самих грошей: кому його віддати, що означає відповідь, у якому стані платіж зараз і кого повідомити про зміну. Ваш код говорить з одним API. Шар говорить з усіма еквайерами, гаманцями, банківськими рейками під ним.
Зверніть увагу на слово шар. Це позиція у стеку, а не назва продукту. Цю позицію можна купити у вендора, а можна побудувати самим і посадити на неї людей. Частини всередині однакові в обох випадках. Тому й варто знати, які вони.
Саму практику — тримати кілька провайдерів за правилами — розібрано в матеріалі що таке оркестрація платежів. Цей текст про коробку: де вона стоїть, що в ній, що вона знімає з вас і чого не зробить ніколи.
Що таке шар оркестрації платежів
Шар визначається тим, що стоїть над ним і під ним.
Над: ваш checkout, бекофіс, білінг підписок, фінансові звіти. Під: еквайери, гаманцеві схеми, рейки банківських переказів, ризик-вендори. Шар перетворює багато знизу на одне зверху. У цьому реченні вся ідея. Решта статті — наслідки з нього.
Уявіть подорож з однією вилкою. У кожній країні своя розетка, тому ви возите перехідник. Місцеву проводку ви так і не вивчите. Її знає перехідник, а вам показує ту форму, яку ваш пристрій уже розуміє.
Шар не є провайдером. У нього немає еквайрингової ліцензії, він не зараховує гроші на ваш рахунок і не несе ризику чарджбеку. Він продає вам форму, а не розрахунок. Межу між шаром і звичайним gateway розібрано окремо: оркестрація платежів проти платіжного шлюзу.
Шар, платформа чи провайдер: яке слово вам потрібне
Три слова вживають як синоніми, і ця плутанина коштує цілих зустрічей.
| Слово | Що це насправді |
|---|---|
| Шар | Місце в архітектурі. Воно існує навіть тоді, коли розробник зліпив його вручну на if |
| Платформа | Продукт, який дає це місце готовим: конектори, правила, звітність |
| Провайдер | Компанія, яка реально рухає гроші й тримає ліцензію |
Платформа оркестрації — це куплений шар. Ваш власний код маршрутизації — побудований шар. Обидва стоять в одному слоті. Обидва розв’язують той самий список проблем нижче.
Де шар стоїть у вашому стеку
Намалюйте чотири поверхи — і картинка перестане бути абстрактною.
| Поверх | Приклади | Чого тут бути не повинно |
|---|---|---|
| Над | Checkout, застосунок, бекофіс, білінг, аналітика | Дивацтв провайдерів, ключів підпису, кодів відмов |
| Шар | Маршрутизація, конектори, стан платежу, події назовні | Сирих номерів карток, політики, за яку ніхто не відповідає |
| Поруч | Сховище карток, реєстр, база звітів | Того, на що чекає гарячий шлях платежу |
| Під | Еквайери, гаманці, банківські рейки, ризик-вендори | Вашого словника звітності |
Найбільше дивує поверх поруч. Сховище карток лежить не всередині шару, і це зроблено навмисно.
У нас у платформі сервіс маршрутизації взагалі не бачить номера картки. Він тримає UUID-токен. Номер живе в окремому сервісі, який шифрує його через HashiCorp Vault Transit ключем aes256-gcm96 з ротацією кожні 2160 годин — 90 днів. Сервіс маршрутизації може попросити провести платіж токеном X. Розгорнути X назад у номер картки для власних потреб він не може.
Розділення нудне, а виграш від нього зовсім не нудний. Дані карток — та частина системи, якою найбільше цікавляться регулятори, аудитори, зловмисники. Коли їх немає в найзавантаженішому та найчастіше змінюваному сервісі, код маршрутизації можна викочувати двічі на тиждень і не тягти сховище за собою.
З чого складається шар оркестрації платежів
Роботу роблять вісім частин. Першу покупці пропускають, а інженери гублять на ній тижні.
1. Край (edge). Автентифікація, підпис запиту, ідемпотентність, валідація. Це контракт, у якому живе ваш код. Змінити його потім, не зламавши жодної інтеграції, вже не вийде.
2. Маршрутизатор. Правила плюс живі сигнали. Одна відповідь на платіж: кому його віддати і кому віддати, якщо перший скаже «ні».
3. Конектори. По одному на провайдера. П’ять еквайерів у нас підписують запити чотирма різними способами: RSA SHA-512, двічі HMAC-SHA1, SHA1 з Base64, голий SHA1. Конектор поглинає цей зоопарк, і ваш checkout про нього не дізнається.
4. Машина станів. Один словник на всіх провайдерів. У нас дванадцять статусів платежу, з них п’ять фінальні: declined, expired, voided, refunded, error. Settle дозволений лише з одного статусу (on_hold), refund — з трьох, void — з чотирьох.
5. Шлях грошей назовні. Повернення, скасування, виплати. У кожного свій життєвий цикл, свої способи зламатися, свій виклик API в кожного провайдера.
6. Події назовні. Вебхуки у ваші системи. Найнедооціненіша частина коробки — і з найкращою бойовою історією нижче.
7. Площина конфігурації. Правила маршруту, креденшели провайдерів, тарифи, sandbox- і production-акаунти. Тут потрібен ще й сухий прогін: у нас він вміє симулювати рішення маршруту та повернути обраного провайдера, запасного, вартість і правила, які спрацювали, не створюючи транзакції. Питайте цю функцію на ім’я.
8. Реконсиляція. Звіряння того, що каже провайдер, з тим, що каже банк. Її зазвичай продають під словом «звітність», і зазвичай це найслабша частина будь-якого шару — купленого чи власного.
Як платіж проходить крізь шар, крок за кроком
Ось маршрут разом із деталями, які вилазять тільки в проді.
Крок 1. Запит прийшов, і його автентичність доведено. Підпис, timestamp, nonce. Канонічний рядок підпису у нас має вісім рядків: версія, метод, шлях, відсортована query-строка, SHA-256 тіла, timestamp, nonce, ключ ідемпотентності. Вікно для timestamp — ±5 хвилин, кожен nonce пам’ятається вдвічі довше.
Крок 2. Перевірка ідемпотентності. Якщо такий самий ключ уже приходив, назад віддається збережена відповідь, а платіж не проводиться вдруге. У нас відповідь лежить 24 години в просторі імен, прив’язаному до конкретного API-ключа.
Крок 3. Бар’єр середовищ. Sandbox-акаунти та production-акаунти не змішуються ніколи й для жодної операції. Якщо після бар’єра кандидатів не лишилося, платіж відхиляється з відповідною причиною. Тихої підміни середовища не буває.
Крок 4. Маршрут обирає основного та запасного. Спочатку правила, далі можливості, далі здоров’я, далі вартість. Покроковий розбір самого маршруту — у матеріалі що таке оркестрація платежів. Тут важливо інше: відповідь — це два провайдери, а не один.
Крок 5. Конектор перекладає і викликає. Ваші поля стають їхніми полями, їхня відповідь стає вашим статусом.
Крок 6. Платіж паркується, якщо треба. Челендж 3DS відправляє держателя картки до його банку. Платіж стоїть у статусі waiting_auth, поки людина вбиває код на сторінці, яку ви не контролюєте. Шар мусить тримати цей стан, пережити подорож браузера туди й назад і впоратися з тим, що колбек провайдера прийде раніше, ніж повернеться браузер покупця. Ця гонка реальна, вона трапляється щодня. Шар, який вважає, що браузер завжди перший, задвоїть платежі.
Крок 7. Статус змінився — про це кажуть світу. Ваші системи отримують вебхук. Ваші звіти отримують рядок. Ваша реконсиляція отримує очікування, яке треба буде звести.
Шість кроків із семи не мають до маршрутизації жодного стосунку. Ось у чому помиляється більшість текстів про оркестрацію: маршрут — це відома частина, але інженерні тижні з’їдають стан, контракт і події.
Що шар знімає з вашого коду
Якщо коротко: він поглинає різницю, щоб ваш застосунок лишався необізнаним.
- Різницю в діалекті. Чотири схеми підпису, п’ять провайдерів, одна форма запиту для вас.
- Різницю в словнику. П’ятнадцять нормалізованих причин відмови замість власного списку в кожного еквайера:
insufficient_fundsозначає те саме, хто б це не сказав. - Різницю в життєвому циклі. Одне місце, яке знає, що void — не refund, а прострочений hold — не відмова.
- Різницю в безпеці. Ідемпотентність, захист від повторів і бар’єр sandbox пишуться один раз, а не на кожну інтеграцію.
- Різницю в часі. Повтор до запасного провайдера відбувається всередині шару, у тому самому запиті, і ваш checkout навіть не дізнається, що щось пішло не так.
Цінність не в тому, що якась одна з цих задач складна. Цінність у тому, що всі вони нудні, а нудна робота в п’яти місцях завжди розповзається.
Де шар ламається на практиці
Кожен пункт нижче комусь коштував реального часу. Більшість — нам.
Вихідні вебхуки всередині запиту платника
Це найкращий приклад проблеми шару, від якої не врятує жодна функція маршрутизації.
Доставка вебхуків у нас колись була синхронною — просто в тому запиті, на який дивиться платник. Один підвислий endpoint мерчанта блокував потік на всі 10 секунд HTTP-таймауту. Доставки йшли одна за одною, тож мерчант із трьома підписками додавав 30 секунд до відповіді чекауту. Це заміряне число, а не оцінка. Повторів не було зовсім: один POST, а при невдачі рядок у лозі — і сповіщення зникало.
Виправлення було не розумним, а просто правильним. Доставка переїхала в чергу: п’ять спроб із паузами 10 секунд, 1 хвилина, 5 хвилин, 15 хвилин. Тіло фіксується в момент події, тому повтор не може привезти новіший стан і переплутати порядок подій. Підпис рахується заново на кожній спробі: після 15-хвилинної паузи старий timestamp виглядав би для мерчанта як replay, і той справедливо відхилив би запит. Невдачі осідають у dead-letter із журналом доставок, а не зникають.
Питайте будь-якого вендора, де вихідні вебхуки стоять відносно платіжного запиту. Розмита відповідь означає, що ви знайшли те, що покладе ваш чекаут у найгарячіший день.
Підпис, який не покриває шлях
Перша схема підпису у нас підписувала тільки тіло та timestamp. Метод, шлях, query-строка, ключ ідемпотентності — нічого з цього в неї не входило.
Звучить академічно, поки не випишеш наслідок: підпис для POST /payments/{A}/refund був так само дійсний для POST /payments/{B}/void, бо тіло в них однакове. Схему замінили на місці — на той восьмирядковий канонічний рядок вище — ще до того, як вона побачила бойовий трафік. Заодно з’явився nonce: вікно ±5 хвилин саме собою захистом від повторів не є.
Коли дивитеся на чужий шар, питайте, що саме покриває підпис. «Ми підписуємо запит» — це не відповідь. Відповідь — це рядки канонічного рядка.
Здоров’я провайдера завжди трохи протухле
Оцінка здоров’я у нас — це 70% частка успішних запитів і 30% час відповіді. Менше секунди дає максимум за час, десять секунд дають нуль, провайдер без свіжого трафіку сидить на нейтральних 50, а не на нулі. Нижче 40 провайдер випадає зі списку кандидатів.
А тепер частина, важлива архітектурно. Ця оцінка рахується за розкладом раз на п’ять хвилин і лежить у Redis десять хвилин, бо платіжний шлях не може дозволити собі SQL-агрегат на кожну транзакцію. Тобто маршрут вирішує за числом, яке описує вікно, що вже закрилося. Живого варіанта тут не існує. Коротке вікно перебільшує шум, довге проґавить збій, який почався вісім хвилин тому, а будь-який кеш перед ними додає власне запізнення.
Чесна мета — не свіжість. Чесна мета — щоб шар продовжував платити, коли число бреше: якщо всі кандидати нижче порога, фільтр здоров’я знімається взагалі й платіж іде далі. Кволий провайдер кращий за жодного.
Каталог можливостей зручно бреше
Каталог у нас показує Click to Pay як підтриманий метод у всіх п’яти еквайерів. У коді, який працює о третій ночі, криптограму гаманця на нашому власному чекауті приймають тільки двоє: Hutko та Ощадбанк. Решта троє підтримують гаманець на своїй хостованій сторінці. Слово одне, інтеграції дві різні.
Тому маршрут читає для цієї перевірки окрему, вужчу функцію, а не каталог. Читав би каталог — відправив би гаманцевий платіж туди, де його фізично не приймуть, і покупець побачив би помилку, якої не пояснює жодна панель.
У кожного шару є своя версія цієї пастки. Питати треба, яке джерело правди читає маршрутизатор, а не що написано в матриці функцій.
Некарткові рейки не лізуть у карткову машину станів
Картковий платіж — це діалог: ви питаєте, емітент відповідає, ви отримуєте авторизацію. Банківський переказ — ні. Ніхто вам не відповідає. Гроші або приходять на рахунок пізніше, або ні.
Український QR за стандартом IBAN+ працює саме так. Його задає Постанова Правління НБУ № 97 від 19 серпня 2025 року, чинна з 1 листопада 2025 року. Покупець сканує код, його банківський застосунок робить кредитовий переказ, а шар дізнається про це лише з банківської виписки. Формат 003 обмежує закодований payload 507 байтами, старіший формат 001 — 331 байтом. PAN у ньому не буває взагалі, тому вся рейка лежить поза scope карткових даних.
Для шару це означає дві осі одночасно:
- Вісь платежу — те, що покупець збирався зробити.
- Вісь розрахунку — те, що, за словами банку, сталося насправді.
Їх зводять пізніше, за випискою, із захистом від дублів за ідентифікатором банківської транзакції. Типове вікно на оплату у нас — 30 хвилин. Гроші, що прийшли після нього, потребують написаної політики, а не знизування плечима.
Якщо ви обираєте шар і місцеві банківські рейки є у вашій дорожній карті, саме це питання розводить продукти по різні боки. Шар, у якому все змодельовано як карткова авторизація, прикрутить перекази окремим випадком — і цей випадок протече у ваші звіти.
Шар — це одна залежність із бюджетом пропускної здатності
Ви прибрали п’ять інтеграцій і додали одну штуку, крізь яку тепер іде кожен платіж. Зазвичай це правильний розмін. І це все одно розмін.
Бюджет — його частина. На одному бета-хості, з обмеженням у 8 воркерів платіжного сервісу, 4 для клієнта сховища та 2 для самого Vault, навантажувальні тести показали близько 30 транзакцій на секунду стійко і близько 33 на стелі. Це число описує один тестовий стенд одного дня. Це не обіцянка про чийсь бойовий трафік — і це рівно те число, яке варто просити у вендора з тими самими застереженнями.
Чого шар оркестрації платежів не вміє
Скажу прямо, бо категорію продають так, наче коробка лікує все.
PCI-scope сам собою нікуди не їде. Scope ходить за даними карток, а не за схемами архітектури. Частина вимог не залишає вас узагалі: у PCI DSS v4.0.1 вимоги 6.4.3 та 11.6.1 — інвентаризація скриптів і виявлення підміни на платіжній сторінці — стали обов’язковими з 31 березня 2025 року й стосуються сторінки у браузері покупця, тобто вашої. Шар змінює, скільки карткових даних торкається ваших серверів. Пропатчити вашу сторінку чекауту він не може.
Погляд на гроші лишається розділеним. Шар зводить погляд на платежі, а не погляд банку. П’ять провайдерів — це й далі п’ять файлів розрахунків, п’ять розкладів, п’ять способів назвати повернення, п’ять наборів комісій, утриманих до того, як гроші прийдуть. Питайте, що шар робить після розрахунку, а не лише до авторизації.
Відсутня можливість не з’явиться. Маршрутизатор не замінює покриття: якщо у вашого еквайера немає ринку чи методу, він його не наколдує. Він лише здешевлює відправку цього трафіку кудись іще.
Політику все одно хтось тримає. Софт не замінює людину, яка ухвалює рішення. Хтось усе одно має ці рішення ухвалювати, дивитися на результат і міняти їх, коли міняється ринок. Команди, які купили шар і не призначили нікого, отримують дорожчу версію того, що мали.
Перевірка вендора лишається вашою. Вимога PCI DSS 12.8.5 очікує, що ви знаєте, якими вимогами керує постачальник послуг, а які лишаються на вас. Ця матриця — документ, який ви тримаєте, а не логотип на чужому сайті.
Повніший список того, що вимагати від продукту по функціях, є в матеріалі софт для оркестрації платежів: що він мусить уміти.
Хто користується шаром оркестрації платежів
Усі, у кого більше одного провайдера. Питання лише в тому, чи знають вони про це.
Якщо двоє розробників колись сперечалися, якому еквайеру віддати повтор, шар у вас уже є. Просто він живе всередині if, а вся його документація — це пам’ять однієї людини.
На практиці явний шар заводять чотири групи: транскордонні мерчанти, які збирали місцевих провайдерів ринок за ринком; підписки, чий дохід тримається на тому, чи переживе продовження першу відмову; високоризикові вертикалі, яким другий живий провайдер потрібен заради безперервності, а не оптимізації; платформи, що успадковують географію всіх своїх продавців одразу.
Зверніть увагу: розміру в цьому списку немає. Маленький мерчант, який продає у шість країн, впирається в цю стіну значно раніше за великого з одним ринком.
Вам потрібна платформа оркестрації чи достатньо шару
Шар вам потрібен у будь-якому разі. Питання в тому, хто його будує та обслуговує.
Будуйте самі, коли платежі — це ваш продукт, ваша логіка маршруту справді незвичайна, а в команді є людина, для якої цей код — робота, а не підробіток. Купуйте, коли хочете, щоб вісім нудних частин уже існували, а інженерів краще витратити на свою предметну область. Чесна перевірка — одне питання: за три роки, коли автор того коду піде, чи лишиться в нього господар?
Сигнал, що ви переросли свій if, зазвичай один із таких:
- Додати провайдера означає реліз, і цей реліз когось лякає.
- Ніхто не назве три головні причини відмов за минулий місяць без розробника.
- Збій провайдера зупинить дохід, а не сповільнить його.
- Ваші звіти не сходяться з банком, і розходження зводять руками.
Один пункт — звичайний вівторок. Три пункти — проєкт.
Як обрати провайдера оркестрації платежів: п’ять питань про шар
Список функцій підробити легко. Ці п’ять питань слайдом не закриєш: у кожного є конкретна правильна форма відповіді.
1. Що саме покриває ваш підпис? Вам потрібен канонічний рядок по рядках. Метод і шлях входять? Query-строка? Ключ ідемпотентності? Є nonce чи лише часове вікно?
2. Як працює ідемпотентність? Питайте про строк зберігання, простір імен ключа і про те, що буде, якщо той самий ключ прийде з іншим тілом. Мовчання на останньому пункті — це баг, який стане вашим.
3. Коли порахували число здоров’я? Будь-яка конкретна відповідь годиться. «У реальному часі» означає, що ніхто не дивився.
4. Де вихідні вебхуки стоять у шляху запиту? Далі: скільки повторів, за яким розкладом, і чи можна перевідправити доставку з їхньої панелі, коли ваш endpoint лежав годину.
5. Як змодельована некарткова рейка? Банківські перекази, QR, гаманці. Якщо у відповіді все зводиться до authorise-and-capture, ви вже знаєте, звідки прийде біль із реконсиляцією.
Ось як читати відповіді.
| Що ви чуєте | Що це означає |
|---|---|
| Названо поле, файл або розклад, який можна перевірити потім | Вони билися об цю проблему |
| Правильна поведінка описана загальними словами | Швидше за все нормально, просіть документ |
| «Наш рушій робить це автоматично» | У кімнаті ніхто не знає |
Запишіть дослівно відповідь на четверте питання. Саме її переписують між дзвінками.
Що зробити цього тижня
Три речі, і жодна з них не потребує проєкту.
Знайдіть свій шар. Пошукайте в кодовій базі місце, яке обирає провайдера. Воно є. Прочитайте його вголос на зустрічі: той, хто це писав, залишив коментар, і цей коментар — ваш документ вимог.
Заміряйте шлях вебхука. Надішліть собі сповіщення на приймач, який спить 10 секунд, і подивіться, що станеться з відповіддю чекауту. Якщо вона чекає — ви знайшли той самий баг, що був у нас, і тепер знаєте його ціну.
Опишіть одну гонку. Візьміть повернення з 3DS. Запишіть, що робить ваша система, коли колбек провайдера приходить раніше за браузер покупця. Якщо ніхто не знає — ось перший тест, який варто написати.
Зробіть ці три речі — і знатимете про власний шар більше, ніж скаже будь-яка порівняльна таблиця. А коли час дивитися, хто стоїть під ним, довідник провайдерів показує еквайерів і методи оплати за країнами та вертикалями, щоб почати з тих, хто реально працює там, де ви продаєте.
Числа про платформу взято з вихідного коду платіжного сервісу P26M, звірено 1 вересня 2026 року. Номери вимог PCI DSS і дата 31 березня 2025 року подані за PCI DSS v4.0.1 у редакції PCI Security Standards Council. Український QR описано за Постановою Правління НБУ № 97 від 19 серпня 2025 року.
