Skip to main content

Portmone Payment Link. API Reference.

Glossary

TermDefinition
Merchant, PartnerOrganization which has signed a payment acceptance agreement with Portmone.com
Client, 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 Customer, program or process
Personal AreaA specialized site with a set of pages and interactive forms, where the authorized user can receive the necessary information and carry out other operations in the Portmone.com system
ITNIndividual Taxpayer Number
NBUThe National Bank of Ukraine
Weekends or holidaysNon-working days in Ukraine, during which the bank does not carry out banking operations
Back officeSpecialized software used by Portmone.com staff
IBANInternational Bank Account Number

1. General description

Payment link is a securely generated web address that allows your customers to make payments using the supported payment methods.

If you want to provide clients with the option of periodic (or one-time) automatic payments using Portmone.com, you should generate the payment link as follows: https://www.portmone.com.ua/r3/uk/autoinsurance?i=<payment_parameters>.

The i parameter contains the clients details, that are necessary for their identification by the Partner, automatic payment setting options and the unique identifier assigned to each Partner by Portmone.com (for more detailed information, refer to section 2 "Creating payment parameters").

By clicking this link the client is redirected to the page with the payment form containing order details, where all the necessary parameters are filled in. The client can easily complete the checkout process by entering payment card details only. If necessary, the Partner may specify the field or a number of the fields as those that can be filled in by the clients themselves. To set up an automatic payment, according to the schedule provided by the Partner, the client must accept the automatic payments terms. In this case client’s account and Personal Area in Portmone.com will be generated, if the client don’t have them yet. If the client has refused to register and to set up the automatic payment, only one-time payment will be made.

The below screenshots illustrate the view of payment page, with the Insurance company as a Partner.

An example of payment page, with the Insurance company as a Partner

Fig. 1. An example of payment page

An example of displaying automatic payment parameters without editing

Fig. 2. An example of displaying automatic payment parameters without editing

An example of displaying automatic payment parameters with editing

Fig. 3. An example of displaying automatic payment parameters with editing

2. Creating payment parameters

Payment parameters are sent as encoded string in the i parameter of GET-request at the following URL: https://www.portmone.com.ua/r3/uk/autoinsurance.

This section describes parameters used to create the request.

Payment parameters:

ParameterDescriptionRequiredValue
vProtocol versionYesAlways takes the value "2"
payeeIdA unique identifier of the Partner in the Portmone.com systemYesAssigned to each Partner individually when connected to the Portmone.com system
amountAmount of the payment. The decimal separator is the dot symbol ("."). If the parameters for automatic payment are set, the specified amount will be used to make automatic paymentsYesFor example: 100.50
langPayment system interface languageNouk – Ukrainian, en – English, (default value) uk – Ukrainian
editEditing automatic payment settings by client. By default editing is not possibleNo"Y" – editable, "N" – non-editable
description*Comment to the order / description of payment detailsNoMaximum length is 250 symbols
attribute1*Service fieldNoFilled at company's discretion
attribute2*Service fieldNoFilled at company's discretion
attribute3*Service fieldNoFilled at company's discretion
attribute4*Service fieldNoFilled at company's discretion
billCurrencyCurrency of the paymentNoPossible values: UAH (default value), USD, EUR, GBP, KZT
billNumberNumber of paid order (bill) in the Partner's system. Bill number must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transactionNoMaximum length is 120 symbols
emailAddressEmail address of the payerYesFor example: [email protected]
timeToLiveDeadline for payment. The countdown starts from the effective date of the contract. If the parameter is not passed, the payment term for the client is not limitedNoFrom 1 to 30 (in days). For example, if contractDate=20.01.2020 and timeToLive=1, it would be possible to make a payment before 20.01.2020 23:59:59
contractDateThe effective date of the contractNoMM.DD.YYYY
limitExpiration date of the contractNoMM.DD.YYYY
successUrlThe URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after successful paymentNoFor example: https://portmone2.com/r3/ecommerce/test/master-test-form"
infoParamsA block of parameters for additional client information that will be displayed when setting up automatic paymentsNoSee the infoParams structure
settingsA block of parameters for setting up automatic paymentsNoSee the settings structure

infoParams structure

ParameterDescriptionRequiredValue
phoneNumber of the client’s mobile phoneNo380ХХХХХХХХХ
birthDateDate of birth of the clientNoMM.DD.YYYY

