Embedding PortmoneDirect bill payment service into customer service banking systems. Technical description

Glossary

Term	Definition
Merchant, Partner	Organization which has signed a payment acceptance agreement with Portmone.com
Buyer, Client or Customer	A person who visits the Merchant's Online Store in order to learn about the range of goods (services) and to make a purchase
Card, Payment Card	Payment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
Authorization	The process of giving access rights or other powers to the Buyer, program or process
CVV2/CVC2	CVV2 (Card Verification Value 2) is a three-digit card security code that helps to verify legitimacy of a Visa payment card. The Mastercard payment system has similar card security code called CVC2 (Card Validation Code 2)
Acquiring Bank	A bank that organizes banking cards acceptance points (terminals, ATM’s) and processes full range of financial operations connected with performing bank settlements and payments by banking cards at that points
Issuing Bank (Card Issuing Bank)	A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards
IBAN	International Bank Account Number

1. General information

The PortmoneDirect uses Representational State Transfer (REST) technology. Requests and responses are transferred over the HTTPS channel (note that at the moment only TLS 1.2 protocol is supported by the server).

The execution of methods with the required parameters is to be formed on the side of merchant and to be transferred to the Portmone.com server by POST requests.

** Please note ** that all parameters are transferred in the body of the POST request, in no case in the body of the URL. In query examples, the ? sign is specified at the beginning of the string - this is not an indication for the use of GET messages.

Endpoint URL: https://direct.portmone.com.ua/api/directcash/.

Each request must contain two mandatory parameters - login and password (login and password of the reseller company). The login, password and HTTPS certificate should be provided by the Portmone manager.

The response format is XML. UTF-8 encoding is used for data transferring.

The date format is DD.MM.YYYY.

An example of request for bill delivery:

method=bills.create&login=login&password=password&version=2&payeeId=value&contractNumber=value

An example of successful response:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
[xml-data there]
</rsp>

An example of response in case of an error:

For version 1:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="Error code">Error description</error>
</rsp>

For version 2 and higher:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="Error code">Error description</error>
    <error_description>Detailed error description (protocol version - 2)</error_description>
</rsp>

Protocol

By default, the protocol version is “1”.

If the parameter version = 2 is transferred in the request, additional tags entered for the protocol version “2” become available.

Localization

Optional parameter lang added to the protocol version “2” (possible values are: ru - Russian, uk - Ukrainian, en - English). The parameter localizes attribute values and service names in the response (but not the company name). If the parameter is not passed, the result is returned in Ukrainian.

If you use the protocol version 2 (version = 2) and the values of the lang parameter in the request, the values of <name/> and <*_name/> tags in the <tariff_items> block of the response will be returned localized to the needed language.

For the protocol version 2 (version = 2), the <tariff_items> block of the response does not contain the <name_ua/> and the <name_en/> tags (due to the lang parameter using).

An example of using the lang parameter.

Request:

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

Response:

<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>

The <contractNumber title> parameter is localized in Russian.

Description of XML-structure

To study structure of XML-response refer to Attachment 1.

Notifications of Invoice Uploads by Company

Partner notifications are sent after an invoice is uploaded for each company. The partner must provide a URL that can receive a POST request for further processing on their side.

Request examples:

<?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. Methods

Method name	Description
2.1. bills.create	this method is used to create a subscription on the Portmone.com side to receive bills for the required company and return the bill ID (`billId`)
2.2. bills.createByPhone	this method is used to create a bill on the Portmone.com side to add funds to a mobile phone account and return the ID of the payee company (`payeeId`) and the bill ID (`billId`)
2.3. bills.createAll	this method is used to get bills from companies issuing several bills for the current month
2.4. bills.pay	this method is used to pay bills
2.5. bills.get	This method is used when you need to get information about a bill. You need to send request l if the method bills.pay received a connection error, received a response of an unexpected format that does not match the protocol. And also if errors p009, p017, p100 are received.
2.6. bills.paymentOrder	this method is used to transfer a list of transactions and payment details of cover payment from bank to the Portmone.com system
2.7. bills.date	this method is used to obtain a control registry of transactions for the period (day)
2.8. bills.exported	this method is used to obtain a control registry of transactions for the period (day), the funds for which were sent to the service provider (biller)
2.9. bills.balance	this method is used to view the current balance of the biller company (`PAYEE`)
2.10. bills.payees	this method is used to get biller (`PAYEE`) parameters
2.11. bills.regions	this method is used to obtain a list of available regions and a list of billers (`PAYEE`) for each region
2.12. bills.additionalPayees	this method is used to get a list of companies for which the client can pay bills
2.13. search.regions	this method is used to obtain a complete list of regions of Ukraine
2.14. search.regionsExtended	this method is used to obtain a list of regions of Ukraine with additional filtering by region name
2.15. search.citiesByRegion	this method is used to get a list of cities for the specified region
2.16. search.citiesByRegionExtended	this method is used to get a list of cities for the specified region with additional filtering by city name
2.17. search.streetsByCity	this method is used to get a list of streets for the specified city
2.18. search.streetsByCityExtended	this method is used to get a list of streets for the specified city with additional filtering by street name
2.19. search.housesByStreet	this method is used to get a list of buildings for the specified street
2.20. search.housesByStreetExtended	this method is used to get a list of buildings for the specified street with additional filtering by building number
2.21. search.apartmentsByHouse	this method is used to obtain a list of apartments by known houseId. For apartment buildings only
2.22. search.apartmentsByHouseExtended	this method is used to obtain a list of apartments by known houseId with additional filtering by apartment number. For apartment buildings only
2.23. search.userDocsByAddress*	this method is used to obtain a list of bills by known `houseId` (for private houses) or `apartmentId` (for apartment buildings). Returns bills with the full match by the address
2.24. companies.top10ByRegion*	this method is used to get a list of the TOP 10 companies by `regionId` (partial match)
2.25. companies.top10ByCity*	this method is used to get a list of the TOP 10 companies by `cityId` (partial match)
2.26. companies.top10ByStreet*	this method is used to get a list of the TOP 10 companies by `streetId` (partial match)
2.27. companies.top10ByHouse*	this method is used to get a list of the TOP 10 companies by known `houseId` (full match for house or partial match for apartment)
2.28. companies.top10ByAddress*	this method is used to get a list of the companies by known `houseId` (for private houses) or `apartmentId` (for apartment buildings). Returns bills with the full or partial match by the address
2.29. bills.getreference	this method is used to obtain a list of values of the specified dictionary using the related value from the upper-level dictionary
2.30. bills.update	is a part of method 2.4. bills.pay, is used for update a bill with no change of its status
2.31. bank.params.guaranteeAmount	the method of checking the amount of the guarantee payment for the partner according to the individual login
2.32. bills.recreate	this method to create a copy of a paid invoice
2.33. bills.cancel	this method for canceling payments that are in PAYED status (all versions of the protocol)
2.34. counters.get	мethod for submitting meter readings without payment (for incoming companies) — creating a request
2.35. counters.set	мethod for submitting meter readings without payment (data transmission to the company, readings entered by the customer).

* How to use companies searching methods

If only the regionId is known, use the companies.top10ByRegion method for searching bills by region

If the cityId is known, use the companies.top10ByCity method for searching bills by the specified locality (city)

If the streetId is known, use the companies.top10ByStreet method for searching bills for a specified street

If the houseId is known, use the companies.top10ByHouse method for searching bills for a specified building

If house has apartments (hasApartments=Y) and apartment id is known, use the companies.top10ByAddress method (if there is no full match by the address, the method searches for bills by higher steps (by home, street, city, etc.)) or the search.userDocsByAddress method (returns bills with the full match for search parameter).

2.1. Request for bill delivery

Method: bills.create

Description of the method: the result of calling this method is creating a subscription on the Portmone.com side to receive bills for the required company and return the bill ID (billId - unique payment identifier). The answer contains data about the last available unpaid bill. If the company does not provide invoices, the wallet system creates an invoice for 0 amount and returns it to the partner for payment.

Before calling the bills.create method, you need to pay attention to <balance_source> tag value, obtained during the execution of the bills.payees method. If the value is <balance_source>Y</balance_source> for the company, you should use the bills.create method. In other cases call the bills.createAll method.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
payeeId	ID of the payee company	Yes
contractNumber	The main requisite (identifier) of the client in this company	Yes
billNumber	Order number	No
attribute1-4	For additional information	No

An example of request:

method=bills.create&login=login&password=password&version=2&payeeId=value&contractNumber=value

An example of successful response: see Attachment 1.

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.2. Request for bill delivery by phone number

Method: bills.createByPhone

Description of the method: this method is used to create a bill on the Portmone.com side to add funds to a mobile phone account and return the ID of the payee company (payeeId) and the bill ID (billId).

To pay the bill call the bills.pay method.

Interaction scheme:

The Client enters the mobile phone number on the Partner's website.
The Partner sends this data to the Portmone.com using the bills.createByPhone method.
Portmone.com identifies the ID of the company to which the client’s phone belongs by the mobile network operator code, and sends an XML-message with the ID of the payee company (payeeId) and the bill ID (billId) to the Partner.
The Partner sends the payment request using the bills.pay method.
Portmone.com transfers funds to the service provider.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
payeeId	ID of the payee company	Yes
contractNumber	Phone number to which funds are transferred. Format of the number: 9 digits, without "+380" (for example, 673334411)	Yes
billAmount	Amount of payment (default to 0)	No
billNumber	Order number	No
attribute1-4	For additional information	No

