Payment Initiation Service

Payment Initiation Service (PIS)

Послуга ініціювання платежів дозволяє стороннім надавачам платіжних послуг (Third Party Provider, TPP) ініціювати платіжні операції з рахунку користувача платіжних послуг (Payment Service User, PSU) на підставі його згоди. Сервіс забезпечує безпечну передачу платіжних інструкцій через API та дозволяє TPP інтегрувати функціональність онлайн-платежів у власні продукти.

1. Загальна інформація та умови підключення до сервісу

1.1. Архітектура та стандарт

Спеціалізовані інтерфейси побудовані за принципами REST API та базуються на специфікації XS2A (Access to Account), яка реалізована через платформу відкритого банкінгу (Open Banking Platform, OBP). XS2A є стандартним інтерфейсом доступу третіх сторін до платіжних рахунків відповідно до вимог PSD2.

1.2. Транспортний протокол

Протокол: HTTPS (HTTP over TLS/SSL). Усі запити передаються виключно по захищеному каналу HTTPS. Використання незахищеного протоколу HTTP не допускається.

1.3. Формат даних

Формат тіла запитів та відповідей: JSON (JavaScript Object Notation). Заголовок Content-Type: application/json обов'язковий для всіх запитів, що містять тіло (POST).

1.4. Версійність

Поточна версія v2. Версія зазначається у базовому шляху URL: /pis/v2/ та /ais/v2/.

1.5. Обов'язкові заголовки HTTP 

