¶ Загальна інформація
При роботі з терміналами через Device Manager (далі ДМ) можливо проводити операції оплати частинами які працюють на терміналах ingenico по протоколу BPOS1 та на терміналах Приватбанку по JSON протоколу. На терміналах Приватбанку також доступні додаткові сервіси через метод універсального сервісу.
Звертаємо увазу що доступність оплати частинами на терміналах ingenico по протоколу BPOS1 буде залежати від банку. Чи підтримує таку послугу ваш термінал - рекомендовано уточнити у вашого банку.
Процес оплати частинами виглядає наступним чином:
- Відправляється запит оплату частинами на термінал з вказанням обов'язкових даних окрім суми для оформлення списання.
- Покупець прикладає картку до терміналу, після зчитування картки, на стороні банку відбувається оформлення оплати частинами. Це може зайняти до 1-2 хв часу в середньому.
- Якщо по карті покупця можливо оформити оплату частинами, операція завершується успішно - повертаються дані по транзакції та номер договору (номер договору повертає лише Приватбанк), який потрібно зберегти. Також цей номер договору використовується для здійснення повернення по оплаті частинами або при роботі з іншими сервісами на терміналах Приватбанку.
¶ Схема роботи
Для оплати частинами для терміналів на протоколі BPOS1:
- Через використання окремого завдання (
"task":15) оформлення оплати частинами.
Для ініціювання оплати частинами для терміналів Приватбанку використовується один із 2-х способів.
- Через використання окремого завдання (
"task":15) оформлення оплати частинами. Та, в разі потреби оформлення повернення по оплаті частинами ("task":16). - Через використання універсального сервісу ("task": 5).
В чому різниця:
- Перший спосіб підійде лише якщо на терміналі налаштовано один мерчант, та необхідно провести оформлення оплати частинами або повернення по оплаті частинами. Якщо на терміналі більше як один мерчант, або потрібна інша операція, наприклад миттєва розстрочка - даний спосіб не підходить.
- Другий спосіб підходить якщо на терміналі більше як 1 мерчант або якщо потрібно виконати іншу операцію із доступних сервісів, наприклад миттєву розстрочку.
Рекомендовано використовувати 2 спосіб для терміналів Приватбанку, так як він більш універсальний в роботі.
¶ Перший спосіб (через окремі запити на оформлення оплати частинами та повернення)
Перший спосіб проводиться наступним чином:
Якщо потрібно відправити запит на оформлення оплати чаcтинами чи оформити повернення в об'єкт "pay" передаються дані:
"task"- номер завдання, для оформлення оплати частинами 15, для повернення 16. Обов'язковий параметр."sum"- повна сума на яку оформлюється договір на оплату частинами або сума на яку здійснюється повернення. Обов'язковий параметр."amountOfParts"- кількість частин. Обов'язковий параметр тільки для оформлення оплати частинами."agreementNum"- номер договору. Використовується для оформлення повернення. Обов'язковий параметр тільки для повернення по оплаті частинами
Приклад запиту для оформлення оплати:
curl --location 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"source": "DM_API",
"device": "Term",
"type": 3,
"pay": {
"task": 15,
"sum": 1000,
"amountOfParts": 3
}
}'
Приклад запиту для повернення по оплаті частинами:
curl --location 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"source": "DM_API",
"device": "Term",
"type": 3,
"pay": {
"task": 16,
"sum": 1000,
"agreementNum": "9999999999"
}
}'
У відповідь після успішного оформлення заявки в значенні тегу hstFld63Sf89 в об'єкті "info" буде повернуто текст з процесингу Приватбанку в якому буде зазначено номер договору. Цей номер використовується у випадку оформлення повернення як значення тегу agreementNum.
Повний опис структури запиту і відповіді знаходиться в описі API.
¶ Другий спосіб (через універсальний сервіс)
Другий спосіб проводиться наступним чином. В об'єкт "pay" передаються дані:
"task" - номер завдання, для універсального сервісу завджи 5. Обов'язковий параметр.
"sum" - сума на яку оформлюється договір на оплату частинами чи іншого сервісу або сума на яку здійснюється повернення. Обов'язковий параметр.
"param" - для оплати частинами, або миттєвої розстрочки - кількість платежів. Обов'язковий параметр.
"merch" - номер мерчанта по якому необхідно провести операцію. Обов'язковий параметр.
"srvNum" - номер сервісу. Потрібно передавати в srvNum значення в полі Service ID з таблиці. Обов'язковий параметр.
Таблиця номерів сервісів згідно документації Приватбанку:
Приклад запиту оплати частинами:
curl --location 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"source": "DM_API",
"device": "Term",
"type": 3,
"pay": {
"task": 5,
"sum": 302,
"param": 2,
"merch": 61,
"srvNum": "046"
}
}'
Відповідь після оформлення оплати частинами майже не буде відрізнятись від першого способу.
Приклад успішного оформлення (деякі дані у відповіді були замінені для збереження конфіденційності):
{
"transaction_id": "eb7ef9a6-21b7-4cda-9404-dcccbdbf2fc9",
"transaction_search": 0,
"info": {
"dt": "03.04.2025 16:38:36",
"termid": "1111111",
"bankid": "X11111",
"bankname": "ПриватБанк",
"payid": "406024",
"cancelid": "924401615",
"refundid": "095688143680",
"cardmask": "5209********4096",
"paysys": "MASTERCARD",
"sum": 302,
"sumcash": 0,
"curr": "ГРН",
"restxt": "",
"sliptxt": "",
"isprint": 1,
"devinfo": "",
"deb_amount": 0,
"deb_num": 0,
"cred_amount": 0,
"cred_num": 0,
"canc_amount": 0,
"canc_num": 0,
"tx_num": 0,
"receipt": "<div class=\"receipt\"><div class=\"font-xl\">ПРИВАТБАНК</div><div class=\"font-xs\" id=\"receipt_header\"> ТЕСТ<br/> вул......,буд.....<br/> м.Київ<br/> ОЧ ФОП 11111 Л.Г.<br/> ЄДРПОУ: 2222222222<br/> </div><div class=\"oper\" id=\"oper\">ОПЛАТА ЧАСТИНАМИ</div><div class=\"block font-l mt20\" id=\"report_info\"><div class=\"block align-left\"><div class=\"block\">Договір: 16040338479405 від 03.04.2025</div><div class=\"block\">Регулярний платіж з картки: 5457********8853</div><div class=\"block\">Розмір кредиту: 302,00 грн.</div><div class=\"block\">Кiлькiсть платежiв: 2</div><div class=\"block\">Графік погашення:<br/>Оплата - щомісяця (до 3 числа) у розмірі 151,03 грн. ,у т. ч. відсоток 0.01% - 0,03 грн.</div><div class=\"block\">Перший платiж: 03.04.2025</div><div class=\"block\">Останнiй платiж: 03.05.2025</div><div class=\"block\">Детальна виписка — у Вашому Приват24 «Мої кредити»</div></div><div class=\"block\">*** ЗБЕРЕЖІТЬ ЧЕК ***</div></div><div class=\"block5\">Підпис власника картки не потрібен</div><div class=\"block5 align-right\"> </div><div class=\"block\" id=\"masked_pan\"> MASTERCARD 545708********53</div><div class=\"block mt-10\" id=\"aid\"> AID: A0000000041010 </div><div class=\"block mb0 font-s\"><div class=\"block5\"><div class=\"pull-left\" id=\"datetime\"> 03.04.2025 16:38:46</div><div class=\"pull-right\" id=\"receipt_id\"> Чек № 924401615 (Пакет: 0) </div></div><div class=\"block5\"><div class=\"pull-left\" id=\"merchant\"> Мерчант: 111111</div><div class=\"pull-right\" id=\"terminal_name\"> Термінал № 111111</div></div><div class=\"block5\"><div class=\"pull-left\" id=\"approval_code\"> Код авторизації: 406024 </div><div class=\"pull-right\" id=\"rrn\"> RRN: 095688143680 </div></div></div></div>",
"hstFld63Sf89": "ДОГОВІР 16040338479405 ВІД 03.04.2025 РЕГУЛЯРНИЙ ПЛАТІЖ З КАРТКИ 111111******8853 РОЗМІР КРЕДИТУ 302.00 грн. ПОГАШЕННЯ-ЩОМІСЯЦЯ ДО 3 ЧИСЛА У РОЗМІРІ 151.00 грн. У Т.Ч. ВІДСОТОК 0.01%-(0.03)ГРН ПЕРШИЙ ПЛАТIЖ 03.04.2025 ОСТАННIЙ ПЛАТIЖ 03.05.2025 ДЕТАЛЬНА ВИПИСКА У ПРИВАТ24 \"МОЇ КРЕДИТИ\" ",
"merch": "1221212",
"submerch": "",
"reference": "",
"purchase_dt": "20250403163836",
"pan": "",
"acquirerid": "",
"agreementNum": "16040338479405",
"scenario_data": ""
},
"resp_ver": 4,
"source": "",
"device": "1171045553",
"tag": "",
"task_status": 1,
"type": 3,
"task": 5,
"dt": "20250403163852599",
"res": 0,
"res_action": 0,
"errortxt": "",
"aq_errortxt": "",
"warnings": []
}
Після успішного оформлення заявки в значенні тегу agreementNum в об'єкті "info" буде повернуто номер договору.
Додаткова інформація з процесингу Приватбанку в значенні hstFld63Sf89 в об'єкті "info" при цьому також буде повертатись.
¶ Важливі деталі при роботі з додатковими сервісами.
-
Жоден із зазначених вище способів не підтримується при роботі з ПРРО в пакетному режимі. Вони доступні лише через окреме API для роботи з терміналами.
-
Наразі оформлення оплати частинами доступно лише покупцям з картками Приватбанку. Детальніше про всі умови можна дізнатись у фахівців Приватбанку.
-
За замовчуванням у вас можуть бути доступні не всі сервіси. Які саме сервіси та під якими кодами мерчанту у вас налаштовані на терміналі можна уточнити у Приватбанку.
-
При роботі по 2 схемі через універсальний сервіс, а саме при здійсненні повернення якщо вказати в
"srvNum"значення сервісу "047" - часткове повернення оплати частинами, але при цьому вказувати повну суму транзакції - термінал повертає помилку про "невірну суму", отже перед формуванням запиту, необхідно проводити аналіз сум повернень (чи повертається лише частина суми договору чи весь договір), аби вказати правильний код сервісу.