Skip to main content

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

Glossary

TermDefinition
Merchant, PartnerOrganization which has signed a payment acceptance agreement with Portmone.com
Buyer, Client or CustomerA 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 CardPayment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
AuthorizationThe process of giving access rights or other powers to the Buyer, program or process
CVV2/CVC2CVV2 (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 BankA 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
IBANInternational 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.

2. Methods

Method nameDescription
2.1. bills.createthis 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.createByPhonethis 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.createAllthis method is used to get bills from companies issuing several bills for the current month
2.4. bills.paythis method is used to pay bills
2.5. bills.getThis 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.paymentOrderthis 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.datethis method is used to obtain a control registry of transactions for the period (day)
2.8. bills.exportedthis 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.balancethis method is used to view the current balance of the biller company (PAYEE)
2.10. bills.payeesthis method is used to get biller (PAYEE) parameters
2.11. bills.regionsthis method is used to obtain a list of available regions and a list of billers (PAYEE) for each region
2.12. bills.additionalPayeesthis method is used to get a list of companies for which the client can pay bills
2.13. search.regionsthis method is used to obtain a complete list of regions of Ukraine
2.14. search.regionsExtendedthis method is used to obtain a list of regions of Ukraine with additional filtering by region name
2.15. search.citiesByRegionthis method is used to get a list of cities for the specified region
2.16. search.citiesByRegionExtendedthis method is used to get a list of cities for the specified region with additional filtering by city name
2.17. search.streetsByCitythis method is used to get a list of streets for the specified city
2.18. search.streetsByCityExtendedthis method is used to get a list of streets for the specified city with additional filtering by street name
2.19. search.housesByStreetthis method is used to get a list of buildings for the specified street
2.20. search.housesByStreetExtendedthis method is used to get a list of buildings for the specified street with additional filtering by building number
2.21. search.apartmentsByHousethis method is used to obtain a list of apartments by known houseId. For apartment buildings only
2.22. search.apartmentsByHouseExtendedthis 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.getreferencethis 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.updateis a part of method 2.4. bills.pay, is used for update a bill with no change of its status
2.31. bank.params.guaranteeAmountthe method of checking the amount of the guarantee payment for the partner according to the individual login
2.32. bills.recreatethis method to create a copy of a paid invoice
2.33. bills.cancelthis method for canceling payments that are in PAYED status (all versions of the protocol)

* 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). The answer contains data on the last bill created and unpaid for the previous period. If the organization does not provide invoice (for example, mobile operators), then the bills.create method ensures that this phone number is available in the database of the mobile operator.

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
payeeIdID of the payee companyYes
contractNumberThe main requisite (identifier) of the client in this companyYes
billNumberOrder numberNo
attribute1-4For additional informationNo

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:

  1. The Client enters the mobile phone number on the Partner's website.
  2. The Partner sends this data to the Portmone.com using the bills.createByPhone method.
  3. 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.
  4. The Partner sends the payment request using the bills.pay method.
  5. Portmone.com transfers funds to the service provider.

Method parameters:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
payeeIdID of the payee companyYes
contractNumberPhone number to which funds are transferred. Format of the number: 9 digits, without "+380" (for example, 673334411)Yes
billAmountAmount of payment (default to 0)No
billNumberOrder numberNo
attribute1-4For additional informationNo

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
payeeIdID of the payee companyYes
contractNumberThe main requisite (identifier) of the client in this companyYes
billNumberOrder numberNo
attribute1-4For additional informationNo

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.

Method parameters:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdBill ID. The value returned by the bills.create method (or by the bills.createByPhone method in case of a mobile phone replenishment)Yes
amountAmount for payment by order (it may differ from the one proposed in the bill)Yes
auth codeAuthorization codeNo
transaction IdTransaction IDNo
payment_pointUnique description of a partner sales pointNo
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
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 

or

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

ParameterDescriptionRequired
idCounter IDYes
amountThe amount of the counter in UAHYes
prev_counterPrevious counter valueNo
counterCurrent counter valueNo
tariffTariff value in UAHNo
subsidySubsidy in UAHNo
debtDebt in UAHNo
attribute1Optional tag (depends on biller) (protocol version - 2)No
attribute2Optional tag (depends on biller) (protocol version - 2)No
attribute3Optional 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdBill 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
xmlRegistry in XML formatYes

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:

ParameterDescription
record idPayment 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
dateDate for which the registry is displayed. Format: DD.MM.YYYYYes

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:

ParameterDescription
bill idBill ID (для транзакції устатусі RETURN, bill id набуває нового унікального значення)
сontractNumber titleNumber of contract
statusTransaction status on the Portmone.com side. Possible values: PAYED, RETURN
transaction_IdThe 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)
paidAmountAmount of payment
payDateDate of payment
payee_export_dateDate of funds transfer to the service provider
payee_export_flagTransfer status (possible values: Y, N, R, E)
bank_commissionBank remuneration in UAH (protocol version – 2). The parameter may takes both positive and negative values
nameName of the recipient company
payee_idA 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
payeeIdCompany IDYes
dateDate for which the registry is displayed. Format: DD.MM.YYYYYes

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:

ParameterDescription
bill idBill ID
сontractNumber titleNumber of contract
statusTransaction status on the Portmone.com side. Possible values: PAYED, RETURN
transaction_IdThe 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)
paidAmountAmount of payment
payDateDate of payment
payee_export_dateDate of funds transfer to the service provider
payee_export_flagTransfer 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
payeeIdID of the company for which the balance is requestedYes

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:

ParameterDescription
payee idID of the company for which the balance is requested
balanceThe 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
LastUpdateDateDate from which any changes were made. Format: DD.MM.YYYYNo
deletedDeactivated companiesNo

An example of request:

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

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

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

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdBill 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
searchQuerySubstring 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
regionIdID of the region obtained using the search.regions method or the search.regionsExtended methodYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
regionIdID of the region obtained using the search.regions method or the search.regionsExtended methodYes
searchQuerySubstring for filtering by city name, from 3 charactersYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
cityIdID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended methodYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
cityIdID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended methodYes
searchQuerySubstring for filtering by street name, from 3 charactersYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
streetIdID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended methodYes

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!

  1. The house id parameter in the response may takes negative values
  2. 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
streetIdID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended methodYes
searchQuerySubstring for filtering by building number (specify the part of region name, from 3 characters)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!

  1. The house id parameter in the response may takes negative values
  2. 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
houseIdID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended methodYes

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
houseIdID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended methodYes
searchQuerySubstring for filtering by apartment number (specify the part of region name, from 3 characters)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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
addressIdID of the building or ID of the apartmentYes

Important!

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

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

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
regionIdID of the region obtained using the search.regions method or the search.regionsExtended methodYes

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:

ParameterDescription
PAYEE_IDA unique company identifier
NAMECompany name
CONTRACT_NUMBERThe main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLEName of the client identifier in the company
CONTRACT_NUMBER_TYPEType of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZESize of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLEAttribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPEAttribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZEAttribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFOThe ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGEFile name with company logo
MATCH_TYPEMatch type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAYIf <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, this field contains dictionary
ATTRIBUTE1_ARRAYIf <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, this field contains dictionary
ATTRIBUTE2_ARRAYIf <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, this field contains dictionary
ATTRIBUTE3_ARRAYIf <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, this field contains dictionary
ATTRIBUTE4_ARRAYIf <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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
cityIdID of the city obtained using the search.citiesByRegion method or the search.citiesByRegionExtended methodYes

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:

ParameterDescription
PAYEE_IDA unique company identifier
NAMECompany name
CONTRACT_NUMBERThe main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLEName of the client identifier in the company
CONTRACT_NUMBER_TYPEType of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZESize of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLEAttribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPEAttribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZEAttribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFOThe ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGEFile name with company logo
MATCH_TYPEMatch type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAYIf <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, this field contains dictionary
ATTRIBUTE1_ARRAYIf <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, this field contains dictionary
ATTRIBUTE2_ARRAYIf <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, this field contains dictionary
ATTRIBUTE3_ARRAYIf <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, this field contains dictionary
ATTRIBUTE4_ARRAYIf <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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
streetIdID of the street obtained using the search.streetsByCity method or the search.streetsByCityExtended methodYes

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:

ParameterDescription
PAYEE_IDA unique company identifier
NAMECompany name
CONTRACT_NUMBERThe main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLEName of the client identifier in the company
CONTRACT_NUMBER_TYPEType of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZESize of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLEAttribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPEAttribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZEAttribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFOThe ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGEFile name with company logo
MATCH_TYPEMatch type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAYIf <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, this field contains dictionary
ATTRIBUTE1_ARRAYIf <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, this field contains dictionary
ATTRIBUTE2_ARRAYIf <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, this field contains dictionary
ATTRIBUTE3_ARRAYIf <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, this field contains dictionary
ATTRIBUTE4_ARRAYIf <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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
houseIdID of the building obtained using the search.housesByStreet method or the search.housesByStreetExtended methodYes

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:

ParameterDescription
PAYEE_IDA unique company identifier
NAMECompany name
CONTRACT_NUMBERThe main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLEName of the client identifier in the company
CONTRACT_NUMBER_TYPEType of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZESize of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLEAttribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPEAttribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZEAttribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFOThe ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGEFile name with company logo
MATCH_TYPEMatch type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAYIf <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, this field contains dictionary
ATTRIBUTE1_ARRAYIf <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, this field contains dictionary
ATTRIBUTE2_ARRAYIf <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, this field contains dictionary
ATTRIBUTE3_ARRAYIf <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, this field contains dictionary
ATTRIBUTE4_ARRAYIf <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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
addressIdID of the building or ID of the apartmentYes

Important!

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

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

ParameterDescription
RWDA system parameter that indicates that the account is related to the user and the user's address
PAYEE_IDA unique company identifier
NAMECompany name
CONTRACT_NUMBERThe main requisite (identifier) of the client in this company
CONTRACT_NUMBER_TITLEName of the client identifier in the company
CONTRACT_NUMBER_TYPEType of the client identifier in the company. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
CONTRACT_NUMBER_SIZESize of the client identifier in the company
ATTRIBUTE1, ATTRIBUTE2, ATTRIBUTE3, ATTRIBUTE4Additional payment attribute
ATTRIBUTE1_TITLE, ATTRIBUTE2_TITLE, ATTRIBUTE3_TITLE, ATTRIBUTE4_TITLEAttribute name
ATTRIBUTE1_TYPE, ATTRIBUTE2_TYPE, ATTRIBUTE3_TYPE, ATTRIBUTE4_TYPEAttribute type. Possible values: A – bank card, С – string, N – number, D – date, L – dictionary
ATTRIBUTE1_SIZE, ATTRIBUTE2_SIZE, ATTRIBUTE3_SIZE, ATTRIBUTE4_SIZEAttribute size
ATTRIBUTE1_FOR_INFO, ATTRIBUTE2_FOR_INFO, ATTRIBUTE3_FOR_INFO, ATTRIBUTE4_FOR_INFOThe ability for the client to edit additional payment attribute (Y – not editable; N – editable)
IMAGEFile name with company logo
MATCH_TYPEMatch type (PARTIAL – partial match for search parameter, FULL – full match for search parameter)
CONTRACT_NUMBER_TYPE_ARRAYIf <CONTRACT_NUMBER_TYPE>L</CONTRACT_NUMBER_TYPE>, this field contains dictionary
ATTRIBUTE1_ARRAYIf <ATTRIBUTE1_TYPE>L</ATTRIBUTE1_TYPE>, this field contains dictionary
ATTRIBUTE2_ARRAYIf <ATTRIBUTE2_TYPE>L</ATTRIBUTE2_TYPE>, this field contains dictionary
ATTRIBUTE3_ARRAYIf <ATTRIBUTE3_TYPE>L</ATTRIBUTE3_TYPE>, this field contains dictionary
ATTRIBUTE4_ARRAYIf <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:

ParameterDescriptionRequired
referenceIdA unique dictionary identifier in the Portmone.com system. IntegerYes
parentReferenceIdID 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. IntegerYes/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:

ParameterDescriptionType
itemsList of dictionary items
item idDictionary 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
nameDictionary item value. Used to be displayed to the client or to call the bills.create method in case of L-type fieldString
descriptionAdditional description of the dictionary item. Required if not emptyString
parent_item_idID of the parent dictionary item obtained from a previous bills.getreference method callInt

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdBill 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):

ParameterDescriptionRequired
idCounter IDYes
amountThe amount of the counter in UAHYes
prev_counterPrevious counter valueNo
counterCurrent counter valueNo
tariffTariff value in UAHNo
subsidySubsidy in UAHNo
debtDebt in UAHNo
attribute1Optional tag (depends on biller) (protocol version - 2)No
attribute2Optional tag (depends on biller) (protocol version - 2)No
attribute3Optional 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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
versionVersion APIYes
langlangNo

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:

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdPaid invoice IDYes
versionVersion APIYes
langlangNo

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 a successful response:

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

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the methodYes
billIdPaid invoice IDYes
versionVersion APIYes
langlangNo

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>

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

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

