Payment Initiation Service

Payment Initiation Service (PIS)

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

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)

TPP ініціює платіж (POST /payments/{payment-product}) → отримує paymentId.
TPP запускає авторизацію (POST /payments/{payment-product}/{payment-id}/authorisations) → отримує authorisationId та або psuMessage (Decoupled) або scaRedirect URL (Redirect).
PSU авторизує платіж (через застосунок банку або банківську веб-сторінку залежно від режиму SCA).
TPP перевіряє статус платежу (GET /payments/{payment-product}/{payment-id}/status) → отримує transactionStatus.
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:

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

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

Тест кейс №1 Сreate consent initiation payments (POST /payments/instant-credit-transfers | POST /payments/credit-transfers)

Кроки виконання:

обрати провайдера до якого створюється платіж, зафіксувати providerId
обрати тип {payment-product} - instant-credit-transfers або credit-transfers
Зробити виклик до API:

POST /providers/{provider-id}/pis/v2/payments/{payment-product}

HEADERS:

X-Request-ID: 123e4567-e89b-12d3-a456-426614174000 // {uuid}

PSU-IP-Address: "1.1.1.1"

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

BODY

{

"debtorAccount": {

"iban": "UA313220000000026007233566001",

"currency": "UAH"

"instructedAmount": {

"currency": "UAH",

"amount": "12.21"

"creditor": {

"name": "Coden Postal",

"creditorId": "CP122540",

"creditorIdType": "PSPT"

"creditorAccount": {

"iban": "UA633220000000029908753443001",

"currency": "UAH"

"remittanceInformationUnstructured": [

"Some details"

]

}

Очікуваний результат:

Створено платіж з "transactionStatus": "RCVD"
У відповіді присутній "paymentId"

Приклад відповіді:

{

"transactionStatus": "RCVD",

"paymentId": "019cfaf3-6d52-76a0-9064-969a181c03ee",

"_links": {

"self": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfaf3-6d52-76a0-9064-969a181c03ee"

"status": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfaf3-6d52-76a0-9064-969a181c03ee/status"

"startAuthorisation": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfaf3-6d52-76a0-9064-969a181c03ee/authorisations"

}

Тест кейс № 2 Старт авторизації платежу (POST /payments/{payment-product}/{payment-id}/authorisations)

Передумови:

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

УВАГА: тип {payment-product} в запиті повинен відповідати типу, для якого створювався платіж у Тест кейс № 1

Можливі значення {payment-product} - instant-credit-transfers або credit-transfers

Кроки виконання:

Зробити Виклик до API:

POST /providers/{provider-id}/pis/v2/payments/{payment-product}/{payment-id}/authorisations

HEADERS:

X-Request-ID: 123e4567-e89b-12d3-a456-426614174000

Client-Redirect-URI: https://google.com

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

PSU-ID: "2353909119" // use this value for sandbox

PSU-ID-Type: "PHONE"

BODY:

{}

Очікуваний результат:

Створено платіж з "transactionStatus": "RCVD"
У відповіді присутній "paymentId"

Приклад відповід

{

"scaStatus": "received",

"_links": {

"scaStatus": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfb75-7982-78b5-9a50-b92813afcd7b/authorisations/019cfb75-8e7d-755d-bbc2-e1e5928a3698"

"scaRedirect": {

"href": "https://portal.preprod.api.upc.ua/sca-client/mock/upc/bfdb6794-bcb8-4dde-9f3b-07acf73ef202/019cfb75-8e7d-755d-bbc2-e1e5928a3698/consent"

}

"authorisationId": "019cfb75-8e7d-755d-bbc2-e1e5928a3698"

}

Для Client-SCA-Approach-Preference: redirect

Додатково: на sandbox доступна емуляція підтвердження платежу з боку користувача з PSU-ID: "2353909119".

Перейти за посиланням у _links/scaRedirect (якщо Client-SCA-Approach-Preference: redirect) або ініціювати SCA через інший канал (якщо Client-SCA-Approach-Preference: decoupled)
на Sandbox сторінці створено обробник, де можна прийняти або відхилити запит на авторизацію:
Підтвердити авторизацію натиснувши "Confirm"

Тест кейс № 3 Отримання деталей платежу (GET /payments/{payment-product}/{payment-id})

Передумови:

Користувач має дійсний токен доступу (залогінений)
- POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
Існує створений платіж (див. Тест кейс № 1, № 2), зафіксовано payment-id

Кроки виконання:

Зробити Виклик до API:

GET /providers/{provider-id}/pis/{apiGroupVersion}/payments/{payment-product}/{payment-id}

HEADERS:

X-Request-ID: "72ebf0c7-31d4-43be-8786-261bd4e5d8a3" // {uuid}

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

BODY:

Null

Очікуваний результат:

Тіло відповіді містить поточний статус Consent

Приклад, фрагмент відповіді:

{

"transactionStatus": "RCVD",

"_links": {

"self": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfbb3-d015-7a47-bd16-76f18e90d58e"

}

//...

}

Тест кейс № 4 Отримання статус платежу (GET /payments/{payment-product}/{payment-id}/status)

Передумови:

Користувач має дійсний токен доступу (залогінений)
- POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
Існує створений Consent (див. Тест кейс № 1, № 2), зафіксовано consentId (він же payment-id)

Кроки виконання:

Зробити Виклик до API:

GET /providers/{provider-id}/pis/{apiGroupVersion}/payments/{payment-product}/{payment-id}/status

HEADERS:

X-Request-ID: "72ebf0c7-31d4-43be-8786-261bd4e5d8a3" // {uuid}

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

BODY:

null

Очікуваний результат:

Тіло відповіді містить поточний статус Consent

Приклад, фрагмент відповіді

{

"transactionStatus": "RCVD"

}

Тест кейс №5 Отримання авторизацій платежу (GET /payments/{payment-product}/{payment-id}/authorisations)

Передумови:

Користувач має дійсний токен доступу (залогінений)
- POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
Існує створений платіж (див. Тест кейс № 1, № 2), зафіксовано consentId (він же payment-id)

Кроки виконання:

Зробити Виклик до API:

GET /providers/{provider-id}/pis/{apiGroupVersion}/payments/{payment-product}/{payment-id}/authorisations

HEADERS:

X-Request-ID: "72ebf0c7-31d4-43be-8786-261bd4e5d8a3" // {uuid}

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

BODY:

null

Очікуваний результат:

Тіло відповіді містить наявні authorisationIds

Приклад відповіді:

{

"authorisationIds": [

"019cfbb3-eee5-771a-b877-89a5a17cd505"

]

}

Тест кейс № 6 Отримання деталей авторизації платежу (GET /payments/{payment-product}/{payment-id}/authorisations/{authorisation-id})

Передумови:

Користувач має дійсний токен доступу (залогінений)
- POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
Існує створений платіж (див. Тест кейс № 1, № 2), зафіксовано consentId (він же payment-id)
зафіксовано authorisation-id (див. Тест кейс № 5)

Кроки виконання:

Зробити Виклик до API:

GET /providers/{provider-id}/pis/{apiGroupVersion}/payments/{payment-product}/{payment-id}/authorisations/{authorisation-id}

HEADERS:

X-Request-ID: "72ebf0c7-31d4-43be-8786-261bd4e5d8a3" // {uuid}

Content-Type: application/json

Authorization: "Bearer {openid-connect/token}"

BODY:

null

Очікуваний результат:

Тіло відповіді містить деталі authorisationId

Приклад відповіді:

{

"scaStatus": "finalised",

"_links": {

"scaStatus": {

"href": "/sandbox/pis/v2.0/payments/instant-credit-transfers/019cfbb3-d015-7a47-bd16-76f18e90d58e/authorisations/019cfbb3-eee5-771a-b877-89a5a17cd505"

"scaRedirect": {

"href": "https://portal.preprod.api.upc.ua/sca-client/mock/upc/bfdb6794-bcb8-4dde-9f3b-07acf73ef202/019cfbb3-eee5-771a-b877-89a5a17cd505/consent"

}

"authorisationId": "019cfbb3-eee5-771a-b877-89a5a17cd505"

}