6. Отримання статусу платіжної операції
Редакція OpenBanking Ukraine
Цей розділ описує, як перевірити статус ініційованої платіжної операції та як отримати вміст (деталі) об’єкта платіжної операції за її ідентифікатором paymentId.
6.1. Отримання статусу платіжної операції
Виклик
GET /v2/{payment-service}/{payment-product}/{paymentId}/status
Дозволяє перевірити статус платіжної операції.
Path parameters
| Атрибут | Тип | Опис |
|---|---|---|
| paymentservice | String | Можливе значення: payments. |
| paymentproduct | String | Платіжний продукт, за яким було ініційовано платіжну операцію відповідно до paymentId. ASPSP має перевірити, чи відповідає вказаний платіжний продукт тому, який був зазначений при ініціюванні платіжної операції (відповідно до розділу 5 даного документу) по paymentId. |
| paymentId | String | Ідентифікатор ресурсу платіжної операції. |
Request headers
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| X-Request-ID | UUID | Mandatory | Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором (TPP). |
| Authorization | String | Conditional | Атрибут заповнюється, якщо обрано OAuth2 як попередній крок для автентифікації PSU. |
| Accept | String | Optional | Формат, підтримуваний цією специфікацією: JSON (обов’язковий для базових API). Якщо ASPSP підтримує лише один формат — то при отриманні запиту від TPP із значенням формату, який не підтримується — такий запит буде відхилений ASPSP. |
Query parameters
Немає.
Request body
Немає.
Response
Response code: 200.
Response headers
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| X-Request-ID | UUID | Mandatory | Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором (ТРР). |
Response body
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| transactionStatus | Transaction Status | Mandatory | Статус платіжної операції. Можливі значення: RCVD, ACTC, PDNG, ACSC, ACCC, RJCT. |
| reasonCode | Status Reason Code | Or - Optional | Додаткова інформація про причину, наприклад, відхилення запиту — див. таблицю нижче “Status Reason Code”. |
| reasonProprietary | Max35Text | Or – Optional | Опис для Status Reason Code (див. поле “Назва“ у таблиці нижче – “Status Reason Code”). |
| fundsAvailable | Boolean | Conditional | Цей елемент даних міститься, якщо він підтримується ASPSP, якщо перевірка коштів була виконана і якщо статус транзакції є ACTC. |
| transactionFees | Amount | Optional | Може використовуватися ASPSP для передачі загальної комісії за операцію, що стосується виконання платіжної операції. |
| currencyConversion Fees | Amount | Optional | На даний момент не буде використовуватись в Україні. Може використовуватися ASPSP для передачі конкретних комісій за конвертацію валюти, пов’язаних з ініційованим кредитним переказом, у разі надання послуги з ініціювання платіжної операції. |
| estimatedTotalAmount | Amount | Optional | Розрахункова сума списання з рахунку платника у разі виконання платіжної операції. Примітка: ця сума включає комісії. |
| estimatedInterbank SettlementAmount | Amount | Optional | Розрахункова сума, яка буде переведена отримувачу у разі виконання платіжної операції. |
| psuMessage | Max500Text | Optional | ASPSP може за потреби надіслати текст стосовно платіжної операції, який відображатиметься PSU. За замовчуванням текст повідомлення передається українською мовою. |
| ownerNames | Array of Account Owner | Optional | Список імен власників рахунку, наприклад, довірені особи. Повинен надаватися лише після успішної автентифікації PSU (SCA). |
| _links | Links | Optional | Має вказувати на наступні кроки, якщо потенційну ситуацію, що блокує завершення виконання платіжної операції, можна вирішити через інтерфейс платіжного застосунку ТРР. |
| apiClientMessages | Array of API Client Message Information | Optional | Повідомлення для PISP щодо операційних питань. |
Status Reason Code
ASPSP повинен підтримувати такі коди зі списку ISO20022 ExternalStatusReasonCode1, наведені у таблиці нижче. Зазначені коди слід використовувати лише в тому випадку, якщо відповідний ресурс було створено на рівні API, тобто якщо можна надати статус платіжної операції. В іншому випадку достатньо використовувати відповідний код повідомлення в інформації про помилку (Data Dictionary).
| Код | Назва | Примітки щодо застосування ISO 20022 у відкритому банкінгу |
|---|---|---|
| AM04 | InsufficientFunds | Застосовується коли сума доступних коштів є недостатньою для виконання платіжної операції. |
| AM21 | LimitExceeded | Застосовується, коли сума транзакції перевищує ліміти, узгоджені між ASPSP і PSU. |
| BEXX | There are several codes identifying specific invalid data. | Застосовується коли є декілька причин, зазначених у коді BEХХ. |
| CN01 | AuthorisationCancelled | Застосовується коли авторизацію платіжної операції скасовано. |
| DS0C | SignerCertificateRevoked | Застосовується коли сертифікат підпису/корпоративної печатки PSU відкликано. |
| DS0D | SignerCertificateNotValid | Застосовується коли сертифікат підпису/корпоративної печатки PSU заблокований ASPSP або якщо сертифікат прострочений. |
| DS0A | DataSignRequested | Застосовується коли підпис корпоративною печаткою/сертифікатом PSU є обов’язковим за вимогою ASPSP, але відсутній. |
| DS04 | OrderRejected | Застосовується коли причиною відхилення платіжної операції є те, що зміст ініційованої платіжної операції виявився недійсним під час обробки після початкового прийняття. |
| TKSP | TokenSuspended | Застосовується коли токен доступу зі статусом “призупинено”. |
| TKXP | TokenExpired | Застосовується коли токен доступу прострочений. |
Приклад
{
"transactionStatus": "RCVD"
}
6.2. Отримання вмісту об’єкта платіжної операції
Виклик
GET /v2/{payment-service}/{payment-product}/{paymentId}
Повертає вміст об’єкта платіжної операції.
Path parameters
| Атрибут | Тип | Опис |
|---|---|---|
| paymentservice | String | Можливе значення: payments. |
| paymentproduct | String | Платіжний продукт, за яким було ініційовано платіж під цим paymentId. ASPSP має перевірити, чи відповідає вказаний платіжний продукт тому, який був зазначений при ініціюванні платіжної операції (відповідно до розділу 5 даного документу) по paymentId. |
| paymentId | String | Ідентифікатор ресурсу платіжної операції. |
Query parameters
Немає.
Request headers
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| X-Request-ID | UUID | Mandatory | Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором (TPP). |
| Authorization | String | Conditional | Атрибут заповнюється, якщо обрано OAuth2 як попередній крок для автентифікації PSU. |
Request body
Немає.
Response
Response code: 200.
Response headers
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| X-Request-ID | UUID | Mandatory | Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором. |
Response body
Body містить дані ASPSP про запитуваний платіжний ресурс. У таблиці нижче наведені обов’язкові атрибути. Повний перелік атрибутів можна знайти в yaml-файлі.
| Код параметру | Тип даних | Обов’язковість | Опис | |
|---|---|---|---|---|
| instructedAmount | - | - | mandatory | Сума переказу між платником та отримувачем. |
| currency | string (pattern: [A-Z]{3}) | mandatory | Код валюти відповідно до Класифікатора іноземних валют НБУ (ISO 4217 Alpha 3 currency code). | |
| amount | string | mandatory | Сума, наведена як число з дробовою частиною. Десятковий роздільник - крапка. До крапки можливо не більше 14 значущих цифр. Приклад: 1056 5768.2 5877.78 | |
| creditorAccount | - | - | mandatory | Однозначна ідентифікація рахунку отримувача, на який будуть або зараховані кошти. |
| iban | string (UA[0-9]{27,27}) | - | iban | |
| currency | string (pattern: [A-Z]{3}) | - | Код валюти відповідно до Класифікатора іноземних валют НБУ (ISO 4217 Alpha 3 currency code). | |
| creditor | - | - | mandatory | Отримувач |
| name | string (maxLength: 140) | - | Найменування юридичної особи/ФОП/прізвище, ім’я, по батькові (за наявності) фізичної особи - отримувача коштів. | |
| creditorId | string | - | Цей атрибут доданий до оригінальної специфікації Berlin Group і відсутній в yaml файлі. Значення цього атрибуту заповнюється в залежності від обраного creditorIdType відповідно до “Загальні правила реалізації стандарту ISO 20022, спільні для всіх інструментів Частина 2. Ідентифікація”. | |
| creditorIdType | ENUM | - | Цей атрибут доданий до оригінальної специфікації Berlin Group і відсутній в yaml файлі. Тип ідентифікатора отримувача. Можливі значення та умови заповнення наведені у “Загальні правила реалізації стандарту ISO 20022, спільні для всіх інструментів Частина 2. Ідентифікація”: RNRCT, PSPT, OT, UNK, USRC, TRAN, NA. | |
| remittanceInformationUnstructured | array (Max420Text) | mandatory | Призначення платежу. | |
| debtorAccount | - | - | optional | Однозначна ідентифікація рахунку платника |
| iban | string (UA[0-9]{27,27}) | - | iban | |
| currency | string (pattern: [A-Z]{3}) | - | Код валюти відповідно до Класифікатора іноземних валют НБУ (ISO 4217 Alpha 3 currency code). | |
| transactionStatus | Transaction Status | ENUM | Mandatory | Статус. Можливі значення: RCVD, ACTC, PDNG, ACSC, ACCC, RJCT. |