Інтеграція сервісу оплати рахунків PortmoneDirect до банківських систем обслуговування клієнтів. Технічний опис
searchQuery
Терміни та визначення
Термін | Визначення |
---|---|
Мерчант, Партнер | Організація, що уклала договір з Portmone.com про надання послуг з приймання платежів |
Покупець, Клієнт | Відвідувач Інтернет-магазину Мерчанта з метою ознайомлення з асортиментом товарів (послуг) та здійснення покупки |
Картка, Платіжна картка | Платіжні картки міжнародних платіжних систем Visa, Mastercard та Національної платіжної системи ПРОСТІР |
Авторизація | Процес надання прав доступу або інших повноважень Покупцеві, програмі або процесу |
CVV2/CVC2 | CVV2 (Card Verification Value 2) – тризначний код перевірки дійсності картки платіжної системи Visa. Платіжна система Mastercard має аналогічний код перевірки дійсності – CVC2 (Card Validation Code 2) |
Банк-еквайр | Банк, що організовує точки приймання банківських карток (термінали, банкомати) та здійснює весь комплекс фінансових операцій, пов'язаних з виконанням розрахунків і платежів за банківськими картками в цих точках |
Бан к-емітент банківських карток | Банк, що є учасником платіжної системи та здійснює випуск (емісію) та обслуговування банківських карток |
IBAN | Міжнародний номер банківського рахунку (англ. International Bank Account Number) |
1. Загальна інформація
Використовується технологія REST. Запити та відповіді передаються HTTPS-каналом (зверніть увагу – на даний момент сервером підтримується тільки протокол TLS 1.2).
Запити від хоста агента на сервер Portmone.com передаються у вигляді повідомлень типу POST.
Звернiть увагу, що всi параметри передаються в тiлi POST запиту, нi в якому разi не в тiлi URL. У прикладах запитів на початку рядка вказано знак
?
- це не є вказівкою до використання повідомлень типу GET.
URL для виклику методів: https://direct.portmone.com.ua/api/directcash/.
З кожним запитом передаються два обов’язкових параметри – login
та password
(логін та пароль компанії-реселера). Логін, пароль та HTTPS-сертифікат мають бути надані менеджером Portmone.
Формат відповідей - XML. Для передачі даних використовується кодування UTF-8.
Формат дати - DD.MM.YYYY.
Приклад рядка запиту на доставку рахунку:
method=bills.create&login=логін&password=пароль&version=2&payeeId=значення&contractNumber=значення
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
[тут xml-дані]
</rsp>
Приклад відповіді, якщо сталася помилка:
Для версії 1:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
Для версії 2 і більше:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
<error_description>Докладний опис помилки (версія протоколу – 2) </error_description>
</rsp>
Протокол
Без задання, версія протоколу дорівнює «1».
Якщо у запиті переданий параметр version=2
, стають доступними зміни, введені для версії протоколу «2».
Локалізація
У версії протоколу «2» доданий необов’язковий параметр lang
(можливі значення: ru – російська мова, uk – українська мова, en – англійська мова). Параметр локалізує атрибутивні значення та назви послуг у відповіді (але не назву компанії). Якщо параметр не переданий, результат повертається українською мовою.
У разі використання у запиті версії протоколу «2» (version=2
) та значень параметру lang
, у відповіді в блоці <tariff_items>
будуть передані значення тегів <name/>
та <*_name/>
, локалізовані потрібною мовою.
Для версії протоколу «2» у відповіді в блоці <tariff_items>
відсутні теги <name_ua/>
та <name_en/>
(у зв’язку з введенням параметру lang
).
Приклад використання параметру lang
.
Запит:
method=bills.create&payeeId=1755&login=PortmoneDirectTest&password=**************
&version=2&contractNumber=639512625&lang=uk
Відповідь:
<rsp status="ok">
<bill id="598984149">
<payee id="1755">lifecell</payee>
<contractNumber title="Номер телефона (без +380)">639512625</contractNumber>
<attribute1/>
<attribute2/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>21.01.2020</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>0.00</amount>
<debt>0.00</debt>
<sum>0.00</sum>
<status>created</status>
<paidAmount/>
<payDate/>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point/>
</bill>
</rsp>
У відповіді параметр <contractNumber title>
локалізований російською мовою.
Опис структури XML
Опис структури відповіді у XML-форматі наведений у Додатку 1.
2. Методи
Назва методу | Опис |
---|---|
2.1. bills.create | результатом виклику методу bills.create є створення на боці Portmone.com підписки на отримання рахунків для необхідної компанії та повернення ID рахунку (billId ) |
2.2. bills.createByPhone | резул ьтатом виклику цього методу є створення на боці Portmone.com рахунку на поповнення мобільного телефону та повернення ID компанії-одержувача платежу (payeeId ) і ID рахунку (billId ) |
2.3. bills.createAll | цей метод використовується для отримання рахунків компаній, що виставляють кілька рахунків за поточний місяць |
2.4. bills.pay | за допомогою цього методу виконується оплата рахунку |
2.5. bills.get | метод використовується, якщо необхідно отримати інформацію про рахунок (дізнатися статус рахунку). Потрібно викликати, якщо на метод оплати bills.pay отримана помилка зєднання, отримана відповідь не очікуваного формату, який не відповідає протоколу. А також якщо отримані помилки p009, p017, p100. |
2.6. bills.paymentOrder | реєстр передається банком до Portmone.com для контролю платежів, що надсилаються, та формування необхідних контрольних реєстрів до кожної організації за необхідним протоколом. Містить список виконаних транзакцій та реквізити платежу покриття. |
2.7. bills.date | метод використовується для отримання контрольного списку транзакцій за період (день). Необхідний для контролю транзакцій, що відбулись/ не відбулись |
2.8. bills.exported | метод використовується для отримання контрольного списку транзакцій за період (день), кошти за яким були надіслані постачальнику послуги (біллеру) |
2.9. bills.balance | метод використовується для перегляду балансу по компанії-біллеру (PAYEE ) на поточний момент |
2.10. bills.payees | метод використовуєьтся для отримання параметрів біллерів (PAYEE ) |
2.11. bills.regions | метод використовується для отримання списку доступних регіонів та списку біллерів (PAYEE ) для кожного регіону |
2.12. bills.additionalPayees | метод використовується для отримання списку компаній, рахунки яких може сплачувати клієнт |
2.13. search.regions | метод використовується для отримання повного списку регіонів України |
2.14. search.regionsExtended | метод використовується для отримання списку регіонів України з пошуком за назвою регіону |
2.15. search.citiesByRegion | метод використовується для отримання списку населених пунктів для вказаного регіону |
2.16. search.citiesByRegionExtended | метод використовується для отримання списку населених пунктів вказаного регіону за назвою населеного пункту |
2.17. search.streetsByCity | метод використовується для отримання списку вулиць вказаного населеного пункту |
2.18. search.streetsByCityExtended | метод використовується для отримання списку вулиць вказаного населеного пункту з пошуком за назвою вулиці |
2.19. search.housesByStreet | метод використовується для отримання списку будинків для вказаної вулиці |
2.20. search.housesByStreetExtended | метод використовується для отримання списку будинків для вказаної вулиці з пошуком за номером будинку |
2.21. search.apartmentsByHouse | метод використовується для отримання списку квартир за відомим ідентифікатором будинку (тільки для багатоквартирних будинків) |
2.22. search.apartmentsByHouseExtended | метод використовується для отримання списку квартир за відомим ідентифікатором будинку (тільки для багатоквартирних будинків) з пошуком за номером квартири |
2.23. search.userDocsByAddress* | метод використовується для отримання списку рахунків за знайденим ідентифікатором будинку (для приватних будинків) або квартири (для багатоквартирних будинків). Повертає рахунки з повною відповідністю за адресою |
2.24. companies.top10ByRegion* | метод використовується для отримання списку ТОП 10 компаній за ідентификатором регіону (часткова відповідність) |
2.25. companies.top10ByCity* | метод використовується для отримання списку ТОП 10 компаній за ідентифікатором міста (часткова відповідність) |
2.26. companies.top10ByStreet* | метод використовується для отримання списку ТОП 10 компаній за ідентификатором вулиці (часткова відповідність) |
2.27. companies.top10ByHouse* | метод використовується для отримання списку ТОП 10 компаній за відомим ідентифікатором будинку (повна відповідність для будинку або часткова для квартири) |
2.28. companies.top10ByAddress* | метод використовується для отримання списку компаній за відомим ідентифікатором будинку (для приватних будинків) або квартири (для багатоквартирних будинків). Повертає рахунки з повною та частковою відповідністю за адресою |
2.29. bills.getreference | метод використовується для отримання списку значень вказаного довідника з використанням пов'язаного значення з довідника верхнього рівня |
2.30. bills.update | є частиною методу 2.4. bills.pay, використовується для он овлення рахунку без зміни його статусу |
2.31. bank.params.guaranteeAmount | метод перевірки суми гарантійного платежу по партнеру згідно індивідуального логіну |
2.32. bills.recreate | метод для створення копії сплаченого рахунку |
2.33. bills.cancel | метод для відміни оплат, які знаходяться в статусі PAYED (всі версії протоколу) |
* Як використовувати методи пошуку компаній
- Якщо відомий тільки ідентифікатор регіону (
regionId
), шукаємо рахунки за регіоном (використовуючи метод companies.top10ByRegion)- Якщо відомий ідентифікатор міста (
cityId
), шукаємо рахунки для зазначеного міста (використовуючи метод companies.top10ByCity)- Якщо відомий ідентифікатор вулиці (
streetId
), шукаємо за вулицею (використовуючи метод companies.top10ByStreet)- Якщо відомий ідентифікатор будинку (
houseId
), шукаємо за будинком (використовуючи метод companies.top10ByHouse)- Якщо будинок багатоквартирний (
hasApartments=Y
), є ідентифікатор квартири (apartment id
), використовуємо метод companies.top10ByAddress (якщо немає повної відповідності за ад ресою, метод шукає рахунки по вищих пунктах (за будинком, вулицею, містом тощо)) або метод search.userDocsByAddress (повертає рахунки тільки з повною відповідністю параметру пошуку).
2.1. Запит на доставку рахунку
Метод: bills.create
Опис: результатом виклику метода bills.create є створення на боці Portmone.com підписки на отримання рахунків для необхідної компанії та повернення ID рахунку (billId
). Відповідь містить дані про останній виставлений і не оплачений рахунок за попередній період. Якщо організація не виставляє рахунки (наприклад, мобільні оператори), то метод bills.create забезпечує перевірку наявності цього телефону в БД мобільного оператора.
Перед викликом методу bills.create необхідно звертати увагу на значення тегу <balance_source>
, що отримане при виконанні методу bills.payees. Якщо <balance_source>Y</balance_source>
для компанії, то здійснюється виклик методу bills.create. У інших випадках здійснюється виклик методу bills.createAll.
Параметри:
Параметр | Опис | Обов’язковий |
---|---|---|
login | Логін компанії-реселера в системі Portmone.com | Так |
password | Пароль компанії-реселера в системі Portmone.com | Так |
method | Назва методу | Так |
payeeId | ID компанії-одержувача платежу | Так |
contractNumber | Основний реквізит (ідентифікатор) клієнта в цій компанії | Так |
billNumber | Номер замовлення | Ні |
attribute1-4 | Додаткові реквізити | Ні |
Приклад запиту:
method=bills.create&login=логін&password=пароль&version=2&payeeId=значення&contractNumber=значення
Приклад успішної відповіді: див. Додаток 1.
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.2. Запит на доставку рахунку за номером телефону
Метод: bills.createByPhone
Опис: результатом виклику цього методу є створення на боці Portmone.com рахунку на поповнення мобільного телефону та повернення ID компанії-одержувача платежу (payeeId
) і ID рахунку (billId
).
Для оплати рахунку необхідно викликати метод bills.pay.
Схема взаємодії:
- Клієнт на сайті Партнера (компанії-реселера) вказує номер мобільного телефону для поповнення.
- Партнер передає ці дані до Portmone.com за допомогою методу bills.createByPhone.
- Portmone.com за кодом оператора зв’язку визначає ID компанії, до якої належить телефон клієнта, та надсилає Партнерові XML-повідомлення з ID компанії-одержувача платежу (
payeeId
) та ID рахунку (billId
). - Партнер виконунує запит оплати рахунку методом bills.pay.
- Portmone.com здійснює переказ коштів постачальнику послуги.
Параметри:
Параметр | Опис | Обов’язковий |
---|---|---|
login | Логін компанії-реселера в системі Portmone.com | Так |
password | Пароль компанії-реселера в системі Portmone.com | Так |
method | Назва методу | Так |
contractNumber | Номер телефону, на який здійснюється поповнення. Формат номеру: 9 цифр, без "+380" (наприклад, 673334411) | Так |
billAmount | Сума платежу (дорівнюватиме 0, якщо інше не було задане) | Ні |
billNumber | Номер замовлення (рахунку) у системі компанії-реселера | Ні |
attribute1-4 | Додаткові реквізити | Ні |
Приклад запиту:
method=bills.createByPhone&login=логін&password=пароль&version=2&contractNumber=значення
&billAmount=значення
Приклад успішної відповіді:
<rsp status="ok">
<bill id="508828105">
<payee id="2065">Київстар</payee>
<contractNumber title="Номер телефону (без +380)">973452341</contractNumber>
<attribute1/>
<attribute2 title="Номер квитанції Київстар"/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>12.06.2019</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>0.00</amount>
<debt>0.00</debt>
<sum>0.00</sum>
<status>created</status>
<paidAmount/>
<payDate/>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point/>
</bill>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>