¶ Загальна інформація
При роботі з терміналами через 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- повна сума на яку оформлюється договір на оплату частинами або сума на яку здійснюється повернення. Обов'язковий.merch- тільки для терміналів по протоколу BPOS1. Номер мерчанта по якому буде здійснюватись оформлення оплати частинами. Обов'язковий.amountOfParts- кількість частин. Обов'язковий тільки для оформлення оплати частинами.agreementNum- номер договору. Використовується для оформлення повернення (тільки для Приватбанку). Обов'язковий параметр тільки для повернення по оплаті частинами.installment_id- тільки для терміналів по протоколу BPOS1. За чий рахунок відбувається розстрочка. 1 – розстрочка за рахунок клієнта (покупця), 2 – розстрочка за рахунок торговця.
Приклад запиту для оформлення оплати (Приватбанк):
curl --location 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"source": "DM_API",
"device": "Term",
"type": 3,
"pay": {
"task": 15,
"sum": 3000,
"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": 3000,
"agreementNum": "9999999999"
}
}'
Приклад запиту для оформлення оплати частинами (для терміналів на протоколі BPOS1):
curl --location 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"source": "DM_API",
"device": "Term",
"type": 3,
"pay": {
"task": 15,
"merch": 1,
"sum": 1000,
"amountOfParts": 6,
"installment_id": 2
}
}'
Приклад відповіді оформлення оплати частинами (для терміналів на протоколі BPOS1):
{
"transaction_id": "09c79d01-1b0e-43e2-a16b-eca5c87d3e94",
"transaction_search": 0,
"info": {
"dt": "250813100719",
"termid": "20909174",
"bankid": "20905680",
"bankname": "Ощадбанк",
"payid": "867795",
"cancelid": "12",
"refundid": "522577364310",
"cardmask": "5167803206144615",
"paysys": "MasterCard",
"sum": 1000,
"discount": 0,
"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": "",
"hstFld63Sf89": "",
"merch": "20905680",
"submerch": "",
"reference": "",
"purchase_dt": "20250813100719",
"pan": "",
"acquirerid": "",
"agreementNum": "",
"scenario_data": "<Response><ResultCode>0</ResultCode><Result>ОПЕРАЦІЯ УСПІШНА</Result><InstallmentType>UNKNOWN</InstallmentType><part_approve>0</part_approve></Response>",
"transaction_id": "09c79d01-1b0e-43e2-a16b-eca5c87d3e94",
"commission": 13
},
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Term",
"tag": "",
"task_status": 1,
"type": 3,
"task": 15,
"dt": "20250813100727365",
"res": 0,
"res_action": 0,
"errortxt": "",
"aq_errortxt": "",
"warnings": []
}
Для терміналів Приватбанку у відповідь після успішного оформлення заявки в значенні тегу hstFld63Sf89 в об'єкті "info" буде повернуто текст з процесингу Приватбанку в якому буде зазначено номер договору. Цей номер використовується у випадку оформлення повернення як значення тегу agreementNum.
Для терміналів по протоколу BPOS1 номер договору не повертається. Всі дані про операцію будуть практично ідентичні даним що повертаються на звичайну операцію оплати. Додатково в ключі scenario_data буде розміщена повна відповідь терміналу по завершенн офомлення оплати частинами.
Повний опис структури запиту і відповіді знаходиться в описі 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 для роботи з терміналами.
-
Наразі оформлення оплати частинами по терміналам Приватбанку доступно лише покупцям з картками Приватбанку. Детальніше про всі умови можна дізнатись у фахівців Приватбанку.
-
По терміналам що працююсь на протоколі BPOS1 налаштування операції оплати частинами здійснюється банком окремо. Про доступність даної операції можна дізнатись у вашому банку.
-
За замовчуванням у вас можуть бути доступні не всі сервіси на терміналі Приватбанку. Які саме сервіси та під якими кодами мерчанту у вас налаштовані на терміналі можна уточнити у Приватбанку.
-
При роботі по 2 схемі через універсальний сервіс для терміналів Приватбанку, а саме при здійсненні повернення якщо вказати в
"srvNum"значення сервісу "047" - часткове повернення оплати частинами, але при цьому вказувати повну суму транзакції - термінал повертає помилку про "невірну суму", отже перед формуванням запиту, необхідно проводити аналіз сум повернень (чи повертається лише частина суми договору чи весь договір), аби вказати правильний код сервісу.