An example of request:

method=bills.createByPhone&login=login&password=password&version=2&contractNumber=value&billAmount=value

An example of successful response:

<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>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.3. Request for delivery of all bills issued for the current month

Method: bills.createAll

Description of the method: to get bills from companies issuing several bills for the current month, use the bills.createAll method. In terms of parameter set, this method is completely identical to the bills.create method.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
payeeId	ID of the payee company	Yes
contractNumber	The main requisite (identifier) of the client in this company	Yes
billNumber	Order number	No
attribute1-4	For additional information	No

An example of request:

method=bills.createAll&login=login&password=password&version=2&payeeId=value&contractNumber=value

An example of successful response: in case of success, the bills section is returned, containing XML described in Attachment 1 for each of the bills.

<?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>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

Main company and recipient companies:

The Portmone.com system allows you to split a payment, that is, crediting the amount of payment received from the client to several recipients (suppliers of goods or service providers).

Main company is a company that you display to the client when paying for a service/product and indicate in requests for getting bills. Such companies are created, for example, in order to group services provided (e.g. a company with payeeId = 8004 and a company with payeeId = 4568).

Recipient company is an active company that provides a service or a product, but it is not displayed to the client.

When you send a request with payeeId of main company, the bills.createAll method returns you bills with the payeeId of recipient companies for which payments will be made.

2.4. Bill payment

Method: bills.pay

Description of the method: performs debiting of funds on the client's payment card.

In the event that the service debt_state <> 'E', then the corresponding debt should not be taken into account in the total amount of payment on the account

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Bill ID. The value returned by the bills.create method (or by the bills.createByPhone method in case of a mobile phone replenishment)	Yes
amount	Amount for payment by order (it may differ from the one proposed in the bill)	Yes
auth_code	Authorization code	No
transaction_id	Transaction ID	No
payment_point	Unique description of a partner sales point	Yes
payer_iban or payer_card_number or payer_phone_number	the sender's iban, who initiates the transfer, takes the value of 29 characters ------------------------------------------------------------------------------ The card, the sender, who initiates the transfer, takes the value of 16 digits ------------------------------------------------------------------------------ Payer's phone number in the format	Yes

An example of request for company without items:

method=bills.pay&login=login&password=password&version=2&billId=value&amount=value&payer_iban=value

method=bills.pay&login=login&password=password&version=2&billId=value&amount=value&payer_card_number=value

An example of successful response:

<?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>

If payer_iban and payer_card_number are missing, the system will return an error

An example of response in case of an error:

<rsp status="fail">
  <error code="р013">Incorrect customer identification parameters</error>
  <error_description>Incorrect customer identification parameters</error_description>
</rsp>

Parameters for "universal" items (transferred into <tariff_items> array):

Parameter	Description	Required
id	Counter ID	Yes
amount	The amount of the counter in UAH	Yes
prev_counter	Previous counter value	No
counter	Current counter value	No
tariff	Tariff value in UAH	No
subsidy	Subsidy in UAH	No
debt	Debt in UAH	No
attribute1	Optional tag (depends on biller) (protocol version - 2)	No
attribute2	Optional tag (depends on biller) (protocol version - 2)	No
attribute3	Optional tag (depends on biller) (protocol version - 2)	No

prev_counter, counter, tariff, subsidy, debt, attribute1, attribute2, attribute3 parameters are transferred if the corresponding tags in the received bill are not empty.

If a parameter is transferred, it must have a value (“empty” parameters are not allowed).

The invoiced amount entirely paid must be equal to the sum of the transferred amount and debt values for all items.

An example of request for company without items:

method=bills.pay&login=login&password=password&version=2&billId=value&amount=value

An example of request for company with items:

?method=bills.pay&login=login&password=password&billId=value&amount=value&
tariff_items[111111][id]=value&tariff_items[111111][counter]=value&
tariff_items[111111][prev_counter]=value&tariff_items[111111][tariff]=value&
tariff_items[111111][subsidy]=value&tariff_items[111111][debt]=value

where tariff_items – the name of the array with data on the items; 111111 – item ID; counter, prev_counter, tariff, subsidy, debt and amount – item data.

An example of successful response: see Attachment 1.

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.5. Information about a bill

Method: bills.get

Description of the method: This method is used when you need to get information about a bill. You need to send request l if the method bills.pay received a connection error, received a response of an unexpected format that does not match the protocol. And also if errors p009, p017, p100 are received. Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Bill ID (the value returned by the bills.create method)	Yes

An example of request:

method=bills.get&login=login&password=password&version=2&billId=value

An example of successful response: see Attachment 1.

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.6. Transactions list

Method: bills.paymentOrder

Description of the method: the registry is transferred by the bank to Portmone.com to control the payments which were sent and to generate the necessary control registries to each organization using the required protocol. Contains a list of transactions and payment details of cover payment.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
xml	Registry in XML format	Yes

An example of registry in XML format:

<?xml version="1.0" encoding="utf-8"?>
<payment_order order_date="DD.MM.YYYY" order_number="Number of payment order"
payee_id="ID of the payee company" total_amount="Amount of payments accepted"
total_compensation="Amount of compensations of payment order"
total_commission="Amount of commissions of payment order" trx_count="2">
	<transactions>
		<trx>
			<bill_id>Bill ID</bill_id>
			<trx_amount>Transaction amount</trx_amount>
			<compensation>Amount transferred to biller</compensation>
		</trx>
		<trx>
			<bill_id>Bill ID</bill_id>
			<trx_amount>Transaction amount</trx_amount>
			<compensation>Amount transferred to biller</compensation>
		</trx>
	</transactions>
</payment_order>

Where total_commission – the amount of the commissions of all transactions of the payment order, total_compensation – the amount of compensation for all transactions of this payment order. For each transaction (<trx>) commission = trx_amount - compensation.

An example of successful response:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<paymentOrder>
		<record id="value"/>
	</paymentOrder>
</rsp>

Successful response – fields description:

Parameter	Description
record id	Payment ID in the Portmone.com system that recorded this message

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

Please note: if the transactions list for a date has not been transferred for any reason (communication timed out, an error message received from the PortmoneDirect system, etc.), this transactions list must be transferred to the next communication session along with the list for the current date.

2.7. Control registry of transactions

Method: bills.date

Description of the method: the method is used to obtain a control registry of transactions for a period (day). Required to control passed / non-passed transactions.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
date	Date for which the registry is displayed. Format: DD.MM.YYYY	Yes

An example of request:

method=bills.date&login=login&password=password&version=2&date=DD.MM.YYYY

An example of successful response:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<bills>
		<bill id="value">
			<name>Short name of the recipient company</name>
			<contractNumber title="value">value</contractNumber>
			<attribute1 title="value">value</attribute1>
			<attribute2 title="value">value</attribute2>
			<attribute3 title="value">value</attribute3>
			<attribute4 title="value">value</attribute4>
			<bill_attribute1>value</bill_attribute1>
			<bill_attribute2>value</bill_attribute2>
			<bill_attribute3>value</bill_attribute3>
			<bill_attribute4>value</bill_attribute4>
			<status>value</status>
			<transaction_id>value</transaction_id>
			<paidAmount>value</paidAmount>
			<payDate>DD.MM.YYYY HH:mm:ss</payDate>
			<payee_export_date>DD.MM.YYYY HH:mm:ss</payee_export_date>
			<payee_export_flag>value</payee_export_flag>
			<bank_commission>value</bank_commission>
			<payee_id>value</payee_id>
		</bill>
	</bills>
</rsp>

Successful response – fields description:

Parameter	Description
bill id	Bill ID (для транзакції устатусі RETURN, bill id набуває нового унікального значення)
сontractNumber title	Number of contract
status	Transaction status on the Portmone.com side. Possible values: PAYED, RETURN
transaction_id	The identifier assigned to the transaction by the partner bank (transferred when calling the bills.pay method). For transactions with RETURN status will take on the original transaction ID value (charge-off)
paidAmount	Amount of payment
payDate	Date of payment
payee_export_date	Date of funds transfer to the service provider
payee_export_flag	Transfer status (possible values: Y, N, R, E)
bank_commission	Bank remuneration in UAH (protocol version – 2). The parameter may takes both positive and negative values
name	Name of the recipient company
payee_id	A unique company identifier (protocol version – 3)

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

An example of a transaction response in the RETURN status:

<bill id="1367371577"> - unique bill id upon return

<name>lifecell</name>

<contractNumber title="Phone number (without +380)">667678994</contractNumber>

<attribute1/>

<bill_attribute1/>

<attribute2/>

<bill_attribute2/>

<attribute3/>

<bill_attribute3/>

<attribute4/>

<bill_attribute4/>

<status>RETURN</status> - return status

<paidAmount>-5.00</paidAmount> - return amount, a negative value

<payDate>28.03.2023 16:04:01</payDate> - payment date 

<transaction_id>1367371282</transaction_id> - bill ID of the original transaction for which the return was made