ParameterDescriptionRequired
loginYour company login in the Portmone.com systemYes
passwordYour company password in the Portmone.com systemYes
methodA name of the method – verificationYes
success_urlThe 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>
  1. 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

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

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

  1. Call the bills.create method with the following parameters:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.create
payeeIdID of the payee company
contractNumberClient's card mask (first 6 and last 4 digits of the number in 444433XXXXXX1111 format)
attribute1It should be equal to the recipient_id value received in the verification response
attribute2It 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.

  1. Call the bills.pay method using the following parameters:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.pay
billIdBill ID (the value returned by the bills.create method)
amountAmount to be paid (amount that will be credited to the card)
  1. Call the bills.get method to get transaction status information:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.get
billIdBill 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:

  1. status=’PAYED’ and payee_export_flag=’Y’ – payment at the acquiring bank side is successful and the funds are credited to the client, or
  2. status=’CANCELED’ – funds cannot be credited to the client’s card.
  1. 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:

  1. Call the bills.create method with the following parameters:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.create
payeeIdID of the payee company
contractNumberFull recipient card number (for example, 4444333322221111)
attribute1It should be equal to the recipient_id value received in the verification response
attribute2It 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.

  1. Call the bills.pay method using the following parameters:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.pay
billIdBill ID (the value returned by the bills.create method)
amountAmount to be paid (amount that will be credited to the card)
  1. Call the bills.get method to get transaction status information:
ParameterDescription
loginYour company login in the Portmone.com system
passwordYour company password in the Portmone.com system
methodA name of the method – bills.get
billIdBill 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:

  1. status=’PAYED’ and payee_export_flag=’Y’ – payment at the acquiring bank side is successful and the funds are credited to the client, or
  2. status=’CANCELED’ – funds cannot be credited to the client’s card.
  1. 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 codeError messageDescriptionMethod
o001Bill creation errorBill creation error (internal error code)bills.create
o003An error occurred while paying the billAn error occurred while paying the billbills.pay
o003An error occurred while canceling the billAn error occurred while canceling the bill (Bill not found)bills.pay
o004Error displaying control registryError displaying control registrybills.paymentOrder
o006Error displaying company balanceError displaying company balancebills.balance
o010No payees for loginError while searching companybills.additionalPayees
p03Invalid customer identification parametersAn error occurred while paying the billbills.pay
p001Invalid method nameInvalid method nameAll methods
p002Invalid login/passwordInvalid login/passwordAll methods
p003Subscription creation errorSubscription creation error (internal error code)bills.create
p004Updating counter parameters errorUpdating counter parameters errorbills.pay
p005The subscription has "ERROR" statusThe billing company returned an error message for this subscription, or when attempting to repeat the subscription with incorrect detailsbills.create
p006Company doesn’t existThere is no billing company with such ID in the Portmone.com databasebills.create
p007Subscription 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
p008You do not have any unpaid bills. Wait for invoice from your service provider.Subscription created but no bills yetbills.create
p009The bill doesn’t existThere is no bill with such ID in the Portmone.com database (internal error code)bills.get
p010No bills for dateNo bills for this date (internal error code)bills.date
bills.exported
p011Empty or damaged registry receivedEmpty or damaged registry receivedbills.paymentOrder
p012Empty POSTReceived POST array is emptyAll methods
p014Company quota exceededCompany quota exceeded (internal error code)bills.pay
p015Error when checking the validity of the subscriptionReturned 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
p015Invalid date formatInvalid date format (internal error code)bills.date
bills.exported
p017Error requesting bill informationIt is impossible to obtain information about the bill (for example, the bill is currently blocked by the payment session) (internal error code)bills.get
p018To get bills for this company, you must use the bills.createAll methodbills.create
p019A general error for all search.* methodssearch.*
p022Reference not foundA general error for all search.* methodssearch.*
p032Error while searching data. You may try to find apartments by private houseError while searching data. Data (apartments) not foundsearch.apartmentsByHouse, search.apartmentsByHouseExtended
p100Internal database errorInternal 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 = 23782reference 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 = 23782reference 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:

login — PortmoneDirectTest password — PortmoneDirect

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:

login — PORTMONEDIRECTTEST2 password — Direct2

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:

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

Accordingly, when calling the bi