Skip to main content

Інтеграція сервісу оплати рахунків PortmoneDirect до банківських систем обслуговування клієнтів. Технічний опис

Терміни та визначення

ТермінВизначення
Мерчант, ПартнерОрганізація, що уклала договір з Portmone.com про надання послуг з приймання платежів
Покупець, КлієнтВідвідувач Інтернет-магазину Мерчанта з метою ознайомлення з асортиментом товарів (послуг) та здійснення покупки
Картка, Платіжна карткаПлатіжні картки міжнародних платіжних систем Visa, Mastercard та Національної платіжної системи ПРОСТІР
АвторизаціяПроцес надання прав доступу або інших повноважень Покупцеві, програмі або процесу
CVV2/CVC2CVV2 (Card Verification Value 2) – тризначний код перевірки дійсності картки платіжної системи Visa. Платіжна система Mastercard має аналогічний код перевірки дійсності – CVC2 (Card Validation Code 2)
Банк-еквайрБанк, що організовує точки приймання банківських карток (термінали, банкомати) та здійснює весь комплекс фінансових операцій, пов'язаних з виконанням розрахунків і платежів за банківськими картками в цих точках
Банк-емітент банківських картокБанк, що є учасником платіжної системи та здійснює випуск (емісію) та обслуговування банківських карток
IBANМіжнародний номер банківського рахунку (англ. International Bank Account Number)

1. Загальна інформація

Використовується технологія REST. Запити та відповіді передаються HTTPS-каналом (зверніть увагу – на даний момент сервером підтримується тільки протокол TLS 1.2).

Запити від хоста агента на сервер Portmone.com передаються у вигляді повідомлень типу POST.

Звернiть увагу, що всi параметри передаються в тiлi POST запиту, нi в якому разi не в тiлi URL. У прикладах запитів на початку рядка вказано знак ? - це не є вказівкою до використання повідомлень типу GET.

URL для виклику методів: https://direct.portmone.com.ua/api/directcash/.

З кожним запитом передаються два обов’язкових параметри – login та password (логін та пароль компанії-реселера). Логін, пароль та HTTPS-сертифікат мають бути надані менеджером Portmone.

Формат відповідей - XML. Для передачі даних використовується кодування UTF-8.

Формат дати - DD.MM.YYYY.

Приклад рядка запиту на доставку рахунку:

method=bills.create&login=логін&password=пароль&version=2&payeeId=значення&contractNumber=значення

Приклад успішної відповіді:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
[тут xml-дані]
</rsp>

Приклад відповіді, якщо сталася помилка:

Для версії 1:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
</rsp>

Для версії 2 і більше:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
<error code="Код помилки">Опис помилки</error>
<error_description>Докладний опис помилки (версія протоколу – 2) </error_description>
</rsp>

Протокол

Без задання, версія протоколу дорівнює «1».

Якщо у запиті переданий параметр version=2, стають доступними зміни, введені для версії протоколу «2».

Локалізація

У версії протоколу «2» доданий необов’язковий параметр lang (можливі значення: ru – російська мова, uk – українська мова, en – англійська мова). Параметр локалізує атрибутивні значення та назви послуг у відповіді (але не назву компанії). Якщо параметр не переданий, результат повертається українською мовою.

У разі використання у запиті версії протоколу «2» (version=2) та значень параметру lang, у відповіді в блоці <tariff_items> будуть передані значення тегів <name/> та <*_name/>, локалізовані потрібною мовою.

Для версії протоколу «2» у відповіді в блоці <tariff_items> відсутні теги <name_ua/> та <name_en/> (у зв’язку з введенням параметру lang).

Приклад використання параметру lang.

Запит:

method=bills.create&payeeId=1755&login=PortmoneDirectTest&password=**************
&version=2&contractNumber=639512625&lang=uk

Відповідь:

<rsp status="ok">
<bill id="598984149">
<payee id="1755">lifecell</payee>
<contractNumber title="Номер телефона (без +380)">639512625</contractNumber>
<attribute1/>
<attribute2/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>21.01.2020</date>
<description>Рахунок створений автоматично для поповнення балансу</description>
<amount>0.00</amount>
<debt>0.00</debt>
<sum>0.00</sum>
<status>created</status>
<paidAmount/>
<payDate/>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point/>
</bill>
</rsp>

У відповіді параметр <contractNumber title> локалізований російською мовою.

Опис структури XML

Опис структури відповіді у XML-форматі наведений у Додатку 1.