settings structure

ParameterDescriptionRequiredValue
periodFrequency of automatic paymentsYes1 – monthly
2 – quarterly
3 – semiannually
4 – annually
payDateDay of the month for automatic paymentYesFrom 1 to 28
startDateDate of the first payment. If not specified, the current date is automatically setNoMM.DD.YYYY
endDateThe automatic payment end date. If not specified, the current date + 3 years is automatically setNoMM.DD.YYYY

Note: * – the values of description and attribute1-4 appear in the registry and at export. The name of these parameters should be agreed with the Portmone.com manager.

Please note: the first payment for the foreign exchange contracts will be made at the NBU exchange rate for the current day (if the rate for the current day has not yet been set, or payment is made during the weekend, the payment is made at the last set rate). Payments will be made from 7:00 to 8:00 at the NBU exchange rate on the previous day, or at the last set rate of the NBU, if payment is made during a weekend or a holiday.

Example of valid JSON object:

{
"v":"2",
"payeeId":"1185",
"lang":"uk",
"amount":"100.31",
"settings":
{
"period":"1",
"payDate":"5",
"startDate":"20.01.2020",
"endDate":"20.01.2023"
},
"edit":"N",
"description":"40-0111-078-2-5770640",
"attribute1":"2019-08-01",
"attribute2":"Ivanov Oleksandr",
"attribute3":"Payment of insurance services under the contract",
"attribute4":"2710",
"billNumber":"123-123-99",
"emailAddress":"[email protected]",
"timeToLive":"10",
"contractDate":"01.08.2019",
"limit":"10.09.2019",
"successUrl":"https://portmone2.com/r3/ecommerce/test/master-test-form"
}

The string with the formed object should be compressed using gzip and then encoded with base64, the result is the value of the i parameter of GET-request.

Data should be modified like this:

i = base64(gzip(json_encode(data)))

where data – payer’s information and payment parameters.

Below is an example of PHP script that performs this transformation:

$source = '{
"v":"2",
"payeeId":"1185",
"lang":"uk",
"amount":"100.31",
"settings":{
"period":"1",
"payDate":"5",
"startDate":"20.01.2020",
"endDate":"20.01.2023"
},
"edit":"N",
"description":"40-0111-078-2-5770640",
"attribute1":"2019-08-01",
"attribute2":"Ivanov Oleksandr",
"attribute3":"Payment of insurance services under the contract",
"attribute4":"2710",
"billNumber":"123-123-99",
"emailAddress":"[email protected]",
"timeToLive":"10",
"contractDate":"01.08.2019",
"limit":"10.09.2019",
"successUrl":"https://portmone2.com/r3/ecommerce/test/master-test-form"
}';

$i = base64_encode(gzencode($source));
$url = ‘https://www.portmone.com.ua/r3/uk/autoinsurance?i=’ . $i;
//$url now contains the address of the payment link for sending to the client

3. Branding of the payment page

You can customize the appearance of payment page by changing branding parameters in the merchant Personal Area or by contacting the Portmone.com manager and providing parameters for branding.

Branding types:

  • portmone – default value (standard Portmone.com style, see fig. 4);
  • brand – full page styling for a partner (see fig. 5);
  • co-brand – partner’s logo is displayed on the page along with the Portmone.com logo (see fig. 6);
  • light – the version to display as a frame (see fig. 7)

Branding parameters:

ParameterDescriptionBranding type for which a parameter can be used
logoLink to the partner logo. Supports only link with https scheme. Image format SVG or PNG only. It is recommended to use an image with a minimum plot indent from all edgesbrand, co-brand
logoWidthThe width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300pxbrand, co-brand
logoHeightThe height of the logo. Should be entered in the "100px" format. Maximum recommended value is 50px (maximum height for PNG – 53px)brand, co-brand
backgroundColorHeaderThe colour of a header section on the page. The input format is HEX (for example, #ff0000)brand, light
backgroundColorButtonsThe colour of buttons. The input format is HEX (for example, #ff0000)brand, light
colorTextAndIconsText and icon colour. The input format is HEX (for example, #ff0000)brand, light
bcMainThe colour to fill page background. The input format is HEX (for example, #ff0000)brand, light

The view of a payment page with different types of branding:

Branding example for "portmone"

Fig. 4. Portmone.com standard style (branding type – portmone)

Branding example for "brand"

Fig. 5. Partner style for the entire page (branding type – brand)

Branding example for "co-brand"

Fig. 6. Partner’s logo is displayed on the page along with the Portmone.com logo (branding type – co-brand)

Branding example for "light"

Fig. 7. The version to display as a frame on the partner's website (branding type – light)

4. Payment notification for Partner

Portmone.com can immediately inform the Partner about the payment by submitting an email to the address (or several addresses) provided by the Partner.

Notification for successful payment – BILLS

The system of XML-messages transferred by HTTPS protocol is used to exchange the information. The Portmone.com system is always the initiator of such exchange. The company shall provide URL-address to which the Portmone.com system will send XML-messages using POST method via data parameter.

Example:

data=<?xml version="1.0" encoding="UTF-8"?><BILLS> …..

The BILLS message is sent by Portmone.com to the company in case of successful transaction. Intended to receive information about the accepted payment, without waiting for the funds to be transferred to the company’s current account. Message contains information about a single paid bill.

Message format:

<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
<PAYEE>
<NAME>Payee name</NAME>
<CODE> Payee code</CODE>
</PAYEE>
<BANK>
<NAME> Name of sending bank </NAME>
<CODE> MFO of sending bank</CODE>
<ACCOUNT> Account number or IBAN of sending bank </ACCOUNT>
</BANK>
<BILL_ID>Bill ID </BILL_ID>
<BILL_NUMBER> Bill number</BILL_NUMBER>
<BILL_DATE> Bill date</BILL_DATE>
<BILL_PERIOD> Bill period</BILL_PERIOD>
<PAY_DATE>Payment date</PAY_DATE>
<PAYED_AMOUNT> Payment amount</PAYED_AMOUNT>
<PAYED_COMMISSION> Amount of banking commission </PAYED_COMMISSION>
<PAYED_DEBT>Including payment of debt</PAYED_DEBT>
<AUTH_CODE> Card authorization code</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Bill description </CONTRACT_NUMBER>
<ATTRIBUTE1>Additional parameter 1</ATTRIBUTE1>
<ATTRIBUTE2>Additional parameter 2</ATTRIBUTE2>
<ATTRIBUTE3>Additional parameter 3</ATTRIBUTE3>
<ATTRIBUTE4>Additional parameter 4</ATTRIBUTE4>
</PAYER>
</BILL>
</BILLS>

The description of the message is provided in Appendix 1. Example message is shown in Appendix 2.

Notification about bank payment – PAY_ORDERS message

The system of XML-messages transferred by HTTPS protocol is used to exchange the information. The Portmone.com system is always the initiator of such exchange. The company shall provide URL-address to which the Portmone.com system will send XML-messages using POST method via data parameter.

Example:

data=<?xml version="1.0" encoding="UTF-8"?><PAY_ORDERS> …..

The PAY_ORDERS message is sent by the Portmone.com system to the company and contains information about bank payments. This message is used to compare BILLS messages with funds transferred by the bank to the current account of the company. It contains information about a single paid bill.

Message format:

<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
<PAY_ORDER>
<PAY_ORDER_ID> Payment order ID</PAY_ORDER_ID>
<PAY_ORDER_DATE> Payment order date</PAY_ORDER_DATE>
<PAY_ORDER_NUMBER>Payment order number</PAY_ORDER_NUMBER>
<PAY_ORDER_AMOUNT>Payment order amount</PAY_ORDER_AMOUNT>
<PAYEE>
<NAME>Payee name</NAME>
<CODE>Payee code</CODE>
</PAYEE>
<BANK>
<NAME>Bank name</NAME>
<CODE>Bank MFO</CODE>
<ACCOUNT>Sender current account or IBAN of a sender</ACCOUNT>
</BANK>
<BILLS>
<BILL>
<BILL_ID>Bill ID </BILL_ID>
<BILL_NUMBER> Bill number</BILL_NUMBER>
<BILL_DATE> Bill date</BILL_DATE>
<BILL_PERIOD> Bill period</BILL_PERIOD>
<PAY_DATE>Payment date</PAY_DATE>
<PAYED_AMOUNT> Payment amount </PAYED_AMOUNT>
<PAYED_COMMISSION> Amount of banking commission
</PAYED_COMMISSION>
<PAYED_DEBT>Including payment of debt</PAYED_DEBT>
<AUTH_CODE> Card authorization code</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Order description</CONTRACT_NUMBER>
<ATTRIBUTE1>Additional parameter 1</ATTRIBUTE1>
<ATTRIBUTE2>Additional parameter 2</ATTRIBUTE2>
<ATTRIBUTE3>Additional parameter 3</ATTRIBUTE3>
<ATTRIBUTE4>Additional parameter 4</ATTRIBUTE4>
</PAYER>
</BILL>
</BILLS>
</PAY_ORDER>
</PAY_ORDERS>

The description of the message is provided in Appendix 3. Example message is shown in Appendix 4.

Confirmation receipt of payment information – RESULT message

The RESULT message is sent by the company to the Portmone.com system in response to the messages PAY_ORDERS and BILLS.

Message format:

<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
<ERROR_CODE>Error code</ERROR_CODE>
<REASON>Error description</REASON>
</RESULT>

Message RESULT – fields description:

Field nameData typeDescription
ERROR_CODENUMBER(15,0)Error code (0 in case if message processing is successful)
REASONCHAR(250)Error description

Message example:

<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
<ERROR_CODE>0</ERROR_CODE>
<REASON>OK</REASON>
</RESULT>

5. Registration of Partner in the Portmone.com system

To accept payments through a payment link functionality, a Partner should contact the Pormone.com manager. The manager creates the company in the back office of Portmone.com system (first test, with subscription parameters agreed with the Partner).

Additionally, the following should be agreed with the Partner:

  • a set of additional parameters to be passed;
  • branding parameters (HEX colors and URL of partner logo);
  • email addresses or URLs for partner notification about payment, if needed.

After agreeing on all the above parameters, the manager configures the company and provides the Partner with the necessary access.

6. Testing

The Portmone.com system provides partners with two modes for testing: test mode and production mode with an automatic payment cancellation.

The test mode of the payment gateway means that the Portmone.com system checks the validity of entered data from the Partner and its Client, creates an order, but payment card authorization is not performed. 3-D Secure check is not possible.

Cards for testing:

Card numberResult
4444333322221111Successful payment
4111111111111111Failed payment

The production mode with payment auto cancellation provides the possibility to make real payments using real payment cards. The cancellation of payment is performed automatically within 30 minutes.

Please contact our Account Managers to enable and disable test mode or payment auto cancellation

Email: [email protected]

Important! Before putting the payment acceptance system into operation, make sure that the test mode or payment auto cancellation are disabled!

7. Management of paid contracts (refund, cancellation)

7.1. Cancellation of payment

In case if payment cancellation is required, the authorized employee of the Partner contacts the managers of Portmone.com: https://www.portmone.com.ua/r3/uk/contacts.

7.2. Refunds via Personal Area

A Partner should follow these steps to issue a refund:

  1. Log into your Personal Area: https://www.portmone.com.ua/b2b_dash/.
  2. After logging in, look for the menu on the left and select the “Orders” option.
  3. Click the relevant transaction.
  4. In “Return Order” form, check the amount to be refunded ( “Amount” field), add comment (if needed), and click “Return”.

Appendix 1. BILLS message – fields description

Field nameData typeDescription
PAYEE\NAMECHAR(100)Name of a payee’s company
PAYEE\CODENUMBER(15,0)Company code (provided by Portmone.com system)
BANK\NAMECHAR(100)Name of sender's bank
BANK\CODECHAR(6)MFO of sender's bank.
When the IBAN account number is used in payment details, a "0" (zero) is transferred in the BANK\CODE field
BANK\ACCOUNTCHAR(29)Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document)
BILL_IDNUMBER(15,0)Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID
BILL_NUMBERCHAR(120)Bill number
BILL_DATECHAR(10)Bill date in YYYY-MM-DD format
BILL_PERIODCHAR(4)Bill period in MMYY (month and year) format
PAY_DATECHAR(10)Date of payment in YYYY-MM-DD format
PAYED_AMOUNTNUMBER(15,2)Amount of payment. Use dot (".") as the decimal separator
PAYED_COMMISSIONNUMBER(15,2)Amount of banking commission. Always equal to 0
PAYED_DEBTNUMBER(15,2)Including payment of debt. Use dot (".") as the decimal separator
AUTH_CODECHAR(6)Authorization code for a payment card
CONTRACT_NUMBERCHAR(20)Parameter by which the company and the Portmone.com system have agreed to identify the client
ATTRIBUTE1CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE2CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE3CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE4CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message

Appendix 2. BILLS message example

<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
<PAYEE>
<NAME>Public Company “Berezka”</NAME>
<CODE>1001</CODE>
</PAYEE>
<BANK>
<NAME>JSC "Bank "Finance and Credit"</NAME>
<CODE>300131</CODE>
<ACCOUNT>29244020902980</ACCOUNT>
</BANK>
<BILL_ID>14561</BILL_ID>
<BILL_NUMBER>3892/1</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>120.35</PAYED_AMOUNT>
<PAYED_COMMISSION>0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>739280</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Order description </CONTRACT_NUMBER>
<ATTRIBUTE1>12082010</ATTRIBUTE1>
</PAYER>
</BILL>
</BILLS>

Appendix 3. PAY_ORDERS message – fields description

Field nameData typeDescription
PAY_ORDER_IDNUMBER(15,0)Payment order ID. The company must verify that the PAY_ORDER_ID is unique and should not allow to register two messages with the same PAY_ORDER_ID
PAY_ORDER_DATECHAR(10)Date of payment order in YYYY-MM-DD format
PAY_ORDER_NUMBERCHAR(20)Number of payment order
PAY_ORDER_AMOUNTNUMBER(15,2)The amount of payment order. Use dot (".") as the decimal separator
PAYEE\NAMECHAR(100)Name of a payee’s company
PAYEE\CODENUMBER(15,0)Company code (provided by the Portmone.com system)
BANK\NAMECHAR(100)Name of sender's bank
BANK\CODECHAR(6)MFO of sender's bank.
When the IBAN account number is used in payment details, a "0" (zero) is transferred in the BANK\CODE field
BANK\ACCOUNTCHAR(29)Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document)
BILL_IDNUMBER(15,0)Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID
BILL_NUMBERCHAR(120)Bill number
BILL_DATECHAR(10)Bill date in YYYY-MM-DD format
BILL_PERIODCHAR(4)Bill period in MMYY (month and year) format
PAY_DATECHAR(10)Date of payment in YYYY-MM-DD format
PAYED_AMOUNTNUMBER(15,2)Amount of payment. Use dot (".") as the decimal separator
PAYED_COMMISSIONNUMBER(15,2)Amount of banking commission
PAYED_DEBTNUMBER(15,2)Including payment of debt. Use dot (".") as the decimal separator
AUTH_CODECHAR(6)Authorization code for a payment card
CONTRACT_NUMBERCHAR(20)Parameter by which the company and the Portmone.com system have agreed to identify the client
ATTRIBUTE1CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE2CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE3CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE4CHAR(20)Additional client identification parameter. If it is not required for client identification, it will not be sent in a message

Appendix 4. PAY_ORDERS message example

<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
<PAY_ORDER>
<PAY_ORDER_ID>26792</PAY_ORDER_ID>
<PAY_ORDER_DATE>2010-02-16</PAY_ORDER_DATE>
<PAY_ORDER_NUMBER>120985735</PAY_ORDER_NUMBER>
<PAY_ORDER_AMOUNT>138.85</PAY_ORDER_AMOUNT>
<PAYEE>
<NAME>Public Company “Berezka”</NAME>
<CODE>1001</CODE>
</PAYEE>
<BANK>
<NAME>JSC “Bank “Finance and Credit”</NAME>
<CODE>300131</CODE>
<ACCOUNT>29244020902980</ACCOUNT>
</BANK>
<BILLS>
<BILL>
<BILL_ID>14561</BILL_ID>
<BILL_NUMBER>3892/1</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>120.35</PAYED_AMOUNT>
<PAYED_COMMISSION>5.0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>739280</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>08967563</CONTRACT_NUMBER>
<ATTRIBUTE1>12082010</ATTRIBUTE1>
</PAYER>
</BILL>
<BILL>
<BILL_ID>14569</BILL_ID>
<BILL_NUMBER>3892/2</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>20.50</PAYED_AMOUNT>
<PAYED_COMMISSION>1.0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>360157</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>08967568</CONTRACT_NUMBER>
<ATTRIBUTE1>12082011</ATTRIBUTE1>
</PAYER>
</BILL>
</BILLS>
</PAY_ORDER>
</PAY_ORDERS>