<payee_export_date>28.03.2023 16:04:01</payee_export_date> - return date and time

<payee_export_flag/>

<bank_commission>-0.50</bank_commission>

2.8. Control registry of funds transferred to the service provider

Method: bills.exported

Description of the method: the method is used to obtain a control registry of transactions for a period (day), the funds for which were sent to the service provider (biller). Required to control the binding of funds.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
payeeId	Company ID	Yes
date	Date for which the registry is displayed. Format: DD.MM.YYYY	Yes

An example of request:

method=bills.exported&login=login&password=password&version=2&payeeId=value&date=DD.MM.YYYY

An example of successful response:

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

Successful response – fields description:

Parameter	Description
bill id	Bill ID
сontractNumber title	Number of contract
status	Transaction status on the Portmone.com side. Possible values: PAYED, RETURN
transaction_id	The identifier assigned to the transaction by the partner bank (transferred when calling the bills.pay method). For transactions with RETURN status will take of the original transaction ID value (charge-off)
paidAmount	Amount of payment
payDate	Date of payment
payee_export_date	Date of funds transfer to the service provider
payee_export_flag	Transfer status (possible values: Y, N, R, E)

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.9. Request for data on the reseller company balance

Method: bills.balance

Description of the method: this method is used to view the current balance of the biller company (PAYEE).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
payeeId	ID of the company for which the balance is requested	Yes

An example of request:

method=bills.balance&login=login&password=password&version=2&payeeId=value

An example of successful response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
	<payee id="value">
		<balance>value</balance>
	</payee>
</rsp>

Successful response – fields description:

Parameter	Description
payee id	ID of the company for which the balance is requested
balance	The balance of the company

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.10. Request for information on available biller companies

Method: bills.payees

Description of the method: the method is used to get biller* (PAYEE) parameters. By default, all data on available companies at the current moment is downloaded. When adding the optional LastUpdateDate parameter, only data that has had any changes since the specified date.

When adding the additional parameter LastUpdateDate and deleted with the value on at the same time, only the company is deactivated starting from the date in the parameter LastUpdateDate

*from among those for whom payment terminals have been established for this login.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
LastUpdateDate	Date from which any changes were made. Format: DD.MM.YYYY	No
deleted	Deactivated companies	No

An example of request:

method=bills.payees&login=login&password=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

Successful response structure:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
    <payee id="value">
        <header_payee> Used by some partners </header_payee>
        <merchant> Used by some partners </merchant>
        <terminal> Used by some partners </terminal>
        <name> Short name of the recipient company (for menu items)</name>
        <name_in_check> Legal name of the recipient company </name_in_check>
        <image_file> Link to company logo </image_file>
        <contact_info> The contact person </contact_info>
        <zkpo> EDRPO code of the company </zkpo>
        <bank_name> Bank name of the recipient company </bank_name>
        <bank_code> MFO of the bank of the recipient company </bank_code>
        <bank_account> Account number or IBAN of the recipient company bank
        </bank_account>
        <contract_number_title> Name of the 1st contract detail </contract_number_title>
        <contract_number_type> Type of the 1st contract detail (N - numeric; C - string;
        P – payment card; R, L - hierarchical dictionary) </contract_number_type>
        <related_references>
                <reference id="Dictionary ID" order_number="Order number">
                    Dictionary name</reference>
        </related_references>
        <contract_number_size> Size of the 1st contract detail </contract_number_size>
        <contract_number_hint> Hint to the client for entering the first contract detail
        </contract_number_hint>
        <contract_number_mask> Input mask for the first contract detail 
        </contract_number_mask>
        <attributes>
	        <attribute1>
		        <title> Attribute name </title>
		        <type> Attribute type (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary) </type>
   		        <size> Maximum size </size>
                <related_references>
                        <reference id="Dictionary ID" order_number="Order number">
                            Dictionary name</reference>
                </related_references>
	        </attribute1>
	        <attribute2>
		        <title> Attribute name </title>
		        <type> Attribute type (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary) </type>
		        <size> Maximum size </size>
                <related_references>
                        <reference id="Dictionary ID" order_number="Order number">
                            Dictionary name</reference>
                </related_references>
	        </attribute2>
	        <attribute3>
		        <title> Attribute name </title>
		        <type> Attribute type (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary) </type>
		        <size> Maximum size </size>
                <related_references>
                        <reference id="Dictionary ID" order_number="Order number">
                            Dictionary name</reference>
                </related_references>
	        </attribute3>
	        <attribute4>
		        <title> Attribute name </title>
		        <type> Attribute type (N - numeric; C - character; D - data;
                    R, L - hierarchical dictionary) </type>
		        <size> Maximum size </size>
                <related_references>
                        <reference id="Dictionary ID" order_number="Order number">
                            Dictionary name</reference>
                </related_references>
	        </attribute4>
	    </attributes>
	    <min_pay_amount> The size of the minimum payment </min_pay_amount>
	    <pay_round_amount> Whether to allow payments with kopecks (Y - only whole sums,
        N - allow sums with kopecks) </pay_round_amount>
	    <pay_different_amount> Whether to allow payment with the amount different from
        that obtained in the bill (Y, N) </pay_different_amount>
	    <payee_group_id> ID of the type of services provided by biller </payee_group_id>
	    <payee_group_name> Type of services provided by biller </payee_group_name>
	    <bill_source> The company allows payment of bills (Y, N) (payment by
        invoices) </bill_source>
	    <balance_source> The company allows the replenishment of the balance (Y, N)
       (payment without invoice) </balance_source>
	    <pay_order_description_format> Pay order description format
        </pay_order_description_format>
	    <billing_day> Date of loading bills(protocol version – 2) </billing_day>
	    <max_pay_amount> Maximum payment amount(protocol version – 2) </max_pay_amount>
	    <bank_tariff> Bank remuneration, which must be converted to a percentage
        (protocol version  – 2) </bank_tariff>
        <bank_tariff (value with minus)>FC reward to be converted into interest 
            (protocol version  – 2)</bank_tariff>
	    <bank_amount> Portmone remuneration in UAH (protocol version – 2) </bank_amount>
	    <min_bank_amount> The minimum amount of the Portmone remuneration from each
        transaction, in UAH (protocol version – 2) </min_bank_amount>
        <min_bank_amount (value with minus)>Not used (protocol version – 2)</min_bank_amount>
	    <max_bank_amount> Currently not used (protocol version – 2) </max_bank_amount>
	    <bank_deduction> Currently not used (protocol version – 2) </bank_deduction>
	    <bank_deduction_amount> Remuneration of the bank, which is held by the bank before
        sending coverage. This value must be converted to percentage
        (protocol version – 2) </bank_deduction_amount>
	    <min_bank_deduction_amount> Currently not used (protocol version – 2)
        </min_bank_deduction_amount>
	    <max_bank_deduction_amount> Currently not used (protocol version – 2)
        </max_bank_deduction_amount>
        <hide> Recipient company that is not displayed to clients
            (protocol version - 2)</hide>
        <payee_groups>
            <payee_group id="1001">Type of services provided by biller: Mobile Communication</payee_group>
            <payee_group id="1003">Type of services provided by biller: Internet</payee_group>
            <payee_group id="1006">Type of services provided by biller: telephony</payee_group>
        </payee_groups> (protocol version – 3)
		 <payee_group_name> name of the group to which the service belongs </payee_group_name> (protocol version – 2 or more)
		 <service_in_check> the name of the service for the receipt </service_in_check> (protocol version – 2 or more)
		 
    </payee>
…
</rsp>

Note!
The <hide> parameter:
<hide>N</hide> - the main (front) company, designed to display the service for the client
<hide>Y</hide> - hidden service, hidden when displayed for the client

