Загальний протокол прийому платежів
Протокол прийому платежів та обміну даними між клієнтм і банком в режимі on-line. СЕРВЕРНА ЧАСТИНА РЕАЛІЗУЄТЬСЯ НА
СТОРОНІ клієнта.
Історія змін
Терміни та визначення
Транспортна взаємодія
протокол обміну даними
Криптографічні ключі
HTTP заголовки
Підпис повідомлення
Тестування прийому платежів
Статуси операцій
Пошук платника
Підтвердження сплати
Нотифікація - Фінальний статус платежу
Статус операції в ПШ
Звіт по прийнятим платежам
додаток
поля для пошуку платника
додаткові поля
Історія змін
Дата ФІО Опис
27.09.2023 Данилюк Віктор Сергійович Доданий метод Нотифікація - Фінальний статус платежу
31.05.2023 Данилюк Віктор Сергійович Додана структура ReceiverInfo
Терміни та визначення
Платіжна система (ПС)– програмно-апаратный комплекс, що здійснює прийом платежів від платників в банку.
Платіжний шлюз (ПШ) – програмно-апаратный комплекс на стороні клієнта, що надає за запитом платіжної системи інформацію
про платника і служить для запису информації щодо прийнятого платежу Платіжною системою в Білінгову систему клієнта.
Білінгова система - автоматизована система облік наданих услуг, їх тарифікації і виставлення рахунків для сплати.
- набір домовленостей (класів, процедур, функцій, структур або констант), який надається Банком Клієнту таПротокол API
визначає обмін даними між Платіжною системою та Платіжним шлюзом.
Сторнування - спосіб виправлення помилок при прийомі платежів, що полягає в тому, що помилково внесена операція
помічається видаленю і виключається із ітогової суми, що перераховується клієнту.
Щоденний підсумковий реєстр – электронний документ, який містить інформацію про всі Платежі, прийняті Банком від Платників
протягом підсумкового дня.
Підсумковий день – день прийом Банком Платежів від Платників. Підсумковим днем є кожна календарна доба.
Платіж – сума готівкових і безготівкових грошових цінностей у валюті України, яка отримана Банком від Платника з метою
подальшого перерахуванна на рахунок клієнта для поповнення персонального рахунку платника.
– Персональни рахунок платника аналітичний рахунок в білінговій системі клієнта, на якому обліковуються операції, пов'язанні з
наданням послуг платнику.
- HTTP URL для тестування функционалу приему платежів.UAT URL
- HTTP URL для проведения реальних платежівProduction URL
Транспортна взаємодія
Взаимодія ПС та ПШ відбувається по відкритому каналу зв'язку мережі Internet. Для обміну використовується транспортний
протокол , запити виконуються по захищеному информаційному протоколу TCP/IP HTTPS (443-й порт або вказавши в анкеті
.інший порт)
протокол обміну даними
Криптографічні ключі
ПС та ПШ обмінюються публічними ключами.
HTTP заголовки
назва значення обов'язковий опис
content-type application/json Так
x-jws-signature Так підпис повідомлення
згідно вищевказаного
стандарту
Підпис повідомлення
Пари ключів (приватний та публічний) генеруються окремо для ПС та ПШ.
Підпис відбувається за допомогою приватного ключа на стороні відправника (ПС та ПШ). Захист цілісності запитів та
віповідей здійснюється згідно стандарт , а конкретніше у віповідності з до зазначеної специфікації. JWS додатком
Алгоритм підпису вибираєтсья згідно , а конкретніше один із RS або ES:таблиці RS256, RS384, RS512, ES256, ES384,
ES512.
Для роботи згідно вказаного алгоритму можна використовувати бібліотеки для з пітримкою потрібних алгоритмів JWT
підпису, тому що по своїй природі насправді являє собою токен у якого частина є об'єктом (JWS JWT JWS payload JSON
не обмежується лише JSON). З цього моменту і надалі під мається на увазі саме JSON об'єкт. payload
Наведені приклади в цьому документі сформовані за допомогою ключів ПС:
fuib_priv_key.pem fuib_pub_key.pem
та ключів умовного ПШ:
facility_priv_key.pem facility_pub_key.pem
Вищевказані ключі надані лише для прикладу і не повинні викоритовуватись в реальних умовах.
1.
2.
Отримання запиту:
Відновлюється початковий токен із поля та хедераpayload x-jws-signature.
наприклад, маємо тіло запиту
тіло запиту
{
"payload":
"eyJmaWVsZHMiOlt7ImFsaWFzIjoiQ0xJRU5UX0lEIiwidmFsdWUiOiJ0ZXN0In1dLCJpYXQiOjE2MDM3MDI5ODF9"
}
та заголовки:
заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD1iOilA2_ylCgS7SfZ7YBILDjJf-
DGPVhQBN47kjo5aAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPmN7dRbAfuWMSgrLymBfb7dcodJ3WuYgQPMpn
Lrzw89
payload із тіла підставляється в залоговок x-jws-signature між двома крапками і отримується відновлений токен
токен
eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.
eyJmaWVsZHMiOlt7ImFsaWFzIjoiQ0xJRU5UX0lEIiwidmFsdWUiOiJ0ZXN0In1dLCJpYXQiOjE2MDM3MDI5ODF9.
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD1iOilA2_ylCgS7SfZ7YBILDjJf-
DGPVhQBN47kjo5aAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPmN7dRbAfuWMSgrLymBfb7dcodJ3WuYgQPMpn
Lrzw89
Токен перевіряється публічним ключем та обровляється далі у разі успіху, в іншом разі формується відповідь з
помилкою валідації.
:ВІдправка відповіді
1. Сформувати підписаний токен
Наприклад, маємо наступний об'єкт для відповіді:
{
"payer_id": "6c82770d-e20f-456a-9207-18a571ad43ee",
"service_code": "7",
"fields": [
{
"alias": "DEBT",
"value": "234"
},
{
"alias": "REC_AMOUNT",
"value": "300",
"options": {
"amount_restriction": "EQ"
}
}
]
}
У підписаному вигляді (з ключем facility_priv_key.pem) отримуєм:
токен
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJwYXllcl9pZCI6ImQzYTIwMTI0LTcwNWQtNDJlZS1hZDExLWIyNGZjOTc0NGU4OSIsInNlcnZpY2VfY29kZSI6IjciLCJma
WVsZHMiOlt7ImFsaWFzIjoiREVCVCIsInZhbHVlIjoiMjM0In0seyJhbGlhcyI6IlJFQ19BTU9VTlQiLCJ2YWx1ZSI6IjMwMC
IsIm9wdGlvbnMiOnsiYW1vdW50X3Jlc3RyaWN0aW9uIjoiRVEifX1dfQ.d9cRDpyu01f-heD_VFC0ujpDWOBqr2VBFT1t-
F8hEaFYrEsOcvY6iTuGRGUWpYWuqINvLja45KXVN5Rpa7fZJ00QAk2HTrvDVaaXFuUAg6KHLB9Un1C4ze1tUxygnct6ZkokHR
ELMabAMpVYYQWzPERdvzJ82Cwa9LqwEWzqQG85dDCV19dzQfJES7aqCZfvGKYGV9587cLp-xuNaT1Blu_-
EKc_8Q0MvM6QUJcCYO3WjFL66qpjYjjZcZkcuf_fIlGlJhN24e4oxN0JFcakVDvUFAMZq1CHC5NRbdXld5D6_V__v15ytuxWT
Si1TR_QEAdaycqAA2YFogg9km6p9AtN7Q-
d919AXFBaeeEZb14I5oqJlzAw03IObdfqHbja4vFNvFvPw7980YoHLHeMx0C6cbqSg_7ZCgUFwFKmHLzzSP6C39TIs-
8d4nTPoDBVMWs-wb7vZY65jjD9EXJZzih-m4Y8WnEH61O4y5-
GIOB0LXjwnC1WgPXLmD3Qi51JAQRMFO1eL8omLw8yAirmZuuqy-
5suQGEb9RqpXVMCfY_7chNienGnm1ZEmpW9Yhh7CSyc6d35zYGHgv0nL-
9hnEFxK9bAFWLyN15GiKLD4I5Hb0UJvXSbDZ37kjIQf-1MCt3jazvfrUVbI9tVCaxYMoKYyzK_2fZd0XufdDvOlM
УВАГА
Підпис може (і буде) відрізнятись від вищенаданого прикладу. Впевнитись у правильності нового
токену або вищевказаного можна за допомогою публічного ключа . Можна навіть facility_pub_key.pem
онлайн за посиланням: https://jwt.io/
Тестування прийому платежів
Клієнт повинен надати та тестові ідентифікатори користувачів для тестування різнобічних сценаріїв проведенняUAT URL
платежів. Перед початком прийому реальных платежів клієнт має надати ідентифікатор платника, платежі за яким будуть завжди
вважатися несправжніми. Всі інші властивості платника не мають відрізнятись від реального платника.
2.
a.
b.
3.
Відокремити тіло відповіді від підпису
Взяти сформований токен, війняти з нього , додати його в тіло запиту в зашифрованому вігляді.payload
payload
eyJwYXllcl9pZCI6ImQzYTIwMTI0LTcwNWQtNDJlZS1hZDExLWIyNGZjOTc0NGU4OSIsInNlcnZpY2VfY29kZSI6Ijc
iLCJmaWVsZHMiOlt7ImFsaWFzIjoiREVCVCIsInZhbHVlIjoiMjM0In0seyJhbGlhcyI6IlJFQ19BTU9VTlQiLCJ2YW
x1ZSI6IjMwMCIsIm9wdGlvbnMiOnsiYW1vdW50X3Jlc3RyaWN0aW9uIjoiRVEifX1dfQ
Токен з відокремленим має бути передано в HTTP-хедеріpayload x-jws-signature
x-jws-signature
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..d9cRDpyu01f-heD_VFC0ujpDWOBqr2VBFT1t-
F8hEaFYrEsOcvY6iTuGRGUWpYWuqINvLja45KXVN5Rpa7fZJ00QAk2HTrvDVaaXFuUAg6KHLB9Un1C4ze1tUxygnct6
ZkokHRELMabAMpVYYQWzPERdvzJ82Cwa9LqwEWzqQG85dDCV19dzQfJES7aqCZfvGKYGV9587cLp-xuNaT1Blu_-
EKc_8Q0MvM6QUJcCYO3WjFL66qpjYjjZcZkcuf_fIlGlJhN24e4oxN0JFcakVDvUFAMZq1CHC5NRbdXld5D6_V__v15
ytuxWTSi1TR_QEAdaycqAA2YFogg9km6p9AtN7Q-
d919AXFBaeeEZb14I5oqJlzAw03IObdfqHbja4vFNvFvPw7980YoHLHeMx0C6cbqSg_7ZCgUFwFKmHLzzSP6C39TIs-
8d4nTPoDBVMWs-wb7vZY65jjD9EXJZzih-m4Y8WnEH61O4y5-
GIOB0LXjwnC1WgPXLmD3Qi51JAQRMFO1eL8omLw8yAirmZuuqy-
5suQGEb9RqpXVMCfY_7chNienGnm1ZEmpW9Yhh7CSyc6d35zYGHgv0nL-
9hnEFxK9bAFWLyN15GiKLD4I5Hb0UJvXSbDZ37kjIQf-1MCt3jazvfrUVbI9tVCaxYMoKYyzK_2fZd0XufdDvOlM
відправити відповідь
відповідь
//
'x-jws-signature': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..d9cRDpyu01f-heD_VFC0ujpDWOBqr2VBFT1t-
F8hEaFYrEsOcvY6iTuGRGUWpYWuqINvLja45KXVN5Rpa7fZJ00QAk2HTrvDVaaXFuUAg6KHLB9Un1C4ze1tUxygnct6ZkokHR
ELMabAMpVYYQWzPERdvzJ82Cwa9LqwEWzqQG85dDCV19dzQfJES7aqCZfvGKYGV9587cLp-xuNaT1Blu_-
EKc_8Q0MvM6QUJcCYO3WjFL66qpjYjjZcZkcuf_fIlGlJhN24e4oxN0JFcakVDvUFAMZq1CHC5NRbdXld5D6_V__v15ytuxWT
Si1TR_QEAdaycqAA2YFogg9km6p9AtN7Q-
d919AXFBaeeEZb14I5oqJlzAw03IObdfqHbja4vFNvFvPw7980YoHLHeMx0C6cbqSg_7ZCgUFwFKmHLzzSP6C39TIs-
8d4nTPoDBVMWs-wb7vZY65jjD9EXJZzih-m4Y8WnEH61O4y5-
GIOB0LXjwnC1WgPXLmD3Qi51JAQRMFO1eL8omLw8yAirmZuuqy-
5suQGEb9RqpXVMCfY_7chNienGnm1ZEmpW9Yhh7CSyc6d35zYGHgv0nL-
9hnEFxK9bAFWLyN15GiKLD4I5Hb0UJvXSbDZ37kjIQf-1MCt3jazvfrUVbI9tVCaxYMoKYyzK_2fZd0XufdDvOlM'
'content-type': 'application/json; charset=utf-8'
'content-length': '264'
//
{
payload:
'eyJwYXllcl9pZCI6ImQzYTIwMTI0LTcwNWQtNDJlZS1hZDExLWIyNGZjOTc0NGU4OSIsInNlcnZpY2VfY29kZSI6IjciLCJm
aWVsZHMiOlt7ImFsaWFzIjoiREVCVCIsInZhbHVlIjoiMjM0In0seyJhbGlhcyI6IlJFQ19BTU9VTlQiLCJ2YWx1ZSI6IjMwM
CIsIm9wdGlvbnMiOnsiYW1vdW50X3Jlc3RyaWN0aW9uIjoiRVEifX1dfQ'
}
Тест-кейс №1. Коректний
Крок Результат
Створоення платежу з
коректними реквізитам
Платіж успішно створено
Перевірка обов'язкових
полів від партнера(check)
Найменування полів та код відповіді
співпадають з протоколом
Підтвердження платежу Платіж успішно підтверджено
Перевірка обов'язкових
полів від партнера(confirm)
Найменування полів та код відповіді
співпадають з протоколом
Тест-кейс №2. Некоректний(користувач відсутній)
Крок Результат
Створоення платежу з
коректними реквізитам
Платіж не створено
Перевірка обов'язкових
полів від партнера(check)
Найменування полів та код відповіді
співпадають з протоколом.
Отриманий статус платежу - failed
Тест-кейс №3. Некоректний(помилка на фінальному етапі - confirm)
Крок Результат
Створоення платежу з
коректними реквізитам
Платіж успішно створено
Перевірка обов'язкових
полів від партнера(check)
Найменування полів та код відповіді
співпадають з протоколом
Підтвердження платежу Платіж не підтверджено
Перевірка обов'язкових
полів від партнера(confirm)
Найменування полів та код відповіді
співпадають з протоколом.
Отриманий статус платежу - failed
Статуси операцій
- платіж прийнято успішно;SUCCESS
CANCELED - платіж видалено (при сторнуванні);
- платіж відхилено;FAILED
Пошук платника
Перевірка можливості проведення платежу
POST
/check
body
name description type required default
payment_id ідентифікатор платежу payhub string
fields поля для ідентифікації CheckField[]
payload
{
"fields": [
{
"alias": "CLIENT_ID",
"value": "test"
}
]
}
тіло запиту
{
"payload": "eyJmaWVsZHMiOlt7ImFsaWFzIjoiQ0xJRU5UX0lEIiwidmFsdWUiOiJ0ZXN0In1dLCJpYXQiOjE2MDM3MTQ2Mzd9"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABo7iXb1zliErPJveQo9JTiU3UkxZTp2WBopWOjiCGWGAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAJD9v4uX7boL9d2tdX9FOj-9THhPAxXdyt-TrzVyyzya
response
200
name description type required default
service_code код послуги string
payer_id ідентифікатор платника string
payer_info інформація про платника PayerInfo
receiver_info інформація про отримувача ReceiverInfo
fields набір додаткових полів ExtraField[]
operation_id id операції (якщо є на цьому кроці) string
тіло відповіді
{
"payload":
"eyJwYXllcl9pZCI6IjZkY2Q5NjI3LWY1NGItNDFlZC1iOTMyLWFhNWRjYmM0Y2ZlMyIsInNlcnZpY2VfY29kZSI6IjciLCJmaWVsZHMiOlt7ImF
saWFzIjoiREVCVCIsInZhbHVlIjoiMjM0In0seyJhbGlhcyI6IlJFQ19BTU9VTlQiLCJ2YWx1ZSI6IjMwMCIsIm9wdGlvbnMiOnsiYW1vdW50X3J
lc3RyaWN0aW9uIjoiRVEifX1dfQ"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..SXCA565yye4nOU0D-
6IEE0fTNP7tUFah8aS9Oshicf2Hq9iC7kDBQJ3FF769jjV8YuDriE7lCmp-TFL2Yh0oB0eJInjpii_-
mewwoSMHjG_ar7EZGpynKsuMaQRGK9V8tkT1UPjPKQAPTHu0iF2-JUF4V8PhXt8PN0nbzbgZ8KchNLRNaUIky-
7EoCNPItle6OHH5RLdOQJNvlKun_fZqVEdWf5iWbE3zkkN63t1uWCZKI6T4jA_k4tKcXW4AwHfElBXa5kjXYoSyz2h4HzMBFpD2Q2VZMV3TTZz4-
Da-FyCiuz30P-
JaNlsV_p4G097kQGgqXP9TpTrj_F4N8EhZbI3fN1tQ87z20bnVtaVC_aI4vWVXJLpWqJGB1kY5huomWxxADcl3gkRasKScSp9VQz8uNGhgycI98N
haGd6hVjGVJEFRCaTUQG40EVldJaQq3rXRR1CtXVrNW2ObYk75QwXyIIblcuWelLVXKPLeXBCIjBILj9tQOi0azbLLEaMxGJ8_ekZOLsmSSX2KXu
xRnJHxQPlLBYUNy-vbIF8XodSbr7TRKmIcYSb2XZE0hGylwTtnGxuTvGBoXuQcU5AN15Oq_tWYXQ5Kk2admk-
_0wmOimt_MiydGb3PfQSp4RdEs_vgfiVurAcRnOmtGsKUQNJ810w28_fS-ODX-kgZkU
payload (розкодований)
{
"payer_id": "6dcd9627-f54b-41ed-b932-aa5dcbc4cfe3",
"service_code": "7",
"fields": [
{
"alias": "DEBT",
"value": "234"
},
{
"alias": "REC_AMOUNT",
"value": "300",
"options": {
"amount_restriction": "EQ"
}
}
]
}
400
500
ПОМИЛКА СЕРВІСУ
Підтвердження сплати
Передаеться інформація про сплачуну суму і внутрішній ідентифікатор. Після відправки запиту очікується обов'язкова відповідь
про прийом інформациї. Час очікування - 60 секунд. При відсутності відповіді від ПШ з підтвердженням після визначенного часу
очікування запит може бути надіслано повторно. Виходячи з цього
інтерфейс ПШ повинен підтримуваті повторне отримання
інформаціі по одному і тому самому платежу без дублювання в своїй білінговій системі.
POST
/confirm
body
name description type required default
payer_id идентификатор платника string
amount сплачена сума в копійках integer
payment_id ідентифікатор платежу payhub string
service_code ідентифікатор послуги string
fields додаткові поля (із відповіді на check) ExtraField[]
operation_id id операції (із відповіді на check, якщо вона
була передана)
string
payload
{
"payer_id": "78387c71-0a2b-4eac-bbf7-fc5bc4212a4e",
"service_code": "7",
"payment_id": "12345",
"amount": 1317
}
тіло запиту
{
"payload":
"eyJwYXllcl9pZCI6IjM3NTI4Y2FhLWQ3NjItNDI1Ni1iNTVlLWNiNWRlZjYxNDU5NCIsInNlcnZpY2VfY29kZSI6IjciLCJwYXltZW50X2lkIjo
iMTIzNDU2IiwiZmllbGRzIjpbeyJhbGlhcyI6Ik9WRVJQQVlNRU5UIiwidmFsdWUiOiIyMDAwIiwidHlwZSI6IkFNT1VOVCJ9XSwiYW1vdW50Ijo
xMzE3LCJpYXQiOjE2MDM3MjIxODJ9"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPenmnRyXucKQmP0c6MnBbcvSCjrJfqZ41nBY_8W5pBUAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAKF2sU14U1Imvy0juHGCNMZ9Jyu6ayaxTf-jVh6AaJeS
200
name description type required default
service_code ідентификатор послуги string
operation_id ідентифікатор операції в ПШ string
status статус операції ОperationStatus
payload
{
"service_code": "7",
"operation_id": "d6b236a0-f0df-45d0-b436-b8b022ad3150",
"status": "SUCCESS"
}
тіло відповіді
{
"payload":
"eyJzZXJ2aWNlX2NvZGUiOiI3Iiwib3BlcmF0aW9uX2lkIjoiZDZiMjM2YTAtZjBkZi00NWQwLWI0MzYtYjhiMDIyYWQzMTUwIiwic3RhdHVzIjo
iU1VDQ0VTUyJ9"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..W9BQ7CeSH0C0IhXuoEf_bVjYjxWTkz-IDNuj_NPtiCvWjBK4-
2FdqpHBSoCgFoluTZ00rB2RK8HARQwF1rNAqWb4qzQvc471p8WAb55C-ElXkx9G5mmP7Zm6utClLcH4gI_WxamM6QVP-
KpvVRUcwP1CVRUzveahSX8xcTcnSB4JVUpbjS8GjeUaBjsM84Bd7ihSkXn1cmbSdYr1wjQ3kscpb0744331siAewk6yGzzaZtUn_ACYtyeq1RdPN
3u3GND6uzGaJAFOw1mLLV6mXb81RnRstzVcm3qYRhoe3ddV_gfp9JkbRlBt6X4Ng845dwha7i9JTovLkHMxprGrm-
ycmveP9rwnkYIm_h_OjoYOpvGDd8FRwvopPwwPfxcJfuhEBvOFDZIbrFbh_qMw-
PrLjYqEtUL0SOsTzFBsIABAV7YP_KuXJzlJ3SbiCmInN_4mTzbmw2w7Xx-
E4lVZRd0YjbEdnQdWnXyHSvQ6SYMzQ2tgyCrVuyPHoODuRuqRwC6cckJSKwQAF2-
yvFZYkxEZshtdFUFoUAM2TDrytSdknAkxQtXRHTGfw_MKoVSrfp0r9eG9oxSLgcJPBFXj_CYoO1d1f11iFoHd1mgAFwqFcUyjb_V8mDsRnxJ22vb
lQ_scvfL-dX4-uvuH7dslNJhbJlmUQWGo3Uiu5_08CEE
400
500
ПОМИЛКА СЕРВІСУ
Нотифікація - Фінальний статус платежу
Передає інформацію про успішно прийнятий/відхилений банком платіж. Після відправки запиту очікується обов'язкова відповідь
про прийом інформації. Час очікування - 60 секунд. У випадку відсутності/некоректної відповіді, запит може бути надісланий
повторно.
Обов'язково необхідно реалізувати перевірку статусу (status) в інтерфейсі ПШ. У випадку отримання статусу
відмінного від "SUCCESS" платіж вважати неуспішним.
POST
/payment-notification
body
name description type required default
payment_id ідентифікатор платежу payhub string
operation_id id операції (із відповіді на confirm) string
amount сплачена сума в копійках integer
status статус операції ОperationStatus
payload
{
"payment_id": "1695814107709",
"operation_id": "f3b20191-0213-4f24-b806-1ca866dedbe3",
"amount": 201,
"status": "SUCCESS"
}
тіло запиту
{
"payload":
"eyJwYXltZW50X2lkIjoiMTY5NTgxNDEwNzcwOSIsIm9wZXJhdGlvbl9pZCI6ImYzYjIwMTkxLTAyMTMtNGYyNC1iODA2LTFjYTg2NmRlZGJlMyI
sImFtb3VudCI6MjAxLCJzdGF0dXMiOiJTVUNDRVNTIiwiaWF0IjoxNjk1ODE0MTA4fQ"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9..
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOQa68NgygGKmHYqbhMpq5JLFYCQExxKB9VFfhmG6viQAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAOo_-Fng6RWcDGIu4TTf4OCqzIqWgf-ns06L5duTSkG8
200
payload
{}
тіло відповіді
{
"payload": "e30"
}
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..NaqGlPrA2cB467wGY7qP3xp5rkwqtVWstzeC1DKfLNdX9yHRfw-
TQd1SO9dKMb85y9x_drhnfM_Yh9StYgBmZzGg8eS6HSSTmYmZp6-
qJo2KHmfi0vdBNqE3cAK0JQJxEqcKy7XpqrBAZPhLL3NuWRjbPRhXZmD87rrZnLPG2LpgYDiFpbwDt5BzeFC-
2dDmwB4AkpQtelkfyNSWb1VbO5OJ4LZX8FM8H0grI0G64lpg3IUIKan4Tn9KtCZlnYduNU498RkkjFlbjv3mpEiFKN3TJPSkKZ1fnJS27PlhC6MK
u4Z-AvH-dDZdQgEEWt_Td_2RxTlvQ9rNqATDdSDx2FCHdcjf1FvlQidt9Z5VSyQwImCtmvt-NJD0-4QsH-wEXd11qHFBUDGvuzEKqXnt4Twz_Gv-
U6_EhiWTtnoTk7IJ0cO-
tF798ux3AKMQXhMovP2u3vuOdzutCbn_x3DcksMqZ5mz6CwcWwEpHavQdXpmADQ7B2bqQqFZyilPpqrAQNKKsgAbSb4FXrG8lpcjsLLHQxSYRklt
8hX7yndQwZDF-zTrvKj97toP-lDtRRjOPCc7Br3k8M69oM4a8C8a6kOI5R_VGazP-zRuJgZZUVAS-2H_JDcT_-
udt1jQiti5aWOXJphC2qMWD0JyhN7pahYHFJ1u304fhuogiRyIy0E
Статус операції в ПШ
summary: Перевірка статусу операції
Отримання статусу операции в ПШ. Метод має підтримвати запити як по payment_id від банка, так и по operation_id description:
в ПШ.
GET
/status
query
name description type required default
payment_id ідентифікатор платежу payhub string
operation_id ідентифікатор операції в ПШ string
example (payment_id)
https://<url>/status?payment_id=123456
example (opration_id)
https://<url>/status?operation_id=9d712323-c429-4603-b322-d393bef50c29
example (opration_id + payment_id)
https://<url>/status?operation_id=9d712323-c429-4603-b322-d393bef50c29&payment_id=123456
response
200
name description type required default
service_code ідентифікатор послуги string
operation_id ідентифікатор операції в ПШ string
status статус операції ОperationStatus
payment_id ідентифікатор платежу payhub string
HTTP заголовки
content-type: application/json
x-jws-signature: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..FzjDGtmja-yVIXsl3UDCjG4pna2j-
ZzrgqtMhvyY5T5hkvdknHs29YOVIk9ON1LwOrB-VI57rWvyeilfZCUQVO0YbzohIxzI40i0l2NT_nGlvMPBkRcuT8Hah-
5KWNx8aFskxbBDjszay5mu5gHcvc83WO6OIHuZ0SPAU_WP724VzO4GT1UAMyw89UfNblEKIskh1IV8s6L1GYNbyHX1vF_wmfsCuQ9ALsOnW7QVFZ
n_GAneV7Kuae_MzEGrwwfRA_CNVFCU8BnqLirce3nQEpl4jCg1yHYwnwG0G2CWQ1j6DLcNLglAh070wuVoYbYDLHGQDUCYhJ2l9S1Z4szJRJ7WKe
KP4GBCeai9IyST-Npk0NIWnDQs5FxK78kRcTE2A2fVaaO3dAKT4AV-Q_oWh9K7qunNd0H1OWw55MxuCz9N-
xJMCB7o_ARPc8l_tY70EanZPJ4os10ik8yj2bLqUpRAeD6FSOtd1n3_bHDz6stL62FlxU1cD9pUKyvUghWyNJV4nh6_AyPb9lkcr2Xlv9fAXi-
b2oL7yDAULYNcCAexSxnYtAVLipyxSNVgG3qR_afQ-7fXrfl1O-
R44gfrvbUjBEPksCOp3a_6y04mu8rZ_q_PgAwOdhOnSULr4k1hhNNxd77XUjEkbJLsWAgKauYi_vbQI4cCZy5lY0wn5oQ
тіло відповіді
{
"payload":
"eyJzZXJ2aWNlX2NvZGUiOiI3Iiwib3BlcmF0aW9uX2lkIjoiNDY2MDhjOTItYzQyMS00ZGY2LWFkYTQtZGUzODA5ZmQ0NWU5IiwicGF5bWVudF9
pZCI6IjEyMzQ1NiIsInN0YXR1cyI6IlNVQ0NFU1MifQ"
}
payload
{
"service_code": "7",
"operation_id": "46608c92-c421-4df6-ada4-de3809fd45e9",
"payment_id": "123456",
"status": "SUCCESS"
}
400
500
ПОМИЛКА СЕРВІСУ
Звіт по прийнятим платежам
summary: звіт
description: На наступний рабочий день посля прийому платежів банк виконує преказ грошей. Формируется підсумковий реєстр
прийнятых платежів и передається клієнту. Щоденний підсумковий реєстр платежів є остаточним документом, що підтверджує
проведення платежів.
POST
/report
body
name description type required default
id ідентифікатор звіту на стороні банку string
date Дата проведення платежів (YYYY-MM-DD) string
service_code ідентифікатор послуги в ПШ' string
payments список прийнятых платежів ReportEntry[]
response
200
name description type required default
report_id ідентифікатор звіту в системі клієнта string
400
500
ПОМИЛКА СЕРВІСУ
додаток
AmountAlias
type values
string AMOUNT
AmountRestriction
type values description
string NONE немає обмежень
EQ значення не може змінюватись
AmountOptions
name description type required
amount_min Описание структуры полей integer
amount_max Описание структуры полей integer
amount_restriction Описание структуры полей AmountRestr
iction
Amount
name description type required default
alias AmountAlias
value в копійках integer
options настройки суммы оплаты AmountOptions
PayerInfo
name description type required default
name Ф.И.О. string
msisdn номер телефона string
address aдрес проживания string
ReceiverInfo
name description type required default
subdivision_code код підрозділу string
Error
name description type required default
code код помилки
CLIENT_NOT_FOUND - платника не знайдено
SERVICE_TEMPORARILY_UNAVAILABLE - сервіс тимчасово
недоступний
VALIDATION_ERROR - помилка валідації вхідних параметрів
OPERATION_FORBIDDEN - операція заборонена (з різних причин)
ENUM(
'CLIENT_NOT_FOUND',
'SERVICE_TEMPORARILY_UNAVAILABLE
',
'VALIDATION_ERROR',
'OPERATION_FORBIDDEN'
)
message короткий опис string
OperationStatus
type value description
string SUCCESS Платіж прийнято
FAILED Платіж відхилено
CANCELED Платіж видалено
ReportEntry
name description type required default
id ідентифікатор платежу ПУМБ string
operation_id ідентифікатор операції в ПШ string
service_code код послуги string
amount сплачена сума integer
date час сплати (в UTC) string
поля для пошуку платника
CheckField
alias description value type
CLIENT_ID рахунок, номер
договору
string
PERIOD Період сплати string
DATE дата сплати string
FULL_NAME ПІБ string
BILL_ID номер рахунку до сплати string
example
{
"alias": "CLIENT_ID",
"value": "test"
}
додаткові поля
ExtraField
alias description value type
PERIOD Період сплати string
DATE дата сплати
ADDRESS адреса
DEBT заборгованність в коп.
OVERPAYMENT переплата в коп
REC_AMOUNT рекомендована сума до сплати
DOP_INFO додаткова інформація для платника
TARIFF інформація про тариф
COURSE_NAME назва курсу (навчальної програми)
FULL_NAME ПІБ
BILL_ID номер рахунку до сплати
REC_AMOUNT МОЖЕ МАТИ ДОДАТКОВІ в полі ОПЦІЇ options
example
//
{
"alias": "DATE",
"value": "2020-10-13"
}
//
{
"alias": "DEBT",
"value": "100"
}
//
{
"alias": "REC_AMOUNT",
"value": "100",
"options": {
"amount_restriction": "EQ"
}
}
//
{
"alias": "REC_AMOUNT",
"value": "100",
"options": {
"amount_min": 100, //
"amount_max": 500 //
}
}
