5. Ініціювання платіжної операції у форматі JSON

Редакція OpenBanking Ukraine

Ця сторінка описує виклик API для створення запиту на ініціювання платіжної операції в ASPSP у форматі JSON, включно з параметрами шляху, заголовками, тілом запиту та структурою відповіді.

Ендпойнт

POST /v2/payments/{payment-product}

Створює запит на ініціювання платіжної операції в ASPSP.

Path Parameters

Атрибут	Тип	Опис
`payment-product`	String	Запитуваний платіжний продукт: - `instant-credit-transfers` — миттєвий кредитовий переказ; - `credit-transfers` — кредитовий переказ. Яке значення продукту TPP має передати — визначається згідно параметру, обраного PSU, який вказує це миттєвий кредитовий переказ, чи ні.

Query Parameters

Немає.

Request Header

Атрибут	Тип	Умова	Опис
`Content-Type`	String	Mandatory	`application/json`
`X-Request-ID`	UUID	Mandatory	Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором (TPP).
`Authorization`	String	Conditional	Атрибут заповнюється, якщо обрано OAuth2 як попередній крок для автентифікації PSU.
`PSU-IP-Address`	String	Mandatory	Поле заголовка IP-адреси, що пересилається, складається з відповідного поля IP-адреси запиту HTTP між PSU і TPP. Якщо воно недоступне, TPP повинен використовувати IP-адресу, яку використовує TPP під час подання цього запиту.
`ClientRejectionNoFundsPreferred`	Boolean	Optional	Якщо значення дорівнює `true`, то TPP віддає перевагу відхиленню ASPSP ініційованої платіжної операції в разі, якщо недостатньо коштів на рахунку. Якщо значення дорівнює `false`, то TPP віддає перевагу, щоб ASPSP прийняв до виконання платіжну операцію так само, як у своєму засобі дистанційної комунікації з PSU, можливо, очікуючи певний період часу для надходження коштів для виконання платіжної операції. Цей параметр може бути проігнорований ASPSP.
`PSU-ID`	String	Conditional	Ідентифікатор PSU-фізичної особи в клієнтському інтерфейсі ASPSP. Якщо використовується Decoupled SCA — цей атрибут передається обов’язково.
`PSU-ID-Type`	String	Conditional	Тип `PSU-ID` фізичної особи, можливі значення визначені у розділі 8.2 Протоколу функцій та заходів безпеки.
`PSU-Corporate-ID`	String	Conditional	Ідентифікатор PSU-ФОП в клієнтському інтерфейсі ASPSP. Якщо використовується Decoupled SCA — цей атрибут передається обов’язково.
`PSU-Corporate-ID-Type`	String	Conditional	Тип `PSU-ID` ФОП, можливі значення визначені у розділі 8.2 Протоколу функцій та заходів безпеки.

Request Body

Код параметру		Тип даних	Обов’язковість	Опис
`instructedAmount`	-	-	mandatory	Сума коштів, що підлягає переказу між платником та отримувачем.
`currency`	string (pattern: [A-Z]{3})	mandatory	Код валюти відповідно до Класифікатора іноземних валют НБУ (ISO 4217 Alpha 3 currency code). На момент написання цієї специфікації можливе значення тільки `UAH` (через існуючі обмеження по переказах).
`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). На момент написання цієї специфікації можливе значення тільки `UAH` (через існуючі обмеження по переказах).
`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	Однозначна ідентифікація рахунку платника. Якщо не переданий — то має бути обраний PSU у платіжному застосунку ASPSP.
`iban`	string `UA[0-9]{27,27}`	-	iban
`currency`	string (pattern: [A-Z]{3})	-	Код валюти відповідно до Класифікатора іноземних валют НБУ (ISO 4217 Alpha 3 currency code). На момент написання цієї специфікації можливе значення тільки `UAH` (через існуючі обмеження по переказах).

Response Code

HTTP response code дорівнює 201.

Response Header

Атрибут	Тип	Умова	Опис
`Location`	String	Mandatory	Розташування створеного ресурсу (якщо створено).
`X-Request-ID`	UUID	Mandatory	Ідентифікатор запиту, унікальний для виклику, визначений стороною-ініціатором.

Response Body

Атрибут	Тип	Умова	Опис
`transactionStatus`	Transaction Status	Mandatory	Статус платіжної операції, можливі значення: `RCVD`, `ACTC`, `PDNG`, `ACSC`, `ACCC`, `RJCT`.
`paymentId`	Max70Text	Mandatory	Ідентифікатор ресурсу створеної платіжної операції.
`transactionFee`	Amount	Optional	Може використовуватися ASPSP для передачі загальної комісії по платіжній операції.
`currencyConversion Fee`	Amount	Optional	На даний момент не буде використовуватись в Україні. Може використовуватися ASPSP для передачі конкретних комісій за конвертацію валюти, пов’язаних з ініційованим кредитним переказом.
`estimatedTotal Amount`	Amount	Optional	Сума, яка буде списана з рахунку платника. Примітка: ця сума включає комісії.
`estimated Interbank Settlement Amount`	Amount	Optional	Сума, що буде перерахована отримувачу.
`transactionFeesIndicator`	Boolean	Optional	Якщо дорівнює `true`, операція включатиме комісію ASPSP. Якщо дорівнює `false`, операція не включатиме додаткових комісій для PSU, якщо сума комісії не вказана конкретно в елементах даних `transactionFees` та/або `currencyConversionFee`. Якщо цей елемент даних не використовується, інформація про комісії за операцію відсутня, якщо сума комісії не вказана явно в елементі даних `transactionFees` та/або `currencyConversionFees`.
`_links`	Links	Mandatory	Гіперлінк для початку авторизації ресурсу платіжної операції: - `startAuthorisation` — посилання може бути використане, як перший крок для визначення наступних дій. - `startAuthorisationWithPsuIdentification` — посилання для початку процесу авторизації з `PSU-ID`. Примітка: Усі посилання можуть бути відносними або повними, на розсуд ASPSP.
`psuMessage`	Max500Text	Optional	Текст, який відображатиметься PSU, наприклад, при підході Decoupled SCA. Надсилати для Decoupled SCA обов’язково. За замовчуванням текст повідомлення передається українською мовою.
`apiClientMessages`	Array of Client Message Information	Optional	Повідомлення для API client щодо операційних питань.

Приклади

У вихідному матеріалі приклади наведені у вигляді зображень (скріншотів) для сценаріїв Redirect SCA та Decoupled SCA без текстового JSON-вмісту, тому на цій сторінці приклади у форматі JSON не відтворені.