The parameter <image_file> must be analyzed only for the main (cap) companies on which `N`` is passed. The URL of the source from where the logo can be downloaded is specified in image_file.

Parameter <pay_different_amount> Whether to allow payment for an amount different from that received in the account (Y, N) (protocol version – 1) </pay_different_amount>
Important! in the absence of "universal" items (passed in the tariff_items array) in the response to the bills.create/bills.createAll method (protocol version - 2 and more) </pay_different_amount> is analyzed by <pay_different_amount>

Dictionaries

For fields attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type, values R and L are possible.

This means that the corresponding fields attribute1, attribute2, attribute3, attribute4, contract_number have a complex data type and the values of these fields must be formed on the basis of hierarchical directories.

That is, if any of the attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type fields is either R or L, you must call bills.getreference method with the appropriate parameters to obtain the end hierarchy level and find the identifier / value of the dictionary item.

After that, use the bills.create method to create the bill with correct payment details. Use the identifier of the dictionary item (<item id>) obtained for the end dictionary level (for R-type field) or value (<name>) of the dictionary item (for L-type field) and send them at the appropriate request field (attribute1, attribute2, attribute3, attribute4, contract_number).

An example of the R-type dictionary:

<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>

where:

<related_references> – describes a hierarchy of dictionaries;

<reference id> – a unique dictionary identifier in the Portmone.com system (integer);

<reference order_number="1"> – dictionary sequence number in the hierarchy (ascending; integer);

<reference></reference> – name of the current dictionary level for the client (string).

For the L-type dictionary, the response will look the same, except for the value of the contract_number_type parameter.

Examples of using dictionaries are give in Section 5 "Examples" (Using R-type dictionaries, Using L-type dictionaries).

An example of successful response:

<?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 - an optional parameter, passed in case the parent company uses linked dictionaries. header_payee - parameter for binding companies, passed only in the response to the bills.payees method. Indicates to which main company the current payee id belongs. The parameter exists only for protocol versions – 2, 3. For main companies, this field will be empty.

Please note When money transfer document contains two payment details (account number of the recipeient company bank and MFO of the bank), MFO of recipient's bank is transferred in the bank_code field. When the IBAN account number is used in payment details, a "0" (zero) is transferred in the bank_code field.

Recipient's bank account number or IBAN of a recipient (depending on payment details filled out in money transfer document) is transferred in the bank_account field. Note that not only numbers but also letters will be contained in this field, according to the IBAN format (29 alphanumeric characters).

The merchant parameter will be transferred to Payany if the company provides services without a direct agreement.

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.11. Request for information on biller companies in the context of regions

Method: bills.regions

Description of the method: the method is used to obtain a list of available* regions and a list of billers (PAYEE) for each region.

*from among those for whom payment terminals have been established for this login.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes

An example of request:

method=bills.regions&login=login&password=password&version=2

An example of successful response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
   <regions>
	<region id="value">
	   <name>Name of the region (for example, Kyiv)</name>
	   <payees>
		<payee id="value">
		  <name>Company name (for example, VOLIA Broadband, Kyiv)</name>
		</payee>
		…
	   </payees>
	</region>
	…
   </regions>
</rsp>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.12. Request for companies providing bills for a client, by a previously received bill

Method: bills.additionalPayees

Description of the method: this method is used to get a list of companies for which the client can pay bills. After a client has received the requested bill, you can request a list of companies and client IDs in these companies that provide services at the same address. If the returned list is not empty, you can offer a client to choose companies whose bills they want to pay and request these bills using the standard method. Companies search is carried out at the client's address.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Bill ID (the value returned by the bills.create method)	Yes

An example of request:

method=bills.additionalPayees&login=login&password=password&version=2&billId=value

An example of successful response:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
	<payee id="ID of the company whose bill can be offered to the client">
	   <contract_number> client’s ID in this company </contract_number>
	   <attribute1> additional client’s identifier in this company	</attribute1>
	   <attribute2> additional client’s identifier in this company	</attribute2>
	   <attribute3> additional client’s identifier in this company	</attribute3>
	   <attribute4> additional client’s identifier in this company	</attribute4>
	</payee>
</rsp>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.13. Request for information about regions

Method: search.regions

Description of the method: this method is used to obtain a complete list of regions of Ukraine.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes

An example of request:

method=search.regions&login=login&password=password&version=2

An example of successful response:

<?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>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.14. Request for information about regions (with a filter by region name)

Method: search.regionsExtended

Description of the method: this method is used to obtain a list of regions of Ukraine with additional filtering by region name.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
searchQuery	Substring for filtering by name (specify the part of region name, from 3 characters)	Yes

An example of request:

method=search.regions&login=login&password=password&version=2&searchQuery=filter

An example of successful response:

<?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>

An example of response in case of an error (if searchQuerry is not specified):

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="p019">
    <![CDATA[ Server error while processing the request ]]>
    </error>
    <error_description>
    <![CDATA[ search.regionsExtended p019 ]]>
    </error_description>
</rsp>

2.15. Request for information about cities in the region

Method: search.citiesByRegion

Description of the method: this method is used to get a list of cities for the specified region.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
regionId	ID of the region obtained using the search.regions method or the search.regionsExtended method	Yes

An example of request:

method=search.citiesByRegion&login=login&password=password&version=2&regionId=regionID

An example of successful response:

<?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>

Pay attention! The city id parameter in the response may take negative values

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
    <error code="p022">
    <![CDATA[ Incorrect param regionId (citiesByRegion) ]]>
    </error>
    <error_description>
    <![CDATA[ search.citiesByRegion p022 ]]>
    </error_description>
</rsp>

2.16. Request for information about cities in the region (with a filter by city name)

Method: search.citiesByRegionExtended

Description of the method: this method is used to get a list of cities for the specified region with additional filtering by city name.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
regionId	ID of the region obtained using the search.regions method or the search.regionsExtended method	Yes
searchQuery	Substring for filtering by city name, from 3 characters	Yes

An example of request:

method=search.citiesByRegionExtended&login=login&password=password&version=2&regionId=
regionID&searchQuery=filter

An example of successful response:

<?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>

Pay attention! The city id parameter in the response may take negative values

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.17. Request for information about the city streets

Method: search.streetsByCity

Description of the method: this method is used to get a list of streets for the specified city.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
cityId	ID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended method	Yes

An example of request:

method=search.streetsByCity&login=login&password=password&version=2&cityId=cityID

An example of successful response:

<?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>

Pay attention! The street id parameter in the response may take negative values

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.18. Request for information about the city streets (with a filter by street name)

Method: search.streetsByCityExtended

Description of the method: this method is used to get a list of streets for the specified city with additional filtering by street name.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
cityId	ID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended method	Yes
searchQuery	Substring for filtering by street name, from 3 characters	Yes

An example of request:

method=search.streetsByCityExtended&login=login&password=password&version=2&cityId=cityID
&searchQuery=filter

An example of successful response:

<?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>

Pay attention! The street id parameter in the response may take negative values

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.19. Request for information about the street buildings

Method: search.housesByStreet

Description of the method: this method is used to get a list of buildings for the specified street.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
streetId	ID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended method	Yes

An example of request:

method=search.housesByStreet&login=login&password=password&version=2&streetId=streetID

An example of successful response:

<?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>

Pay attention!

The house id parameter in the response may takes negative values

The hasApartments parameter identifies if the house has apartments (possible values: Y – this house has apartments, N – this house is private and further search for apartments is not possible)

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.20. Request for information about the street buildings (with a filter by building number)

Method: search.housesByStreetExtended

Description of the method: this method is used to get a list of buildings for the specified street with additional filtering by building number.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
streetId	ID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended method	Yes
searchQuery	Substring for filtering by building number (specify house number)	Yes

An example of request:

method=search.housesByStreetExtended&login=login&password=password&version=2&streetId=
streetID&searchQuery=filter

An example of successful response:

<?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>

Pay attention!

The house id parameter in the response may takes negative values

The hasApartments parameter identifies if the house has apartments (possible values: Y – this house has apartments, N – this house is private and further search for apartments is not possible)

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.21. Request for information about apartments at the building

Method: search.apartmentsByHouse

Description of the method: this method is used to obtain a list of apartments by known houseId. For apartment buildings only (hasApartments=Y).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
houseId	ID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended method	Yes

An example of request:

method=search.apartmentsByHouse&login=login&password=password&version=2&houseId=buildingID

An example of successful response:

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

An example of response in case of an error:

<?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. Request for information about apartments at the building (with a filter by apartment number)

Method: search.apartmentsByHouseExtended

Description of the method: this method is used to obtain a list of apartments by known houseId with additional filtering by apartment number. For apartment buildings only (hasApartments=Y).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
houseId	ID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended method	Yes
searchQuery	Substring for filtering by apartment number (specify the apartment number)	Yes

An example of request:

method=search.apartmentsByHouseExtended&login=login&password=password&version=2&houseId=buildingID
&searchQuery=filter

An example of successful response:

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

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.23. Request for context information at the address (a list of bills)

Method: search.userDocsByAddress

Description of the method: this method is used to obtain a list of bills by known houseId (for private houses) or apartmentId (for apartment buildings). Returns bills with the full match by the address.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
addressId	ID of the building or ID of the apartment	Yes

Important!

For houses that have apartments (hasApartments=Y), addressId = apartment id (the value of apartment id is returned by the search.apartmentsByHouse and the search.apartmentsByHouseExtended methods).

For private houses (hasApartments=N), addressId = house id (the value of the house id is returned by the search.housesByStreet method and the search.housesByStreetExtended method).

An example of request:

method=search.userDocsByAddress&login=login&password=password&version=2&addressId=apartmentID

An example of successful response:

<?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>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.24. Searching for companies in a specified region

Method: companies.top10ByRegion

Description of the method: this method is used to get a list of the TOP 10 companies by regionId (partial match).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
regionId	ID of the region obtained using the search.regions method or the search.regionsExtended method	Yes

An example of request:

method=companies.top10ByRegion&login=login&password=password&version=2&regionId=regionID

An example of successful response:

<?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>

Successful response – fields description:

Parameter	Description
PAYEE_ID	A unique company identifier
NAME	Company name
CONTRACT_NUMBER	The main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLE	Name of the client identifier in the company
CONTRACT_NUMBER_TYPE	Type of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZE	Size of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Attribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Attribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Attribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	The ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGE	File name with company logo
MATCH_TYPE	Match type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAY	If `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, this field contains dictionary
ATTRIBUTE1_ARRAY	If `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, this field contains dictionary
ATTRIBUTE2_ARRAY	If `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, this field contains dictionary
ATTRIBUTE3_ARRAY	If `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, this field contains dictionary
ATTRIBUTE4_ARRAY	If `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, this field contains dictionary