2. Методи

Назва методуОпис
2.1. bills.createрезультатом виклику методу bills.create є створення на боці Portmone.com підписки на отримання рахунків для необхідної компанії та повернення ID рахунку (billId)
2.2. bills.createByPhoneрезультатом виклику цього методу є створення на боці Portmone.com рахунку на поповнення мобільного телефону та повернення ID компанії-одержувача платежу (payeeId) і ID рахунку (billId)
2.3. bills.createAllцей метод використовується для отримання рахунків компаній, що виставляють кілька рахунків за поточний місяць
2.4. bills.payза допомогою цього методу виконується оплата рахунку
2.5. bills.getметод використовується, якщо необхідно отримати інформацію про рахунок (дізнатися статус рахунку). Потрібно викликати, якщо на метод оплати bills.pay отримана помилка зєднання, отримана відповідь не очікуваного формату, який не відповідає протоколу. А також якщо отримані помилки p009, p017, p100.
2.6. bills.paymentOrderреєстр передається банком до Portmone.com для контролю платежів, що надсилаються, та формування необхідних контрольних реєстрів до кожної організації за необхідним протоколом. Містить список виконаних транзакцій та реквізити платежу покриття.
2.7. bills.dateметод використовується для отримання контрольного списку транзакцій за період (день). Необхідний для контролю транзакцій, що відбулись/ не відбулись
2.8. bills.exportedметод використовується для отримання контрольного списку транзакцій за період (день), кошти за яким були надіслані постачальнику послуги (біллеру)
2.9. bills.balanceметод використовується для перегляду балансу по компанії-біллеру (PAYEE) на поточний момент
2.10. bills.payeesметод використовуєьтся для отримання параметрів біллерів (PAYEE)
2.11. bills.regionsметод використовується для отримання списку доступних регіонів та списку біллерів (PAYEE) для кожного регіону
2.12. bills.additionalPayeesметод використовується для отримання списку компаній, рахунки яких може сплачувати клієнт
2.13. search.regionsметод використовується для отримання повного списку регіонів України
2.14. search.regionsExtendedметод використовується для отримання списку регіонів України з пошуком за назвою регіону
2.15. search.citiesByRegionметод використовується для отримання списку населених пунктів для вказаного регіону
2.16. search.citiesByRegionExtendedметод використовується для отримання списку населених пунктів вказаного регіону за назвою населеного пункту
2.17. search.streetsByCityметод використовується для отримання списку вулиць вказаного населеного пункту
2.18. search.streetsByCityExtendedметод використовується для отримання списку вулиць вказаного населеного пункту з пошуком за назвою вулиці
2.19. search.housesByStreetметод використовується для отримання списку будинків для вказаної вулиці
2.20. search.housesByStreetExtendedметод використовується для отримання списку будинків для вказаної вулиці з пошуком за номером будинку
2.21. search.apartmentsByHouseметод використовується для отримання списку квартир за відомим ідентифікатором будинку (тільки для багатоквартирних будинків)
2.22. search.apartmentsByHouseExtendedметод використовується для отримання списку квартир за відомим ідентифікатором будинку (тільки для багатоквартирних будинків) з пошуком за номером квартири
2.23. search.userDocsByAddress*метод використовується для отримання списку рахунків за знайденим ідентифікатором будинку (для приватних будинків) або квартири (для багатоквартирних будинків). Повертає рахунки з повною відповідністю за адресою
2.24. companies.top10ByRegion*метод використовується для отримання списку ТОП 10 компаній за ідентификатором регіону (часткова відповідність)
2.25. companies.top10ByCity*метод використовується для отримання списку ТОП 10 компаній за ідентифікатором міста (часткова відповідність)
2.26. companies.top10ByStreet*метод використовується для отримання списку ТОП 10 компаній за ідентификатором вулиці (часткова відповідність)
2.27. companies.top10ByHouse*метод використовується для отримання списку ТОП 10 компаній за відомим ідентифікатором будинку (повна відповідність для будинку або часткова для квартири)
2.28. companies.top10ByAddress*метод використовується для отримання списку компаній за відомим ідентифікатором будинку (для приватних будинків) або квартири (для багатоквартирних будинків). Повертає рахунки з повною та частковою відповідністю за адресою
2.29. bills.getreferenceметод використовується для отримання списку значень вказаного довідника з використанням пов'язаного значення з довідника верхнього рівня
2.30. bills.updateє частиною методу 2.4. bills.pay, використовується для оновлення рахунку без зміни його статусу
2.31. bank.params.guaranteeAmountметод перевірки суми гарантійного платежу по партнеру згідно індивідуального логіну
2.32. bills.recreateметод для створення копії сплаченого рахунку
2.33. bills.cancelметод для відміни оплат, які знаходяться в статусі PAYED (всі версії протоколу)

