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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для версії 1:

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

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

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

Протокол

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

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

Локалізація

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

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

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

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

Запит:

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

Відповідь:

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

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

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

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

Нотифікації завантаження рахунків по компаніях

Нотифікацій партнеру направляються після завантаження рахунку по кожній компанії. Партнер має надати URL, на який зможуть приймати POST запит для свого опрацювання.

Приклади запитів:

<?xml version="1.0" encoding="UTF-8"?><req name="billsLoaded"><payee id="16020"/></req>

<?xml version="1.0" encoding="UTF-8"?><req name="billsLoaded"><payee id="140264"/><payee id="140235"/></req>

2. Методи

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

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

Якщо відомий тільки ідентифікатор регіону (regionId), шукаємо рахунки за регіоном (використовуючи метод companies.top10ByRegion)

Якщо відомий ідентифікатор міста (cityId), шукаємо рахунки для зазначеного міста (використовуючи метод companies.top10ByCity)

Якщо відомий ідентифікатор вулиці (streetId), шукаємо за вулицею (використовуючи метод companies.top10ByStreet)

Якщо відомий ідентифікатор будинку (houseId), шукаємо за будинком (використовуючи метод companies.top10ByHouse)

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

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

Метод: bills.create

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

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

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
payeeId	ID компанії-одержувача платежу	Так
contractNumber	Основний реквізит (ідентифікатор) клієнта в цій компанії	Так
billNumber	Номер замовлення	Ні
attribute1-4	Додаткові реквізити	Ні

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

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

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

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

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

2.2. Запит на доставку рахунку за номером телефону

Метод: bills.createByPhone

Опис: результатом виклику цього методу є створення на боці Portmone.com рахунку на поповнення мобільного телефону та повернення ID компанії-одержувача платежу (payeeId) і ID рахунку (billId).

Для оплати рахунку необхідно викликати метод bills.pay.

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

Клієнт на сайті Партнера (компанії-реселера) вказує номер мобільного телефону для поповнення.
Партнер передає ці дані до Portmone.com за допомогою методу bills.createByPhone.
Portmone.com за кодом оператора зв’язку визначає ID компанії, до якої належить телефон клієнта, та надсилає Партнерові XML-повідомлення з ID компанії-одержувача платежу (payeeId) та ID рахунку (billId).
Партнер виконунує запит оплати рахунку методом bills.pay.
Portmone.com здійснює переказ коштів постачальнику послуги.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
contractNumber	Номер телефону, на який здійснюється поповнення. Формат номеру: 9 цифр, без "+380" (наприклад, 673334411)	Так
billAmount	Сума платежу (дорівнюватиме 0, якщо інше не було задане)	Ні
billNumber	Номер замовлення (рахунку) у системі компанії-реселера	Ні
attribute1-4	Додаткові реквізити	Ні

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

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

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

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

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

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

2.3. Запит на доставку всіх рахунків, виставлених за поточний місяць

Метод: bills.createAll

Опис: цей метод використовується для отримання рахунків компаній, що виставляють кілька рахунків за поточний місяць. За набором параметрів цей метод повністю ідентичний методу bills.create.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
payeeId	ID компанії-одержувача платежу	Так
contractNumber	Основний реквізит (ідентифікатор) клієнта в цій компанії	Так
billNumber	Номер замовлення	Ні
attribute1-4	Додаткові реквізити	Ні

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

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

Приклад успішної відповіді: у разі успіху повертається секція bills, що містить для кожного з рахунків XML, описаний у Додатку 1.

<?xml version="1.0" encoding="utf-8"?>
	<rsp status="ok">
		<bills>
			<bill id="id">
			…
			</bill>
			<bill id="id">
			…
			</bill>
			<bill id="id">
			…
			</bill>
		</bills>
	</rsp>

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

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

Основна компанія та компанії-одержувачі:

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

Основна компанія – це компанія, яку ви відображаєте клієнтові при сплаті за послугу/товар та вказуєте у запитах на отримання рахунків. Такі компанії створюються, наприклад, з метою групування послуг, що надаються (приклад: ГІОЦ (payeeId = 8004), ГЕРЦ (payeeId = 4568)).

Компанія-одержувач – це активна компанія, що надає послугу або товар, але клієнтові вона не відображається.

При запиті на payeeId основної компанії метод bills.createAll у відповідь поверне Вам рахунки з payeeId компаній-одержувачів, по яким і буде проходити оплата.

2.4. Оплата рахунку

Метод: bills.pay

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

У випадку якщо по послузі debt_state <> 'E' то відповідний debt не повинен враховуватися в загальну суму оплати по рахунку

Параметри:

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

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

method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&payer_iban=значення

або

method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&payer_card_number=значення

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <bill id="1046347926">
        <payee id="6968">Воля ТБ та/або Інтернет</payee>
        <contractNumber title="Номер договору">901386637</contractNumber>
        <attribute1 title="Адреса">Київ, Архипенка Олександра, б.4А, кв.185</attribute1>
        <attribute2 />
        <attribute3 />
        <attribute4 />
        <bill_attribute1 />
        <bill_attribute2 />
        <bill_attribute3 />
        <bill_attribute4 />
        <date>11.01.2022</date>
        <description>Рахунок створений автоматично для поповнення балансу</description>
        <amount>0.00</amount>
        <debt>0.00</debt>
        <sum>0.00</sum>
        <status>paid</status>
<paidAmount>31000.00</paidAmount>
        <payDate>12.01.2022 08:49:29</payDate>
        <payee_export_flag>N</payee_export_flag>
        <auth_code />        
        <transaction_id />
        <payment_point>PORTMONEDIRECTTEST</payment_point>
       <bill_attribute10>UA77*********************6900</bill_attribute10>
    </bill>
</rsp>

У випадку і відсутнього payer_iban і payer_card_number система повертатиме помилку

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

<rsp status="fail">
  <error code="р013">Неправильні параметри ідентифікації клієнта.</error>
  <error_description>Неправильні параметри ідентифікації клієнта.</error_description>
</rsp>

Параметри для платежів більше 30000 грн (безготівкові оплати), 4999 грн (готівкові оплати):

Опис: за законодавством України: для оплати понад 30000 грн (крім категорій комунальних послуг та податків) для безготівкових оплат та всих категорій сервісів понад 4999 грн для готівкових оплат - необхідно передавати та зберігати ПІБ клієнта та ІПН з прив'язкою до транзакції (або ПІБ та дату народження, якщо ІПН у клієнта відсутня за релігійними переконаннями).

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону)	Так
amount	Сума, що сплачується (вона може відрізнятись від запропонованої у рахунку)	Так
first_name	Ім'я клієнта	Так
last_name	Прізвище клієнта	Так
middle_name	По батькові клієнта	Так
taxId	ІПН клієнта	Так
birth_date	Дата народження клієнта	Так, якщо ІПН у клієнта відсутня за релігійними переконаннями

Приклад запиту для платежів більше 30000 грн:

curl --location --request POST 'http://127.0.0.1/api/directcash' \
--form 'version="2"' \
--form 'lang="uk"' \
--form 'login="PortmoneDirectTest"' \
--form 'password="PortmoneDirect"' \
--form 'method="bills.pay"' \
--form 'billId="1046347926"' \
--form 'amount="31000"' \
--form 'first_name="Антон"' \
--form 'last_name="Волоха"' \
--form 'middle_name="Олександрович"' \
--form 'taxId="9999"' \
--form 'birth_date="03.08.1998"'
--form 'payer_iban="UA773510050000026003590876900"'

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <bill id="1078035627">
        <payee id="6968">Воля ТБ та/або Інтернет</payee>
        <contractNumber title="Номер договору">901386637</contractNumber>
        <attribute1 title="Адреса">Київ, Архипенка Олександра, б.4А, кв.185</attribute1>
        <attribute2 />
        <attribute3 />
        <attribute4 />
        <bill_attribute1 />
        <bill_attribute2 />
        <bill_attribute3 />
        <bill_attribute4 />
        <date>11.01.2022</date>
        <description>Рахунок створений автоматично для поповнення балансу</description>
        <amount>0.00</amount>
        <debt>0.00</debt>
        <sum>0.00</sum>
        <status>paid</status>
        <paidAmount>31000.00</paidAmount>
        <payDate>12.01.2022 08:49:29</payDate>
        <payee_export_flag>N</payee_export_flag>
        <auth_code />        
        <transaction_id />
        <payment_point>PORTMONEDIRECTTEST</payment_point>
       <bill_attribute10>UA77*********************6900</bill_attribute10>

    </bill>
</rsp>

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="o003">
        <![CDATA[Ошибка при оплате счета.]]>
    </error>
    <error_description>
        <![CDATA[bills.pay 02 - Счета нет или счет уже оплачен.]]>
    </error_description>
</rsp>

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

Параметр	Опис	Обов’язковий
id	ID лічильника	Так
amount	Розрахована сума за лічильником	Так
prev_counter	Попереднє значення лічильника	Ні
counter	Поточне значення лічильника	Ні
tariff	Тариф	Ні
subsidy	Субсидія	Ні
debt	Сплачений борг	Ні
attribute1	Атрибут 1 (версія протоколу – 2)	Ні
attribute2	Атрибут 2 (версія протоколу – 2)	Ні
attribute3	Атрибут 3 (версія протоколу – 2)	Ні

Параметри prev_counter, counter, tariff, subsidy, debt, attribute1, attribute2, attribute3 передаються, якщо в отриманому рахунку відповідні теги не порожні.

Якщо параметр переданий, він обов’язково повинен мати значення («порожні» параметри не допускаються).

Сума, що сплачується цілком за рахунком, повинна дорівнювати сумі переданих значень amount та debt за всіма айтемами.

Приклад рядка запиту для компаній без айтемів:

method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення

Той же запит з даними по айтемах:

method=bills.pay&login=логін&password=пароль&version=2&billId=значення&amount=значення&
tariff_items[111111][id]=значення&tariff_items[111111][counter]=значення&
tariff_items[111111][prev_counter]=значення&tariff_items[111111][tariff]=значення&
tariff_items[111111][subsidy]=значення&tariff_items[111111][debt]=значення

де tariff_items — назва масиву з даними по айтемах; 111111 — ID айтему; counter, prev_counter, tariff, subsidy, debt та amount — дані по айтему.

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

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

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

2.5. Інформація про рахунок

Метод: bills.get

Опис: метод використовується, якщо необхідно отримати інформацію про рахунок (дізнатися статус рахунку). Потрібно викликати, якщо на метод оплати bills.pay отримана помилка зєднання, отримана відповідь не очікуваного формату, який не відповідає протоколу. А також якщо отримані помилки p009, p017, p100. Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID рахунку (його повертає метод bills.create)	Так

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

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

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

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

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

2.6. Реєстр надісланих платежів

Метод: bills.paymentOrder

Опис: реєстр передається банком до Portmone.com для контролю платежів, що надсилаються, та формування необхідних контрольних реєстрів до кожної організації за необхідним протоколом. Містить список виконаних транзакцій та реквізити платежу покриття.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
xml	Реєстр у XML-форматі	Так

Приклад реєстру у XML-форматі:

<?xml version="1.0" encoding="utf-8"?>
<payment_order order_date="DD.MM.YYYY" order_number="Номер платіжного доручення"
payee_id="ID компанії-отримувача" total_amount="Сума отриманих платежів"
total_compensation="Сума компенсацій платіжного доручення"
total_commission="Сума комісій платіжного доручення" trx_count="2">
	<transactions>
		<trx>
			<bill_id>ID рахунку</bill_id>
			<trx_amount>Сума транзакції</trx_amount>
			<compensation>Сума,що перерахована біллеру</compensation>
		</trx>
		<trx>
			<bill_id>ID рахунку</bill_id>
			<trx_amount>Сума транзакції</trx_amount>
			<compensation>Сума,що перерахована біллеру</compensation>
		</trx>
	</transactions>
</payment_order>

Де total_commission – сума комісій за всіма транзакціями цього платіжного доручення, total_compensation – сума компенсацій за всіма транзакціями цього платіжного доручення. Для кожної транзакції (<trx>) commission = trx_amount - compensation.

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<paymentOrder>
		<record id="значення"/>
	</paymentOrder>
</rsp>

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

Параметр	Опис
record id	ID платежу в Portmone.com, яким зафіксоване це повідомлення

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

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

Зверніть увагу – якщо реєстр за дату з будь-якої причини не був переданий (розрив зв'язку через таймаут, повідомлення про помилку, отримане від системи PortmoneDirect і т. д.), цей реєстр має бути переданий у наступний сеанс зв'язку разом з реєстром за поточну дату.

2.7. Контрольний реєстр транзакцій

Метод: bills.date

Опис: метод використовується для отримання контрольного списку транзакцій за період (день). Необхідний для контролю транзакцій, що відбулись/ не відбулись.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
date	Дата, для якої виводиться реєстр. Формат: DD.MM.YYYY	Так

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

method=bills.date&login=логін&password=пароль&date=DD.MM.YYYY

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<bills>
		<bill id="значення">
			<name>Коротка назва компанії-отримувача</name>
			<contractNumber title="значення">значення</contractNumber>
			<attribute1 title="значення">значення</attribute1>
			<attribute2 title="значення">значення</attribute2>
			<attribute3 title="значення">значення</attribute3>
			<attribute4 title="значення">значення</attribute4>
			<bill_attribute1>значення</bill_attribute1>
			<bill_attribute2>значення</bill_attribute2>
			<bill_attribute3>значення</bill_attribute3>
			<bill_attribute4>значення</bill_attribute4>
			<status>значення</status>
			<transaction_id>значення</transaction_id>
			<paidAmount>значення</paidAmount>
			<payDate>DD.MM.YYYY HH:mm:ss</payDate>
			<payee_export_date>DD.MM.YYYY HH:mm:ss</payee_export_date>
			<payee_export_flag>значення</payee_export_flag>
			<bank_commission>значення</bank_commission>
			<payee_id>значення</payee_id>
		</bill>
	</bills>
</rsp>

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

Параметр	Опис
bill id	ID рахунку (для транзакції устатусі RETURN, bill id набуває нового унікального значення
сontractNumber title	Номер договору
status	Статус транзакції на боці Portmone.com. Можливі значення: PAYED, RETURN
transaction_id	Ідентифікатор, наданий транзакції банком-партнером (передається під час виклику методу bills.pay). Для транзакцій у статусі RETURN буде набувати значення ID оригінальної транзакції (списання)
paidAmount	Сплачена сума
payDate	Дата оплати
payee_export_date	Дата спроби передачі коштів постачальнику послуги
payee_export_flag	Статус передачі (можливі значення: Y, N, R, E)
bank_commission	Винагорода банку, у грн (версія протоколу – 2). Параметр може приймати як додатні, так і від'ємні значення
name	Назва компанії-отримувача
payee_id	унікальний ідентифікатор компанії (версія протоколу – 3)

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

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

Приклад відповіді по транзакції в статус RETURN:

<bill id="1367371577"> - унікальне bill id при поверненні

<name>lifecell</name>

<contractNumber title="Номер телефону (без +380)">667678994</contractNumber>

<attribute1/>

<bill_attribute1/>

<attribute2/>

<bill_attribute2/>

<attribute3/>

<bill_attribute3/>

<attribute4/>

<bill_attribute4/>

<status>RETURN</status> - статус повернення

<paidAmount>-5.00</paidAmount> - сума повернення, від'ємне значення

<payDate>28.03.2023 16:04:01</payDate> - дата оплати 

<transaction_id>1367371282</transaction_id> - bill ID оригінальнох операції, по котрій виконано повернення

<payee_export_date>28.03.2023 16:04:01</payee_export_date> - дата та час повернення

<payee_export_flag/>

<bank_commission>-0.50</bank_commission>

2.8. Контрольний реєстр коштів, переданих постачальнику послуги

Метод: bills.exported

Опис: метод використовується для отримання контрольного списку транзакцій за період (день), кошти за яким були надіслані постачальнику послуги (біллеру). Необхідний для контролю прив'язування коштів.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
payeeId	ID компанії	Так
date	Дата, для якої виводиться реєстр. Формат: DD.MM.YYYY	Так

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

method=bills.exported&login=логін&password=пароль&version=2&payeeId=значення&date=DD.MM.YYYY

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<bills>
		<bill id="значення">
			<contractNumber title="значення">значення</contractNumber>
			<attribute1 title="значення">значення</attribute1>
			<attribute2 title="значення">значення</attribute2>
			<attribute3 title="значення">значення</attribute3>
			<attribute4 title="значення">значення</attribute4>
			<bill_attribute1>значення</bill_attribute1>
			<bill_attribute2>значення</bill_attribute2>
			<bill_attribute3>значення</bill_attribute3>
			<bill_attribute4>значення</bill_attribute4>
			<status>значення</status>
			<transaction_id>значення</transaction_id>
			<paidAmount>значення</paidAmount>
			<payDate>DD.MM.YYYY HH:mm:ss</payDate>
			<payee_export_date>DD.MM.YYYY HH:mm:ss</payee_export_date>
			<payee_export_flag>значення</payee_export_flag>
		</bill>
	</bills>
</rsp>

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

Параметр	Опис
bill id	ID рахунку
сontractNumber title	Номер договору
status	Статус транзакції на боці Portmone.com. Можливі значення: PAYED, RETURN
transaction_id	Ідентифікатор, наданий транзакції банком-партнером (передаєтсья під час виклику метода bills.pay). Для транзакцій у статусі RETURN буде набувати значення ID оригінальної транзакції (списання)
paidAmount	Сплачена сума
payDate	Дата оплати
payee_export_date	Дата спроби передачі коштів постачальнику послуги
payee_export_flag	Статус передачі (можливі значення: Y, N, R, E)

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

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

2.9. Запит даних по балансу компанії-реселера

Метод: bills.balance

Опис: метод використовується для перегляду балансу по компанії-біллеру (PAYEE) на поточний момент.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
payeeId	ID компанії	Так

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
	<payee id="значення">
		<balance>значення</balance>
	</payee>
</rsp>

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

Параметр	Опис
payee id	ID компанії, для якої виконується запит балансу
balance	Баланс у компанії

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

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

2.10. Запит інформації про доступні компанії-біллери

Метод: bills.payees

Опис: метод використовується для отримання параметрів біллерів* (PAYEE). За замовченням відбувається завантаження всіх даних по доступним компаніям на поточний момент. При додаванні необов'язкового параметру LastUpdateDate, лише даних, по яким були будь-які зміни від вказаної дати.

При додаванні одночасно необов'язкового параметру LastUpdateDate та deleted зі значенням on, лише деактивовані компанії, починаючи з дати в параметрі LastUpdateDate.

*з числа тих, для яких на цей логін заведені платіжні термінали.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
LastUpdateDate	Дата, від якої вносились будь-які зміни. Формат: DD.MM.YYYY	Ні
deleted	Деактивовані компанії	Ні

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

method=bills.payees&login=логін&password=пароль&version=2
method=bills.payees&login=логін&password=пароль&version=2&lastUpdateDate=DD.MM.YYYY
method=bills.payees&login=логін&password=пароль&version=2&lastUpdateDate=DD.MM.YYYY&deleted=on

Структура успішної відповіді:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
    <payee id="значення">
        <header_payee>Використовується деякими партнерами</header_payee>
        <merchant>Використовується деякими партнерами</merchant>
        <terminal>Використовується деякими партнерами</terminal>
        <name>Коротка назва компанії-отримувача (для пунктів меню)</name>
        <name_in_check>Юридична назва компанії-отримувача</name_in_check>
        <image_file>Посилання на логотип компанії</image_file>
        <contact_info>Контактна особа</contact_info>
        <zkpo>Код ЄДРПОУ компанії</zkpo>
        <bank_name>Назва банку компанії-отримувача</bank_name>
        <bank_code> МФО банку компанії-отримувача</bank_code>
        <bank_account>Р/р компанії-отримувача або номер рахунку за стандартом IBAN
        </bank_account>
        <contract_number_title>Назва 1-го реквізиту </contract_number_title>
        <contract_number_type>Тип 1-го реквізиту (N - число; C - рядок; P – платіжна
            картка; R, L - ієрархічний довідник) </contract_number_type>
        <related_references>
                <reference id="ID довідника" order_number="Порядковий номер">
                    Назва довідника</reference>
        </related_references>
        <contract_number_size>Розмір 1-го реквізиту</contract_number_size>
        <contract_number_hint>Підказка клієнту для введення першого реквізиту
        </contract_number_hint>
        <contract_number_mask>Маска вводу першого реквізиту</contract_number_mask>
        <attributes>
	        <attribute1>
		        <title>Назва атрибуту</title>
		        <type>Тип атрибуту (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary)</type>
   		        <size>Максимальний розмір</size>
                <related_references>
                        <reference id="ID довідника" order_number="Порядковий номер">
                            Назва довідника</reference>
                </related_references>
	        </attribute1>
	        <attribute2>
		        <title>Назва атрибуту</title>
		        <type>Тип атрибуту (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary)
                </type>
		        <size>Максимальний розмір</size>
                <related_references>
                        <reference id="ID довідника" order_number="Порядковий номер">
                            Назва довідника</reference>
                </related_references>
	        </attribute2>
	        <attribute3>
		        <title>Назва атрибуту</title>
		        <type>Тип атрибуту (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary)</type>
		        <size>Максимальний розмір</size>
                <related_references>
                        <reference id="ID довідника" order_number="Порядковий номер">
                            Назва довідника</reference>
                </related_references>
	        </attribute3>
	        <attribute4>
		        <title>Назва атрибуту</title>
		        <type>Тип атрибуту (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary)</type>
		        <size>Максимальний розмір</size>
                <related_references>
                        <reference id="ID довідника" order_number="Порядковий номер">
                            Назва довідника</reference>
                </related_references>
	        </attribute4>
	    </attributes>
	    <min_pay_amount>Розмір мінімального платежу</min_pay_amount>
	    <pay_round_amount> Чи дозволити сплачувати з копійками (Y- тільки цілі суми,
            N- дозволити з копійками)</pay_round_amount>
	    <pay_different_amount> Чи дозволити оплату на суму, що відрізняється від
            отриманої у рахунку (Y, N)</pay_different_amount>
	    <bill_source> Компанія допускає оплату за рахунками (Y, N) (оплата за
            виставленими рахунками)</bill_source>
	    <balance_source> Компанія допускає оплату з поповнення балансу (Y, N)(оплата
            без виставленого рахунку)</balance_source>
	    <pay_order_description_format> Формат банківського призначення платежу
        </pay_order_description_format>
	    <billing_day>Дата завантаження рахунків (версія протоколу – 2)</billing_day>
	    <max_pay_amount>Максимальна сума оплати (версія протоколу – 2) </max_pay_amount>
	    <bank_tariff>Винагорода банку, яку необхідно конвертувати у відсотки
            (версія протоколу – 2)</bank_tariff>
        <bank_tariff (значення з мінусом)>Винагорода ФК, яку необхідно конвертувати у відсотки 
            (версія протоколу – 2)</bank_tariff>
        <bank_amount>Винагорода Портмоне, у грн (версія протоколу – 2) </bank_amount>
	    <min_bank_amount>Мінімальна сума винагороди Портмоне від кожної транзакції, у грн
            (версія протоколу – 2)</min_bank_amount>
        <min_bank_amount (значення з мінусом)>Не використовується (версія протоколу – 2)</min_bank_amount>
	    <max_bank_amount>На цей час не використовується (версія протоколу – 2)
        </max_bank_amount>
	    <bank_deduction>На цей час не використовується (версія протоколу – 2)
        </bank_deduction>
	    <bank_deduction_amount>Винагорода банку, яка утримується банком перед
            відправкою покриття. Це значення необхідно конвертувати у відсотки
            (версія протоколу – 2)</bank_deduction_amount>
	    <min_bank_deduction_amount>На цей час не використовується (версія протоколу – 2)
        </min_bank_deduction_amount>
	    <max_bank_deduction_amount>На цей час не використовується (версія протоколу – 2)
        </max_bank_deduction_amount>
        <hide>Компанія-одержувач, що не призначена для відображення клієнтам
            (версія протоколу – 2)</hide>
        <payee_groups>
            <payee_group id="1001">типу послуг, що надаються біллером: мобільний зв’язок</payee_group>
            <payee_group id="1003">типу послуг, що надаються біллером: інтернет</payee_group>
            <payee_group id="1006">типу послуг, що надаються біллером: телефонія</payee_group>
        </payee_groups> (версія протоколу – 3)
         <payee_group_name> назва групи, до якої належить сервіс </payee_group_name> (версія протоколу – 2 і більше)
        <service_in_check>назва послуги для квитанції </service_in_check> (версія протоколу – 2 і більше)
		
    </payee>
…
</rsp>

Зверніть увагу!
Параметр <hide>:
<hide>N</hide> - основна (шапочна) компанія, призначена для відображення сервісу для клієнта
<hide>Y</hide> - підшапочний сервіс, скривається при відображенні для клієнта

Параметр <image_file> необхідно аналізувати лише для основних (шапочних) компаній, по яким передається `N``. В image_file зазначається URL джерела, звідки логотип можна завантажити.

Параметр <pay_different_amount> Чи дозволити оплату на суму, що відрізняється від отриманої у рахунку (Y, N) (версія протоколу – 1) </pay_different_amount>
Важливо! при відсутності «універсальних» айтемів (передаються у масиві tariff_items) у відповіді на метод bills.create/bills.createAll (версія протоколу – 2 і більше) </pay_different_amount> аналізується <pay_different_amount>

Довідники

Поля attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type можуть приймати значення R та L.

Це означає, що відповідні поля attribute1, attribute2, attribute3, attribute4, contract_number мають складний тип даних і значення цих полів повинно формуватись на основі ієрархічних довідників.

Тобто, якщо будь-яке з полів attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type приймає значення R або L, необхідно послідовно викликати метод bills.getreference з відповідними параметрами до отримання кінцевого рівня ієрархії та знаходження ідентифікатора/значення рядку довідника.

Після цього, для подальшої обробки та формування коректного призначення платежу та реквізитів, до методу bills.create у відповідному полі (attribute1, attribute2, attribute3, attribute4, contract_number) повинен бути переданий або ідентифікатор рядку довідника нижнього рівня (<item id>) при типі поля R, або значення рядку довідника нижнього рівня (<name>) при типі поля L.

Приклад довідника типу R:

<contract_number_type>R</contract_number_type>
<related_references>
	<reference id="1180" order_number="1">
    		Регіон:
	</reference>
	<reference id="1183" order_number="2">
    		Найменування отримувача:
	</reference>
	<reference id="4308" order_number="3">
    		Населений пункт/район:
	</reference>
</related_references>

де:

<related_references> – описує ієрархію довідників;

<reference id> – унікальний ідентифікатор довідника в системі Portmone.com (тип INT);

<reference order_number="1"> – порядковий номер довідника в ієрархії (у порядку зростання; тип INT);

<reference></reference> – назва поточного рівня довідника для клієнта (тип String).

Для довідника типу L вигляд відповіді буде аналогічним, за винятком значення параметру contract_number_type.

Приклади роботи з довідниками наведені у розділі 5 "Приклади" (Робота з довідниками типу R, Робота з довідниками типу L).

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

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
        ...
        <payee id="23782">
            <header_payee>1185</header_payee>
            <merchant>X</merchant>
            <terminal>X</terminal>
            <name>Єдиний податок з фіз. осіб підприємців</name>
            <name_in_check>Платежі до бюджету</name_in_check>
            <image_file>https://cdn-images.portmone.com.ua/company/128_128/9974.png</image_file>
            <contact_info></contact_info>
            <zkpo>00032129</zkpo>
            <bank_name>АТ «Ощадбанк»</bank_name>
            <bank_code>300465</bank_code>
            <bank_account>29240000087016</bank_account>
            <contract_number_title>Управление казначейства</contract_number_title>
            <contract_number_type>R</contract_number_type>
            <related_references>
                <reference id="1180" order_number="1">Регіон:</reference>
                <reference id="1183" order_number="2">Найменування отримувача:</reference>
                <reference id="4308" order_number="3">Населений пункт/район:</reference>
            </related_references>
            <contract_number_size>4308</contract_number_size>
            <attributes>
                <attribute1>
                    <title>ІПН</title>
                    <type>N</type>
                    <size/>
                </attribute1>
                <attribute2>
                    <title>За період</title>
                    <type>L</type>
                    <size>4311</size>
                    <related_references>
                        <reference id="4310" order_number="1"parent_value="attribute1">Групи дитячіх садочків м. Київ</reference>
                        <reference id="4311" order_number="2"parent_value="attribute2">Вихованці дитячіх садочків м. Київ</reference>
                    </related_references>
                </attribute2>
                <attribute3>
                    <title>Период</title>
                    <type>N</type>
                    <size/>
                </attribute3>
                <attribute4>
                    <title>ФИО</title>
                    <type>C</type>
                    <size/>
                </attribute4>
            </attributes>
            <min_pay_amount>1</min_pay_amount>
            <pay_round_amount>N</pay_round_amount>
            <pay_different_amount>N</pay_different_amount>
            <payee_group_id>1100</payee_group_id>
            <payee_group_name>Податки, платежі до бюджету</payee_group_name>
            <bill_source>N</bill_source>
            <balance_source>Y</balance_source>
            <pay_order_description_format>(_____) Покриття по транзакцiям сплати рахункiв
                через систему Portmone.com згiдно договору ____вiд____ на суму___
                (_____) - код банку)</pay_order_description_format>
        </payee>
        ...
    </rsp>

parent_value опціональний параметр, передається у випадку викорисатання зв'язаних словників материнською компанією. header_payee параметр для зв'язки компаній,передається лише у відповідь метода bills.payees.Означає до якої основної компанії належить поточне payee id. Параметр існує лише для версій протоколу – 2, 3. Для основних компаній - це поле буде порожнє.

Зверніть увагу! У полі bank_code буде переданий номер МФО банку компанії-отримувача – у разі заповнення реквізитів платежу у форматі "розрахунковий рахунок + код МФО", або 0 (нуль) – у разі заповнення номеру рахунку за стандартом IBAN.

У полі bank_account буде передаватись розрахунковий рахунок компанії-отримувача або IBAN (в залежності від того, який з реквізитів був заповнений при здійсненні платежу). Також слід звернути увагу на те, що в цьому полі раніше передавались лише числа, тепер будуть також передаватись літери згідно з форматом IBAN (29 літерно-цифрових символів).

У полі merchant буде передане значення PAYANY у разі роботи з компанією, яка надає послуги, без прямого договру.

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

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

2.11. Запит інформації про компанії-біллери у контексті регіонів

Метод: bills.regions

Опис: метод використовується для отримання списку доступних* регіонів та списку біллерів (PAYEE) для кожного регіону.

*з числа тих, для яких на цей логін заведені платіжні термінали.

Якщо ідентифікатор регіону не встановлений то вважається, що компанія належить до усих регіонів України.

Усі регіони

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так

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

method=bills.regions&login=логін&password=пароль&version=2

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

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
   <regions>
	<region id="значення">
	   <name>Назва регіону (наприклад — м. Київ)</name>
	   <payees>
		<payee id="значення">
		  <name>Назва компанії (наприклад — ВОЛЯ Броадбенд, м. Київ) </name>
		</payee>
		…
	   </payees>
	</region>
	…
   </regions>
</rsp>

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

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

2.12. Запит компаній, що надають рахунки для клієнта, за раніше отриманим рахунком

Метод: bills.additionalPayees

Опис: метод використовується для отримання списку компаній, рахунки яких може сплачувати клієнт. Після отримання клієнтом запитуваного рахунку можна здійснити запит списку компаній (та ідентифікаторів клієнта в цих компаніях), що надають послуги за тією ж адресою. Якщо список, що повертається, не порожній, можна запропонувати клієнту обрати компанії, рахунки яких він бажає сплатити та здійснити запит цих рахунків стандартним методом. Пошук компаній здійснюється за адресою клієнта.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID рахунку (його повертає метод bills.create)	Так

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<payee id="ID компанії, оплату рахунку якої можна запропонувати клієнту">
	   <contract_number> ідентифікатор клієнта в цій компанії </contract_number>
	   <attribute1> додатковий ідентифікатор клієнта в цій компанії	</attribute1>
	   <attribute2> додатковий ідентифікатор клієнта в цій компанії	</attribute2>
	   <attribute3> додатковий ідентифікатор клієнта в цій компанії	</attribute3>
	   <attribute4> додатковий ідентифікатор клієнта в цій компанії	</attribute4>
	</payee>
</rsp>

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

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

2.13. Запит інформації по регіонах

Метод: search.regions

Опис: метод використовується для отримання повного списку регіонів України.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так

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

method=search.regions&login=логін&password=пароль

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <regions>
        <region id="44">
	        <name>м. Київ</name>
	        <orderIndex>1</orderIndex>
        </region>
        <region id="45">
	        <name>Київська область</name>
	        <orderIndex>2</orderIndex>
        </region>
        <region id="34">
            <name>Івано-Франківська область</name>
            <orderIndex>3</orderIndex>
        </region>
        <region id="43">
            <name>Вінницька область</name>
            <orderIndex>4</orderIndex>
        </region>
        <region id="33">
            <name>Волинська область</name>
            <orderIndex>5</orderIndex>
        </region>
        <region id="56">
            <name>Дніпропетровська область</name>
            <orderIndex>6</orderIndex>
        </region>
        <region id="62">
            <name>Донецька область</name>
            <orderIndex>7</orderIndex>
        </region>
        <region id="41">
            <name>Житомирська область</name>
            <orderIndex>8</orderIndex>
        </region>
        <region id="31">
            <name>Закарпатська область</name>
            <orderIndex>9</orderIndex>
        </region>
        <region id="61">
            <name>Запорізька область</name>
            <orderIndex>10</orderIndex>
        </region>
        <region id="52">
            <name>Кіровоградська область</name>
            <orderIndex>11</orderIndex>
        </region>
        <region id="64">
            <name>Луганська область</name>
            <orderIndex>12</orderIndex>
        </region>
        <region id="32">
            <name>Львівська область</name>
            <orderIndex>13</orderIndex>
        </region>
        <region id="51">
            <name>Миколаївська область</name>
            <orderIndex>14</orderIndex>
        </region>
        <region id="48">
            <name>Одеська область</name>
            <orderIndex>15</orderIndex>
        </region>
        <region id="53">
            <name>Полтавська область</name>
            <orderIndex>16</orderIndex>
        </region>
        <region id="36">
            <name>Рівненська область</name>
            <orderIndex>17</orderIndex>
        </region>
        <region id="54">
            <name>Сумська область</name>
            <orderIndex>18</orderIndex>
        </region>
        <region id="35">
            <name>Тернопільська область</name>
            <orderIndex>19</orderIndex>
        </region>
        <region id="57">
            <name>Харківська область</name>
            <orderIndex>20</orderIndex>
        </region>
        <region id="55">
            <name>Херсонська область</name>
            <orderIndex>21</orderIndex>
        </region>
        <region id="38">
            <name>Хмельницька область</name>
            <orderIndex>22</orderIndex>
        </region>
        <region id="47">
            <name>Черкаська область</name>
            <orderIndex>23</orderIndex>
        </region>
        <region id="37">
            <name>Чернівецька область</name>
            <orderIndex>24</orderIndex>
        </region>
        <region id="46">
            <name>Чернігівська область</name>
            <orderIndex>25</orderIndex>
        </region>
    </regions>
</rsp>

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

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

2.14. Запит інформації по регіонах (з пошуком за назвою регіону)

Метод: search.regionsExtended

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

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
searchQuery	Підрядок для пошуку за назвою регіону (вказати частину назви регіону, від 3 символів)	Так

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

method=search.regionsExtended&login=логін&password=пароль&version=2&searchQuery=фільтр

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <regions>
        <region id="44">
            <name>м. Київ</name>
            <orderIndex>1</orderIndex>
        </region>
        <region id="45">
            <name>Київська область</name>
            <orderIndex>2</orderIndex>
        </region>
    </regions>
</rsp>

Приклад відповіді, якщо сталася помилка (якщо searchQuery не задано):

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="p019">
    <![CDATA[ Помилка сервера у процесі обробки запиту ]]>
    </error>
    <error_description>
    <![CDATA[ search.regionsExtended p019 ]]>
    </error_description>
</rsp>

2.15. Запит інформації по містах (населених пунктах) регіону

Метод: search.citiesByRegion

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

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
regionId	Унікальний ідентифікатор регіону, що отриманий з методу search.regions або search.regionsExtended	Так

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

method=search.citiesByRegion&login=логін&password=пароль&version=2&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>

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

Ідентифікатор будинку (house id) у відповіді може приймати від'ємні значення

Параметр hasApartments – ознака наявності квартир у будинку. Може приймати два значення: Y – цей будинок є багатоквартирним й можливий подальший пошук квартири, N – цей будинок є приватним й подальший пошук квартири не дасть результатів

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

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

2.20. Запит інформації по будинках вулиці (з пошуком за номером будинку)

Метод: search.housesByStreetExtended

Опис: метод використовується для отримання списку будинків для вказаної вулиці з пошуком за номером будинку.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
streetId	Унікальний ідентифікатор вулиці, що отриманий з методу search.streetsByCity або search.streetsByCityExtended	Так
searchQuery	Підрядок для пошуку за номером будинку (вказати номер будинку)	Так

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

method=search.housesByStreetExtended&login=логін&password=пароль&version=2&streetId=
IDвулиці&searchQuery=фільтр

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <houses>
	    <house id="182744">
	        <name>121</name>
            <orderIndex>2</orderIndex>
            <streetId>54635</streetId>
            <hasApartments>Y</hasApartments>
        </house>
        <house id="-2687333">
            <name>174</name>
            <orderIndex>3</orderIndex>
            <streetId>54635</streetId>
            <hasApartments>N</hasApartments>
        </house>
        <house id="-2687334">
            <name>189а</name>
            <orderIndex>4</orderIndex>
            <streetId>54635</streetId>
            <hasApartments>N</hasApartments>
        </house>
    </houses>
</rsp>

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

Ідентифікатор будинку (house id) у відповіді може приймати від'ємні значення

Параметр hasApartments – ознака наявності квартир у будинку. Може приймати два значення: Y – цей будинок є багатоквартирним й можливий подальший пошук квартири, N – цей будинок є приватним й подальший пошук квартири не дасть результатів

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

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

2.21. Запит інформації по квартирах будинку (тільки для багатоквартирних будинків)

Метод: search.apartmentsByHouse

Опис: метод використовується для отримання списку квартир за відомим ідентифікатором будинку houseId (тільки для багатоквартирних будинків – hasApartments=Y).

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
houseId	Унікальний ідентифікатор будинку, що отриманий з методу search.housesByStreet або search.housesByStreetExtended	Так

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

method=search.apartmentsByHouse&login=логін&password=пароль&version=2&houseId=IDбудинку

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <apartments>
	    <apartment id="3405561">
	        <name>276</name>
	        <houseId>182744</houseId>
	    </apartment>
	...
    </apartments>
</rsp>

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="p032">
    <![CDATA[Ошибка поиска данных. Возможно Вы пытаетесь найти квартиры по
    частному дому (apartmentsByHouse)]]> </error>
    <error_description> <![CDATA[ search.apartmentsByHouse p032 ]]>
    </error_description>
</rsp>

2.22. Запит інформації по квартирах будинку (з пошуком за номером квартири)

Метод: search.apartmentsByHouseExtended

Опис: метод використовується для отримання списку квартир за відомим ідентифікатором будинку з додатковим фільтруванням за номером квартири (тільки для багатоквартирних будинків – hasApartments=Y).

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
houseId	Унікальний ідентифікатор будинку, що отриманий з методу search.housesByStreet або search.housesByStreetExtended	Так
searchQuery	Підрядок для пошуку за номером квартири (вказати номер квартири)	Так

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

method=search.apartmentsByHouseExtended&login=логін&password=пароль&version=2&houseId=IDбудинку
&searchQuery=фільтр

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <apartments>
	    <apartment id="3405561">
	        <name>276</name>
	        <houseId>182744</houseId>
	    </apartment>
	...
    </apartments>
</rsp>

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

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

2.23. Запит контекстної інформації за адресою (список рахунків)

Метод: search.userDocsByAddress

Опис: метод використовується для отримання списку рахунків за знайденим ідентифікатором будинку (houseId) для приватних будинків або квартири (apartmentId) для багатоквартирних будинків. Повертає рахунки з повною відповідністю за адресою.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
addressId	Унікальний ідентифікатор будинку або квартири	Так

Важливо!

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

Для приватних будинків (hasApartments=N), addressId = house id (його повертають методи search.housesByStreet або search.housesByStreetExtended)

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

method=search.userDocsByAddress&login=логін&password=пароль&version=2&addressId=IDапартаменту

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <docs>
	    <doc>
	        <addressId>3162324</addressId>
	        <payeeId>8004</payeeId>
            <contractNumber>1404</contractNumber>
            <attribute1>144</attribute1>
            <attribute2/>
            <attribute3/>
            <attribute4/>
            <matchType>FULL</matchType>
            <attribute1Title>О/Р</attribute1Title>
            <attribute2Title>Адреса</attribute2Title>
            <attribute3Title/>
            <attribute4Title/>
            <contractNumberType>N</contractNumberType>
            <contractNumberTitle>№ ЖEК-у</contractNumberTitle>
	    </doc>
	...
    </docs>
</rsp>

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

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

2.24. Пошук компаній для зазначеного регіону

Метод: companies.top10ByRegion

Опис: метод використовується для отримання списку ТОП 10 компаній за ідентификатором регіону (часткова відповідність).

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
regionId	Унікальний ідентифікатор регіону, що отриманий з методу search.regions або search.regionsExtended	Так

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

method=companies.top10ByRegion&login=логін&password=пароль&version=2&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	Унікальний ідентифікатор будинку або квартири	Так

Важливо!

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

Для приватних будинків (hasApartments=N), addressId = house id (його повертають методи search.housesByStreet або search.housesByStreetExtended)

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

method=companies.top10ByAddress&login=логін&password=пароль&version=2&addressId=IDквартири

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <companies>
        <company>
            <RWD/>
            <PAYEE_ID>9817</PAYEE_ID>
            <NAME>ХАРКІВГАЗ ЗБУТ (м. Харків)</NAME>
            <CONTRACT_NUMBER>1310480114</CONTRACT_NUMBER>
            <CONTRACT_NUMBER_TITLE>Особовий рахунок</CONTRACT_NUMBER_TITLE>
            <CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
            <CONTRACT_NUMBER_SIZE>10</CONTRACT_NUMBER_SIZE>
            <ATTRIBUTE1> вул.Морозова, буд.24, кв.15, м.Харків, м.Харків, 61105
            </ATTRIBUTE1>
            <ATTRIBUTE1_TITLE>Поштова адреса</ATTRIBUTE1_TITLE>
            <ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
            <ATTRIBUTE1_SIZE/>
            <ATTRIBUTE1_FOR_INFO>Y</ATTRIBUTE1_FOR_INFO>
            <ATTRIBUTE2/>
            <ATTRIBUTE2_TITLE>Старий особовий рахунок</ATTRIBUTE2_TITLE>
            <ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
            <ATTRIBUTE2_SIZE/>
            <ATTRIBUTE2_FOR_INFO>Y</ATTRIBUTE2_FOR_INFO>
            <ATTRIBUTE3/>
            <ATTRIBUTE3_TITLE>Дільниця</ATTRIBUTE3_TITLE>
            <ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
            <ATTRIBUTE3_SIZE/>
            <ATTRIBUTE3_FOR_INFO>Y</ATTRIBUTE3_FOR_INFO>
            <ATTRIBUTE4/>
            <ATTRIBUTE4_TITLE/>
            <ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
            <ATTRIBUTE4_SIZE/>
            <ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
            <IMAGE>9817.png</IMAGE>
            <MATCH_TYPE>FULL</MATCH_TYPE>
            <CONTRACT_NUMBER_TYPE_ARRAY/>
            <ATTRIBUTE1_ARRAY/>
            <ATTRIBUTE2_ARRAY/>
            <ATTRIBUTE3_ARRAY/>
            <ATTRIBUTE4_ARRAY/>
        </company>
        <company>
            <RWD/>
            <PAYEE_ID>6813</PAYEE_ID>
            <NAME>Тріолан</NAME>
            <CONTRACT_NUMBER/>
            <CONTRACT_NUMBER_TITLE>Номер договору</CONTRACT_NUMBER_TITLE>
            <CONTRACT_NUMBER_TYPE>C</CONTRACT_NUMBER_TYPE>
            <CONTRACT_NUMBER_SIZE/>
            <ATTRIBUTE1/>
            <ATTRIBUTE1_TITLE/>
            <ATTRIBUTE1_TYPE>C</ATTRIBUTE1_TYPE>
            <ATTRIBUTE1_SIZE/>
            <ATTRIBUTE1_FOR_INFO>N</ATTRIBUTE1_FOR_INFO>
            <ATTRIBUTE2/>
            <ATTRIBUTE2_TITLE/>
            <ATTRIBUTE2_TYPE>C</ATTRIBUTE2_TYPE>
            <ATTRIBUTE2_SIZE/>
            <ATTRIBUTE2_FOR_INFO>N</ATTRIBUTE2_FOR_INFO>
            <ATTRIBUTE3/>
            <ATTRIBUTE3_TITLE/>
            <ATTRIBUTE3_TYPE>C</ATTRIBUTE3_TYPE>
            <ATTRIBUTE3_SIZE/>
            <ATTRIBUTE3_FOR_INFO>N</ATTRIBUTE3_FOR_INFO>
            <ATTRIBUTE4/>
            <ATTRIBUTE4_TITLE/>
            <ATTRIBUTE4_TYPE>C</ATTRIBUTE4_TYPE>
            <ATTRIBUTE4_SIZE/>
            <ATTRIBUTE4_FOR_INFO>N</ATTRIBUTE4_FOR_INFO>
            <IMAGE>triolan.png</IMAGE>
            <MATCH_TYPE>PARTIAL</MATCH_TYPE>
            <CONTRACT_NUMBER_TYPE_ARRAY/>
            <ATTRIBUTE1_ARRAY/>
            <ATTRIBUTE2_ARRAY/>
            <ATTRIBUTE3_ARRAY/>
            <ATTRIBUTE4_ARRAY/>
        </company>
    	...
    </companies>
</rsp>

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

Параметр	Опис
RWD	Cистемний параметр, який показує, що рахунок прив'язаний до користувача та до адреси користувача
PAYEE_ID	Унікальний ідентифікатор компанії
NAME	Назва компанії
CONTRACT_NUMBER	Основний реквізит (ідентифікатор) клієнта в цій компанії
CONTRACT_NUMBER_TITLE	Назва ідентифікатора клієнта у компанії
CONTRACT_NUMBER_TYPE	Тип ідентифікатора клієнта у компанії. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник
CONTRACT_NUMBER_SIZE	Розмір ідентифікатора клієнта у компанії
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Додатковий атрибут платежу у компанії
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Назва додаткового атрибуту платежу
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Тип додаткового атрибуту платежу. Може приймати значення: A – банківська картка, С – рядок, N – число, D – дата, L – довідник
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Розмір додаткового атрибуту платежу
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	Можливість для клієнта редагувати додатковий атрибут платежу (Y – приховане поле, не можна редагувати; N – видиме поле, доступне для введення даних користувачем)
IMAGE	Ім’я файлу з логотипом компанії
MATCH_TYPE	Тип відповідності (PARTIAL – часткова відповідність параметру пошуку, FULL – повна відповідність параметру пошуку)
CONTRACT_NUMBER_TYPE_ARRAY	Якщо `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, в цьому полі міститься довідник
ATTRIBUTE1_ARRAY	Якщо `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, в цьому полі міститься довідник
ATTRIBUTE2_ARRAY	Якщо `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, в цьому полі міститься довідник
ATTRIBUTE3_ARRAY	Якщо `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, в цьому полі міститься довідник
ATTRIBUTE4_ARRAY	Якщо `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, в цьому полі міститься довідник

2.29. Отримання значень довідника

Метод: bills.getreference

Опис: метод призначений для послідовного проходження по ієрархії довідників та отримання ідентіфікатора/значення довідника нижнього рівня для подальшої обробки та формування коректного призначення платежу та реквізитів.

Якщо будь-яке з полів attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type у відповіді методу bills.payees приймає значення R або L, необхідно послідовно викликати метод bills.getreference з відповідними параметрами до отримання кінцевого рівня ієрархії та знаходження ідентифікатора/значення рядку довідника.

Параметри:

Параметр	Опис	Обов’язковий
referenceId	Унікальний ідентифікатор довідника в системі Portmone.com. Тип INT	Так
parentReferenceId	Ідентифікатор рядка батьківського довідника (у відповіді методу bills.getreference – `<item id>`). Опціональний параметр для ідентифікатора довідника верхнього рівня та обов’язковий для всіх наступних запитів. Тип INT	Так/Ні

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

method=bills.getreference&referenceId=1183&parentReferenceId=42809

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

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <reference id="1183">
        <items>
            <item id="705299">
                <name>УК у Голос.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705301">
                <name>УК у Дарн.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705303">
                <name>УК у Десн.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705305">
                <name>УК у Дніпр.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705307">
                <name>УК у Оболон.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705309">
                <name>УК у Печер.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705311">
                <name>УК у Поділ.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705313">
                <name>УК у Святош.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705315">
                <name>УК у Солом.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            <item id="705317">
                <name>УК у Шевчен.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
        </items>
    </reference>
</rsp>

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

Параметр	Опис
items	Список значень довідника
item id	Ідентифікатор рядка довідника. Використовується для отримання нащадків (якщо рівень не останній) або для передачі до методу bills.create у випадку типу поля R (якщо рівень останній). Тип INT
name	Значення рядка довідника. Використовується для відображення клієнту або для передачі до методу bills.create у випадку типу поля L. Тип String
description	Додатковий опис значення довідника для відображення клієнту. Обов’язковий, якщо присутній. Тип String
parent_item_id	Ідентифікатор рядка батьківського довідника, що отриманий при попередньому виклику методу bills.getreference. Тип INТ

В результаті знаходження останнього рівня ієрархії і вибору клієнтом необхідного рядку у списку, до методу bills.create у відповідному полі (attribute1, attribute2, attribute3, attribute4, contract_number) повинен бути переданий або ідентифікатор рядку довідника нижнього рівня (<item id>) при типі поля R, або значення рядку довідника нижнього рівня (<name>) при типі поля L.

Приклади використання методу наведені у розділі 5 "Приклади" (Робота з довідниками типу R, Робота з довідниками типу L).

2.30. Оновлення рахунку

Метод: bills.update

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

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID рахунку. Його повертає метод bills.create (або bills.createByPhone – у разі поповнення мобільного телефону)	Так

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

Параметр	Опис	Обов’язковий
id	ID лічильника	Так
amount	Розрахована сума за лічильником	Так
prev_counter	Попереднє значення лічильника	Ні
counter	Поточне значення лічильника	Ні
tariff	Тариф	Ні
subsidy	Субсидія	Ні
debt	Сплачений борг	Ні
attribute1	Атрибут 1 (версія протоколу – 2)	Ні
attribute2	Атрибут 2 (версія протоколу – 2)	Ні
attribute3	Атрибут 3 (версія протоколу – 2)	Ні

Якщо параметр переданий, він обов’язково повинен мати значення («порожні» параметри не допускаються).

Приклад рядка запиту для компаній без айтемів:

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

Той же запит з даними по айтемах:

?method=bills.pay&login=логін&password=пароль&billId=значення&
tariff_items[111111][id]=значення&tariff_items[111111][counter]=значення&
tariff_items[111111][prev_counter]=значення&tariff_items[111111][tariff]=значення&
tariff_items[111111][subsidy]=значення&tariff_items[111111][debt]=значення

де tariff_items — назва масиву з даними по айтемах; 111111 — ID айтему; counter, prev_counter, tariff, subsidy, debt — дані по айтему.

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

<rsp status="ok">
<bill id="754838110">
<payee id="17590">ТОВ "КИЇВСЬКІ ЕНЕРГЕТИЧНІ ПОСЛУГИ" (двозонні лічильники)</payee>
<contractNumber title="Лицевой счет">08028002701</contractNumber>
<attribute1 title="Адрес">вул.Героїв Севастополя буд.29 кв.27</attribute1>
<attribute2/>
<attribute3/>
<attribute4/>
<bill_attribute1/>
<bill_attribute2/>
<bill_attribute3/>
<bill_attribute4/>
<date>06.11.2020</date>
<description>За жовтень 2020 року.</description>
<amount>120.00</amount>
<debt>0.00</debt>
<sum>120.00</sum>
<status>created</status>
<paidAmount/>
<payDate/>
<payee_export_flag/>
<auth_code/>
<transaction_id/>
<payment_point/>
<tariff_items>
<item id="380552112">
<name>Показания счетчика (день)</name>
<subsidy>0.00</subsidy>
<tariff>0.0000</tariff>
<counter>0</counter>
<prev_counter>0</prev_counter>
<amount>120.00</amount>
<debt>0.00</debt>
<name_ua>Показання лiчильника (день)</name_ua>
<name_eng>Meter characteristic (day)</name_eng>
<code>1</code>
<sub_code/>
<attribute1/>
<attribute2>120.24</attribute2>
<attribute3/>
<attribute4/>
<attribute5/>
<attribute6/>
<attribute7/>
<attribute8/>
<attribute9/>
<attribute10/>
<counter_accuracy>0</counter_accuracy>
<description/>
<pay_different_amount>Y</pay_different_amount>
</item>
<item id="380552114">
<name>Показания счетчика (ночь)</name>
<subsidy>0.00</subsidy>
<tariff>0.0000</tariff>
<counter>0</counter>
<prev_counter>0</prev_counter>
<amount>0.00</amount>
<debt>0.00</debt>
<name_ua>Показання лiчильника (ніч)</name_ua>
<name_eng>Meter characteristic (night)</name_eng>
<code>2</code>
<sub_code/>
<attribute1/>
<attribute2/>
<attribute3/>
<attribute4/>
<attribute5/>
<attribute6/>
<attribute7/>
<attribute8/>
<attribute9/>
<attribute10/>
<counter_accuracy>0</counter_accuracy>
<description/>
<pay_different_amount>Y</pay_different_amount>
</item>
</tariff_items>
</bill>
</rsp>

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

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

2.31. Перевірка суми гарантійного платежу

Метод: bank.params.guaranteeAmount

Опис: за допомогою цього методу можливо зробити перевірку суми гарантійного платежу.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
version	Версія API	Так
lang	Мова	Ні

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

method=bank.params.virtualBalance&login=PortmoneDirectTest&password=**************
&version=2&lang=ua

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

<rsp status="ok">
    <params>
        <amount_guarantee_payment>1000</amount_guarantee_payment>
    </params>
</rsp>

Де amount_guarantee_payment - сума гарантійного платежу в грн по партнеру.

У разі, якщо Сума гарантійного платежу відсутня по партнеру згідно переданого login, відповідь виглядає так:

<rsp status="ok">

<params> <amount_guarantee_payment/> </params>

</rsp>

2.32. Створення копії сплаченого рахунку

Метод: bills.recreate

Опис: за допомогою цього методу можливо зробити копії сплаченого рахунку та повернення нового ID рахунку (billId). .

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID сплаченого рахунку	Так
version	Версія API	Так
lang	Мова	Ні

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

method=bills.recreate&billId=1328599111&login=PortmoneDirectTest&password=**************
&version=2&lang=ua

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

<rsp status="ok">
    <bill id="1328946390">
        <payee id="***">Name</payee>
        <contractNumber>**********</contractNumber>
        <attribute1/>
        <attribute2/>
        <attribute3/>
        <attribute4/>
        <bill_attribute1/>
        <bill_attribute2/>
        <bill_attribute3/>
        <bill_attribute4/>
        <date>21.01.2020</date>
        <description></description>
        <amount>0.00</amount>
        <debt>0.00</debt>
        <sum>0.00</sum>
        <status>created</status>
        <paidAmount/>
        <payDate/>
        <payee_export_flag/>
        <auth_code/>
        <transaction_id/>
        <payment_point/>
    </bill>
</rsp>

Приклад помилки

"p003">У вас вже є неоплачений рахунок. </error> 
</rsp>

Також ймовірні помилки можуть бути наступні:

Опис	Помилка
Спроба перестворити рахунок повторно (компанія надає рахунки, не поповнює баланс)	`<error code="p003">У вас вже є неоплачений рахунок. [BILL_ID=1329627753]</error>`
Несплачений рахунок (компанія надає рахунки, не поповнює баланс)	`<error code="p003">Рахунок для копіювання неоплачений.</error>`
Невірний номер рахунку (компанія надає рахунки, не поповнює баланс)	`<error code="p003">Рахунок для оновлення не знайдений.</error>`
Оплачений рахунок (компанія поповнює баланс)	`<error code="p003">Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.</error>`
Несплачений рахунок (компанія поповнює баланс)	`<error code="p003">Рахунок для копіювання неоплачений.</error>`
Компанія дозволяє і поповнення балансу, і виставляє рахунки	`<error code="p003">Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.</error>`

2.33. Відміна оплат, які знаходяться в статусі PAYED

Метод: bills.cancel

Опис: за допомогою цього методу можливо відмінити оплати,які знаходяться в статусі PAYED

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
billId	ID сплаченого рахунку	Так
version	Версія API	Так
lang	Мова	Ні

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

method=bills.cancel&login=логін&password=пароль&version=2&billId=XXXXXXXXXX

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

<rsp status="ok">
  <bill id="1404012705">
    <payee id="2065">Київстар</payee>
    <contractNumber title="Номер телефону (без +380) ">965259529</contractNumber>
    <attribute1/>
    <attribute2 title="Номер квитанцii Київстар"/>
    <attribute3/>
    <attribute4/>
    <bill_attribute1/>
    <bill_attribute2/>
    <bill_attribute3/>
    <bill_attribute4/>
    <date>15.05.2023</date>
    <description>Рахунок створений автоматично для поповнення балансу</description>
    <amount>10.00</amount>
    <debt>0.00</debt>
    <sum>10.00</sum>
    <status>canceled</status>
    <paidAmount>10.00</paidAmount>
    <payDate>15.05.2023 13:42:42</payDate>
    <payee_export_flag/>
    <auth_code/>
    <transaction_id/>
    <payment_point>PORTMONEDIRECTTEST</payment_point>
  </bill>
</rsp>

2.34. Метод для передачі показів лічильника без оплати (для вхідних компаній) створення запиту.

Метод: counters.get

Опис: за допомогою цього методу можливо створити запит на передачу показів лічильника без оплати.

Метод працює аналогічно методу bills.createAll чи bills.create, в якому передаються атрибути по компанії з bills.payees

Параметри:

Параметр	Опис	Обов’язковий
payeeId	ID компанії-одержувача платежу	Так
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
contractNumber	Основний реквізит (ідентифікатор) клієнта в цій компанії	Так
attribute1-4	Додаткові реквізити	Так
version	Версія API	Так
lang	Мова	Ні

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

version:2
lang:uk
login:PortmoneDirectTest
password:PortmoneDirect
method:counters.get
payeeId:27322
contractNumber:774037010600
attribute1:12
attribute2:12
attribute3:12
attribute4:21

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

<rsp status="ok">
  <counters>
    <counter id="1212773">
      <name>холодна вода ЛК-15 (48міс.) №987604 октябрь 2</name>
      <service_name>Показники лічильників</service_name>
      <value>0</value>
      <prev_value>566</prev_value>
      <counter_number/>
      <counter_accuracy>0</counter_accuracy>
    </counter>
  </counters>
</rsp>

Приклад помилки

<rsp status="fail">
  <error code="p000">Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки.</error>
</rsp>

2.35. Метод для передачі показів лічильника без оплати (передача даних в компанію, показники, які вніс клієнт).

Метод: counters.set

Опис: за допомогою цього методу можливо передачі показів лічильника без оплати.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу	Так
counters	показник лічильника	Так
version	Версія API	Так
lang	Мова	Ні

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

version:2
lang:uk
login:PortmoneDirectTest
password:PortmoneDirect
method:counters.set
counters[1212773][counter]:1157

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

<rsp status="ok">
  <counters>
    <counter id="1212773">
      <value>1157</value>
    </counter>
  </counters>
</rsp>

Приклад помилки

<rsp status="fail">
  <error code="p000">Передача показань лічильника, що менші за попередні, заборонено постачальником послуги. Зверніться до постачальника послуги.</error>
  <error_description>Передача показань лічильника, що менші за попередні, заборонено постачальником послуги. Зверніться до постачальника послуги.</error_description>
</rsp>

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

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

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

Аутентифікація партнера за допомогою логіну та паролю облікового запису, що отриманий при реєстрації у системі Portmone.com. Запит з необхідними параметрами формується на стороні партнера та передається методом POST на URL https://www.portmone.com.ua/r3/verification/card/.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
method	Назва методу – verification	Так
success_url	Адреса партнера, на яку буде спрямовано клієнта після успішної перевірки. За цією ж адресою методом POST Portmone.com надішле параметри для наступного кроку	Так

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

<form action="https://www.portmone.com.ua/r3/verification/card/" method="post">
	<input type="hidden" name="success_url" value="https://api.credit-pro.com.ua/portmone/
    direct/a2c/card?uuid=004182e7-b05f-4415-9c2d-fb220ee655af" />
	<input type="hidden" name="method" value="verification" />
	<input type="hidden" name="login" value="P_DIRECT_CITY" />
	<input type="hidden" name="password" value="11111111" />
	<input type="submit" value="RESULT" style={{ width: '350px' }} class="button_green" />
</form>

У випадку успішної аутентифікації партнера клієнт переходить на сторінку перевірки платіжної картки, де необхідно ввести номер платіжної картки, термін її дії та CVV2, натиснути "Верифікувати":

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

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

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

У випадку успішного проходження перевірки на success_url, що вказаний у запиті, будуть надіслані наступні дані:

CARD_MASK: 410232******5594
SHOP_BILL_ID: 488377227
RECIPIENT_ID: 45467512

де:

CARD_MASK – маска картки клієнта (перші 6 та останні 4 цифри номеру);

SHOP_BILL_ID – ідентифікатор транзакції у системі Portmone.com;

RECIPIENT_ID – ідентифікатор одержувача у системі Portmone.com.

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

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

Викликати метод bills.create з наступними параметрами:

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

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

Викликати метод bills.pay з використанням наступних параметрів:

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

Викликати метод bills.get для отримання інформації про статус зарахування:

Параметр	Опис
login	Логін компанії-реселера в системі Portmone.com
password	Пароль компанії-реселера в системі Portmone.com
method	Назва методу – bills.get
billId	ID рахунку (його повертає метод bills.create)

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

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

status=’PAYED’ та payee_export_flag=’Y’ – оплата у еквайра успішна і кошти зараховані клієнту, або

status=’CANCELED’ – кошти на картку клієнта не можуть бути зараховані.

Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.

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

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

Викликати метод bills.create з наступними параметрами:

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

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

Викликати метод bills.pay з використанням наступних параметрів:

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

Викликати метод bills.get для отримання інформації про статус зарахування:

Параметр	Опис
login	Логін компанії-реселера в системі Portmone.com
password	Пароль компанії-реселера в системі Portmone.com
method	Назва методу – bills.get
billId	ID рахунку (його повертає метод bills.create)

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

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

status=’PAYED’ та payee_export_flag=’Y’ – оплата у еквайра успішна і кошти зараховані клієнту, або

status=’CANCELED’ – кошти на картку клієнта не можуть бути зараховані.

Зверніть увагу! При використанні сервісу поповнення карток Партнер повинен обов’язково робити звірення контрольного списку транзакцій за період (день) методом bills.date та направляти реєстри до Portmone.com методом bills.paymentOrder.

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

Код помилки	Повідомлення про помилку	Опис	Метод
o001	Помилка при створенні рахунку	Помилка при створенні рахунку (внутрішній код помилки)	bills.create
o003	Помилка під час оплати рахунку	Помилка під час оплати рахунку	bills.pay
o003	Помилка під час відміни рахунку	Помилка під час скасування рахунку. (Рахунок не знайдено)	bills.cancel
o003	Помилка при створенні рахунку. XXXXXXXXXXXXXXXXXXXXXXXX	Помилка при створенні рахунку. XXXXXXXXXXXXXXXXXXXXXXXX	bills.recreate
o004	Помилка при виведенні контрольного реєстру	Помилка при виведенні контрольного реєстру	bills.paymentOrder
o006	Помилка при виведенні балансу по компанії	Помилка при виведенні балансу по компанії	bills.balance
o010	Немає отримувачів платежу для логіну	Помилка при пошуку компанії	bills.additionalPayees
р013	Невірні параметри ідентифікації клієнта	Помилка під час оплати рахунку	bills.pay
p001	Invalid method name	Невірне ім'я методу	Усі методи
p002	Invalid login/password	Невірний логін або пароль	Усі методи
p003	Помилка при створенні підписки	Помилка при створенні підписки (внутрішній код помилки)	bills.create
p003	Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки.	Системна помилка. За роз’ясненнями зверніться до служби технічної підтримки.	bills.recreate
p003	Рахунок для оновлення не знайдений	Рахунок для оновлення не знайдений	bills.recreate
p003	Рахунок для оновлення несплачений.	Рахунок для оновлення несплачений.	bills.recreate
p003	Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.	Компанія дозволяє поповнення балансу. Скористайтеся стандартним методом отримання рахунків.	bills.recreate
p003	У вас вже є несплачений рахунок [BILL_ID=XXXXXX]	У вас вже є несплачений рахунок [BILL_ID=XXXXXX]	bills.recreate
p004	Помилка при оновленні параметрів лічильника	Помилка при оновленні параметрів лічильника	bills.pay
p005	Підписка має статус "ERROR"	Компанія-біллер повернула повідомлення про помилку за цією підпискою, або при спробі повторно створити підписку з невірними реквізитами	bills.create
p006	Немає такої компанії	У БД Portmone.com немає компанії-біллера з таким ID	bills.create
p007	Підписка створена. Чекаємо на відповідь компанії.	Підписка створена (“CREATED”), але поки немає підтвердження від компанії-біллера про правильність введеної інформації (якщо компанія-біллер відповість, що передана інформація некоректна, статус підписки буде змінений на “ERROR”).	bills.create
p008	У вас немає несплачених рахунків. Очікуйте на виставлення рахунків від вашого постачальника послуг.	Підписка створена, але рахунків поки що немає (як у випадку з ГІОЦем, наприклад)	bills.create
p009	Немає такого рахунку	У БД Portmone.com немає рахунку з таким ID (внутрішній код помилки)	bills.get
p010	No bills for date	Немає рахунків за отриману дату (внутрішній код помилки)	bills.date, bills.exported
p011	Отримано порожній або пошкоджений реєстр	Отримано порожній або пошкоджений реєстр	bills.paymentOrder
p012	Empty POST	Отриманий масив POST порожній	Усі методи
p014	Перевищена квота по компанії	Перевищена квота по компанії (внутрішній код помилки)	bills.pay
p015	Помилка при перевірці валідності підписки	Видається, якщо реквізити раніше створеної підписки більш не дійсні (наприклад, номер телефону деактивовано біллером) (внутрішній код помилки)	bills.create
p015	Invalid date format	Невірний формат дати (внутрішній код помилки)	bills.date, bills.exported
p017	Помилка при запиті інформації за рахунком	Неможливо отримати інформацію про рахунок (наприклад, рахунок у цей момент заблокований сесією оплати) (внутрішній код помилки)	bills.get
p018		Для отримання рахунків для цієї компанії необхідно використовувати метод bills.createAll	bills.create
p019		Загальна помилка для усіх методів search.*	search.*
p022		Довідник не знайдений	bills.getreference
p032	Помилка пошуку даних. Можливо ви намагаєтесь знайти квартири за приватним будинком	Помилка пошуку даних. Дані (квартири) не знайдено	search.apartmentsByHouse, search.apartmentsByHouseExtended
p033	Формат номеру телефону має відповідати формату +38ХХХХХХХХХХ
p100	Помилка при зверненні до БД	Внутрішня помилка системи. При виникненні цієї помилки необхідно обовязково здійснити наступний виклик методу bills.get, оскільки в цьому випадку статус рахунку невідомий — рахунок може бути як оплачений, так і не оплачений	Усі методи

5. Приклади

Приклад використання методів PortmoneDirect для отримання географічних даних клієнта (ідентифікатори регіону, міста, вулиці, будинку та/або квартири)

(на прикладі пошуку за адресою: м. Київ, проспект Бажана, буд. 1а, кв. 4)

1. Пошук регіону Києва серед регіонів (searchQuery=Ки)

POST method=search.regionsExtended&login=логін&password=пароль&version=2&searchQuery=Ки

Результат: regionId = 44

2. Пошук міста Києва у регіоні Київ (regionId = 44, searchQuery=Ки)

POST method=search.citiesByRegionExtended&login=логін&password=пароль&version=2&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 = 23782 – reference id = 1180, reference id = 1183, reference id = 4308

2. Отримання даних найвищого рівня ієрархіїї – вибір регіону для сплати податку (referenceId = 1180, parentReferenceId порожній)

Запит:

method=bills.getreference&referenceId=1180&parentReferenceId=

Відповідь:

 <rsp status="ok">
    <reference id="1180">
        <items>
            <item id="42809">
                <name>м. Київ</name>
                <description/>
                <parent_item_id/>
            </item>
            ...
        </items>
    </reference>
</rsp>

Результат: у відповіді обираємо елемент найвищого рівня ієрархії – item id = 42809 - м. Київ

3. Отримання даних наступного рівня ієрархії – вибір району для сплати податку (referenceId = 1183, parentReferenceId = 42809)

Запит:

method=bills.getreference&referenceId=1183&parentReferenceId=42809

Відповідь:

<rsp status="ok">
    <reference id="1183">
        <items>
            ...
            <item id="705301">
                <name>УК у Дарн.р-ні</name>
                <description/>
                <parent_item_id>42809</parent_item_id>
            </item>
            ...
        </items>
    </reference>
</rsp>

Результат: у відповіді обираємо елемент поточного рівня ієрархії – item id = 705301 - УК у Дарн.р-ні

4. Отримання даних наступного рівня ієрархії – вибір кінцевого одержувача платежу (referenceId = 4308, parentReferenceId = 705301)

Запит:

method=bills.getreference&referenceId=4308&parentReferenceId=705301

Відповідь:

<rsp status="ok">
    <reference id="4308">
        <items>
            <item id="849062">
                <name>Дарниц.р-н/18050400</name>
                <description/>
                <parent_item_id>705301</parent_item_id>
            </item>
        </items>
    </reference>
</rsp>

Результат: у відповіді обираємо елемент найнижчого рівня ієрархії – item id = 849062 - Дарниц.р-н/18050400

5. Створення рахунку (метод bills.create, payeeId = 23782, contractNumber = 849062) та його оплата (метод bills.pay)

Результатом роботи з довідником типу R є ідентифікатор, що отриманий на найнижчому рівні ієрархії – 849062. Цей ідентифікатор буде використовуватись на наступному етапі для виклику методу bills.create.

Робота з довідниками типу L

(на прикладі вибору групи ФОП та податкового періоду для сплати єдиного податку ФОП в Дарницькому районі м. Києва для тестової компанії з payee id = 23782)

1. Отримання даних про компанію (метод bills.payees)

Запит:

method=bills.payees&login=логін&password=пароль&version=2

Відповідь:

<rsp status="ok">
    …
    <payee id="23782">
        ...
        <name>Єдиний податок з фіз. осіб підприємців</name>
        <attributes>
            ...
            <attribute2>
                <title>За период</title>
                <type>L</type>
                <size>4311</size>
                <related_references>
                    <reference id="4310" order_number="1">Група:</reference>
                    <reference id="4311" order_number="2">За період:</reference>
                </related_references>
            </attribute2>
        ...
        </attributes>
      ...
    </payee>
    ...
</rsp>

Результат: у відповіді використовуємо список довідників з блоку payee/attributes/attribute2/related_references для payee id = 23782 – reference id = 4310, reference id = 4311

2. Отримання даних найвищого рівня ієрархіїї – вибір групи ФОП (referenceId = 4310, parentReferenceId порожній)

Запит:

method=bills.getreference&referenceId=4310&parentReferenceId=

Відповідь:

  <rsp status="ok">
        <reference id="4310">
            <items>
                <item id="832244">
                    <name>1 группа</name>
                    <description/>
                    <parent_item_id/>
                </item>
                <item id="832245">
                    <name>2 группа</name>
                    <description/>
                    <parent_item_id/>
                </item>
                <item id="832247">
                    <name>3 группа</name>
                    <description/>
                    <parent_item_id/>
                </item>
            </items>
        </reference>
    </rsp>

Результат: у відповіді обираємо елемент найвищого рівня ієрархії – item id = 832247 - 3 группа

3. Отримання даних наступного рівня ієрархії – вибір податкового періоду (referenceId = 4311, parentReferenceId = 832247)

Запит:

method=bills.getreference&referenceId=4311&parentReferenceId=832247

Відповідь:

 <rsp status="ok">
        <reference id="4311">
            <items>
                <item id="832280">
                    <name>1-й квартал</name>
                    <description/>
                    <parent_item_id>832247</parent_item_id>
                </item>
                <item id="832281">
                    <name>2-й квартал</name>
                    <description/>
                    <parent_item_id>832247</parent_item_id>
                </item>
                <item id="832282">
                    <name>3-й квартал</name>
                    <description/>
                    <parent_item_id>832247</parent_item_id>
                </item>
                <item id="832283">
                    <name>4-й квартал</name>
                    <description/>
                    <parent_item_id>832247</parent_item_id>
                </item>
            </items>
        </reference>
    </rsp>

Результат: у відповіді обираємо елемент найнижчого рівня ієрархії – item id = 832247 - 4-й квартал

4. Створення рахунку (метод bills.create, payeeId = 23782, attribute2 = 4-й квартал) та його оплата (метод bills.pay)

Результатом роботи з довідником типу L є значення атрибуту, що отримане на найнижчому рівні ієрархії – 4-й квартал. Це значення буде використовуватись на наступному етапі для виклику методу bills.create.

6. Тестування

Веб-інтерфейс API PortmoneDirect: https://direct.portmone.com.ua/api/.

Адреса виклику методів (endpoint URL): https://direct.portmone.com.ua/api/directcash/.

Логін та пароль для тестування:

логін — PortmoneDirectTest пароль — PortmoneDirect

Для імитації відмов у роботі системи (таймаути та інше), для тестового логіну PORTMONEDIRECTTEST2, до методу bills.pay додано таймаут, що виникає випадковим чином (ймовірність спрацювання приблизно 40%). Необхідно враховувати, що у разі спрацювання таймауту, рахунок на боці Portmone може бути як оплачений, так і не оплачений.

Логін та пароль для тестування з імитацією таймаутів:

логін — PORTMONEDIRECTTEST2 пароль — Direct2

На етапі тестування (для логіну PortmoneDirectTest) доступні три компанії-біллери: ГІОЦ (payeeId = 22494), Воля ТБ та/або Iнтернет (payeeId = 6968) та Vodafone (payeeId = 10196). Ці три біллери ілюструють три типи бізнес-логіки:

Біллери, які не виставляють рахунки періодично (наприклад, оператори мобільного зв'язку (МТС-Україна)).
Біллери, які виставляють рахунки періодично і допускають поповнення балансу (наприклад, Воля Броадбенд).
Біллери, які виставляють рахунки періодично і не допускають поповнення балансу (наприклад, ГІОЦ)

Відповідно, під час виклику bills.create:

Для біллерів першого типу — при кожному запиті завжди створюється новий раунок на нульову суму.
Для біллерів другого типу — якщо в системі Portmone вже існує рахунок, виставлений біллером, повертаємо цей рахунок (на сумму, що виставлена біллером), якщо ні — створюємо новий на нульову суму.
Для біллерів третього типу — якщо в системі Portmone вже есть існує рахунок, виставлений біллером, повертаємо цей рахунок (на суму, що виставлена біллером), якщо ні — генеруємо повідомлення про помилку «p008 – У вас немає несплачених рахунків. Очікуйте на виставлення рахунків від вашого постачальника послуг.».

Додаток 1. Опис структури XML

Такий XML повертається у разі виклику методів bills.create, bills.pay та bills.get.

<?xml version="1.0" encoding="utf-8"?>
<rsp status="">
    <bill id="id">
        <payee id="id"> Назва компанії </payee>
        <contractNumber title="title"> Номер договору або номер телефону (для телефону —
        9 знаків) </contractNumber>
        <attribute1 title="title"> Значення атрибуту (наприклад, “710”) </attribute1>
        <attribute2 title="title" />
        <attribute3 title="title" />
        <attribute4 title="title" />
        <bill_attribute1 />
        <bill_attribute2 />
        <bill_attribute3 />
        <bill_attribute4 />
        <date>DD.MM.YYYY</date>
        <description />
        <amount />
        <debt />
        <sum>amount + debt</sum>
        <period />
        <status />
        <paidAmount />
        <payDate>DD.MM.YYYY hh24:mi:ss</payDate>
        <payee_export_flag>Y</payee_export_flag>
        <auth_сode />
        <transaction_id />
        <payment_point>payment_point</payment_point>
        <tariff_items>
            <item id="id">
                <name />
                <name_ua />
                <name_eng />
                <code />
                <sub_code />
                <tariff />
                <tariff_state /> <!-- версія протоколу – 2 -->
                <tariff_name />  <!-- версія протоколу – 2 -->
                <counter />
                <counter_state /> <!-- версія протоколу – 2 -->
                <counter_name />  <!-- версія протоколу – 2 -->
                <prev_counter />
                <prev_counter_state />  <!-- версія протоколу – 2 -->
                <prev_counter_name />   <!-- версія протоколу – 2 -->
                <subsidy />
                <subsidy_state />  <!-- версія протоколу – 2 -->
                <subsidy_name />   <!-- версія протоколу – 2 -->
                <debt />
                <debt_state />  <!-- версія протоколу – 2 -->
                <debt_name />   <!-- версія протоколу – 2 -->
                <amount />
                <negative_amount />  <!-- версія протоколу – 2 -->
                <amount_state />     <!-- версія протоколу – 2 -->
                <amount_name />      <!-- версія протоколу – 2 -->
                <counter_accuracy />
                <pay_different_amount />
                <attribute1 />
                <attribute1_state />   <!-- версія протоколу – 2 -->
                <attribute1_name />    <!-- версія протоколу – 2 -->
                <attribute2 />
                <attribute2_state />   <!-- версія протоколу – 2 -->
                <attribute2_name />    <!-- версія протоколу – 2 -->
                <attribute3 />
                <attribute3_state />   <!-- версія протоколу – 2 -->
                <attribute3_name />    <!-- версія протоколу – 2 -->
                <attribute4 />
                <attribute5 />
                <attribute6 />
                <attribute7 />
                <attribute8 />
                <attribute9 >
                <attribute10 />
                <description />
                <calculated />      <!-- версія протоколу – 2 -->
            </item>
        </tariff_items>
    </bill>
</rsp>

Параметр	Опис
rsp status	Стутус запиту: "ok" – все Ok, "fail" – помилка
bill id	ID рахунку
payee id	ID компанії – передається у запиті bills.create
contractNumber title	Наприклад, "Номер телефону (+380)"
attribute1 title	Призначення (назва) атрибуту1 (наприклад, “Номер ЖЕКу”). Залежить від організації
attribute2	Назва атрибуту2. Залежить від організації
attribute3	Назва атрибуту3. Залежить від організації
attribute4	Назва атрибуту4. Залежить від організації
bill_attribute1-4	Додаткові параметри рахунку (номер квитанції Київстару і т.д.). Залежать від біллера
date	Дата створення рахунку. Формат: DD.MM.YYYY
description	Опис рахунку
amount	Сума рахунку. Десятковий знак – крапка (“.”)
debt	Борг. Якщо у рахунку є переплата, це поле містить знак мінуса
sum	Сума до сплати, зазвичай дорівнює `amount` + `debt`
period	Період, за який виставлений рахунок (у форматі біллера)
status	Статус рахунку. Можливі значення: "created", "payed", "canceled", "return"
paidAmount	Сума, що реально сплачена (вона може відрізнятись від тієї, що запропонована у рахунку)
payDate	Дата оплати рахунку. Формат: DD.MM.YYYY hh24:mi:ss
payee_export_flag	Ознака того, чи передана інформація про сплату до компанії-біллера. Можливі значення: "Y" – інформація успішно передана; "N" – спроб передачі ще не було; "E" – під час останньої спроби сталася помилка (наприклад, біллер «лежить»); "B" – відправка заблокована (наприклад, на прохання банку); "R" – транзакція реверсована (для тих біллерів, що вміють робити реверс); "" – для тих компаній, за якими передача не здійснюється.
auth_сode	Код авторизації – передається при оплаті
transaction_id	ID транзакції – передається при оплаті
payment_point	Унікальний опис торгової точки партнера – передається нам при оплаті

Далі опційні теги:

"Універсальні" айтеми (раніше називалися лічильниками):

Поля %_state можуть приймати три значення:

"N" – колонка не повинна відображатись;
"V" – колонка та її вміст відображається клієнту без можливості редагування;
"E" – колонка та її вміст відображається клієнту з можливістю редагування.

Атрибут tariff_state - це поле може приймати значення W_%. Цей тип означає, що тариф може залежати від обсягів, тощо і необхідності розрахунку може приймати значення.

Приклади:

"W" – необхідність розрахувати послугу за електропостачання
"W_GAZ" – необхідність розрахувати послугу з газу
"W_Y" – необхідність розрахувати послуги за світло

у цьому випадку, колонка не повинна відображатися і для розрахунку вартості оплати можна використовувати помічники.

Параметр	Опис
tariff_items	Лічильнкики, що редагуються та не редагуються
item id	ID послуги
name	Назва послуги (рос.) (всі версії протоколу)
name_ua	Назва послуги (укр.) (версія протоколу – 1)
name_eng	Назва послуги (англ.) (версія протоколу - 1)
code	Код послуги
sub_code	Підкод послуги
tariff	Значення тарифу в грн.
tariff_state	Тип колонки (версія протоколу – 2 і більше)
tariff_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
counter	Поточне значення лічильника
counter_state	Тип колонки (версія протоколу – 2 і більше)
counter_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
prev_counter	Попереднє значення лічильника
prev_counter_state	Тип колонки (версія протоколу – 2 і більше)
prev_counter_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
subsidy	Субсидія у грн.
subsidy_state	Тип колонки (версія протоколу – 2 і більше)
subsidy_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
debt	Борг у грн.
debt_state	Тип колонки (версія протоколу – 2 і більше)
debt_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
amount	Сума за лічильником у грн.
negative_amount	Ознака того, чи може в тезі `<amount />` бути отримане негативне значення. Можливі значення: "N", "Y" (версія протоколу – 2 і більше)
amount_state	Тип колонки (версія протоколу – 2 і більше)
amount_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
counter_accuracy	Розрядність лічильника: "0" – значення лічильника округлюються до цілого числа "1" – до 1-го знаку після коми "2" – до 2-го знаку "3" – до 3-го знаку "4" – до 4-го знаку
pay_different_amount	Ознака того, чи можливо сплатити суму, що відрізняється від отриманої. Має значення тільки для протоколу версії 1.0 (у пізніших версіях для прийняття рішення, чи можливо змінювати отримані дані, необхідно приймати до уваги значення тегів з суфіксом " _state", наприклад, `<amount_state>` для суми за лічильником). Можливі значення: "N" – сума лічильника вже врахована у сумі рахунку (лічильник не треба передавати при оплаті) "Y" – сума лічильника розраховується та додається до суми рахунку (лічильник передається при оплаті)
attribute1	Опційний тег (залежить від біллера)
attribute1_state	Тип колонки (версія протоколу – 2 і більше)
attribute1_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
attribute2	Опційний тег (залежить від біллера)
attribute2_state	Тип колонки (версія протоколу – 2 і більше)
attribute2_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
attribute3	Опційний тег (залежить від біллера)
attribute3_state	Тип колонки (версія протоколу – 2 і більше)
attribute3_name	Заголовок колонки (укр.) (версія протоколу – 2 і більше)
attribute4-10	Опційні теги (залежать від біллера)
description	Опис лічильника
calculated	Ознака того, чи необхідно розраховувати `amount` айтему за формулою, або можна просто передати в `amount` довільне значення: "Y" – використовується формула: (`counter` - `prev_counter`) * `tariff` – `subsidy`; "N" – довільне значення (версія протоколу – 2 і більше)

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

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

2. Методи​

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

2.2. Запит на доставку рахунку за номером телефону​

2.3. Запит на доставку всіх рахунків, виставлених за поточний місяць​

2.4. Оплата рахунку​

2.5. Інформація про рахунок​

2.6. Реєстр надісланих платежів​

2.7. Контрольний реєстр транзакцій​

2.8. Контрольний реєстр коштів, переданих постачальнику послуги​

2.9. Запит даних по балансу компанії-реселера​

2.10. Запит інформації про доступні компанії-біллери​

2.11. Запит інформації про компанії-біллери у контексті регіонів​

2.12. Запит компаній, що надають рахунки для клієнта, за раніше отриманим рахунком​

2.13. Запит інформації по регіонах​

2.14. Запит інформації по регіонах (з пошуком за назвою регіону)​

2.15. Запит інформації по містах (населених пунктах) регіону​

2.16. Запит інформації по населених пунктах регіону (з пошуком за назвою)​

2.17. Запит інформації по вулицях міста​

2.18. Запит інформації по вулицях міста (з пошуком за назвою вулиці)​

2.19. Запит інформації по будинках вулиці​

2.20. Запит інформації по будинках вулиці (з пошуком за номером будинку)​

2.21. Запит інформації по квартирах будинку (тільки для багатоквартирних будинків)​

2.22. Запит інформації по квартирах будинку (з пошуком за номером квартири)​

2.23. Запит контекстної інформації за адресою (список рахунків)​

2.24. Пошук компаній для зазначеного регіону​

2.25. Пошук компаній для зазначеного населеного пункту​

2.26. Пошук компаній для зазначеної вулиці​

2.27. Пошук компаній для зазначеного будинку​

2.28. Пошук компаній за адресою​

2.29. Отримання значень довідника​

2.30. Оновлення рахунку​

2.31. Перевірка суми гарантійного платежу​

2.32. Створення копії сплаченого рахунку​

2.33. Відміна оплат, які знаходяться в статусі PAYED​

2.34. Метод для передачі показів лічильника без оплати (для вхідних компаній) створення запиту.​

2.35. Метод для передачі показів лічильника без оплати (передача даних в компанію, показники, які вніс клієнт).​

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

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

3.2. Поповнення картки клієнта​

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

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

5. Приклади​

Приклад використання методів PortmoneDirect для отримання географічних даних клієнта (ідентифікатори регіону, міста, вулиці, будинку та/або квартири)​

Робота з довідниками типу R​

Робота з довідниками типу L​

6. Тестування​

Додаток 1. Опис структури XML​

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

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

2. Методи

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

2.2. Запит на доставку рахунку за номером телефону

2.3. Запит на доставку всіх рахунків, виставлених за поточний місяць

2.4. Оплата рахунку

2.5. Інформація про рахунок

2.6. Реєстр надісланих платежів

2.7. Контрольний реєстр транзакцій

2.8. Контрольний реєстр коштів, переданих постачальнику послуги

2.9. Запит даних по балансу компанії-реселера

2.10. Запит інформації про доступні компанії-біллери

2.11. Запит інформації про компанії-біллери у контексті регіонів

2.12. Запит компаній, що надають рахунки для клієнта, за раніше отриманим рахунком

2.13. Запит інформації по регіонах

2.14. Запит інформації по регіонах (з пошуком за назвою регіону)

2.15. Запит інформації по містах (населених пунктах) регіону

2.16. Запит інформації по населених пунктах регіону (з пошуком за назвою)

2.17. Запит інформації по вулицях міста

2.18. Запит інформації по вулицях міста (з пошуком за назвою вулиці)

2.19. Запит інформації по будинках вулиці

2.20. Запит інформації по будинках вулиці (з пошуком за номером будинку)

2.21. Запит інформації по квартирах будинку (тільки для багатоквартирних будинків)

2.22. Запит інформації по квартирах будинку (з пошуком за номером квартири)

2.23. Запит контекстної інформації за адресою (список рахунків)

2.24. Пошук компаній для зазначеного регіону

2.25. Пошук компаній для зазначеного населеного пункту

2.26. Пошук компаній для зазначеної вулиці

2.27. Пошук компаній для зазначеного будинку

2.28. Пошук компаній за адресою

2.29. Отримання значень довідника

2.30. Оновлення рахунку

2.31. Перевірка суми гарантійного платежу

2.32. Створення копії сплаченого рахунку

2.33. Відміна оплат, які знаходяться в статусі PAYED

2.34. Метод для передачі показів лічильника без оплати (для вхідних компаній) створення запиту.

2.35. Метод для передачі показів лічильника без оплати (передача даних в компанію, показники, які вніс клієнт).

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

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

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

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

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

5. Приклади

Приклад використання методів PortmoneDirect для отримання географічних даних клієнта (ідентифікатори регіону, міста, вулиці, будинку та/або квартири)

Робота з довідниками типу R

Робота з довідниками типу L

6. Тестування

Додаток 1. Опис структури XML