2.25. Searching for companies in the specified locality (city)

Method: companies.top10ByCity

Description of the method: this method is used to get a list of the TOP 10 companies by cityId (partial match).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
cityId	ID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended method	Yes

An example of request:

method=companies.top10ByCity&login=login&password=password&version=2&cityId=cityID

An example of successful response:

<?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>

Successful response – fields description:

Parameter	Description
PAYEE_ID	A unique company identifier
NAME	Company name
CONTRACT_NUMBER	The main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLE	Name of the client identifier in the company
CONTRACT_NUMBER_TYPE	Type of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZE	Size of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Attribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Attribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Attribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	The ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGE	File name with company logo
MATCH_TYPE	Match type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAY	If `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, this field contains dictionary
ATTRIBUTE1_ARRAY	If `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, this field contains dictionary
ATTRIBUTE2_ARRAY	If `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, this field contains dictionary
ATTRIBUTE3_ARRAY	If `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, this field contains dictionary
ATTRIBUTE4_ARRAY	If `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, this field contains dictionary

2.26. Searching for companies for a specified street

Method: companies.top10ByStreet

Description of the method: this method is used to get a list of the TOP 10 companies by streetId (partial match).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
streetId	ID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended method	Yes

An example of request:

method=companies.top10ByStreet&login=login&password=password&version=2&streetId=streetID

An example of successful response:

<?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>

Successful response – fields description:

Parameter	Description
PAYEE_ID	A unique company identifier
NAME	Company name
CONTRACT_NUMBER	The main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLE	Name of the client identifier in the company
CONTRACT_NUMBER_TYPE	Type of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZE	Size of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Attribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Attribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Attribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	The ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGE	File name with company logo
MATCH_TYPE	Match type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAY	If `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, this field contains dictionary
ATTRIBUTE1_ARRAY	If `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, this field contains dictionary
ATTRIBUTE2_ARRAY	If `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, this field contains dictionary
ATTRIBUTE3_ARRAY	If `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, this field contains dictionary
ATTRIBUTE4_ARRAY	If `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, this field contains dictionary

2.27. Searching for companies for a specified building

Method: companies.top10ByHouse

Description of the method: this method is used to get a list of the TOP 10 companies by known houseId (full match for house or partial match for apartment).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
houseId	ID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended method	Yes

An example of request:

method=companies.top10ByHouse&login=login&password=password&version=2&houseId=buildingID

An example of successful response:

<?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>

Successful response – fields description:

Parameter	Description
PAYEE_ID	A unique company identifier
NAME	Company name
CONTRACT_NUMBER	The main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLE	Name of the client identifier in the company
CONTRACT_NUMBER_TYPE	Type of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZE	Size of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Attribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Attribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Attribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	The ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGE	File name with company logo
MATCH_TYPE	Match type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAY	If `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, this field contains dictionary
ATTRIBUTE1_ARRAY	If `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, this field contains dictionary
ATTRIBUTE2_ARRAY	If `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, this field contains dictionary
ATTRIBUTE3_ARRAY	If `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, this field contains dictionary
ATTRIBUTE4_ARRAY	If `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, this field contains dictionary

2.28. Searching for companies by the address

Method: companies.top10ByAddress

Description of the method: this method is used to get a list of the companies by known houseId (for private houses) or apartmentId (for apartment buildings). Returns bills with the full or partial match by the address. If there is no full match by the address, the method searches for bills by higher steps (by home, street, city, etc.).

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
addressId	ID of the building or ID of the apartment	Yes

Important!

For houses that have apartments (hasApartments=Y), addressId = apartment id (the value of apartment id is returned by the search.apartmentsByHouse and the search.apartmentsByHouseExtended methods).

For private houses (hasApartments=N), addressId = house id (the value of the house id is returned by the search.housesByStreet method and the search.housesByStreetExtended method).

An example of request:

method=companies.top10ByAddress&login=login&password=password&version=2&addressId=apartmentID

An example of successful response:

<?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>

Successful response – fields description:

Parameter	Description
RWD	A system parameter that indicates that the account is related to the user and the user's address
PAYEE_ID	A unique company identifier
NAME	Company name
CONTRACT_NUMBER	The main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLE	Name of the client identifier in the company
CONTRACT_NUMBER_TYPE	Type of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZE	Size of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4	Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLE	Attribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPE	Attribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZE	Attribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFO	The ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGE	File name with company logo
MATCH_TYPE	Match type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAY	If `<CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>`, this field contains dictionary
ATTRIBUTE1_ARRAY	If `<ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>`, this field contains dictionary
ATTRIBUTE2_ARRAY	If `<ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>`, this field contains dictionary
ATTRIBUTE3_ARRAY	If `<ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>`, this field contains dictionary
ATTRIBUTE4_ARRAY	If `<ATTRIBUTE4_TYPE>L</ATTRIBUTE4_TYPE>`, this field contains dictionary

2.29. Getting dictionary values

Method: bills.getreference

Description of the method: this method is used to obtain a list of values of the specified hierarcical dictionary using the related value from the upper-level hierarchy data.

If any of the attribute1_type, attribute2_type, attribute3_type, attribute4_type, contract_number_type fields at the bills.payees response is either R or L, you must call bills.getreference method with the appropriate parameters to obtain the end hierarchy level and find the identifier / value of the dictionary item.

Method parameters:

Parameter	Description	Required
referenceId	A unique dictionary identifier in the Portmone.com system. Integer	Yes
parentReferenceId	ID of the parent dictionary item (at the response of the bills.getreference method – `<item id>`). Optional parameter for superior level dictionary ID and required for all subsequent requests. Integer	Yes/No

An example of request:

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

An example of successful response:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="ok">
    <reference id="1183">
        <name>(Податки) Єдиний податок для фізичних осіб-підприємців. Райони</name>
        <description>(Податки) Єдиний податок для фізичних осіб-підприємців. Райони
        </description>
        <parent_reference_id>42809</parent_reference_id>
        <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>

Successful response – fields description:

Parameter	Description	Type
items	List of dictionary items
item id	Dictionary item ID. Used to get children (if the level is not the last) or to call the bills.create method in case of the R-type field (if the level is the last)	Int
name	Dictionary item value. Used to be displayed to the client or to call the bills.create method in case of L-type field	String
description	Additional description of the dictionary item. Required if not empty	String
parent_item_id	ID of the parent dictionary item obtained from a previous bills.getreference method call	Int

After finding the end level of the hierarchy and selecting the necessary row in the list by the client, the bills.create method must be called to create the bill. Use the identifier of the dictionary item (item id) obtained for the end dictionary level (for R-type field) or value (name) of the dictionary item (for L-type field) and send them at the appropriate request field (attribute1, attribute2, attribute3, attribute4, contract_number).

Examples of using the method are given in Section 5 “Examples” (Using R-type dictionaries, Using L-type dictionaries).

2.30. Bill update

Method: bills.update

Description of the method: performs a bill update.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Bill ID. The value returned by the bills.create method (or by the bills.createByPhone method in case of a mobile phone replenishment)	Yes

Parameters for "universal" items (transferred into <tariff_items> array):

Parameter	Description	Required
id	Counter ID	Yes
amount	The amount of the counter in UAH	Yes
prev_counter	Previous counter value	No
counter	Current counter value	No
tariff	Tariff value in UAH	No
subsidy	Subsidy in UAH	No
debt	Debt in UAH	No
attribute1	Optional tag (depends on biller) (protocol version - 2)	No
attribute2	Optional tag (depends on biller) (protocol version - 2)	No
attribute3	Optional tag (depends on biller) (protocol version - 2)	No

prev_counter, counter, tariff, subsidy, debt, attribute1, attribute2, attribute3 parameters are transferred if the corresponding tags in the received bill are not empty.

If a parameter is transferred, it must have a value (“empty” parameters are not allowed).

An example of request for company without items:

method=bills.pay&login=login&password=password&billId=value

An example of request for company with items:

?method=bills.pay&login=login&password=password&billId=value&
tariff_items[111111][id]=value&tariff_items[111111][counter]=value&
tariff_items[111111][prev_counter]=value&tariff_items[111111][tariff]=value&
tariff_items[111111][subsidy]=value&tariff_items[111111][debt]=value

where tariff_items – the name of the array with data on the items; 111111 – item ID; counter, prev_counter, tariff, subsidy, debt – item data.

An example of a successful response:

<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>

An example of response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<rsp status="fail">
	<error code="Error code">Error description</error>
</rsp>

2.31. Checking the amount of the guarantee payment

Method: bank.params.guaranteeAmount

Description of the method: with the help of this method it is possible to check the amount of the guarantee payment.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
version	Version API	Yes
lang	lang	No

An example of request

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

An example of a successful response:

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

where amount_guarantee_payment – the amount of the guarantee payment in hryvnias per partner.

In the event that the amount of the guarantee payment is not available for the partner according to the provided login, the answer looks like this:

<rsp status="ok">

<params> <amount_guarantee_payment/> </params>

</rsp>

2.32. Creating a copy of a paid invoice

Method: bills.recreate

Description of the method: with this method it is possible to make copies of the paid bill and return a new bill ID (billId). .

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Paid invoice ID	Yes
version	Version API	Yes
lang	lang	No

An example of request

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

An example of a successful response:

<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>

An example of response in case of an error:

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

2.33. Cancellation of payments that are in PAYED status

Method: bills.cancel

Description of the method: using this method, it is possible to cancel payments that are in PAYED status

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
billId	Paid invoice ID	Yes
version	Version API	Yes
lang	lang	No

An example of request

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

An example of a successful response:

<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.Мethod for submitting meter readings without payment (for incoming companies) — creating a request

Method: counters.get

Description of the method: Using this method, it is possible to create a request for submitting meter readings without payment.

The method works similarly to the bills.createAll or bills.create methods, where attributes for the company are passed from bills.payees.

Method parameters:

Parameter	Description	Required
payeeId	ID of the payee company	Yes
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
contractNumber	The main requisite (identifier) of the client in this company	Yes
attribute1-4	For additional information	Yes
version	Version API	Yes
lang	lang	No

An example of request

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

An example of a successful response:

<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>

An example of response in case of an error:

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

2.35.Method for submitting meter readings without payment (data transmission to the company, readings entered by the customer).

Method: counters.set

Description of the method: Using this method, it is possible to submit meter readings without payment.

Method parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method	Yes
counters	Meter reading.	Yes
version	Version API	Yes
lang	lang	No

An example of request

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

An example of a successful response:

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

An example of response in case of an error:

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

3. Replenishment of bank cards (Account-2-Card)

Portmone.com payment system provides possibility to replenish individuals cards from a bank account by card number.

3.1. Verification of the customer's card

Partner authentication using the login and password of the account obtained when registering on the Portmone.com system. The request with required parameters is formed on the partner's side and transferred by POST method to URL https://www.portmone.com.ua/r3/verification/card/.

Parameters:

Parameter	Description	Required
login	Your company login in the Portmone.com system	Yes
password	Your company password in the Portmone.com system	Yes
method	A name of the method – verification	Yes
success_url	The URL of the partner to which the client will be redirected after successful verification. After successful verification Portmone.com will send parameters for the next step to this address using POST method.	Yes

An example of request:

<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>

In case of a successful partner authentication, the client goes to the payment card verification page. There the client enters the payment card number, its expiration date and CVV2-code, then presses "Verify":

Payment card verification page

At the next step the client enters the VCODE (verification code), obtained from the SMS-message sent by the card issuing bank:

Page for entering VCODE

In case of successful verification the following data will be sent to the success_url specified in the request:

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

where:

CARD_MASK – client's card mask (first 6 and last 4 digits of the number);

SHOP_BILL_ID – a unique identifier (Id) assigned to every transaction in the Portmone.com system;

RECIPIENT_ID – Id of the recipient in the Portmone.com system.

3.2. Replenishment of the customer's card

Using the PortmoneDirect protocol, follow these steps for crediting funds to the card:

Call the bills.create method with the following parameters:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.create
payeeId	ID of the payee company
contractNumber	Client's card mask (first 6 and last 4 digits of the number in 444433XXXXXX1111 format)
attribute1	It should be equal to the `recipient_id` value received in the verification response
attribute2	It should be equal to the `shop_bill_id` value received in the verification response
payer_iban or payer_card_number	the sender's iban, who initiates the transfer, takes the value of 29 characters ------------------------------------------------------------------------------ The card, the sender, who initiates the transfer, takes the value of 16 digits

In response, an invoice for the amount of 0 UAH will be generated with the assignment of a unique identifier – billId.

Call the bills.pay method using the following parameters:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.pay
billId	Bill ID (the value returned by the bills.create method)
amount	Amount to be paid (amount that will be credited to the card)

Call the bills.get method to get transaction status information:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.get
billId	Bill ID (the value returned by the bills.create method)

Important! The response that the Portmone.com system returns to the status request using the bills.get method contains additional information about the success of funds transfer from our acquirer – the attribute payee_export_flag.

If the bill has status=’PAYED’, but payee_export_flag = ’E’, it means that the payment by the bill is accepted, but the funds have not yet been credited to the client (the bill is in the process of payment). Therefore, it is necessary to continue to request the bill payment status from the Portmone.com system for a couple of hours until one of the following statuses is received:

status=’PAYED’ and payee_export_flag=’Y’ – payment at the acquiring bank side is successful and the funds are credited to the client, or

status=’CANCELED’ – funds cannot be credited to the client’s card.

Pay attention! When using the card replenishment service, the Partner must obtain a control registry of transactions for a period (day) using the bills.date method and send the registers to the Portmone.com using the bills.paymentOrder method.

3.3. Replenishment of the customer's card by full card number

Using the PortmoneDirect protocol, follow these steps for crediting funds to the card:

Call the bills.create method with the following parameters:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.create
payeeId	ID of the payee company
contractNumber	Full recipient card number (for example, 4444333322221111)
attribute1	It should be equal to the `recipient_id` value received in the verification response
attribute2	It should be equal to the `shop_bill_id` value received in the verification response
payer_iban or payer_card_number	the sender's iban, who initiates the transfer, takes the value of 29 characters ------------------------------------------------------------------------------ The card, the sender, who initiates the transfer, takes the value of 16 digits

In response, an invoice for the amount of 0 UAH will be generated with the assignment of a unique identifier – billId.

Call the bills.pay method using the following parameters:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.pay
billId	Bill ID (the value returned by the bills.create method)
amount	Amount to be paid (amount that will be credited to the card)

Call the bills.get method to get transaction status information:

Parameter	Description
login	Your company login in the Portmone.com system
password	Your company password in the Portmone.com system
method	A name of the method – bills.get
billId	Bill ID (the value returned by the bills.create method)

Important! The response that the Portmone.com system returns to the status request using the bills.get method contains additional information about the success of funds transfer from our acquirer – the attribute payee_export_flag.

If the bill has status=’PAYED’, but payee_export_flag = ’E’, it means that the payment by the bill is accepted, but the funds have not yet been credited to the client (the bill is in the process of payment). Therefore, it is necessary to continue to request the bill payment status from the Portmone.com system for a couple of hours until one of the following statuses is received:

status=’PAYED’ and payee_export_flag=’Y’ – payment at the acquiring bank side is successful and the funds are credited to the client, or

status=’CANCELED’ – funds cannot be credited to the client’s card.

Pay attention! When using the card replenishment service, the Partner must obtain a control registry of transactions for a period (day) using the bills.date method and send the registers to the Portmone.com using the bills.paymentOrder method.

4. Error codes list

Error code	Error message	Description	Method
o001	Bill creation error	Bill creation error (internal error code)	bills.create
o003	An error occurred while paying the bill	An error occurred while paying the bill	bills.pay
o003	An error occurred while canceling the bill	An error occurred while canceling the bill (Bill not found)	bills.pay
o003	Bill creation error	Bill creation error (internal error code)	Bills.recreate
o004	Error displaying control registry	Error displaying control registry	bills.paymentOrder
o006	Error displaying company balance	Error displaying company balance	bills.balance
o010	No payees for login	Error while searching company	bills.additionalPayees
p03	Invalid customer identification parameters	An error occurred while paying the bill	bills.pay
p001	Invalid method name	Invalid method name	All methods
p002	Invalid login/password	Invalid login/password	All methods
p003	Subscription creation error	Subscription creation error (internal error code)	bills.create
p003	System error. Please contact technical support for assistance.	System error. Please contact technical support for assistance.	bills.recreate
p003	Bill to update not found.	Bill to update not found.	bills.recreate
p003	The bill to be updated is unpaid.	The bill to be updated is unpaid.	bills.recreate
p003	The company allows balance top-ups. Please use the standard method for obtaining bills.	The company allows balance top-ups. Please use the standard method for obtaining bills.	bills.recreate
p003	You already have an unpaid bill [BILL_ID=XXXXXX]	You already have an unpaid bill [BILL_ID=XXXXXX]	bills.recreate

|p004|Updating counter parameters error|Updating counter parameters error|bills.pay| |p005|The subscription has "ERROR" status|The billing company returned an error message for this subscription, or when attempting to repeat the subscription with incorrect details|bills.create| |p006|Company doesn’t exist|There is no billing company with such ID in the Portmone.com database|bills.create| |p007|Subscription created. Waiting for response from the company.|A subscription is created (“CREATED”), but there is no confirmation from the billing company that the provided information is valid (if the billing company responds that the information sent is not correct, the subscription status will be changed to “ERROR”).|bills.create| |p008|You do not have any unpaid bills. Wait for invoice from your service provider.|Subscription created but no bills yet |bills.create| |p009|The bill doesn’t exist|There is no bill with such ID in the Portmone.com database (internal error code)|bills.get| |p010|No bills for date|No bills for this date (internal error code)|bills.date
bills.exported| |p011|Empty or damaged registry received|Empty or damaged registry received|bills.paymentOrder| |p012|Empty POST|Received POST array is empty|All methods| |p014|Company quota exceeded|Company quota exceeded (internal error code)|bills.pay| |p015|Error when checking the validity of the subscription|Returned when details of the previously created subscription are no longer valid (for example, the phone number is deactivated by the biller) (internal error code)|bills.create| |p015|Invalid date format|Invalid date format (internal error code)|bills.date
bills.exported| |p017|Error requesting bill information|It is impossible to obtain information about the bill (for example, the bill is currently blocked by the payment session) (internal error code)|bills.get| |p018||To get bills for this company, you must use the bills.createAll method|bills.create| |p019||A general error for all search.* methods|search.*| |p022|Reference not found|A general error for all search.* methods|search.*| |p032|Error while searching data. You may try to find apartments by private house|Error while searching data. Data (apartments) not found|search.apartmentsByHouse, search.apartmentsByHouseExtended| |p033|The phone number format must match the format +38ХХХХХХХХХХ| |p100|Internal database error|Internal system error. When this error occurs, a mandatory subsequent call to the bills.get, method is required, since in this case the bill status is unknown – the bill can be either paid or not paid.|All methods|

5. Examples

An example of using PortmoneDirect methods for getting a customer's geographic information (region, city, street, house and/or apartment IDs)

Search by address: м. Київ, проспект Бажана, буд. 1а, кв.4 (Kyiv, Mykoly Bazhana Ave, 1A, 4)

1. Searching for Kyiv region (searchQuery=Ки)

POST method=search.regionsExtended&login=login&password=password&version=2&searchQuery=Ки

Result: regionId = 44

2. Search for Kyiv city in the Kiev region (regionId = 44, searchQuery=Ки)

POST method=search.citiesByRegionExtended&login=login&password=password&version=2&regionId=44&searchQuery=Ки

Result: cityId = 22

3. Search for a street in the city (cityId = 22, searchQuery=баж)

POST method=search.streetsByCityExtended&login=login&password=password&version=2&cityId=22&searchQuery=баж

Result: streetId = 3059

4. Search for a house on the street (streetId = 3059, searchQuery=1а)

POST method=search.housesByStreetExtended&login=login&password=password&version=2&streetId=3059&searchQuery=1а

Result: houseId = 1905560, hasApartments = Y

5. Search for an apartment in the house (houseId = 1905560, searchQuery=4)

POST method=search.apartmentsByHouseExtended&login=login&password=password&version=2&houseId=1905560&searchQuery=4

Result: apartmentId = 7284220

6. Getting a list of bills by the address (addressId = apartmentId = 7284220)

POST method=search.userDocsByAddress&login=login&password=password&version=2&addressId=7284220

In case of using method search.userDocsByAddress the response contains bills with full match by address only - <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>
...

In case of using method companies.top10ByAddress the response contains bills with both full and partial match by address

<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>
...

It is necessary to request bills.create or bills.createAll by received bills with full match by address by received bill IDs.

It is necessary to ask a user to fill required contractNumber parameters for receiving the bill of corresponding payeeId by received bills with partial match by address.

Using R-type dictionaries

(selecting the payee to pay a unified tax as individual entrepreneur in Darnytskyi district of Kiev for test company with payee id = 23782)

1. Getting the information about company (the bills.payees method)

Request:

method=bills.payees&login=login&password=password&version=2

Response:

<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>

Result: use a list of dictionaries from the payee/related_references block for payee id = 23782 – reference id = 1180, reference id = 1183, reference id = 4308

2. Getting the superior hierarchy level data – selecting the region to pay tax (referenceId = 1180, parentReferenceId is empty)

Request:

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

Response:

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

Result: select the superior hierarchy level item from the response – item id = 42809 (Kyiv)

3. Getting the next hierarchy level data – selecting the district to pay tax (referenceId = 1183, parentReferenceId = 42809)

Request:

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

Response:

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

Result: select an item of the current hierarchy level from the response – item id = 705301 (Treasury department in Darnytskyi district)

4. Getting the next hierarchy level data – selecting the final payee (referenceId = 4308, parentReferenceId = 705301)

Request:

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

Response:

<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>

Result: select an item of the end hierarchy level from the response – item id = 849062 (Darnytskyi district/18050400)

5. Bill creation (the bills.create method, payeeId = 23782, contractNumber = 849062) and payment (the bills.pay method)

The result of using R-type dictionary is the identifier obtained at the end hierarchy level – 849062. Use this identifier at the next step to call the bills.create method.

Using L-type dictionaries

(selecting the group of the unified tax for individual entrepreneurs (IE) and tax period to pay a unified tax as IE in Darnytskyi district of Kiev (for test company with payee id = 23782))

1. Getting the information about company (the bills.payees method)

Request:

method=bills.payees&login=login&password=password&version=2

Response:

<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>

Result: use a list of dictionaries from the payee/attributes/attribute2/related_references block for payee id = 23782 – reference id = 4310, reference id = 4311

2. Getting the superior hierarchy level data – selecting the group of the unified tax for individual entrepreneurs (referenceId = 4310, parentReferenceId is empty)

Request:

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

Response:

  <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>

Result: select the superior hierarchy level item from the response – item id = 832247 (3rd group)

3. Getting the next hierarchy level data – selecting the tax period (referenceId = 4311, parentReferenceId = 832247)

Request:

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

Response:

 <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>

Result: select an item of the end hierarchy level from the response – item id = 832247 (4th quarter)

5. Bill creation (the bills.create method, payeeId = 23782, attribute2 = 4-й квартал) and payment (the bills.pay method)

The result of using L-type dictionary is the attribute value obtained at the end hierarchy level – 4-й квартал. Use this value at the next step to call the bills.create method.

6. Testing

Web-interface API PortmoneDirect: https://direct.portmone.com.ua/api/.

Endpoint URL: https://direct.portmone.com.ua/api/directcash/.

Login and password for testing:

To simulate system failures (timeouts, etc.), for the PORTMONEDIRECTTEST2 test login, a randomly occurring timeout was added to the bills.pay method (the probability of response is approximately 40%). It should be noted that in the event of a timeout, the bill on the Portmone side can be either paid or not paid.

Login and password for testing with imitation of timeouts:

At the testing stage (for the PortmoneDirectTest login), three billing companies are available: GIVC (payeeId = 22494), Volia TV and/or Internet (payeeId = 6968) and Vodafone (payeeId = 10196). These three billers illustrate three types of business logic:

Billers that do not bill periodically (for example, mobile operators (MTS-Ukraine)).
Billers that bill periodically and allow balance recharge (for example, Volia Broadband).
Billers that bill periodically and do not allow balance recharge (for example, GIVC).

Accordingly, when calling the bills.create method:

For billers of the first type – with each request a new bill is always created for a zero amount.
For billers of the second type – if there is already a bill issued by the biller in the Portmone system, we return this bill (for the amount issued by the biller), if not, create a new one with a zero amount.
For billers of the third type – if there is already a bill issued by the biller in the Portmone system, we return this bill (for the amount issued by the biller), if not, generate an error message “p008 – You do not have any unpaid bills. Wait for invoice from your service provider.”.

Attachment 1. Description of XML-structure

This XML is returned when calling bills.create, bills.pay and bills.get methods.

<?xml version="1.0" encoding="utf-8"?>
<rsp status="">
    <bill id="id">
        <payee id="id"> Company name </payee>
        <contractNumber title="title"> Contract number or phone number (for phone
        number – 9 digits) </contractNumber>
        <attribute1 title="title"> Additional attribute value (for example, “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 /> <!-- protocol version – 2 -->
                <tariff_name />  <!-- protocol version – 2 -->
                <counter />
                <counter_state /> <!-- protocol version – 2 -->
                <counter_name />  <!-- protocol version – 2 -->
                <prev_counter />
                <prev_counter_state />  <!-- protocol version – 2 -->
                <prev_counter_name />   <!-- protocol version – 2 -->
                <subsidy />
                <subsidy_state />  <!-- protocol version – 2 -->
                <subsidy_name />   <!-- protocol version – 2 -->
                <debt />
                <debt_state />  <!-- protocol version – 2 -->
                <debt_name />   <!-- protocol version – 2 -->
                <amount />
                <negative_amount />  <!-- protocol version – 2 -->
                <amount_state />     <!-- protocol version – 2 -->
                <amount_name />      <!-- protocol version – 2 -->
                <counter_accuracy />
                <pay_different_amount />
                <attribute1 />
                <attribute1_state />   <!-- protocol version – 2 -->
                <attribute1_name />    <!-- protocol version – 2 -->
                <attribute2 />
                <attribute2_state />   <!-- protocol version – 2 -->
                <attribute2_name />    <!-- protocol version – 2 -->
                <attribute3 />
                <attribute3_state />   <!-- protocol version – 2 -->
                <attribute3_name />    <!-- protocol version – 2 -->
                <attribute4 />
                <attribute5 />
                <attribute6 />
                <attribute7 />
                <attribute8 />
                <attribute9 >
                <attribute10 />
                <description />
                <calculated />      <!-- protocol version – 2 -->
            </item>
        </tariff_items>
    </bill>
</rsp>

Parameter	Description
rsp status	Response status. Possible values are: "ok" – everything is Ok, "fail" – an error occured
bill id	Bill ID
payee id	Company ID – transferred in bills.create request
contractNumber title	For example, "Phone number (+380)"
attribute1 title	Attribute1 appointment (name) (for example, “Number of the housing office”). Depends on the organization
attribute2	Attribute2 name. Depends on the organization
attribute3	Attribute3 name. Depends on the organization
attribute4	Attribute4 name. Depends on the organization
bill_attribute1-4	Additional bill parameters (Kyivstar receipt number, etc.). Depends on a biller
date	Bill creation date. Format: DD.MM.YYYY
description	Bill description
amount	Amount of payment. Use dot (“.”) as the decimal separator
debt	Debt. If the bill has an overpayment, this field contains a minus sign
sum	Amount to be paid, usually equals to `amount` + `debt`
period	Bill period (in the biller format)
status	Bill status. Possible values are: "created", "payed", "canceled", "return"
paidAmount	Amount actually paid (it may differ from the one proposed in the bill)
payDate	Date of payment. Format: DD.MM.YYYY hh24:mi:ss
payee_export_flag	Shows whether the billing information has been transferred to the biller or not. Possible values are: "Y" – information successfully transferred; "N" – no transfer attempts have yet been made; "E" – an error occurred during the last attempt; "B" – sending is blocked (for example, at the request of the bank); "R" – the transaction is reversed (for those billers who can do a reverse); "" – for those companies for which the transfer is not carried out.
auth_сode	Authorization code – is transferred when payment is made
transaction_id	Transaction ID – is transferred when payment is made
payment_point	Unique description of a partner’s point of sale – transferred to us upon payment

Further optional tags:

"Universal" items (previously called counters):

The %_state fields can have three values:

"N" – the column should not be displayed;
"V" – the column and its content are displayed to the client without a possibility of editing;
"E" – the column and its content are displayed to the client with a possibility of editing.

The tariff_state attribute can be W_%. Type means that the tariff may depend on volumes.

Example:

"W" – the need to calculate the service for electricity,
"W_GAZ" – the need to calculate gas service.
"W_Y" – the need to calculate light service.

In this case, the column should not be displayed and helpers can be used to calculate the cost of payment.

Parameter	Description
tariff_items	Editable and not editable counters
item id	Service ID
name	Service name (in Russian) (all protocol versions)
name_ua	Service name (in Ukrainian) (protocol version – 1)
name_eng	Service name (in English) (protocol version - 1)
code	Service code
sub_code	Service subcode
tariff	Tariff value in UAH
tariff_state	Column type (protocol version – 2 and more)
tariff_name	Column heading (in Ukrainian) (protocol version – 2 and more)
counter	Current counter value
counter_state	Column type (protocol version – 2 and more)
counter_name	Column heading (in Ukrainian) (protocol version – 2 and more)
prev_counter	Previous counter value
prev_counter_state	Column type (protocol version – 2 and more)
prev_counter_name	Column heading (in Ukrainian) (protocol version – 2 and more)
subsidy	Subsidy in UAH
subsidy_state	Column type (protocol version – 2 and more)
subsidy_name	Column heading (in Ukrainian) (protocol version – 2 and more)
debt	Debt in UAH
debt_state	Column type (protocol version – 2 and more)
debt_name	Column heading (in Ukrainian) (protocol version – 2 and more)
amount	The amount of the counter in UAH
negative_amount	Indicates whether a negative value can be obtained in the `<amount />` tag or not. Possible values are: "N", "Y" (protocol version – 2 and more)
amount_state	Column type (protocol version – 2 and more)
amount_name	Column heading (in Ukrainian) (protocol version – 2 and more)
counter_accuracy	Counter width: "0" – counter values are rounded to the nearest whole number "1" – counter values are rounded to the 1st decimal place "2" – counter values are rounded to the 2nd decimal place "3" – counter values are rounded to the 3rd decimal place "4" – counter values are rounded to the 4th decimal place
pay_different_amount	Is it possible to pay an amount which differs from the received one. Only relevant for protocol version 1.0 (in later versions, to decide whether the data can be changed or not, take into account tag values with the "_state" suffix, for example, `<amount_state>` for the amount of the counter). Possible values are: "N" – the amount of the counter was already taken into account in the total of the bill (the counter does not need to be transferred when paying) "Y" – the counter amount was calculated and added to the bill amount (the counter is transferred when paying)
attribute1	Optional tag (depends on a biller)
attribute1_state	Column type (protocol version – 2 and more)
attribute1_name	Column heading (in Ukrainian) (protocol version – 2 and more)
attribute2	Optional tag (depends on a biller)
attribute2_state	Column type (protocol version – 2 and more)
attribute2_name	Column heading (in Ukrainian) (protocol version – 2 and more)
attribute3	Optional tag (depends on a biller)
attribute3_state	Column type (protocol version – 2 and more)
attribute3_name	Column heading (in Ukrainian) (protocol version – 2 and more)
attribute4-10	Optional tags (depends on a biller)
description	Counter description
calculated	Shows whether the amount of an item should be calculated by the formula or not (you can simply pass an arbitrary value through the `amount`). Possible values are: "Y" – use formula: (`counter` - `prev_counter`) * `tariff` – `subsidy`; "N" – arbitrary value (protocol version - 2 and more)

Glossary​

1. General information​

2. Methods​

2.1. Request for bill delivery​

2.2. Request for bill delivery by phone number​

2.3. Request for delivery of all bills issued for the current month​

2.4. Bill payment​

2.5. Information about a bill​

2.6. Transactions list​

2.7. Control registry of transactions​

2.8. Control registry of funds transferred to the service provider​

2.9. Request for data on the reseller company balance​

2.10. Request for information on available biller companies​

2.11. Request for information on biller companies in the context of regions​

2.12. Request for companies providing bills for a client, by a previously received bill​

2.13. Request for information about regions​

2.14. Request for information about regions (with a filter by region name)​

2.15. Request for information about cities in the region​

2.16. Request for information about cities in the region (with a filter by city name)​

2.17. Request for information about the city streets​

2.18. Request for information about the city streets (with a filter by street name)​

2.19. Request for information about the street buildings​

2.20. Request for information about the street buildings (with a filter by building number)​

2.21. Request for information about apartments at the building​

2.22. Request for information about apartments at the building (with a filter by apartment number)​

2.23. Request for context information at the address (a list of bills)​

2.24. Searching for companies in a specified region​

2.25. Searching for companies in the specified locality (city)​

2.26. Searching for companies for a specified street​

2.27. Searching for companies for a specified building​

2.28. Searching for companies by the address​

2.29. Getting dictionary values​

2.30. Bill update​

2.31. Checking the amount of the guarantee payment​

2.32. Creating a copy of a paid invoice​

2.33. Cancellation of payments that are in PAYED status​

2.34.Мethod for submitting meter readings without payment (for incoming companies) — creating a request​

2.35.Method for submitting meter readings without payment (data transmission to the company, readings entered by the customer).​

3. Replenishment of bank cards (Account-2-Card)​

3.1. Verification of the customer's card​

3.2. Replenishment of the customer's card​

3.3. Replenishment of the customer's card by full card number​

4. Error codes list​

5. Examples​

An example of using PortmoneDirect methods for getting a customer's geographic information (region, city, street, house and/or apartment IDs)​

Using R-type dictionaries​

Using L-type dictionaries​

6. Testing​

Attachment 1. Description of XML-structure​

Glossary

1. General information

2. Methods

2.1. Request for bill delivery

2.2. Request for bill delivery by phone number

2.3. Request for delivery of all bills issued for the current month

2.4. Bill payment

2.5. Information about a bill

2.6. Transactions list

2.7. Control registry of transactions

2.8. Control registry of funds transferred to the service provider

2.9. Request for data on the reseller company balance

2.10. Request for information on available biller companies

2.11. Request for information on biller companies in the context of regions

2.12. Request for companies providing bills for a client, by a previously received bill

2.13. Request for information about regions

2.14. Request for information about regions (with a filter by region name)

2.15. Request for information about cities in the region

2.16. Request for information about cities in the region (with a filter by city name)

2.17. Request for information about the city streets

2.18. Request for information about the city streets (with a filter by street name)

2.19. Request for information about the street buildings

2.20. Request for information about the street buildings (with a filter by building number)

2.21. Request for information about apartments at the building

2.22. Request for information about apartments at the building (with a filter by apartment number)

2.23. Request for context information at the address (a list of bills)

2.24. Searching for companies in a specified region

2.25. Searching for companies in the specified locality (city)

2.26. Searching for companies for a specified street

2.27. Searching for companies for a specified building

2.28. Searching for companies by the address

2.29. Getting dictionary values

2.30. Bill update

2.31. Checking the amount of the guarantee payment

2.32. Creating a copy of a paid invoice

2.33. Cancellation of payments that are in PAYED status

2.34.Мethod for submitting meter readings without payment (for incoming companies) — creating a request

2.35.Method for submitting meter readings without payment (data transmission to the company, readings entered by the customer).

3. Replenishment of bank cards (Account-2-Card)

3.1. Verification of the customer's card

3.2. Replenishment of the customer's card

3.3. Replenishment of the customer's card by full card number

4. Error codes list

5. Examples

An example of using PortmoneDirect methods for getting a customer's geographic information (region, city, street, house and/or apartment IDs)

Using R-type dictionaries

Using L-type dictionaries

6. Testing

Attachment 1. Description of XML-structure