• X-Request-Id — унікальний ідентифікатор запиту (UUID формат), наприклад: dc7b16a5-4ac8-4fdc-9c4e-9f9d0387dc07. Використовується для ідентифікації та трасування запиту.
• Content-Type — тип вмісту тіла запиту: application/json (для POST-запитів).
• PSU-ID — ідентифікатор користувача платіжних послуг (PSU) у системі банку.
• PSU-IP-Address — IP-адреса пристрою PSU.
• Consent-ID — ідентифікатор підтвердженої AIS-згоди (для запитів до AIS після авторизації).
• Client-Redirect-URI — URL для перенаправлення PSU після успішної авторизації (SCA Redirect).
• Client-Redirect-Nok-URI — URL для перенаправлення PSU у разі невдалої авторизації (SCA Redirect

1.6. Процедура взаємодії (PIS Flow)

1. TPP ініціює платіж (POST /payments/{payment-product}) → отримує paymentId.
2. TPP запускає авторизацію (POST /payments/{payment-product}/{payment-id}/authorisations) → отримує authorisationId та або psuMessage (Decoupled) або scaRedirect URL (Redirect).
3. PSU авторизує платіж (через застосунок банку або банківську веб-сторінку залежно від режиму SCA).
4. TPP перевіряє статус платежу (GET /payments/{payment-product}/{payment-id}/status) → отримує transactionStatus.
5. TPP інформує PSU про результат виконання платежу.

1.7. Коди помилок, специфічні для PIS

• 404 — PRODUCT_UNKNOWN: вказаний платіжний продукт не підтримується банком.
• 400 — PAYMENT_FAILED: запит на ініціювання платежу не вдалося опрацювати.
• 403 — SERVICE_BLOCKED: сервіс недоступний для PSU через незалежне блокування з боку банку.

1.8. Реєстрація та сертифікати

Для підключення до спеціалізованих інтерфейсів необхідно:

• пройти реєстрацію на Developer Portal (portal.api.upc.ua);
• отримати та налаштувати цифрові сертифікати для взаємної автентифікації TLS (mTLS) — відповідно до розділу "Certificates" порталу;
• налаштувати електронні підписи запитів — відповідно до розділу "Electronic signatures" порталу;
• зареєструвати застосунок у розділі "Applications" та оформити підписку на відповідний API-сервіс.

Технічні вимоги

• HTTP-клієнт з підтримкою HTTPS/TLS та мутуальної автентифікації (mTLS).
• Підтримка формату JSON для серіалізації та десеріалізації даних.
• Здатність формувати унікальні UUID для заголовка X-Request-Id.
• Реалізація логіки опитування статусу (polling) для перевірки статусу платежу та згоди.
• Реалізація механізму пагінації для обходу великих наборів транзакцій (параметри limit та offset).
• Наявність публічно доступних URL-адрес для Client-Redirect-URI та Client-Redirect-Nok-URI (для Redirect SCA).

Середовища

• Sandbox (тестове середовище): доступне для розробки та тестування інтеграції.
• Production (продуктивне середовище): для реальної взаємодії з платіжними рахунками PSU.

2. Опис функціоналу спеціалізованих інтерфейсів PIS:

2.1.  Ініціювання платежу

TPP надсилає запит на ініціювання платежу за допомогою методу POST. У запиті передаються дані про рахунок платника (IBAN), суму та валюту переказу, дані отримувача (ім'я, ідентифікатор, IBAN рахунку) та реквізити призначення платежу. Платформа повертає унікальний ідентифікатор транзакції (paymentId) та початковий статус платежу (RCVD — отримано).

• Метод та шлях: POST /pis/v2/payments/{payment-product}
• Параметр шляху: payment-product — тип платіжного продукту (наразі підтримується: instant-credit-transfers).

Тіло запиту (JSON):

• paymentIdentification.endToEndId — наскрізний ідентифікатор платежу (рядок).
• debtorAccount.iban — IBAN рахунку платника.
• debtorAccount.currency — валюта рахунку платника (наприклад, "UAH").
• instructedAmount.currency — валюта суми переказу.
• instructedAmount.amount — сума переказу (рядок у десятковому форматі, наприклад "12.21").
• creditor.name — ім'я отримувача.
• creditor.creditorId — ідентифікатор отримувача.
• creditor.creditorIdType — тип ідентифікатора отримувача (наприклад, "PSPT").
• creditorAccount.iban — IBAN рахунку отримувача.
• creditorAccount.currency — валюта рахунку отримувача.
• remittanceInformationUnstructured — масив рядків із призначенням платежу.

Відповідь (JSON): paymentId (UUID), transactionStatus ("RCVD"), _links.startAuthorisation.href.

2.2. Запуск авторизації (SCA)

Після ініціювання платежу TPP викликає метод POST /pis/v2/payments/{payment-product}/{payment-id}/authorisations для явного запуску процедури авторизації. Підтримуються два режими SCA:

• Decoupled SCA: платформа повертає повідомлення для PSU ($.psuMessage), наприклад, "Авторизуйте платіж у мобільному застосунку банку". PSU авторизує платіж безпосередньо у застосунку Банку (наприклад, через push-сповіщення).
• Redirect SCA: платформа повертає URL-адресу для перенаправлення PSU ($.links.scaRedirect.href). TPP перенаправляє PSU на сторінку банку для автентифікації та підтвердження платежу. Після авторизації банк перенаправляє PSU назад до TPP за вказаним адресою (Client-Redirect-URI).

Метод та шлях: POST /pis/v2/payments/{payment-product}/{payment-id}/authorisations

Параметри шляху: payment-product, payment-id (отримано з попереднього кроку).

Заголовки: Client-Redirect-URI, Client-Redirect-Nok-URI (обов'язкові для Redirect SCA).

Відповідь для Decoupled SCA (JSON): scaStatus ("received"), authorisationId (UUID), psuMessage (текст повідомлення для PSU).

Відповідь для Redirect SCA (JSON): scaStatus ("received"), authorisationId (UUID), _links.scaRedirect.href (URL для перенаправлення PSU на SCA-сторінку банку).

2.3. Перевірка статусу платежу

TPP може перевірити поточний статус платежу за допомогою методу GET /pis/v2/payments/{payment-product}/{payment-id}/status. Платформа повертає актуальний статус транзакції ($.transactionStatus), наприклад, ACCC (успішно завершено). Підтримувані продукти платежу: instant-credit-transfers.

Метод та шлях: GET /pis/v2/payments/{payment-product}/{payment-id}/status

Параметри шляху: payment-product, payment-id.

Відповідь (JSON): transactionStatus — статус транзакції (наприклад, "ACCC" — успішно завершено).

3. Опис програми тестування PIS

Передумови:

• Користувач зареєстрований в системі
• Має дійсний токен доступу (залогінений)
  • POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
  Тест-кейси тут