* Як використовувати методи пошуку компаній

  • Якщо відомий тільки ідентифікатор регіону (regionId), шукаємо рахунки за регіоном (використовуючи метод companies.top10ByRegion)
  • Якщо відомий ідентифікатор міста (cityId), шукаємо рахунки для зазначеного міста (використовуючи метод companies.top10ByCity)
  • Якщо відомий ідентифікатор вулиці (streetId), шукаємо за вулицею (використовуючи метод companies.top10ByStreet)
  • Якщо відомий ідентифікатор будинку (houseId), шукаємо за будинком (використовуючи метод companies.top10ByHouse)
  • Якщо будинок багатоквартирний (hasApartments=Y), є ідентифікатор квартири (apartment id), використовуємо метод companies.top10ByAddress (якщо немає повної відповідності за адресою, метод шукає рахунки по вищих пунктах (за будинком, вулицею, містом тощо)) або метод search.userDocsByAddress (повертає рахунки тільки з повною відповідністю параметру пошуку).

2.1. Запит на доставку рахунку

Метод: bills.create

Опис: результатом виклику метода bills.create є створення на боці Portmone.com підписки на отримання рахунків для необхідної компанії та повернення ID рахунку (billId). Відповідь містить дані про останній виставлений і не оплачений рахунок за попередній період. Якщо організація не виставляє рахунки (наприклад, мобільні оператори), то метод bills.create забезпечує перевірку наявності цього телефону в БД мобільного оператора.

Перед викликом методу bills.create необхідно звертати увагу на значення тегу <balance_source>, що отримане при виконанні методу bills.payees. Якщо <balance_source>Y</balance_source> для компанії, то здійснюється виклик методу bills.create. У інших випадках здійснюється виклик методу bills.createAll.

Параметри:

ПараметрОписОбов’язковий
loginЛогін компанії-реселера в системі Portmone.comТак
passwordПароль компанії-реселера в системі Portmone.comТак
methodНазва методуТак
payeeIdID компанії-одержувача платежуТак
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.

Схема взаємодії:

  1. Клієнт на сайті Партнера (компанії-реселера) вказує номер мобільного телефону для поповнення.
  2. Партнер передає ці дані до Portmone.com за допомогою методу bills.createByPhone.
  3. Portmone.com за кодом оператора зв’язку визначає ID компанії, до якої належить телефон клієнта, та надсилає Партнерові XML-повідомлення з ID компанії-одержувача платежу (payeeId) та ID рахунку (billId).
  4. Партнер виконунує запит оплати рахунку методом bills.pay.
  5. 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Назва методуТак
payeeIdID компанії-одержувача платежуТак
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

Опис: за допомогою цього методу виконується оплата рахунку.

Параметри:

ПараметрОписОбов’язковий
loginЛогін компанії-реселера в системі Portmone.comТак
passwordПароль компанії-реселера в системі Portmone.comТак
methodНазва методуТак
billIdID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону)Так
amountСума, що сплачується (вона може відрізнятись від запропонованої у рахунку)Так
auth_codeКод авторизаціїНі
transaction_idID транзакціїНі
payment_pointУнікальний опис торгової точки партнераНі
payer_iban
або
payer_card_number
iban відправника, хто ініціює переказ, приймає значення 29 символів
------------------------------------------------------------------------------
Карти, відправника, хто ініціює переказ, приймає значення 16 цифр
Так

Приклад запиту:

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Назва методуТак
billIdID рахунку. Його повертає метод 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):

