Інтеграція сервісу оплати рахунків PortmoneDirect до банківських систем обслуговування клієнтів. Технічний опис
Терміни та визначення
| Термін | Визначення |
|---|---|
| Мерчант, Партнер | Організація, що уклала договір з 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 (всі версії протоколу) |
| 2.34. counters.get | метод для передачі показів лічильника без оплати (для вхідних компаній) - створення запиту |
| 2.35. counters.set | метод для передачі показів лічильника без оплати (передача даних в компанію, показники, які вніс клієнт) |
* Як використовувати методи пошуку компаній
- Якщо відомий тільки ідентифікатор регіону (
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 - унікального ідентифікатору платежу). Відповідь містить дані про останній доступний не оплачений рахунок. Якщо компанія не надає рахунки, система портмоне створює рахунок на 0 суму і повертає його партнеру для оплати.
Перед викликом методу 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>
2.3. Запит на доставку всіх рахунків, виставлених за поточний місяць
Метод: bills.createAll
Опис: цей метод використовується для отримання рахунків компаній, що виставляють кілька рахунків за поточний місяць. За набором параметрів цей метод повністю ідентичний методу bills.create.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| payeeId | ID компанії-одержувача платежу | Так |
| contractNumber | Основний реквізит (ідентифікатор) клієнта в цій компанії | Так |
| billNumber | Номер замовлення | Ні |
| attribute1-4 | Додаткові реквізи ти | Ні |
Приклад запиту:
method=bills.createAll&login=логін&password=пароль&version=2&payeeId=значення&contractNumber=значення
Приклад успішної відповіді: у разі успіху повертається секція bills, що містить для кожного з рахунків XML, описаний у Додатку 1.
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<bills>
<bill id="id">
…
</bill>
<bill id="id">
…
</bill>
<bill id="id">
…
</bill>
</bills>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
Основна компанія та компанії-одержувачі:
Платіжна система Portmone.com надає можливість розщеплення платежу, тобто зарахув ання суми платежу, що отриманий від клієнта, на декількох одержувачів (постачальників товару або послуги).
Основна компанія – це компанія, яку ви відображаєте клієнтові при сплаті за послугу/товар та вказуєте у запитах на отримання рахунків. Такі компанії створюються, наприклад, з метою групування послуг, що надаються (приклад: ГІОЦ (payeeId = 8004), ГЕРЦ (payeeId = 4568)).
Компанія-одержувач – це активна компанія, що надає послугу або товар, але клієнтові вона не відображається.
При запиті на payeeId основної компанії метод bills.createAll у відповідь поверне Вам рахунки з payeeId компаній-одержувачів, по яким і буде проходити оплата.
2.4. Оплата рахунку
Метод: bills.pay
Опис: за допомогою цього методу виконується оплата рахунку.
У випадку якщо по послузі debt_state <> 'E' то відповідний debt не повинен враховуватися в загальну суму оплати по рахунку
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону) | Так |
| amount | Сума, що сплачується (вона може відрізнятись від запропонованої у рахунку) | Так |
| auth_code | Код авторизації | Ні |
| transaction_id | ID транзакції | Ні |
| payment_point | Унікальний опис торгової точки партнера | Так |
| payer_iban або payer_card_number або payer_phone_number | iban відправника, хто ініціює переказ, приймає значення 29 символів ------------------------------------------------------------------------------ Карти, відправника, хто ініціює переказ, приймає значення 16 цифр ------------------------------------------------------------------------------ Номер телефону платника в форматі +38ХХХХХХХХХХ | Так |
Приклад запиту:
method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&payer_iban=значення
або
method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&payer_card_number=значення
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<bill id="1046347926">
<payee id="6968">Воля ТБ та/або Інтернет</payee>
<contractNumber title="Номер договору">901386637</contractNumber>
<attribute1 title="Адреса">Київ, Архипенка Олександра, б.4А, кв.185</attribute1>
<attribute2 />
<attribute3 />
<attribute4 />
<bill_attribute1 />
<bill_attribute2 />
<bill_attribute3 />
<bill_attribute4 />
<date>11.01.2022</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>0.00</amount>
<debt>0.00</debt>
<sum>0.00</sum>
<status>paid</status>
<paidAmount>31000.00</paidAmount>
<payDate>12.01.2022 08:49:29</payDate>
<payee_export_flag>N</payee_export_flag>
<auth_code />
<transaction_id />
<payment_point>PORTMONEDIRECTTEST</payment_point>
<bill_attribute10>UA77*********************6900</bill_attribute10>
</bill>
</rsp>
У випадку і відсутнього payer_iban і payer_card_number система повертатиме помилку
Приклад відповіді, якщо сталася помилка:
<rsp status="fail">
<error code="р013">Неправильні параметри ідентифікації клієнта.</error>
<error_description>Неправильні параметри ідентифікації клієнта.</error_description>
</rsp>
Параметри для платежів більше 30000 грн:
Опис: за законодавством України: для оплати понад 30000 грн (крім категорій комунальних послуг та податків) - необхідно передавати та зберігати ПІБ клієнта та ІПН з прив'язкою до транзакції (або ПІБ та дату народження, якщо ІПН у клієнта відсутня за релігійними переконаннями).
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону) | Так |
| amount | Сума, що сплачується (вона може відрізнятись від запропонованої у рахунку) | Так |
| first_name | Ім'я клієнта | Так |
| last_name | Прізвище клієнта | Так |
| middle_name | По батькові клієнта | Так |
| taxId | ІПН клієнта | Так |
| birth_date | Дата народження клієнта | Так, якщо ІПН у клієнта відсутня за релігійними переконаннями |
Приклад запиту для платежів більше 30000 грн:
curl --location --request POST 'http://127.0.0.1/api/directcash' \
--form 'version="2"' \
--form 'lang="uk"' \
--form 'login="PortmoneDirectTest"' \
--form 'password="PortmoneDirect"' \
--form 'method="bills.pay"' \
--form 'billId="1046347926"' \
--form 'amount="31000"' \
--form 'first_name="Антон"' \
--form 'last_name="Волоха"' \
--form 'middle_name="Олександрович"' \
--form 'taxId="9999"' \
--form 'birth_date="03.08.1998"'
--form 'payer_iban="UA773510050000026003590876900"'
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<bill id="1078035627">
<payee id="6968">Воля ТБ та/або Інтернет</payee>
<contractNumber title="Номер договору">901386637</contractNumber>
<attribute1 title="Адреса">Київ, Архипенка Олександра, б.4А, кв.185</attribute1>
<attribute2 />
<attribute3 />
<attribute4 />
<bill_attribute1 />
<bill_attribute2 />
<bill_attribute3 />
<bill_attribute4 />
<date>11.01.2022</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>0.00</amount>
<debt>0.00</debt>
<sum>0.00</sum>
<status>paid</status>
<paidAmount>31000.00</paidAmount>
<payDate>12.01.2022 08:49:29</payDate>
<payee_export_flag>N</payee_export_flag>
<auth_code />
<transaction_id />
<payment_point>PORTMONEDIRECTTEST</payment_point>
<bill_attribute10>UA77*********************6900</bill_attribute10>
</bill>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="o003">
<![CDATA[Ошибка при оплате счета.]]>
</error>
<error_description>
<![CDATA[bills.pay 02 - Счета нет или счет уже оплачен.]]>
</error_description>
</rsp>
Параметри для «універсальних» айтемів (передаються у масиві tariff_items):
| Параметр | Опис | Обов’язковий |
|---|---|---|
| id | ID лічильника | Так |
| amount | Розрахована сума за лічильником | Так |
| prev_counter | Попереднє значення лічильника | Ні |
| counter | Поточне значення лічильника | Ні |
| tariff | Тариф | Ні |
| subsidy | Субсидія | Ні |
| debt | Сплачений борг | Ні |
| attribute1 | Атрибут 1 (версія протоколу – 2) | Ні |
| attribute2 | Атрибут 2 (версія протоколу – 2) | Ні |
| attribute3 | Атрибут 3 (версія протоколу – 2) | Ні |
Параметри prev_counter, counter, tariff, subsidy, debt, attribute1, attribute2, attribute3 передаються, якщо в отриманому рахунку відповідні теги не порожні.
Якщо параметр переданий, він обов’язково повинен мати значення («порожні» параметри не допускаються).
Сума, що сплачується цілком за рахунком, повинна дорівнювати сумі переданих значень amount та debt за всіма айтемами.
Приклад рядка запиту для компаній без айтемів:
method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення
Той же запит з даними по айтемах:
method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&
tariff_items[111111][id]=значення&tariff_items[111111][counter]=значення&
tariff_items[111111][prev_counter]=значення&tariff_items[111111][tariff]=значення&
tariff_items[111111][subsidy]=значення&tariff_items[111111][debt]=значення
де tariff_items — назва масиву з даними по айтемах; 111111 — ID айтему; counter, prev_counter, tariff, subsidy, debt та amount — дані по айтему.
Приклад успішної відповіді: див. Додаток 1.
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.5. Інформація про рахунок
Метод: bills.get
Опис: метод використовується, якщо необхідно отримати інформацію про рахунок (дізнатися статус рахунку). Потрібно викликати, якщо на метод оплати bills.pay отримана помилка зєднання, отримана відповідь не очікуваного формату, який не відповідає протоколу. А також якщо отримані помилки p009, p017, p100. Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID рахунку (його повертає метод bills.create) | Так |
Приклад запиту:
method=bills.get&login=логін&password=пароль&version=2&billId=значення
Приклад успішної відповіді: див. Додаток 1.
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.6. Реєстр надісланих платежів
Метод: bills.paymentOrder
Опис: реєстр передається банком до Portmone.com для контролю платежів, що надсилаються, та формування необхідних контрольних реєстрів до ко жної організації за необхідним протоколом. Містить список виконаних транзакцій та реквізити платежу покриття.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| xml | Реєстр у XML-форматі | Так |
Приклад реєстру у XML-форматі:
<?xml version="1.0" encoding="utf-8"?>
<payment_order order_date="DD.MM.YYYY" order_number="Номер платіжного доручення"
payee_id="ID компанії-отримувача" total_amount="Сума отриманих платежів"
total_compensation="Сума компенсацій платіжного доручення"
total_commission="Сума комісій платіжного доручення" trx_count="2">
<transactions>
<trx>
<bill_id>ID рахунку</bill_id>
<trx_amount>Сума транзакції</trx_amount>
<compensation>Сума,що перерахована біллеру</compensation>
</trx>
<trx>
<bill_id>ID рахунку</bill_id>
<trx_amount>Сума транзакції</trx_amount>
<compensation>Сума,що перерахована біллеру</compensation>
</trx>
</transactions>
</payment_order>
Де total_commission – сума комісій за всіма транзакціями цього платіжного доручення, total_compensation – сума компенсацій за всіма транзакціями цього платіжного доручення. Для кожної транзакції (<trx>) commission = trx_amount - compensation.
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<paymentOrder>
<record id="значення"/>
</paymentOrder>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| record id | ID платежу в Portmone.com, яким зафіксоване це повідомлення |
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
Зверніть увагу – якщо реєстр за дату з будь-якої причини не був переданий (розрив зв'язку через таймаут, повідомлення про помилку, отримане від системи PortmoneDirect і т. д.), цей реєстр має бути переданий у наступний сеанс зв'язку разом з реєстром за поточну дату.
2.7. Контрольний реєстр транзакцій
Метод: bills.date
Опис: метод використовуєт ься для отримання контрольного списку транзакцій за період (день). Необхідний для контролю транзакцій, що відбулись/ не відбулись.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| date | Дата, для якої виводиться реєстр. Формат: DD.MM.YYYY | Так |
Приклад запиту:
method=bills.date&login=логін&password=пароль&date=DD.MM.YYYY
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<bills>
<bill id="значення">
<name>Коротка назва компанії-отримувача</name>
<contractNumber title="значення">значення</contractNumber>
<attribute1 title="значення">значення</attribute1>
<attribute2 title="значення">значення</attribute2>
<attribute3 title="значення">значення</attribute3>
<attribute4 title="значення">значення</attribute4>
<bill_attribute1>значення</bill_attribute1>
<bill_attribute2>значення</bill_attribute2>
<bill_attribute3>значення</bill_attribute3>
<bill_attribute4>значення</bill_attribute4>
<status>значення</status>
<transaction_id>значення</transaction_id>
<paidAmount>значення</paidAmount>
<payDate>DD.MM.YYYY HH:mm:ss</payDate>
<payee_export_date>DD.MM.YYYY HH:mm:ss</payee_export_date>
<payee_export_flag>значення</payee_export_flag>
<bank_commission>значення</bank_commission>
<payee_id>значення</payee_id>
</bill>
</bills>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| bill id | ID рахунку (для транзакції устатусі RETURN, bill id набуває нового унікального значення |
| сontractNumber title | Номер договору |
| status | Статус транзакції на боці Portmone.com. Можливі значення: PAYED, RETURN |
| transaction_id | Ідентифікатор, наданий транзакції банком-партнером (передається під час виклику методу bills.pay). Для транзакцій у статусі RETURN буде набувати значення ID оригінальної транзакції (списання) |
| paidAmount | Сплачена сума |
| payDate | Дата оплати |
| payee_export_date | Дата спроби передачі коштів постачальнику послуги |
| payee_export_flag | Статус передачі (можливі значення: Y, N, R, E) |
| bank_commission | Винагорода банку, у грн (версія протоколу – 2). Параметр може приймати як додатні, так і від'ємні значення |
| name | Назва компанії-отримувача |
| payee_id | унікальний ідентифікатор компанії (версія протоколу – 3) |
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
Приклад відповіді по транзакції в статус RETURN:
<bill id="1367371577"> - унікальне bill id при поверненні
<name>lifecell</name>
<contractNumber title="Номер телефону (без +380)">667678994</contractNumber>
<attribute1/>
<bill_attribute1/>
<attribute2/>
<bill_attribute2/>
<attribute3/>
<bill_attribute3/>
<attribute4/>
<bill_attribute4/>
<status>RETURN</status> - статус повернення
<paidAmount>-5.00</paidAmount> - сума повернення, від'ємне значення
<payDate>28.03.2023 16:04:01</payDate> - дата оплати
<transaction_id>1367371282</transaction_id> - bill ID оригінальнох операції, по котрій виконано повернення
<payee_export_date>28.03.2023 16:04:01</payee_export_date> - дата та час повернення
<payee_export_flag/>
<bank_commission>-0.50</bank_commission>
2.8. Контрольний реєстр коштів, переданих постачальнику послуги
Метод: bills.exported
Опис: метод використовується для отримання контрольного списку транзакцій за період (день), кошти за яким були надіслані постачальнику послуги (біллеру). Необхідний для контролю прив'язування коштів.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| payeeId | ID компанії | Так |
| date | Дата, для якої виводиться реєстр. Формат: DD.MM.YYYY | Так |
Приклад запиту:
method=bills.exported&login=логін&password=пароль&version=2&payeeId=значення&date=DD.MM.YYYY
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<bills>
<bill id="значення">
<contractNumber title="значення">значення</contractNumber>
<attribute1 title="значення">значення</attribute1>
<attribute2 title="значення">значення</attribute2>
<attribute3 title="значення">значення</attribute3>
<attribute4 title="значення">значення</attribute4>
<bill_attribute1>значення</bill_attribute1>
<bill_attribute2>значення</bill_attribute2>
<bill_attribute3>значення</bill_attribute3>
<bill_attribute4>значення</bill_attribute4>
<status>значення</status>
<transaction_id>значення</transaction_id>
<paidAmount>значення</paidAmount>
<payDate>DD.MM.YYYY HH:mm:ss</payDate>
<payee_export_date>DD.MM.YYYY HH:mm:ss</payee_export_date>
<payee_export_flag>значення</payee_export_flag>
</bill>
</bills>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| bill id | ID рахунку |
| сontractNumber title | Номер договору |
| status | Статус транзакції на боці Portmone.com. Можливі значення: PAYED, RETURN |
| transaction_id | Ідентифікатор, наданий транзакції банком-партнером (передаєтсья під час виклику метода bills.pay). Для транзакцій у статусі RETURN буде набувати значення ID оригінальної транзакції (списання) |
| paidAmount | Сплачена сума |
| payDate | Дата оплати |
| payee_export_date | Дата спроби передачі коштів постачальнику послуги |
| payee_export_flag | Статус передачі (можливі значення: Y, N, R, E) |
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.9. Запит даних по балансу компанії-реселера
Метод: bills.balance
Опис: метод використовується для перегляду балансу по компанії-біллеру (PAYEE) на поточний момент.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| payeeId | ID компанії | Так |
Приклад запиту:
method=bills.balance&login=логін&password=пароль&version=2&payeeId=значення
Приклад успішної відповіді:
<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
<payee id="значення">
<balance>значення</balance>
</payee>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| payee id | ID компанії, для якої виконується запит балансу |
| balance | Баланс у компанії |
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.10. Запит інформації про доступні компанії-біллери
Метод: bills.payees
Опис: метод використовується для отримання параметрів біллерів* (PAYEE). За замовченням відбувається завантаження всіх даних по доступним компаніям на поточний момент. При додаванні необов'язкового параметру LastUpdateDate, лише даних, по яким були будь-які зміни від вказаної дати.
При додаванні одночасно необов'язкового параметру LastUpdateDate та deleted зі значенням on, лише деактивовані компанії, починаючи з дати в параметрі LastUpdateDate.
*з числа тих, для яких на цей логін заведені платіжні термінали.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| LastUpdateDate | Дата, від якої вносились будь-які зміни. Формат: DD.MM.YYYY | Ні |
| deleted | Деактивовані компанії | Ні |
Приклад запиту:
1. method=bills.payees&login=логін&password=пароль&version=2
2. method=bills.payees&login=логін&password=пароль&version=2&lastUpdateDate=DD.MM.YYYY
3. method=bills.payees&login=логін&password=пароль&version=2&lastUpdateDate=DD.MM.YYYY&deleted=on
Структура успішної відповіді:
<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
<payee id="значення">
<header_payee>Використовується деякими партнерами</header_payee>
<merchant>Використовується деякими партнерами</merchant>
<terminal>Використовується деякими партнерами</terminal>
<name>Коротка назва компанії-отримувача (для пунктів меню)</name>
<name_in_check>Юридична назва компанії-отримувача</name_in_check>
<image_file>Посилання на логотип компанії</image_file>
<contact_info>Контактна особа</contact_info>
<zkpo>Код ЄДРПОУ компанії</zkpo>
<bank_name>Назва банку компанії-отримувача</bank_name>
<bank_code> МФО банку компанії-отримувача</bank_code>
<bank_account>Р/р компанії-отримувача або номер рахунку за стандартом IBAN
</bank_account>
<contract_number_title>Назва 1-го реквізиту </contract_number_title>
<contract_number_type>Тип 1-го реквізиту (N - число; C - рядок; P – платіжна
картка; R, L - ієрархічний довідник) </contract_number_type>
<related_references>
<reference id="ID довідника" order_number="Порядковий номер">
Назва довідника</reference>
</related_references>
<contract_number_size>Розмір 1-го реквізиту</contract_number_size>
<contract_number_hint>Підказка клієнту для введення першого реквізиту
</contract_number_hint>
<contract_number_mask>Маска вводу першого реквізиту</contract_number_mask>
<attributes>
<attribute1>
<title>Назва атрибуту</title>
<type>Тип атрибуту (N - numeric; C - character; D - data;
R, L - hierarchical dictionary)</type>
<size>Максимальний розмір</size>
<related_references>
<reference id="ID довідника" order_number="Порядковий номер">
Назва довідника</reference>
</related_references>
</attribute1>
<attribute2>
<title>Назва атрибуту</title>
<type>Тип атрибуту (N - numeric; C - character; D - data;
R, L - hierarchical dictionary)
</type>
<size>Максимальний розмір</size>
<related_references>
<reference id="ID довідника" order_number="Порядковий номер">
Назва довідника</reference>
</related_references>
</attribute2>
<attribute3>
<title>Назва атрибуту</title>
<type>Тип атрибуту (N - numeric; C - character; D - data;
R, L - hierarchical dictionary)</type>
<size>Максимальний розмір</size>
<related_references>
<reference id="ID довідника" order_number="Порядковий номер">
Назва довідника</reference>
</related_references>
</attribute3>
<attribute4>
<title>Назва атрибуту</title>
<type>Тип атрибуту (N - numeric; C - character; D - data;
R, L - hierarchical dictionary)</type>
<size>Максимальний розмір</size>
<related_references>
<reference id="ID довідника" order_number="Порядковий номер">
Назва довідника</reference>
</related_references>
</attribute4>
</attributes>
<min_pay_amount>Розмір мінімального платежу</min_pay_amount>
<pay_round_amount> Чи дозволити сплачувати з копійками (Y- тільки цілі суми,
N- дозволити з копійками)</pay_round_amount>
<pay_different_amount> Чи дозволити оплату на суму, що відрізняється від
отриманої у рахунку (Y, N)</pay_different_amount>
<bill_source> Компанія допускає оплату за рахунками (Y, N) (оплата за
виставленими рахунками)</bill_source>
<balance_source> Компанія допускає оплату з поповне ння балансу (Y, N)(оплата
без виставленого рахунку)</balance_source>
<pay_order_description_format> Формат банківського призначення платежу
</pay_order_description_format>
<billing_day>Дата завантаження рахунків (версія протоколу – 2)</billing_day>
<max_pay_amount>Максимальна сума оплати (версія протоколу – 2) </max_pay_amount>
<bank_tariff>Винагорода банку, яку необхідно конвертувати у відсотки
(версія протоколу – 2)</bank_tariff>
<bank_tariff (значення з мінусом)>Винагорода ФК, яку необхідно конвертувати у відсотки
(версія протоколу – 2)</bank_tariff>
<bank_amount>Винагорода Портмоне, у грн (версія протоколу – 2) </bank_amount>
<min_bank_amount>Мінімальна сума винагороди Портмоне від кожної транзакції, у грн
(версія протоколу – 2)</min_bank_amount>
<min_bank_amount (значення з мінусом)>Не використовується (версія протоколу – 2)</min_bank_amount>
<max_bank_amount>На цей час не використовується (версія про токолу – 2)
</max_bank_amount>
<bank_deduction>На цей час не використовується (версія протоколу – 2)
</bank_deduction>
<bank_deduction_amount>Винагорода банку, яка утримується банком перед
відправкою покриття. Це значення необхідно конвертувати у відсотки
(версія протокол у – 2)</bank_deduction_amount>
<min_bank_deduction_amount>На цей час не використовується (версія протоколу – 2)
</min_bank_deduction_amount>
<max_bank_deduction_amount>На цей час не використовується (версія протоколу – 2)
</max_bank_deduction_amount>
<hide>Компанія-одержувач, що не призначена для відображення клієнтам
(версія протоколу – 2)</hide>
<payee_groups>
<payee_group id="1001">типу послуг, що надаються біллером: мобільний зв’язок</payee_group>
<payee_group id="1003">типу послуг, що надаються біллером: інтернет</payee_group>
<payee_group id="1006">типу послуг, що надаються біллером: телефонія</payee_group>
</payee_groups> (версія протоколу – 3)
<payee_group_name> назва групи, до якої належить сервіс </payee_group_name> (версія протоколу – 2 і більше)
<service_in_check>назва послуги для квитанції </service_in_check> (версія протоколу – 2 і більше)
</payee>
…
</rsp>
Зверніть увагу!
Параметр<hide>:
<hide>N</hide>- основна (шапочна) компанія, призначена для відображення сервісу для клієнта
<hide>Y</hide>- підшапочний сервіс, скривається при відображенні для клієнта
Параметр<image_file>необхідно аналізувати лише для основних (шапочних) компаній, по яким передається `N ``. В image_file зазначається URL джерела, звідки логотип можна завантажити.
Параметр<pay_different_amount>Чи дозволити оплату на суму, що відрізняється від отриманої у рахунку (Y, N) (версія протоколу – 1)</pay_different_amount>
Важливо! при відсутності «універсальних» айтемів (передаються у масивіtariff_items) у відповіді на метод bills.create/bills.createAll (версія протоколу – 2 і більше)</pay_different_amount>аналізується<pay_different_amount>
Довідники
Поля attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type можуть приймати значення R та L.
Це означає, що відповідні поля attribute1, attribute2, attribute3, attribute4, contract_number мають складний тип даних і значення цих полів повинно формуватись на основі ієрархічних довідників.
Тобто, якщо будь-яке з полів attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type приймає значення R або L, необхідно послідовно викликати метод bills.getreference з відповідними параметрами до отримання кінцевого рівня ієрархії та знаходження ідентифікатора/значення рядку довідника.
Після цього, для подальшої обробки та формування коректного призначення платежу та реквізитів, до методу bills.create у відповідному полі (attribute1, attribute2, attribute3, attribute4, contract_number) повинен бути переданий або ідентифікатор рядку довідника нижнього рівня (<item id>) при типі поля R, або значення рядку довідника нижнього рівня (<name>) при типі поля L.
Приклад довідника типу R:
<contract_number_type>R</contract_number_type>
<related_references>
<reference id="1180" order_number="1">
Регіон:
</reference>
<reference id="1183" order_number="2">
Найменування отримувача:
</reference>
<reference id="4308" order_number="3">
Населений пункт/район:
</reference>
</related_references>
де:
<related_references> – описує ієрархію довідників;
<reference id> – унікальний ідентифікатор довідника в системі Portmone.com (тип INT);
<reference order_number="1"> – порядковий номер довідника в ієрархії (у порядку зростання; тип INT);
<reference></reference> – назва поточного рівня довідника для клієнта (тип String).
Для довідника типу L вигляд відповіді буде аналогічним, за винятком значення параметру contract_number_type.
Приклади роботи з довідниками наведені у розділі 5 "Приклади" (Робота з довідниками типу R, Робота з довідниками типу L).
Приклад успішної відповіді:
<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
...
<payee id="23782">
<header_payee>1185</header_payee>
<merchant>X</merchant>
<terminal>X</terminal>
<name>Єдиний податок з фіз. осіб підприємців</name>
<name_in_check>Платежі до бюджету</name_in_check>
<image_file>https://cdn-images.portmone.com.ua/company/128_128/9974.png</image_file>
<contact_info></contact_info>
<zkpo>00032129</zkpo>
<bank_name>АТ «Ощадбанк»</bank_name>
<bank_code>300465</bank_code>
<bank_account>29240000087016</bank_account>
<contract_number_title>Управление казначейства</contract_number_title>
<contract_number_type>R</contract_number_type>
<related_references>
<reference id="1180" order_number="1">Регіон:</reference>
<reference id="1183" order_number="2">Найменування отримувача:</reference>
<reference id="4308" order_number="3">Населений пункт/район:</reference>
</related_references>
<contract_number_size>4308</contract_number_size>
<attributes>
<attribute1>
<title>ІПН</title>
<type>N</type>
<size/>
</attribute1>
<attribute2>
<title>За період</title>
<type>L</type>
<size>4311</size>
<related_references>
<reference id="4310" order_number="1"parent_value="attribute1">Групи дитячіх садочків м. Київ</reference>
<reference id="4311" order_number="2"parent_value="attribute2">Вихованці дитячіх садочків м. Київ</reference>
</related_references>
</attribute2>
<attribute3>
<title>Период</title>
<type>N</type>
<size/>
</attribute3>
<attribute4>
<title>ФИО</title>
<type>C</type>
<size/>
</attribute4>
</attributes>
<min_pay_amount>1</min_pay_amount>
<pay_round_amount>N</pay_round_amount>
<pay_different_amount>N</pay_different_amount>
<payee_group_id>1100</payee_group_id>
<payee_group_name>Податки, платежі до бюджету</payee_group_name>
<bill_source>N</bill_source>
<balance_source>Y</balance_source>
<pay_order_description_format>(_____) Покриття по транзакцiям сплати рахункiв
через систему Portmone.com згiдно договору ____вiд____ на суму___
(_____) - код банку)</pay_order_description_format>
</payee>
...
</rsp>
parent_valueопціональний параметр, передається у випадку викорисатання зв'язаних словників материнською компанією.header_payeeпараметр для зв'язки компаній,передається лише у відповідь метода bills.payees.Означає до якої основної компанії належить поточне payee id. Параметр існує лише для версій протоколу – 2, 3. Для основних компаній - це поле буде порожнє.
Зверніть увагу! У полі
bank_codeбуде переданий номер МФО банку компанії-отримувача – у разі заповнення реквізитів платежу у форматі "розрахунковий рахунок + код МФО", або 0 (нуль) – у разі заповнення номеру рахунку за стандартом IBAN.У полі
bank_accountбуде передаватись розрахунковий рахунок компанії-отримувача або IBAN (в залежності від того, який з реквізитів був заповнений при здійсненні платежу). Також слід звернути увагу на те, що в цьому полі раніше передавались лише числа, тепер будуть також передаватись літери згідно з форматом IBAN (29 літерно-цифрових символів).У полі
merchantбуде передане значення PAYANY у разі роботи з компанією, яка надає послуги, без прямого договру.
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.11. Запит інформації про компанії-біллери у контексті регіонів
Метод: bills.regions
Опис: метод використовується для отримання списку доступних* регіонів та списку біллерів (PAYEE) для кожного регіону.
*з числа тих, для яких на цей логін заведені платіжні термінали.
Якщо ідентифікатор регіону не встановлений то вважається, що компанія належить до усих регіонів України.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
Приклад запиту:
method=bills.regions&login=логін&password=пароль&version=2
Приклад успішної відповіді:
<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
<regions>
<region id="значення">
<name>Назва регіону (наприклад — м. Київ)</name>
<payees>
<payee id="значення">
<name>Назва компанії (наприклад — ВОЛЯ Броадбенд, м. Київ) </name>
</payee>
…
</payees>
</region>
…
</regions>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.12. Запит компаній, що надають рахунки для клієнта, за раніше отриманим рахунком
Метод: bills.additionalPayees
Опис: метод використовується для отримання списку компаній, рахунки яких може сплачувати клієнт. Після отримання клієнтом запитуваного рахунку можна здійснити запит списку компаній (та ідентифікаторів клієнта в цих компаніях), що надають послуги за тією ж адресою. Якщо список, що повертається, не порожній, можна запропонувати клієнту обрати компанії, рахунки яких він бажає сплатити та здійснити запит цих рахунків стандартним методом. Пошук компаній здійснюється за адресою клієнта.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID рахунку (його повертає метод bills.create) | Так |
Приклад запиту:
method=bills.additionalPayees&login=логін&password=пароль&version=2&billId=значення
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<payee id="ID компанії, оплату рахунку якої можна запропонувати клієнту">
<contract_number> ідентифікатор клієнта в цій компанії </contract_number>
<attribute1> додатковий ідентифікатор клієнта в цій компанії </attribute1>
<attribute2> додатковий ідентифікатор клієнта в цій компанії </attribute2>
<attribute3> додат ковий ідентифікатор клієнта в цій компанії </attribute3>
<attribute4> додатковий ідентифікатор клієнта в цій компанії </attribute4>
</payee>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.13. Запит інформації по регіонах
Метод: search.regions
Опис: метод використовується для отримання повного списку регіонів України.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
Приклад запиту:
method=search.regions&login=логін&password=пароль
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<regions>
<region id="44">
<name>м. Київ</name>
<orderIndex>1</orderIndex>
</region>
<region id="45">
<name>Київська область</name>
<orderIndex>2</orderIndex>
</region>
<region id="34">
<name>Івано-Франківська область</name>
<orderIndex>3</orderIndex>
</region>
<region id="43">
<name>Вінницька область</name>
<orderIndex>4</orderIndex>
</region>
<region id="33">
<name>Волинська область</name>
<orderIndex>5</orderIndex>
</region>
<region id="56">
<name>Дніпропетровська область</name>
<orderIndex>6</orderIndex>
</region>
<region id="62">
<name>Донецька область</name>
<orderIndex>7</orderIndex>
</region>
<region id="41">
<name>Житомирська область</name>
<orderIndex>8</orderIndex>
</region>
<region id="31">
<name>Закарпатська область</name>
<orderIndex>9</orderIndex>
</region>
<region id="61">
<name>Запорізька область</name>
<orderIndex>10</orderIndex>
</region>
<region id="52">
<name>Кіровоградська область</name>
<orderIndex>11</orderIndex>
</region>
<region id="64">
<name>Луганська область</name>
<orderIndex>12</orderIndex>
</region>
<region id="32">
<name>Львівська область</name>
<orderIndex>13</orderIndex>
</region>
<region id="51">
<name>Миколаївська область</name>
<orderIndex>14</orderIndex>
</region>
<region id="48">
<name>Одеська область</name>
<orderIndex>15</orderIndex>
</region>
<region id="53">
<name>Полтавська облас ть</name>
<orderIndex>16</orderIndex>
</region>
<region id="36">
<name>Рівненська область</name>
<orderIndex>17</orderIndex>
</region>
<region id="54">
<name>Сумська область</name>
<orderIndex>18</orderIndex>
</region>
<region id="35">
<name>Тернопільська область</name>
<orderIndex>19</orderIndex>
</region>
<region id="57">
<name>Харківська область</name>
<orderIndex>20</orderIndex>
</region>
<region id="55">
<name>Херсонська область</name>
<orderIndex>21</orderIndex>
</region>
<region id="38">
<name>Хмельницька область</name>
<orderIndex>22</orderIndex>
</region>
<region id="47">
<name>Черкаська область</name>
<orderIndex>23</orderIndex>
</region>
<region id="37">
<name>Чернівецька область</name>
<orderIndex>24</orderIndex>
</region>
<region id="46">
<name>Чернігівська область</name>
<orderIndex>25</orderIndex>
</region>
</regions>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.14. Запит інформації по регіонах (з пошуком за назвою регіону)
Метод: search.regionsExtended
Опис: метод використовується для отримання списку регіонів України з пошуком за назвою регіону.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| searchQuery | Підрядок для пошуку за назвою регіону (вказати частину назви регіону, від 3 символів) | Так |
Приклад запиту:
method=search.regionsExtended&login=логін&password=пароль&version=2&searchQuery=фільтр
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<regions>
<region id="44">
<name>м. Київ</name>
<orderIndex>1</orderIndex>
</region>
<region id="45">
<name>Київська область</name>
<orderIndex>2</orderIndex>
</region>
</regions>
</rsp>
Приклад відповіді, якщо сталася помилка (якщо searchQuery не задано):
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="p019">
<![CDATA[ Помилка сервера у процесі обробки запиту ]]>
</error>
<error_description>
<![CDATA[ search.regionsExtended p019 ]]>
</error_description>
</rsp>
2.15. Запит інформації по містах (населених пунктах) регіону
Метод: search.citiesByRegion
Опис: метод використовується для отримання списку населених пунктів для вказаного регіону.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| regionId | Унікальний ідентифікатор регіону, що отриманий з методу search.regions або search.regionsExtended | Так |
Приклад запиту:
method=search.citiesByRegion&login=логін&password=пароль&version=2®ionId=IDрегіону
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<cities>
<city id="12">
<name>м. Бровари</name>
<orderIndex>8</orderIndex>
<regionId>45</regionId>
</city>
...
</cities>
</rsp>
Зверніть увагу! Ідентифікатор міста (
city id) у відповіді може приймати від'ємні значення
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="p022">
<![CDATA[ Некоректний параметр regionId ]]>
</error>
<error_description>
<![CDATA[ search.citiesByRegion p022 ]]>
</error_description>
</rsp>
2.16. Запит інформації по населених пунктах регіону (з пошуком за назвою)
Метод: search.citiesByRegionExtended
Опис: метод використовується для отримання списку населених пунктів вказаного регіону за назвою населеного пункту.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| regionId | Унікальний ідентифікатор регіону, що отриманий з методу search.regions або search.regionsExtended | Так |
| searchQuery | Підрядок для пошуку за назвою населеного пункту, від 3 символів | Так |
Приклад запиту:
method=search.citiesByRegionExtended&login=логін&password=пароль&version=2®ionId=
IDрегіону&searchQuery=фільтр
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<cities>
<city id="147">
<name>с. Киданівка</name>
<orderIndex>404</orderIndex>
<regionId>45</regionId>
</city>
<city id="1912">
<name>с. Кийлів</name>
<orderIndex>405</orderIndex>
<regionId>45</regionId>
</city>
<city id="-11929">
<name>с. Кип'ячка</name>
<orderIndex>406</orderIndex>
<regionId>45</regionId>
</city>
<city id="215">
<name>с. Кирдани</name>
<orderIndex>407</orderIndex>
<regionId>45</regionId>
</city>
<city id="-11931">
<name>с. Кириївщина</name>
<orderIndex>408</orderIndex>
<regionId>45</regionId>
</city>
<city id="239">
<name>с. Кислівка</name>
<orderIndex>409</orderIndex>
<regionId>45</regionId>
</city>
<city id="78">
<name>с. Кищинці</name>
<orderIndex>410</orderIndex>
<regionId>45</regionId>
</city>
</cities>
</rsp>
Зверніть увагу! Ідентифікатор міста (
city id) у відповіді може приймати від'ємні значення
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.17. Запит інформації по вулицях міста
Метод: search.streetsByCity
Опис: метод використовується для отримання списку вулиць вказаного населеного пункту.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| cityId | Унікальний ідентифікатор населеного пункту, що отриманий з методу search.citiesByRegion або search.citiesByRegionExtended | Так |
Приклад запиту:
method=search.streetsByCity&login=логін&password=пароль&version=2&cityId=IDміста
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<streets>
<street id="662">
<name>бульвар Незалежності</name>
<orderIndex>36</orderIndex>
<cityId>12</cityId>
</street>
...
</streets>
</rsp>
Зверніть увагу! Ідентифікатор вулиці (
street id) у відповіді може приймати від'ємні значення
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.18. Запит інформації по вулицях міста (з пошуком за назвою вулиці)
Метод: search.streetsByCityExtended
Опис: метод використовується для отримання списку вулиць вказаного населеного пункту з пошуком за назвою вулиці.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| cityId | Унікальний ідентифікатор населеного пункту, що отриманий з методу search.citiesByRegion або search.citiesByRegionExtended | Так |
| searchQuery | Підрядок для пошуку за назвою вулиці, від 3 символів | Так |
Приклад запиту:
method=search.streetsByCityExtended&login=логін&password=пароль&version=2&cityId=IDміста
&searchQuery=фільтр
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<streets>
<street id="3059">
<name>проспект Миколи Бажана</name>
<orderIndex>15</orderIndex>
<cityId>22</cityId>
</street>
...
</streets>
</rsp>
Зверніть увагу! Ідентифікатор вулиці (
street id) у відповіді може приймати від'ємні значення
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.19. Запит інформації по будинках вулиці
Метод: search.housesByStreet
Опис: метод використовується для отримання списку будинків для вказаної вулиці.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| streetId | Унікальний ідентифікатор вулиці, що отриманий з методу search.streetsByCity або search.streetsByCityExtended | Так |
Приклад запиту:
method=search.housesByStreet&login=логін&password=пароль&version=2&streetId=IDвулиці
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<houses>
<house id="182744">
<name>10</name>
<orderIndex>153</orderIndex>
<streetId>3059</streetId>
<hasApartments>Y</hasApartments>
</house>
...
</houses>
</rsp>
Зверніть увагу!
- Ідентифікатор будинку (
house id) у відповіді може приймати від'ємні значення- Параметр
hasApartments– ознака наявності квартир у будинку. Може приймати два значення: Y – цей будинок є багатоквартирним й можливий подальший пошук квартири, N – цей будинок є приватним й подальший пошук квартири не дасть результатів
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.20. Запит інформації по будинках вулиці (з пошуком за номером будинку)
Метод: search.housesByStreetExtended
Опис: метод використовується для отримання списку будинків для вказаної вулиці з пошуком за номером будинку.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| streetId | Унікальний ідентифікатор вулиці, що отриманий з методу search.streetsByCity або search.streetsByCityExtended | Так |
| searchQuery | Підрядок для пошуку за номером будинку (вказати номер будинку) | Так |
Приклад запиту:
method=search.housesByStreetExtended&login=логін&password=пароль&version=2&streetId=
IDвулиці&searchQuery=фільтр
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<houses>
<house id="182744">
<name>121</name>
<orderIndex>2</orderIndex>
<streetId>54635</streetId>
<hasApartments>Y</hasApartments>
</house>
<house id="-2687333">
<name>174</name>
<orderIndex>3</orderIndex>
<streetId>54635</streetId>
<hasApartments>N</hasApartments>
</house>
<house id="-2687334">
<name>189а</name>
<orderIndex>4</orderIndex>
<streetId>54635</streetId>
<hasApartments>N</hasApartments>
</house>
</houses>
</rsp>
Зверніть увагу!
- Ідентифікатор будинку (
house id) у відповіді може приймати від'ємні значення- Параметр
hasApartments– ознака наявності квартир у будинку. Може приймати два значення: Y – цей будинок є багатоквартирним й можливий подальший пошук квартири, N – цей будинок є приватним й подальший пошук квартири не дасть результатів
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.21. Запит інформації по квартирах будинку (тільки для багатоквартирних будинків)
Метод: search.apartmentsByHouse
Опис: метод використовується для отримання списку квартир за відомим ідентифікатором будинку houseId (тільки для багатоквартирних будинків – hasApartments=Y).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| houseId | Унікальний ідентифікатор будинку, що отриманий з методу search.housesByStreet або search.housesByStreetExtended | Так |
Приклад запиту:
method=search.apartmentsByHouse&login=логін&password=пароль&version=2&houseId=IDбудинку
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<apartments>
<apartment id="3405561">
<name>276</name>
<houseId>182744</houseId>
</apartment>
...
</apartments>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="p032">
<![CDATA[Ошибка поиска данных. Возможно Вы пытаетесь найти квартиры по
частному дому (apartmentsByHouse)]]> </error>
<error_description> <![CDATA[ search.apartmentsByHouse p032 ]]>
</error_description>
</rsp>
2.22. Запит інформації по квартирах будинку (з пошуком за номером квартири)
Метод: search.apartmentsByHouseExtended
Опис: метод використовується для отримання списку квартир за відомим ідентифікатором будинку з додатковим фільтруванням за номером квартири (тільки для багатоквартирних будинків – hasApartments=Y).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| houseId | Унікальний ідентифікатор будинку, що отриманий з методу search.housesByStreet або search.housesByStreetExtended | Так |
| searchQuery | Підрядок для пошуку за номером квартири (вказати номер квартири) | Так |
Приклад запиту:
method=search.apartmentsByHouseExtended&login=логін&password=пароль&version=2&houseId=IDбудинку
&searchQuery=фільтр
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<apartments>
<apartment id="3405561">
<name>276</name>
<houseId>182744</houseId>
</apartment>
...
</apartments>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.23. Запит контекстної інформації за адресою (список рахунків)
Метод: search.userDocsByAddress
Опис: метод використовується для отримання списку рахунків за знайденим ідентифікатором будинку (houseId) для приватних будинків або квартири (apartmentId) для багатоквартирних будинків. Повертає рахунки з повною відповідністю за адресою.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| addressId | Унікальний ідентифікатор будинку або квартири | Так |
Важливо!
Для бу динків, в яких є квартири (
hasApartments=Y),addressId=apartment id(його повертають методи search.apartmentsByHouse та search.apartmentsByHouseExtended)Для приватних будинків (
hasApartments=N),addressId=house id(його повертають методи search.housesByStreet або search.housesByStreetExtended)
Приклад запиту:
method=search.userDocsByAddress&login=логін&password=пароль&version=2&addressId=IDапартаменту
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<docs>
<doc>
<addressId>3162324</addressId>
<payeeId>8004</payeeId>
<contractNumber>1404</contractNumber>
<attribute1>144</attribute1>
<attribute2/>
<attribute3/>
<attribute4/>
<matchType>FULL</matchType>
<attribute1Title>О/Р</attribute1Title>
<attribute2Title>Адреса</attribute2Title>
<attribute3Title/>
<attribute4Title/>
<contractNumberType>N</contractNumberType>
<contractNumberTitle>№ ЖEК-у</contractNumberTitle>
</doc>
...
</docs>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.24. Пошук компаній для зазначеного регіону
Метод: companies.top10ByRegion
Опис: метод використовується для отримання списку ТОП 10 компаній за ідентификатором регіону (часткова відповідність).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| regionId | Унікальний ідентифікатор регіону, що отриманий з методу search.regions або search.regionsExtended | Так |
Приклад запиту:
method=companies.top10ByRegion&login=логін&password=пароль&version=2®ionId=IDрегіону
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<companies>
<company>
<PAYEE_ID>22494</PAYEE_ID>
<NAME>ГИВЦ.</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>ИД</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>N</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE>Адрес</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>22494.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
<company>
<PAYEE_ID>14329</PAYEE_ID>
<NAME>КИЕВТЕПЛОЭНЕРГО</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Л/с</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE>15</CONTRACT_NUMBER_SIZE>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE>Адрес</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE/>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
…
</companies>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| PAYEE_ID | Унікальний ідентифікатор компанії |
| NAME | Назва компанії |
| CONTRACT_NUMBER | Основний реквізит (ідентифікатор) клієнта в цій компанії |
| CONTRACT_NUMBER_TITLE | Назва ідентифікатора клієнта у компанії |
| CONTRACT_NUMBER_TYPE | Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| CONTRACT_NUMBER_SIZE | Розмір ідентифікатора клієнта у компанії |
| ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4 | Додатковий атрибут платежу у компанії |
| ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE | Назва додаткового атрибуту платежу |
| ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE | Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE | Розмір додаткового атрибуту платежу |
| ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO | Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем) |
| IMAGE | Ім’я файлу з логотипом компанії |
| MATCH_TYPE | Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку) |
| CONTRACT_NUMBER_TYPE_ARRAY | Якщо <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE1_ARRAY | Якщо <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE2_ARRAY | Якщо <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE3_ARRAY | Якщо <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE4_ARRAY | Якщо <ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>, в цьому полі міститься довідник |
2.25. Пошук компаній для зазначеного населеного пункту
Метод: companies.top10ByCity
Опис: метод використовується для отримання списку ТОП 10 компаній за ідентифікатором міста (часткова відповідність).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| cityId | Унікальний ідентифікатор населеного пункту, що отриманий з методу search.citiesByRegion або search.citiesByRegionExtended | Так |
Приклад запиту:
method=companies.top10ByCity&login=логін&password=пароль&version=2&cityId=IDміста
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<companies>
<company>
<PAYEE_ID>17495</PAYEE_ID>
<NAME>ООО "КИЕВСКИЕ ЭНЕРГЕТИЧЕСКИЕ УСЛУГИ"</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Лицевой счет</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE>11</CONTRACT_NUMBER_SIZE>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE>Адрес</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>17495.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
<company>
<PAYEE_ID>22494</PAYEE_ID>
<NAME>ГИВЦ.</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>ИД</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>N</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE>Адрес</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>22494.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
...
</companies>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| PAYEE_ID | Унікальний ідентифікатор компанії |
| NAME | Назва компан ії |
| CONTRACT_NUMBER | Основний реквізит (ідентифікатор) клієнта в цій компанії |
| CONTRACT_NUMBER_TITLE | Назва ідентифікатора клієнта у компанії |
| CONTRACT_NUMBER_TYPE | Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| CONTRACT_NUMBER_SIZE | Розмір ідентифікатора клієнта у компанії |
| ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4 | Додатковий атрибут платежу у компанії |
| ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE | Назва додаткового атрибуту платежу |
| ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE | Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE | Розмір додаткового атрибуту платежу |
| ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO | Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем) |
| IMAGE | Ім’я файлу з логотипом компанії |
| MATCH_TYPE | Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку) |
| CONTRACT_NUMBER_TYPE_ARRAY | Якщо <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE1_ARRAY | Якщо <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE2_ARRAY | Якщо <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE3_ARRAY | Якщо <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE4_ARRAY | Якщо <ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>, в цьому полі міститься довідник |
2.26. Пошук компаній для зазначеної вулиці
Метод: companies.top10ByStreet
Опис: метод використовується для отримання списку ТОП 10 компаній за ідентификатором вулиці (часткова відповідність).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| streetId | Унікальний ідентифікатор вулиці, що отриманий з методу search.streetsByCity або search.streetsByCityExtended | Так |
Приклад запиту:
method=companies.top10ByStreet&login=логін&password=пароль&version=2&streetId=IDвулиці
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<companies>
<company>
<PAYEE_ID>6813</PAYEE_ID>
<NAME>Триолан</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер договора</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE/>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>triolan.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
<company>
<PAYEE_ID>6968</PAYEE_ID>
<NAME>Воля ТВ и/или Интернет</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер договора</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE>Адрес</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>volia.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
...
</companies>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| PAYEE_ID | Унікальний ідентифікатор компанії |
| NAME | Назва компанії |
| CONTRACT_NUMBER | Основний реквізит (ідентифікатор) клієнта в цій компанії |
| CONTRACT_NUMBER_TITLE | Назва ідентифікатора клієнта у компанії |
| CONTRACT_NUMBER_TYPE | Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| CONTRACT_NUMBER_SIZE | Розмір ідентифікатора клієнта у компанії |
| ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4 | Додатковий атрибут платежу у компанії |
| ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE | Назва додаткового атрибуту платежу |
| ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE | Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE | Розмір додаткового атрибуту платежу |
| ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO | Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем) |
| IMAGE | Ім’я файлу з логотипом компанії |
| MATCH_TYPE | Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку) |
| CONTRACT_NUMBER_TYPE_ARRAY | Якщо <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE1_ARRAY | Якщо <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE2_ARRAY | Якщо <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE3_ARRAY | Якщо <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE4_ARRAY | Якщо <ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>, в цьому полі міститься довідник |
2.27. Пошук компаній для зазначеного будинку
Метод: companies.top10ByHouse
Опис: метод використовується для отримання списку ТОП 10 компаній за відомим ідентифікатором будинку (повна відповідність для будинку або часткова для квартири).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| houseId | Унікальний ідентифікатор будинку, що отриманий з методу search.housesByStreet або search.housesByStreetExtended | Так |
Приклад запиту:
method=companies.top10ByHouse&login=логін&password=пароль&version=2&houseId=IDбудинку
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<companies>
<company>
<PAYEE_ID>2738</PAYEE_ID>
<NAME>ФРИНЕТ/o3.ua</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер контракта</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE/>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>freenet.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
<company>
<PAYEE_ID>6813</PAYEE_ID>
<NAME>Триолан</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер договора</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE/>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>triolan.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
...
</companies>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| PAYEE_ID | Унікальний ідентифікатор компанії |
| NAME | Назва компанії |
| CONTRACT_NUMBER | Основний реквізит (ідентифікатор) клієнта в цій компанії |
| CONTRACT_NUMBER_TITLE | Назва ідентифікатора клієнта у компанії |
| CONTRACT_NUMBER_TYPE | Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| CONTRACT_NUMBER_SIZE | Розмір ідентифікатора клієнта у компанії |
| ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4 | Додатковий атрибут платежу у компанії |
| ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE | Назва додаткового атрибуту платежу |
| ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE | Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE | Розмір додаткового атрибуту платежу |
| ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO | Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем) |
| IMAGE | Ім’я файлу з логотипом компанії |
| MATCH_TYPE | Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку) |
| CONTRACT_NUMBER_TYPE_ARRAY | Якщо <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE1_ARRAY | Якщо <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE2_ARRAY | Якщо <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE3_ARRAY | Якщо <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE4_ARRAY | Якщо <ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>, в цьому полі міститься довідник |
2.28. Пошук компаній за адресою
Метод: companies.top10ByAddress
Опис: метод використовується для отримання списку компаній за відомим ідентифікатором будинку (houseId) для приватних будинків або квартири (apartmentId) для багатоквартирних будинків. Повертає рахунки з повною та частковою відповідністю за адресою.
Якщо немає повної відповідності за адресою, метод шукає рахунки по вищих пунктах (за будинком, вул ицею, містом тощо).
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| addressId | Унікальний ідентифікатор будинку або квартири | Так |
Важливо!
Для будинків, в яких є квартири (
hasApartments=Y),addressId=apartment id(його повертають методи search.apartmentsByHouse та search.apartmentsByHouseExtended)Для приватних будинків (
hasApartments=N),addressId=house id(його повертають методи search.housesByStreet або search.housesByStreetExtended)
Приклад запиту:
method=companies.top10ByAddress&login=логін&password=пароль&version=2&addressId=IDквартири
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<companies>
<company>
<RWD/>
<PAYEE_ID>9817</PAYEE_ID>
<NAME>ХАРКІВГАЗ ЗБУТ (м. Харків)</NAME>
<CONTRACT_NUMBER>1310480114</CONTRACT_NUMBER>
<CONTRACT_NUMBER_TITLE>Особовий рахунок</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE>10</CONTRACT_NUMBER_SIZE>
<ATTRIBUTE1> вул.Морозова, буд.24, кв.15, м.Харків, м.Харків, 61105
</ATTRIBUTE1>
<ATTRIBUTE1_TITLE>Поштова адреса</ATTRIBUTE1_TITLE>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE>Старий особовий рахунок</ATTRIBUTE2_TITLE>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>Y</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE>Дільниця</ATTRIBUTE3_TITLE>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>Y</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>9817.png</IMAGE>
<MATCH_TYPE>FULL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
<company>
<RWD/>
<PAYEE_ID>6813</PAYEE_ID>
<NAME>Тріолан</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер договору</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE/>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>triolan.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
<CONTRACT_NUMBER_TYPE_ARRAY/>
<ATTRIBUTE1_ARRAY/>
<ATTRIBUTE2_ARRAY/>
<ATTRIBUTE3_ARRAY/>
<ATTRIBUTE4_ARRAY/>
</company>
...
</companies>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| RWD | Cистемний параметр, який показує, що рахунок прив'язаний до користувача та до адреси користувача |
| PAYEE_ID | Унікальний ідентифікатор компанії |
| NAME | Назва компанії |
| CONTRACT_NUMBER | Основний реквізит (ідентифікатор) клієнта в цій компанії |
| CONTRACT_NUMBER_TITLE | Назва ідентифікатора клієнта у компанії |
| CONTRACT_NUMBER_TYPE | Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| CONTRACT_NUMBER_SIZE | Розмір ідентифікатора клієнта у компанії |
| ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4 | Додатковий атрибут платежу у компанії |
| ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE | Назва додаткового атрибуту платежу |
| ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE | Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник |
| ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE | Розмір додаткового атрибуту платежу |
| ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO | Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем) |
| IMAGE | Ім’я файлу з логотипом компанії |
| MATCH_TYPE | Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку) |
| CONTRACT_NUMBER_TYPE_ARRAY | Якщо <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE1_ARRAY | Якщо <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE2_ARRAY | Якщо <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE3_ARRAY | Якщо <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, в цьому полі міститься довідник |
| ATTRIBUTE4_ARRAY | Якщо <ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>, в цьому полі міститься довідник |
2.29. Отримання значень довідника
Метод: bills.getreference
Опис: метод призначений для послідовного проходження по ієрархії довідників та отримання ідентіфікатора/значення довідника нижнього рівня для подальшої обробки та формування коректного призначення платежу та реквізитів.
Якщо будь-яке з полів attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type у відповіді методу bills.payees приймає значення R або L, необхідно послідовно викликати метод bills.getreference з відповідними параметрами до отримання кінцевого рівня ієрархії та знаходження ідентифікатора/значення рядку довідника.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| referenceId | Унікальний ідентифікатор довідника в системі Portmone.com. Тип INT | Так |
| parentReferenceId | Ідентифікатор рядка батьківського довідника (у відповіді методу bills.getreference – <item id>). Опціональний параметр для ідентифікатора довідника верхнього рівня та обов’язковий для всіх наступних запитів. Тип INT | Так/Ні |
Приклад запиту:
method=bills.getreference&referenceId=1183&parentReferenceId=42809
Приклад успішної відповіді:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
<reference id="1183">
<items>
<item id="705299">
<name>УК у Голос.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705301">
<name>УК у Дарн.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705303">
<name>УК у Десн.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705305">
<name>УК у Дніпр.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705307">
<name>УК у Оболон.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705309">
<name>УК у Печер.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705311">
<name>УК у Поділ.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705313">
<name>УК у Святош.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705315">
<name>УК у Солом.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
<item id="705317">
<name>УК у Шевчен.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
</items>
</reference>
</rsp>
Успішна відповідь – опис полів:
| Параметр | Опис |
|---|---|
| items | Список значень довідника |
| item id | Ідентифікатор рядка довідника. Використовується для отримання нащадків (якщо рівень не останній) або для передачі до ме тоду bills.create у випадку типу поля R (якщо рівень останній). Тип INT |
| name | Значення рядка довідника. Використовується для відображення клієнту або для передачі до методу bills.create у випадку типу поля L. Тип String |
| description | Додатковий опис значення довідника для відображення клієнту. Обов’язковий, якщо присутній. Тип String |
| parent_item_id | Ідентифікатор рядка батьківського довідника, що отриманий при попередньому виклику методу bills.getreference. Тип INТ |
В результаті знаходження останнього рівня ієрархії і вибору клієнтом необхідного рядку у списку, до методу bills.create у відповідному полі (attribute1, attribute2, attribute3, attribute4, contract_number) повинен бути переданий або ідентифікатор рядку довідника нижнього рівня (<item id>) при типі поля R, або значення рядку довідника нижнього рівня (<name>) при типі поля L.
Приклади використання методу наведені у розділі 5 "Приклади" (Робота з довідниками типу R, Робота з довідниками типу L).
2.30. Оновлення рахунку
Метод: bills.update
Опис: за допомогою цього методу виконується оновлення рахунку.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону) | Так |
Параметри для «універсальних» айтемів (передаються у масиві tariff_items):
| Параметр | Опис | Обов’язковий |
|---|---|---|
| id | ID лічильника | Так |
| amount | Розрахована сума за лічильником | Так |
| prev_counter | Попереднє значення лічильника | Ні |
| counter | Поточне значення лічильника | Ні |
| tariff | Тариф | Ні |
| subsidy | Субсидія | Ні |
| debt | Сплачений борг | Ні |
| attribute1 | Атрибут 1 (версія протоколу – 2) | Ні |
| attribute2 | Атрибут 2 (версія протоколу – 2) | Ні |
| attribute3 | Атрибут 3 (версія протоколу – 2) | Ні |
Параметри prev_counter, counter, tariff, subsidy, debt, attribute1, attribute2, attribute3 передаються, якщо в отриманому рахунку відповідні теги не порожні.
Якщо параметр переданий, він обов’язково повинен мати значення («порожні» параметри не допускаються).
Приклад рядка запиту для компаній без айтемів:
method=bills.pay&login=логін&password=пароль&version=2&billId=значення
Той же запит з даними по айтемах:
?method=bills.pay&login=логін&password=пароль&billId=значення&
tariff_items[111111][id]=значення&tariff_items[111111][counter]=значення&
tariff_items[111111][prev_counter]=значення&tariff_items[111111][tariff]=значення&
tariff_items[111111][subsidy]=значення&tariff_items[111111][debt]=значення
де tariff_items — назва масиву з даними по айтемах; 111111 — ID айтему; counter, prev_counter, tariff, subsidy, debt — дані по айтему.
Приклад успішної відповіді:
<rsp status="ok">
<bill id="754838110">
<payee id="17590">ТОВ "КИЇВСЬКІ ЕНЕРГЕТИЧНІ ПОСЛУГИ" (двозонні лічильники)</payee>
<contractNumber title="Лицевой счет">08028002701</contractNumber>
<attribute1 title="Адрес">вул.Героїв Севастополя буд.29 кв.27</attribute1>
<attribute2/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>06.11.2020</date>
<description>За жовтень 2020 року.</description>
<amount>120.00</amount>
<debt>0.00</debt>
<sum>120.00</sum>
<status>created</status>
<paidAmount/>
<payDate/>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point/>
<tariff_items>
<item id="380552112">
<name>Показания счетчика (день)</name>
<subsidy>0.00</subsidy>
<tariff>0.0000</tariff>
<counter>0</counter>
<prev_counter>0</prev_counter>
<amount>120.00</amount>
<debt>0.00</debt>
<name_ua>Показання лiчильника (день)</name_ua>
<name_eng>Meter characteristic (day)</name_eng>
<code>1</code>
<sub_code/>
<attribute1/>
<attribute2>120.24</attribute2>
<attribute3/>
<attribute4/>
<attribute5/>
<attribute6/>
<attribute7/>
<attribute8/>
<attribute9/>
<attribute10/>
<counter_accuracy>0</counter_accuracy>
<description/>
<pay_different_amount>Y</pay_different_amount>
</item>
<item id="380552114">
<name>Показания счетчика (ночь)</name>
<subsidy>0.00</subsidy>
<tariff>0.0000</tariff>
<counter>0</counter>
<prev_counter>0</prev_counter>
<amount>0.00</amount>
<debt>0.00</debt>
<name_ua>Показання лiчильника (ніч)</name_ua>
<name_eng>Meter characteristic (night)</name_eng>
<code>2</code>
<sub_code/>
<attribute1/>
<attribute2/>
<attribute3/>
<attribute4/>
<attribute5/>
<attribute6/>
<attribute7/>
<attribute8/>
<attribute9/>
<attribute10/>
<counter_accuracy>0</counter_accuracy>
<description/>
<pay_different_amount>Y</pay_different_amount>
</item>
</tariff_items>
</bill>
</rsp>
Приклад відповіді, якщо сталася помилка:
<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>
2.31. Перевірка суми гарантійного платежу
Метод: bank.params.guaranteeAmount
Опис: за допомогою цього методу можливо зробити перевірку суми гарантійного платежу.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| version | Версія API | Так |
| lang | Мова | Ні |
Приклад рядка запиту
method=bank.params.virtualBalance&login=PortmoneDirectTest&password=**************
&version=2&lang=ua
Приклад успішної відповіді
<rsp status="ok">
<params>
<amount_guarantee_payment>1000</amount_guarantee_payment>
</params>
</rsp>
Де amount_guarantee_payment - сума гарантійного платежу в грн по партнеру.
У разі, якщо Сума гарантійного платежу відсутня по партнеру згідно переданого login, відповідь виглядає так:
<rsp status="ok">
<params> <amount_guarantee_payment/> </params>
</rsp>
2.32. Створення копії сплаченого рахунку
Метод: bills.recreate
Опис: за допомогою цього методу можливо зробити копії сплаченого рахунку та повернення нового ID рахунку (billId). .
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID сплаченого рахунку | Так |
| version | Версія API | Так |
| lang | Мова | Ні |
Приклад рядка запиту
method=bills.recreate&billId=1328599111&login=PortmoneDirectTest&password=**************
&version=2&lang=ua
Приклад успішної відповіді
<rsp status="ok">
<bill id="1328946390">
<payee id="***">Name</payee>
<contractNumber>**********</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>
Приклад помилки
"p003">У вас вже є неоплачений рахунок. </error>
</rsp>
Також ймовірні помилки можуть бути наступні:
| Опис | Помилка |
|---|---|
| Спроба перестворити рахунок повторно (компанія надає рахунки, не поповнює баланс) | <error code="p003">У вас вже є неоплачений рахунок. [BILL_ID=1329627753]</error> |
| Несплачений рахунок (компанія надає рахунки, не поповнює баланс) | <error code="p003">Рахунок для копіювання неоплачений.</error> |
| Невірний номер рахунку (компанія надає рахунки, не поповнює баланс) | <error code="p003">Рахунок для оновлення не знайдений.</error> |
| Оплачений рахунок (компанія поповнює баланс) | <error code="p003">Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.</error> |
| Несплачений рахунок (компанія поповнює баланс) | <error code="p003">Рахунок для копіювання неоплачений.</error> |
| Компанія дозволяє і поповнення балансу, і виставляє рахунки | <error code="p003">Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.</error> |
2.33. Відміна оплат, які знаходяться в статусі PAYED
Метод: bills.cancel
Опис: за допомогою цього методу можливо відмінити оплати,які знаходяться в статусі PAYED
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| billId | ID сплаченого рахунку | Так |
| version | Версія API | Так |
| lang | Мова | Ні |
Приклад рядка запиту
method=bills.cancel&login=логін&password=пароль&version=2&billId=XXXXXXXXXX
Приклад успішної відповіді
<rsp status="ok">
<bill id="1404012705">
<payee id="2065">Київстар</payee>
<contractNumber title="Номер телефону (без +380) ">965259529</contractNumber>
<attribute1/>
<attribute2 title="Номер квитанцii Київстар"/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>15.05.2023</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>10.00</amount>
<debt>0.00</debt>
<sum>10.00</sum>
<status>canceled</status>
<paidAmount>10.00</paidAmount>
<payDate>15.05.2023 13:42:42</payDate>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point>PORTMONEDIRECTTEST</payment_point>
</bill>
</rsp>
2.34. Метод для передачі показів лічильника без оплати (для вхідних компаній) створення запиту.
Метод: counters.get
Опис: за допомогою цього методу можливо створити запит на передачу показів лічильника без оплати.
Метод працює аналогічно методу bills.createAll чи bills.create, в якому передаються атрибути по компанії з bills.payees
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| payeeId | ID компанії-одержувача платежу | Так |
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| contractNumber | Основний реквізит (ідентифікатор) клієнта в цій компанії | Так |
| attribute1-4 | Додаткові реквізити | Так |
| version | Версія API | Так |
| lang | Мова | Ні |
Приклад рядка запиту
version:2
lang:uk
login:PortmoneDirectTest
password:PortmoneDirect
method:counters.get
payeeId:27322
contractNumber:774037010600
attribute1:12
attribute2:12
attribute3:12
attribute4:21
Приклад успішної відповіді
<rsp status="ok">
<counters>
<counter id="1212773">
<name>холодна вода ЛК-15 (48міс.) №987604 октябрь 2</name>
<service_name>Показники лічильників</service_name>
<value>0</value>
<prev_value>566</prev_value>
<counter_number/>
<counter_accuracy>0</counter_accuracy>
</counter>
</counters>
</rsp>
Приклад помилки
<rsp status="fail">
<error code="p000">Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки.</error>
</rsp>
2.35. Метод для передачі показів лічильника без оплати (передача даних в компанію, показники, які вніс клієнт).
Метод: counters.set
Опис: за допомогою цього методу можливо передачі показів лічильника без оплати.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу | Так |
| counters | показник лічильника | Так |
| version | Версія API | Так |
| lang | Мова | Ні |
Приклад рядка запиту
version:2
lang:uk
login:PortmoneDirectTest
password:PortmoneDirect
method:counters.set
counters[1212773][counter]:1157
Приклад успішної відповіді
<rsp status="ok">
<counters>
<counter id="1212773">
<value>1157</value>
</counter>
</counters>
</rsp>
Приклад помилки
<rsp status="fail">
<error code="p000">Передача показань лічильника, що менші за попередні, заборонено постачальником послуги. Зверніться до постачальника послуги.</error>
<error_description>Передача показань лічильника, що менші за попередні, заборонено постачальником послуги. Зверніться до постачальника послуги.</error_description>
</rsp>
3. Поповнення карток (Account-2-Card)
Платіжна система Portmone.com дозволяє здійснювати поповнення карток фізичних осіб з банківського рахунку за номером картки.
3.1. Верифікація картки клієнта
- Аутентифікація партнера за допомогою логіну та паролю облікового запису, що отриманий при реєстрації у системі Portmone.com. Запит з необхідними параметрами формується на стороні партнера та передається методом POST на URL https://www.portmone.com.ua/r3/verification/card/.
Параметри:
| Параметр | Опис | Обов’язковий |
|---|---|---|
| login | Логін компанії-реселера в системі Portmone.com | Так |
| password | Пароль компанії-реселера в системі Portmone.com | Так |
| method | Назва методу – verification | Так |
| success_url | Адреса партнера, на яку буде спрямовано клієнта після успішної перевірки. За цією ж адресою методом POST Portmone.com надішле параметри для наступного кроку | Так |
Приклад запиту:
<form action="https://www.portmone.com.ua/r3/verification/card/" method="post">
<input type="hidden" name="success_url" value="https://api.credit-pro.com.ua/portmone/
direct/a2c/card?uuid=004182e7-b05f-4415-9c2d-fb220ee655af" />
<input type="hidden" name="method" value="verification" />
<input type="hidden" name="login" value="P_DIRECT_CITY" />
<input type="hidden" name="password" value="11111111" />
<input type="submit" value="RESULT" style={{ width: '350px' }} class="button_green" />
</form>
- У випадку успішної аутентифікації партнера клієнт переходить на сторінку перевірки платіжної картки, де необхідно ввести номер платіжної картки, термін її дії та CVV2, натиснути "Верифікувати":
- Наступним кроком клієнту необхідно буде ввести VCODE (код верифікації), що надійде у SMS-повідомленні від банку, що випустив картку:
- У випадку успішного проходження перевірки на
success_url, що вказаний у запиті, будуть надіслані наступні дані:
CARD_MASK: 410232******5594
SHOP_BILL_ID: 488377227
RECIPIENT_ID: 45467512
де:
CARD_MASK – маска картки клієнта (перші 6 та останні 4 цифри номеру);
SHOP_BILL_ID – ідентифікатор транзакції у системі Portmone.com;
RECIPIENT_ID – ідентифікатор одержувача у системі Portmone.com.
3.2. Поповнення картки клієнта
Використовуючи протокол роботи PortmoneDirect, виконати наступні кроки для зарахування коштів на картку:
- Викликати метод bills.create з наступними параметрами:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.create |
| payeeId | ID компанії-одержувача платежу |
| contractNumber | Маска картки клієнта (6 перших та 4 останні цифри номера картки у форматі 444433XXXXXX1111) |
| attribute1 | Має дорівнювати значенню recipient_id, що отримане у відповіді на верифікацію |
| attribute2 | Має дорівнюв ати значенню shop_bill_id, що отримане у відповіді на верифікацію |
| attribute2 | Має дорівнювати значенню shop_bill_id, що отримане у відповіді на верифікацію |
| payer_iban або payer_card_number | iban відправника, хто ініціює переказ, приймає значення 29 символів ------------------------------------------------------------------------------ Карти, відправника, хто ініціює переказ, приймає значення 16 цифр |
У відповідь буде сформований рахунок на суму 0 грн. з наданням унікального ідентифікатору – billId.
- Викликати метод bills.pay з використанням наступних параметрів:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.pay |
| billId | ID рахунку (його повертає метод bills.create) |
| amount | Сума, що сплачується (сумма, що буде зарахована на картку) |
- Викликати метод bills.get для отримання інформації про статус зарахування:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.get |
| billId | ID рахунку (його повертає метод bills.create) |
Важливо! У відповіді, яку повертає система Portmone.com на запит статусу за методом bills.get, є додаткова інформація про успішність проходження операції переказу коштів у банка-еквайра – атрибут
payee_export_flag.Якщо у рахунку
status=’PAYED’, алеpayee_export_flag = ’E’– це означає, що оплата за рахунком прийнята, але кошти ще не зараховані клієнту (рахунок у процесі оплати). При цьому необхідно протягом пари годин продовжувати надсилати запит статусу оплати рахунку до системи Portmone.com, доки не буде отриманий один з наступних статусів:
status=’PAYED’таpayee_export_flag=’Y’– оплата у еквайра успішна і кошти зараховані клієнту, абоstatus=’CANCELED’– кошти на картку клієнта не можуть бути зараховані.
- Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.
3.3. Поповнення картки клієнта за повним номером картки
Використовуючи протокол роботи PortmoneDirect, виконати наступні кроки для зарахування коштів на картку:
- Викликати метод bills.create з наступними параметрами:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.create |
| payeeId | ID компанії-одержувача платежу |
| contractNumber | Повний номер картки отримувача (наприклад, 4444333322221111) |
| attribute1 | Має дорівнювати значенню recipient_id, що отримане у відповіді на верифікацію |
| attribute2 | Має дорівнювати значенню shop_bill_id, що отримане у відповіді на верифікацію |
| payer_iban або payer_card_number | iban відправника, хто ініціює переказ, приймає значення 29 символів ------------------------------------------------------------------------------ Карти, відправника, хто ініціює переказ, приймає значення 16 цифр |
У відповідь буде сформований рахунок на суму 0 грн. з наданням унікального ідентифікатору – billId.
- Викликати метод bills.pay з використанням наступних параметрів:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.pay |
| billId | Унікальний ідентифікатор рахунку, що отриманий на попередньому кроці з методу bills.create |
| amount | Сума, що сплачується (сумма, що буде зарахована на картку) |
- Викликати метод bills.get для отримання інформації про статус зарахування:
| Параметр | Опис |
|---|---|
| login | Логін компанії-реселера в системі Portmone.com |
| password | Пароль компанії-реселера в системі Portmone.com |
| method | Назва методу – bills.get |
| billId | ID рахунку (його повертає метод bills.create) |
Важливо! У відповіді, яку повертає система Portmone.com на запит статусу за методом bills.get, є додаткова інформація про успішність проходження операції переказу коштів у банка-еквайра – атрибут
payee_export_flag.Якщо у рахунку
status=’PAYED’, алеpayee_export_flag = ’E’– це означає, що оплата за рахунком прийнята, але кошти ще не зараховані клієнту (рахунок у процесі оплати). При цьому необхідно протягом пари годин продовжувати надсилати запит статусу оплати рахунку до системи Portmone.com, доки не буде отриманий один з наступних статусів:
status=’PAYED’таpayee_export_flag=’Y’– оплата у еквайра успішна і кошти зараховані клієнту, абоstatus=’CANCELED’– кошти на картку клієнта не можуть бути зараховані.
- Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.
4. Коди помилок
| Код помилки | Повідомлення про помилку | Опис | Метод |
|---|---|---|---|
| o001 | Помилка при створенні рахунку | Помилка при створенні рахунку (внутрішній код помилки) | bills.create |
| o003 | Помилка під час оплати рахунку | Помилка під час оплати рахунку | bills.pay |
| o003 | Помилка під час відміни рахунку | Помилка під час скасування рахунку. (Рахунок не знайдено) | bills.cancel |
| o003 | Помилка при створенні рахунку. XXXXXXXXXXXXXXXXXXXXXXXX | Помилка при створенні рахунку. XXXXXXXXXXXXXXXXXXXXXXXX | bills.recreate |
| o004 | Помилка при виведенні контрольного реєстру | Помилка при виведенні контрольного реєстру | bills.paymentOrder |
| o006 | Помилка при виведенні балансу по компанії | Помилка при виведенні балансу по компанії | bills.balance |
| o010 | Немає отримувачів платежу для логіну | Помилка при пошуку компанії | bills.additionalPayees |
| р013 | Невірні параметри ідентифікації клієнта | Помилка під час оплати рахунку | bills.pay |
| p001 | Invalid method name | Невірне ім'я методу | Усі методи |
| p002 | Invalid login/password | Невірний логін або пароль | Усі методи |
| p003 | Помилка при створенні підписки | Помилка при створенні підписки (внутрішній код помилки) | bills.create |
| p003 | Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки. | Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки. | bills.recreate |
| p003 | Рахунок для оновлення не знайдений | Рахунок для оновлення не знайдений | bills.recreate |
| p003 | Рахунок для оновлення несплачений. | Рахунок для оновлення несплачений. | bills.recreate |
| p003 | Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків. | Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків. | bills.recreate |
| p003 | У вас вже є несплачений рахунок [BILL_ID=XXXXXX] | У вас вже є несплачений рахунок [BILL_ID=XXXXXX] | bills.recreate |
| p004 | Помилка при оновленні параметрів лічильника | Помилка при оновленні параметрів лічильника | bills.pay |
| p005 | Підписка має статус "ERROR" | Компанія-біллер повернула повідомлення про помилку за цією підпискою, або при спробі повторно створити підписку з невірними реквізитами | bills.create |
| p006 | Немає такої компанії | У БД Portmone.com немає компанії-біллера з таким ID | bills.create |
| p007 | Підписка створена. Чекаємо на відповідь компанії. | Підписка створена (“CREATED”), але поки немає підтвердження від компанії-біллера про правильність введеної інформації (якщо компанія-біллер відповість, що передана інформація некоректна, статус підписки буде змінений на “ERROR”). | bills.create |
| p008 | У вас немає несплачених рахунків. Очікуйте на виставлення рахунків від вашого постачальника послуг. | Підписка створена, але рахунків поки що немає (як у випадку з ГІОЦем, наприклад) | bills.create |
| p009 | Немає такого рахунку | У БД Portmone.com немає рахунку з таким ID (внутрішній код помилки) | bills.get |
| p010 | No bills for date | Немає рахунків за отриману дату (внутрішній код помилки) | bills.date, bills.exported |
| p011 | Отримано порожній або пошкоджений реєстр | Отримано порожній або пошкоджений реєстр | bills.paymentOrder |
| p012 | Empty POST | Отриманий масив POST порожній | Усі методи |
| p014 | Перевищена квота по компанії | Перевищена квота по компанії (внутрішній код помилки) | bills.pay |
| p015 | Помилка при перевірці валідності підписки | Видається, якщо реквізити раніше створеної підписки більш не дійсні (наприклад, номер телефону деактивовано біллером) (внутрішній код помилки) | bills.create |
| p015 | Invalid date format | Невірний формат дати (внутрішній код помилки) | bills.date, bills.exported |
| p017 | Помилка при запиті інформації за рахунком | Неможливо отримати інформацію про рахунок (наприклад, рахунок у цей момент заблокований сесією оплати) (внутрішній код помилки) | bills.get |
| p018 | Для отримання рахунків для цієї компанії необхідно використовувати метод bills.createAll | bills.create | |
| p019 | Загальна помилка для усіх методів search.* | search.* | |
| p022 | Довідник не знайдений | bills.getreference | |
| p032 | Помилка пошуку даних. Можливо ви намагаєтесь знайти квартири за приватним будинком | Помилка пошуку даних. Дані (квартири) не знайдено | search.apartmentsByHouse, search.apartmentsByHouseExtended |
| p033 | Формат номеру телефону має відповідати формату +38ХХХХХХХХХХ | ||
| p100 | Помилка при зверненні до БД | Внутрішня помилка системи. При виникненні цієї помилки необхідно обовязково здійснити наступний виклик методу bills.get, оскільки в цьому випадку статус рахунку невідомий — рахунок може бути як оплачений, так і не оплачений | Усі методи |
5. Приклади
Приклад використання методів PortmoneDirect для отримання географічних даних клієнта (ідентифікатори регіону, міста, вулиці, будинку та/або квартири)
(на прикладі пошуку за адресою: м. Київ, проспект Бажана, буд. 1а, кв. 4)
1. Пошук регіону Києва серед регіонів (searchQuery=Ки)
POST method=search.regionsExtended&login=логін&password=пароль&version=2&searchQuery=Ки
Результат: regionId = 44
2. Пошук міста Києва у регіоні Київ (regionId = 44, searchQuery=Ки)
POST method=search.citiesByRegionExtended&login=логін&password=пароль&version=2®ionId=44&searchQuery=Ки
Результат: cityId = 22
3. Пошук вулиці у місті (cityId = 22, searchQuery=баж)
POST method=search.streetsByCityExtended&login=логін&password=пароль&version=2&cityId=22&searchQuery=баж
Результат: streetId = 3059
4. Пошук будинку на вулиці (streetId = 3059, searchQuery=1а)
POST method=search.housesByStreetExtended&login=логін&password=пароль&version=2&streetId=3059&searchQuery=1а
Результат: houseId = 1905560, hasApartments = Y
5. Пошук квартири у будинку (houseId = 1905560, searchQuery=4)
POST method=search.apartmentsByHouseExtended&login=логін&password=пароль&version=2&houseId=1905560&searchQuery=4
Результат: apartmentId = 7284220
6. Отримання списку рахунків за адресою (addressId = apartmentId = 7284220)
POST method=search.userDocsByAddress&login=логін&password=пароль&version=2&addressId=7284220
У разі використання методу search.userDocsByAddress відповідь містить рахунки тільки з повною відповідністю за адресою - <MATCH_TYPE>FULL</MATCH_TYPE>
<rsp status="ok">
<docs>
<doc>
<addressId>234</addressId>
<payeeId>9238</payeeId>
<contractNumber>3201001300005250</contractNumber>
<attribute1/>
<attribute2>обл Київська,,м. Бровари,вул. БРОВАРСЬКОЇ СОТНІ,буд 3,,</attribute2>
<attribute3/>
<attribute4/>
<matchType>FULL</matchType>
...
У разі використання методу companies.top10ByAddress відповідь містить рахунки з повною та частковою відповідністю за адресою
<rsp status="ok">
<companies>
<company>
<PAYEE_ID>6813</PAYEE_ID>
<NAME>Триолан</NAME>
<CONTRACT_NUMBER/>
<CONTRACT_NUMBER_TITLE>Номер договора</CONTRACT_NUMBER_TITLE>
<CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
<CONTRACT_NUMBER_SIZE/>
<ATTRIBUTE1/>
<ATTRIBUTE1_TITLE/>
<ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
<ATTRIBUTE1_SIZE/>
<ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
<ATTRIBUTE2/>
<ATTRIBUTE2_TITLE/>
<ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
<ATTRIBUTE2_SIZE/>
<ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
<ATTRIBUTE3/>
<ATTRIBUTE3_TITLE/>
<ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
<ATTRIBUTE3_SIZE/>
<ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
<ATTRIBUTE4/>
<ATTRIBUTE4_TITLE/>
<ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
<ATTRIBUTE4_SIZE/>
<ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
<IMAGE>triolan.png</IMAGE>
<MATCH_TYPE>PARTIAL</MATCH_TYPE>
...
По отриманих рахунках з повною відповідністю за адресою необхідно виконати запит bills.create або bills.createAll по отриманих bill ID.
По отриманих рахунках з частковою відповідністю за адресою у користувача необхідно запитати заповнення обов'язкових параметрів contractNumber для отримання рахунку відповідної payeeId.
Робота з довідниками типу R
(на прикладі вибору кінцевого одержувача платежу для сплати єдиного податку ФОП в Дарницькому районі м. Києва для тестової компанії з payee id = 23782)
1. Отримання даних про компанію (метод bills.payees)
Запит:
method=bills.payees&login=логін&password=пароль
Відповідь:
<rsp status="ok">
...
<payee id="23782">
...
<name>Єдиний податок з фіз. осіб підприємців</name>
<contract_number_type>R</contract_number_type>
<related_references>
<reference id="1180" order_number="1">
Регіон:
</reference>
<reference id="1183" order_number="2">
Найменування отримувача:
</reference>
<reference id="4308" order_number="3">
Населений пункт/район:
</reference>
</related_references>
<contract_number_size>4308</contract_number_size>
...
</payee>
...
</rsp>
Результат: у відповіді використовуємо список довідників з блоку payee/related_references для payee id = 23782 – reference id = 1180, reference id = 1183, reference id = 4308
2. Отримання даних найвищого рівня ієрархіїї – вибір регіону для сплати податку (referenceId = 1180, parentReferenceId порожній)
Запит:
method=bills.getreference&referenceId=1180&parentReferenceId=
Відповідь:
<rsp status="ok">
<reference id="1180">
<items>
<item id="42809">
<name>м. Київ</name>
<description/>
<parent_item_id/>
</item>
...
</items>
</reference>
</rsp>
Результат: у відповіді обираємо елемент найвищого рівня ієрархії – item id = 42809 - м. Київ
3. Отримання даних наступного рівня ієрархії – вибір району для сплати податку (referenceId = 1183, parentReferenceId = 42809)
Запит:
method=bills.getreference&referenceId=1183&parentReferenceId=42809
Відповідь:
<rsp status="ok">
<reference id="1183">
<items>
...
<item id="705301">
<name>УК у Дарн.р-ні</name>
<description/>
<parent_item_id>42809</parent_item_id>
</item>
...
</items>
</reference>
</rsp>
Результат: у відповіді обираємо елемент поточного рівня ієрархії – item id = 705301 - УК у Дарн.р-ні
4. Отримання даних наступного рівня ієрархії – вибір кінцевого одержувача платежу (referenceId = 4308, parentReferenceId = 705301)
Запит:
method=bills.getreference&referenceId=4308&parentReferenceId=705301
Відповідь:
<rsp status="ok">
<reference id="4308">
<items>
<item id="849062">
<name>Дарниц.р-н/18050400</name>
<description/>
<parent_item_id>705301</parent_item_id>
</item>
</items>
</reference>
</rsp>
Результат: у відповіді обираємо елемент найнижчого рівня ієрархії – item id = 849062 - Дарниц.р-н/18050400
5. Створення рахунку (метод bills.create, payeeId = 23782, contractNumber = 849062) та його оплата (метод bills.pay)
Результатом роботи з довідником типу R є ідентифікатор, що отриманий на найнижчому рівні ієрархії – 849062. Цей ідентифікатор буде використовуватись на наступному етапі для виклику методу bills.create.
Робота з довідниками типу L
(на прикладі вибору групи ФОП та податкового періоду для сплати єдиного податку ФОП в Дарницькому районі м. Києва для тестової компанії з payee id = 23782)
1. Отримання даних про компанію (метод bills.payees)
Запит:
method=bills.payees&login=логін&password=пароль&version=2
Відповідь:
<rsp status="ok">
…
<payee id="23782">
...
<name>Єдиний податок з фіз. осіб підприємців</name>
<attributes>
...
<attribute2>
<title>За период</title>
<type>L</type>
<size>4311</size>
<related_references>
<reference id="4310" order_number="1">Група:</reference>
<reference id="4311" order_number="2">За період:</reference>
</related_references>
</attribute2>
...
</attributes>
...
</payee>
...
</rsp>
Результат: у відповіді використовуємо список довідників з блоку payee/attributes/attribute2/related_references для payee id = 23782 – reference id = 4310, reference id = 4311
2. Отримання даних найвищого рівня ієрархіїї – вибір групи ФОП (referenceId = 4310, parentReferenceId порожній)
Запит:
method=bills.getreference&referenceId=4310&parentReferenceId=
Відповідь:
<rsp status="ok">
<reference id="4310">
<items>
<item id="832244">
<name>1 группа</name>
<description/>
<parent_item_id/>
</item>
<item id="832245">
<name>2 группа</name>
<description/>
<parent_item_id/>
</item>
<item id="832247">
<name>3 группа</name>
<description/>
<parent_item_id/>
</item>
</items>
</reference>
</rsp>
Результат: у відповіді обираємо елемент найвищого рівня ієрархії – item id = 832247 - 3 группа
3. Отримання даних наступного рівня ієрархії – вибір податкового періоду (referenceId = 4311, parentReferenceId = 832247)
Запит:
method=bills.getreference&referenceId=4311&parentReferenceId=832247
Відповідь:
<rsp status="ok">
<reference id="4311">
<items>
<item id="832280">
<name>1-й квартал</name>
<description/>
<parent_item_id>832247</parent_item_id>
</item>
<item id="832281">
<name>2-й квартал</name>
<description/>
<parent_item_id>832247</parent_item_id>
</item>
<item id="832282">
<name>3-й квартал</name>
<description/>
<parent_item_id>832247</parent_item_id>
</item>
<item id="832283">
<name>4-й квартал</name>
<description/>
<parent_item_id>832247</parent_item_id>
</item>
</items>
</reference>
</rsp>
Результат: у відповіді обираємо елемент найнижчого рівня ієрархії – item id = 832247 - 4-й квартал
4. Створення рахунку (метод bills.create, payeeId = 23782, attribute2 = 4-й к вартал) та його оплата (метод bills.pay)
Результатом роботи з довідником типу L є значення атрибуту, що отримане на найнижчому рівні ієрархії – 4-й квартал. Це значення буде використовуватись на наступному етапі для виклику методу bills.create.
6. Тестування
Веб-інтерфейс API PortmoneDirect: https://direct.portmone.com.ua/api/.
Адреса виклику методів (endpoint URL): https://direct.portmone.com.ua/api/directcash/.
Логін та пароль для тестування:
логін — PortmoneDirectTest пароль — PortmoneDirect
Для імитації відмов у роботі системи (таймаути та інше), для тестового логіну PORTMONEDIRECTTEST2, до методу bills.pay додано таймаут, що виникає випадковим чином (ймовірність спрацювання приблизно 40%). Необхідно враховувати, що у разі спрацювання таймауту, рахунок на боці Portmone може бути як оплачений, так і не оплачений.
Логін та пароль для тестування з імитацією таймаутів:
логін — PORTMONEDIRECTTEST2 пароль — Direct2
На етапі тестування (для логіну PortmoneDirectTest) доступні три компанії-біллери: ГІОЦ (payeeId = 22494), Воля ТБ та/або Iнтернет (payeeId = 6968) та Vodafone (payeeId = 10196). Ці три біллери ілюструють три типи бізнес-логіки:
- Біллери, які не виставляють рахунки періодично (наприклад, оператори мобільного зв'язку (МТС-Україна)).
- Біллери, які виставляють рахунки періодично і допускають поповнення балансу (наприклад, Воля Броадбенд).
- Біллери, які виставляють рахунки періодично і не допускають поповнення балансу (наприклад, ГІОЦ)
Відповідно, під час виклику bills.create:
- Для біллерів першого типу — при кожному запиті завжди створюється новий раунок на нульову суму.
- Для біллерів другого типу — якщо в системі Portmone вже існує рахунок, виставлений біллером, повертаємо цей рахунок (на сумму, що виставлена біллером), якщо ні — створюємо новий на нульову суму.
- Для біллерів третього типу — якщо в системі Portmone вже есть існує рахунок, виставлений біллером, повертаємо цей рахунок (на суму, що виставлена біллером), якщо ні — генер уємо повідомлення про помилку «p008 – У вас немає несплачених рахунків. Очікуйте на виставлення рахунків від вашого постачальника послуг.».
Додаток 1. Опис структури XML
Такий XML повертається у разі виклику методів bills.create, bills.pay та bills.get.
<?xml version="1.0" encoding="utf-8"?>
<rsp status="">
<bill id="id">
<payee id="id"> Назва компанії </payee>
<contractNumber title="title"> Номер договору або номер телефону (для телефону —
9 знаків) </contractNumber>
<attribute1 title="title"> Значення атрибуту (наприклад, “710”) </attribute1>
<attribute2 title="title" />
<attribute3 title="title" />
<attribute4 title="title" />
<bill_attribute1 />
<bill_attribute2 />
<bill_attribute3 />
<bill_attribute4 />
<date>DD.MM.YYYY</date>
<description />
<amount />
<debt />
<sum>amount + debt</sum>
<period />
<status />
<paidAmount />
<payDate>DD.MM.YYYY hh24:mi:ss</payDate>
<payee_export_flag>Y</payee_export_flag>
<auth_сode />
<transaction_id />
<payment_point>payment_point</payment_point>
<tariff_items>
<item id="id">
<name />
<name_ua />
<name_eng />
<code />
<sub_code />
<tariff />
<tariff_state /> <!-- версія протоколу – 2 -->
<tariff_name /> <!-- версія протоколу – 2 -->
<counter />
<counter_state /> <!-- версія протоколу – 2 -->
<counter_name /> <!-- версія протоколу – 2 -->
<prev_counter />
<prev_counter_state /> <!-- версія протоколу – 2 -->
<prev_counter_name /> <!-- версія протоколу – 2 -->
<subsidy />
<subsidy_state /> <!-- версія протоколу – 2 -->
<subsidy_name /> <!-- версія протоколу – 2 -->
<debt />
<debt_state /> <!-- версія протоколу – 2 -->
<debt_name /> <!-- версія протоколу – 2 -->
<amount />
<negative_amount /> <!-- версія протоколу – 2 -->
<amount_state /> <!-- версія протоколу – 2 -->
<amount_name /> <!-- версія протоколу – 2 -->
<counter_accuracy />
<pay_different_amount />
<attribute1 />
<attribute1_state /> <!-- версія протоколу – 2 -->
<attribute1_name /> <!-- версія протоколу – 2 -->
<attribute2 />
<attribute2_state /> <!-- версія протоколу – 2 -->
<attribute2_name /> <!-- версія протоколу – 2 -->
<attribute3 />
<attribute3_state /> <!-- версія протоколу – 2 -->
<attribute3_name /> <!-- версія протоколу – 2 -->
<attribute4 />
<attribute5 />
<attribute6 />
<attribute7 />
<attribute8 />
<attribute9 >
<attribute10 />
<description />
<calculated /> <!-- версія протоколу – 2 -->
</item>
</tariff_items>
</bill>
</rsp>
| Параметр | Опис |
|---|---|
| rsp status | Стутус запиту: "ok" – все Ok, "fail" – помилка |
| bill id | ID рахунку |
| payee id | ID компанії – передається у запиті bills.create |
| contractNumber title | Наприклад, "Номер телефону (+380)" |
| attribute1 title | Призначення (назва) атрибуту1 (наприклад, “Номер ЖЕКу”). Залежить від організації |
| attribute2 | Назва атрибуту2. Залежить від організації |
| attribute3 | Назва атрибуту3. Залежить від організації |
| attribute4 | Назва атрибуту4. Залежить від організації |
| bill_attribute1-4 | Додаткові параметри рахунку (номер квитанції Київстару і т.д.). Залежать від біллера |
| date | Дата створення рахунку. Формат: DD.MM.YYYY |
| description | Опис рахунку |
| amount | Сума рахунку. Десятковий знак – крапка (“.”) |
| debt | Борг. Якщо у рахунку є переплата, це поле містить знак мінуса |
| sum | Сума до сплати, зазвичай дорівнює amount + debt |
| period | Період, за який виставлений рахунок (у форматі біллера) |
| status | Статус рахунку. Можливі значення: "created", "payed", "canceled", "return" |
| paidAmount | Сума, що реально сплачена (вона може відрізнятись від тієї, що запропонована у рахунку) |
| payDate | Дата оплати рахунку. Формат: DD.MM.YYYY hh24:mi:ss |
| payee_export_flag | Ознака того, чи передана інформація про сплату до компанії-біллера. Можливі значення: "Y" – інформація успішно передана; "N" – спроб передачі ще не було; "E" – під час останньої спроби сталася помилка (наприклад, біллер «лежить»); "B" – відправка заблокована (наприклад, на прохання банку); "R" – транзакція реверсована (для тих біллерів, що вміють робити реверс); "" – для тих компаній, за якими передача не здійснюється. |
| auth_сode | Код авторизації – передається при оплаті |
| transaction_id | ID транзакції – передається при оплаті |
| payment_point | Унікальний опис торгової точки партнера – передається нам при оплаті |
Далі опційні теги:
"Універсальні" айтеми (раніше називалися лічильниками):
Поля %_state можуть приймати три значення:
- "N" – колонка не повинна відображатись;
- "V" – колонка та її вміст відображається клієнту без можливості редагування;
- "E" – колонка та її вміст відображається клієнту з можливістю редагування.
Атрибут tariff_state - це поле може приймати значення W_%. Цей тип означає, що тариф може залежати від обсягів, тощо і необхідності розрахунку може приймати значення.
Приклади:
- "W" – необхідність розрахувати послугу за електропостачання
- "W_GAZ" – необхідність розрахувати послугу з газу
- "W_Y" – необхідність розрахувати послуги за світло
у цьому випадку, колонка не повинна відображатися і для розрахунку вартості оплати можна використовувати помічники.
| Параметр | Опис |
|---|---|
| tariff_items | Лічильнкики, що редагуються та не редагуються |
| item id | ID послуги |
| name | Назва послуги (рос.) (всі версії протоколу) |
| name_ua | Назва послуги (укр.) (версія протоколу – 1) |
| name_eng | Назва послуги (англ.) (версія протоколу - 1) |
| code | Код послуги |
| sub_code | Підкод послуги |
| tariff | Значення тарифу в грн. |
| tariff_state | Тип колонки (версія протоколу – 2 і більше) |
| tariff_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| counter | Поточне значення лічильника |
| counter_state | Тип колонки (версія протоколу – 2 і більше) |
| counter_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| prev_counter | Попереднє значення лічильника |
| prev_counter_state | Тип колонки (версія протоколу – 2 і більше) |
| prev_counter_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| subsidy | Субсидія у грн. |
| subsidy_state | Тип колонки (версія протоколу – 2 і більше) |
| subsidy_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| debt | Борг у грн. |
| debt_state | Тип колонки (версія протоколу – 2 і більше) |
| debt_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| amount | Сума за лічильником у грн. |
| negative_amount | Ознака того, чи може в тезі <amount /> бути отримане негативне значення. Можливі значення: "N", "Y" (версія протоколу – 2 і більше) |
| amount_state | Тип колонки (версія протоколу – 2 і більше) |
| amount_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| counter_accuracy | Розрядність лічильника: "0" – значення лічильника округлюються до цілого числа "1" – до 1-го знаку після коми "2" – до 2-го знаку "3" – до 3-го знаку "4" – до 4-го знаку |
| pay_different_amount | Ознака того, чи можливо сплатити суму, що відрізняється від отриманої. Має значення тільки для протоколу версії 1.0 (у пізніших версіях для прийняття рішення, чи можливо змінювати отримані дані, необхідно приймати до уваги значення тегів з суфіксом " _state", наприклад, <amount_state> для суми за лічильником). Можливі значення:"N" – сума лічильника вже врахована у сумі рахунку (лічильник не треба передавати при оплаті) "Y" – сума лічильника розраховується та додається до суми рахунку (лічильник передається при оплаті) |
| attribute1 | Опційний тег (залежить від біллера) |
| attribute1_state | Тип колонки (версія протоколу – 2 і більше) |
| attribute1_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| attribute2 | Опційний тег (залежить від біллера) |
| attribute2_state | Тип колонки (версія протоколу – 2 і більше) |
| attribute2_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| attribute3 | Опційний тег (залежить від біллера) |
| attribute3_state | Тип колонки (версія протоколу – 2 і більше) |
| attribute3_name | Заголовок колонки (укр.) (версія протоколу – 2 і більше) |
| attribute4-10 | Опційні теги (залежать від біллера) |
| description | Опис лічильника |
| calculated | Ознака того, чи необхідно розраховувати amount айтему за формулою, або можна просто передати в amount довільне значення:"Y" – використовується формула: ( counter - prev_counter) * tariff – subsidy;"N" – довільне значення (версія протоколу – 2 і більше) |