ПараметрОписОбов’язковий
idID лічильникаТак
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Назва методуТак
billIdID рахунку (його повертає метод 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 idID платежу в 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 idID рахунку (для транзакції устатусі 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Назва методуТак
payeeIdID компаніїТак
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 idID рахунку
с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Назва методуТак
payeeIdID компаніїТак

Приклад запиту:

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 idID компанії, для якої виконується запит балансу
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>

</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>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Назва методуТак
billIdID рахунку (його повертає метод 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&regionId=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&regionId=
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>

Зверніть увагу!

  1. Ідентифікатор будинку (house id) у відповіді може приймати від'ємні значення
  2. Параметр 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>

Зверніть увагу!

  1. Ідентифікатор будинку (house id) у відповіді може приймати від'ємні значення
  2. Параметр 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Унікальний ідентифікатор будинку або квартириТак

Важливо!

  1. Для будинків, в яких є квартири (hasApartments=Y), addressId = apartment id (його повертають методи search.apartmentsByHouse та search.apartmentsByHouseExtended)

  2. Для приватних будинків (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&regionId=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Унікальний ідентифікатор будинку або квартириТак

Важливо!

  1. Для будинків, в яких є квартири (hasApartments=Y), addressId = apartment id (його повертають методи search.apartmentsByHouse та search.apartmentsByHouseExtended)

  2. Для приватних будинків (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>

Успішна відповідь – опис полів:

ПараметрОпис
RWDCистемний параметр, який показує, що рахунок прив'язаний до користувача та до адреси користувача
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Назва методуТак
billIdID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону)Так

Параметри для «універсальних» айтемів (передаються у масиві tariff_items):

ПараметрОписОбов’язковий
idID лічильникаТак
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Назва методуТак
billIdID сплаченого рахункуТак
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Назва методуТак
billIdID сплаченого рахункуТак
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>

3. Поповнення карток (Account-2-Card)

Платіжна система Portmone.com дозволяє здійснювати поповнення карток фізичних осіб з банківського рахунку за номером картки.

3.1. Верифікація картки клієнта

  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>
  1. У випадку успішної аутентифікації партнера клієнт переходить на сторінку перевірки платіжної картки, де необхідно ввести номер платіжної картки, термін її дії та CVV2, натиснути "Верифікувати":

Сторінка перевірки платіжної картки

  1. Наступним кроком клієнту необхідно буде ввести VCODE (код верифікації), що надійде у SMS-повідомленні від банку, що випустив картку:

Сторінка для введення VCODE

  1. У випадку успішного проходження перевірки на 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, виконати наступні кроки для зарахування коштів на картку:

  1. Викликати метод bills.create з наступними параметрами:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.create
payeeIdID компанії-одержувача платежу
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.

  1. Викликати метод bills.pay з використанням наступних параметрів:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.pay
billIdID рахунку (його повертає метод bills.create)
amountСума, що сплачується (сумма, що буде зарахована на картку)
  1. Викликати метод bills.get для отримання інформації про статус зарахування:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.get
billIdID рахунку (його повертає метод bills.create)

Важливо! У відповіді, яку повертає система Portmone.com на запит статусу за методом bills.get, є додаткова інформація про успішність проходження операції переказу коштів у банка-еквайра – атрибут payee_export_flag.

Якщо у рахунку status=’PAYED’, але payee_export_flag = ’E’ – це означає, що оплата за рахунком прийнята, але кошти ще не зараховані клієнту (рахунок у процесі оплати). При цьому необхідно протягом пари годин продовжувати надсилати запит статусу оплати рахунку до системи Portmone.com, доки не буде отриманий один з наступних статусів:

  1. status=’PAYED’ та payee_export_flag=’Y’ – оплата у еквайра успішна і кошти зараховані клієнту, або
  2. status=’CANCELED’ – кошти на картку клієнта не можуть бути зараховані.
  1. Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.

3.3. Поповнення картки клієнта за повним номером картки

Використовуючи протокол роботи PortmoneDirect, виконати наступні кроки для зарахування коштів на картку:

  1. Викликати метод bills.create з наступними параметрами:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.create
payeeIdID компанії-одержувача платежу
contractNumberПовний номер картки отримувача (наприклад, 4444333322221111)
attribute1Має дорівнювати значенню recipient_id, що отримане у відповіді на верифікацію
attribute2Має дорівнювати значенню shop_bill_id, що отримане у відповіді на верифікацію
payer_iban
або
payer_card_number
iban відправника, хто ініціює переказ, приймає значення 29 символів
------------------------------------------------------------------------------
Карти, відправника, хто ініціює переказ, приймає значення 16 цифр

У відповідь буде сформований рахунок на суму 0 грн. з наданням унікального ідентифікатору – billId.

  1. Викликати метод bills.pay з використанням наступних параметрів:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.pay
billIdУнікальний ідентифікатор рахунку, що отриманий на попередньому кроці з методу bills.create
amountСума, що сплачується (сумма, що буде зарахована на картку)
  1. Викликати метод bills.get для отримання інформації про статус зарахування:
ПараметрОпис
loginЛогін компанії-реселера в системі Portmone.com
passwordПароль компанії-реселера в системі Portmone.com
methodНазва методу – bills.get
billIdID рахунку (його повертає метод bills.create)

Важливо! У відповіді, яку повертає система Portmone.com на запит статусу за методом bills.get, є додаткова інформація про успішність проходження операції переказу коштів у банка-еквайра – атрибут payee_export_flag.

Якщо у рахунку status=’PAYED’, але payee_export_flag = ’E’ – це означає, що оплата за рахунком прийнята, але кошти ще не зараховані клієнту (рахунок у процесі оплати). При цьому необхідно протягом пари годин продовжувати надсилати запит статусу оплати рахунку до системи Portmone.com, доки не буде отриманий один з наступних статусів:

  1. status=’PAYED’ та payee_export_flag=’Y’ – оплата у еквайра успішна і кошти зараховані клієнту, або
  2. status=’CANCELED’ – кошти на картку клієнта не можуть бути зараховані.
  1. Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.

4. Коди помилок

Код помилкиПовідомлення про помилкуОписМетод
o001Помилка при створенні рахункуПомилка при створенні рахунку (внутрішній код помилки)bills.create
o003Помилка під час оплати рахункуПомилка під час оплати рахункуbills.pay
o003Помилка під час відміни рахункуПомилка під час скасування рахунку. (Рахунок не знайдено)bills.cancel
o004Помилка при виведенні контрольного реєструПомилка при виведенні контрольного реєструbills.paymentOrder
o006Помилка при виведенні балансу по компаніїПомилка при виведенні балансу по компаніїbills.balance
o010Немає отримувачів платежу для логінуПомилка при пошуку компаніїbills.additionalPayees
р013Невірні параметри ідентифікації клієнтаПомилка під час оплати рахункуbills.pay
p001Invalid method nameНевірне ім'я методуУсі методи
p002Invalid login/passwordНевірний логін або парольУсі методи
p003Помилка при створенні підпискиПомилка при створенні підписки (внутрішній код помилки)bills.create
p004Помилка при оновленні параметрів лічильникаПомилка при оновленні параметрів лічильникаbills.pay
p005Підписка має статус "ERROR"Компанія-біллер повернула повідомлення про помилку за цією підпискою, або при спробі повторно створити підписку з невірними реквізитамиbills.create
p006Немає такої компаніїУ БД Portmone.com немає компанії-біллера з таким IDbills.create
p007Підписка створена. Чекаємо на відповідь компанії.Підписка створена (“CREATED”), але поки немає підтвердження від компанії-біллера про правильність введеної інформації (якщо компанія-біллер відповість, що передана інформація некоректна, статус підписки буде змінений на “ERROR”).bills.create
p008У вас немає несплачених рахунків. Очікуйте на виставлення рахунків від вашого постачальника послуг.Підписка створена, але рахунків поки що немає (як у випадку з ГІОЦем, наприклад)bills.create
p009Немає такого рахункуУ БД Portmone.com немає рахунку з таким ID (внутрішній код помилки)bills.get
p010No bills for dateНемає рахунків за отриману дату (внутрішній код помилки)bills.date, bills.exported
p011Отримано порожній або пошкоджений реєстрОтримано порожній або пошкоджений реєстрbills.paymentOrder
p012Empty POSTОтриманий масив POST порожнійУсі методи
p014Перевищена квота по компаніїПеревищена квота по компанії (внутрішній код помилки)bills.pay
p015Помилка при перевірці валідності підпискиВидається, якщо реквізити раніше створеної підписки більш не дійсні (наприклад, номер телефону деактивовано біллером) (внутрішній код помилки)bills.create
p015Invalid date formatНевірний формат дати (внутрішній код помилки)bills.date, bills.exported
p017Помилка при запиті інформації за рахункомНеможливо отримати інформацію про рахунок (наприклад, рахунок у цей момент заблокований сесією оплати) (внутрішній код помилки)bills.get
p018Для отримання рахунків для цієї компанії необхідно використовувати метод bills.createAllbills.create
p019Загальна помилка для усіх методів search.*search.*
p022Довідник не знайденийbills.getreference
p032Помилка пошуку даних. Можливо ви намагаєтесь знайти квартири за приватним будинкомПомилка пошуку даних. Дані (квартири) не знайденоsearch.apartmentsByHouse, search.apartmentsByHouseExtended
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&regionId=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 = 23782reference 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>