Portmone Payment Link. API Reference.
Glossary
Term | Definition |
---|---|
Merchant, Partner | Organization which has signed a payment acceptance agreement with Portmone.com |
Client, Customer | A person who visits the Merchant's online store in order to learn about the range of goods (services) and to make a purchase |
Card, Payment Card | Payment cards of Visa, Mastercard international card associations and the National payment system PROSTIR |
Authorization | The process of giving access rights or other powers to the Customer, program or process |
Personal Area | A 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 |
ITN | Individual Taxpayer Number |
NBU | The National Bank of Ukraine |
Weekends or holidays | Non-working days in Ukraine, during which the bank does not carry out banking operations |
Back office | Specialized software used by Portmone.com staff |
IBAN | International 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.
Fig. 1. An example of payment page
Fig. 2. An example of displaying automatic payment parameters without 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:
Parameter | Description | Required | Value |
---|---|---|---|
v | Protocol version | Yes | Always takes the value "2" |
payeeId | A unique identifier of the Partner in the Portmone.com system | Yes | Assigned to each Partner individually when connected to the Portmone.com system |
amount | Amount 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 payments | Yes | For example: 100.50 |
lang | Payment system interface language | No | uk – Ukrainian, en – English, (default value) uk – Ukrainian |
edit | Editing automatic payment settings by client. By default editing is not possible | No | "Y" – editable, "N" – non-editable |
description* | Comment to the order / description of payment details | No | Maximum length is 250 symbols |
attribute1* | Service field | No | Filled at company's discretion |
attribute2* | Service field | No | Filled at company's discretion |
attribute3* | Service field | No | Filled at company's discretion |
attribute4* | Service field | No | Filled at company's discretion |
billCurrency | Currency of the payment | No | Possible values: UAH (default value), USD, EUR, GBP, KZT |
billNumber | Number 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 transaction | No | Maximum length is 120 symbols |
emailAddress | Email address of the payer | Yes | For example: [email protected] |
timeToLive | Deadline 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 limited | No | From 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 |
contractDate | The effective date of the contract | No | MM.DD.YYYY |
limit | Expiration date of the contract | No | MM.DD.YYYY |
successUrl | The URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after successful payment | No | For example: https://portmone2.com/r3/ecommerce/test/master-test-form" |
infoParams | A block of parameters for additional client information that will be displayed when setting up automatic payments | No | See the infoParams structure |
settings | A block of parameters for setting up automatic payments | No | See the settings structure |
infoParams
structure
Parameter | Description | Required | Value |
---|---|---|---|
phone | Number of the client’s mobile phone | No | 380ХХХХХХХХХ |
birthDate | Date of birth of the client | No | MM.DD.YYYY |
settings
structure
Parameter | Description | Required | Value |
---|---|---|---|
period | Frequency of automatic payments | Yes | 1 – monthly 2 – quarterly 3 – semiannually 4 – annually |
payDate | Day of the month for automatic payment | Yes | From 1 to 28 |
startDate | Date of the first payment. If not specified, the current date is automatically set | No | MM.DD.YYYY |
endDate | The automatic payment end date. If not specified, the current date + 3 years is automatically set | No | MM.DD.YYYY |
Note: * – the values of
description
andattribute1-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:
Parameter | Description | Branding type for which a parameter can be used |
---|---|---|
logo | Link 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 edges | brand, co-brand |
logoWidth | The width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300px | brand, co-brand |
logoHeight | The height of the logo. Should be entered in the "100px" format. Maximum recommended value is 50px (maximum height for PNG – 53px) | brand, co-brand |
backgroundColorHeader | The colour of a header section on the page. The input format is HEX (for example, #ff0000) | brand, light |
backgroundColorButtons | The colour of buttons. The input format is HEX (for example, #ff0000) | brand, light |
colorTextAndIcons | Text and icon colour. The input format is HEX (for example, #ff0000) | brand, light |
bcMain | The 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:
Fig. 4. Portmone.com standard style (branding type – portmone)
Fig. 5. Partner style for the entire page (branding type – brand)
Fig. 6. Partner’s logo is displayed on the page along with the Portmone.com logo (branding type – co-brand)
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 name | Data type | Description |
---|---|---|
ERROR_CODE | NUMBER(15,0) | Error code (0 in case if message processing is successful) |
REASON | CHAR(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 number | Result |
---|---|
4444333322221111 | Successful payment |
4111111111111111 | Failed 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:
- Log into your Personal Area: https://www.portmone.com.ua/b2b_dash/.
- After logging in, look for the menu on the left and select the “Orders” option.
- Click the relevant transaction.
- 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 name | Data type | Description |
---|---|---|
PAYEE\NAME | CHAR(100) | Name of a payee’s company |
PAYEE\CODE | NUMBER(15,0) | Company code (provided by Portmone.com system) |
BANK\NAME | CHAR(100) | Name of sender's bank |
BANK\CODE | CHAR(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\ACCOUNT | CHAR(29) | Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document) |
BILL_ID | NUMBER(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_NUMBER | CHAR(120) | Bill number |
BILL_DATE | CHAR(10) | Bill date in YYYY-MM-DD format |
BILL_PERIOD | CHAR(4) | Bill period in MMYY (month and year) format |
PAY_DATE | CHAR(10) | Date of payment in YYYY-MM-DD format |
PAYED_AMOUNT | NUMBER(15,2) | Amount of payment. Use dot (".") as the decimal separator |
PAYED_COMMISSION | NUMBER(15,2) | Amount of banking commission. Always equal to 0 |
PAYED_DEBT | NUMBER(15,2) | Including payment of debt. Use dot (".") as the decimal separator |
AUTH_CODE | CHAR(6) | Authorization code for a payment card |
CONTRACT_NUMBER | CHAR(20) | Parameter by which the company and the Portmone.com system have agreed to identify the client |
ATTRIBUTE1 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE2 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE3 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE4 | CHAR(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 name | Data type | Description |
---|---|---|
PAY_ORDER_ID | NUMBER(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_DATE | CHAR(10) | Date of payment order in YYYY-MM-DD format |
PAY_ORDER_NUMBER | CHAR(20) | Number of payment order |
PAY_ORDER_AMOUNT | NUMBER(15,2) | The amount of payment order. Use dot (".") as the decimal separator |
PAYEE\NAME | CHAR(100) | Name of a payee’s company |
PAYEE\CODE | NUMBER(15,0) | Company code (provided by the Portmone.com system) |
BANK\NAME | CHAR(100) | Name of sender's bank |
BANK\CODE | CHAR(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\ACCOUNT | CHAR(29) | Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document) |
BILL_ID | NUMBER(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_NUMBER | CHAR(120) | Bill number |
BILL_DATE | CHAR(10) | Bill date in YYYY-MM-DD format |
BILL_PERIOD | CHAR(4) | Bill period in MMYY (month and year) format |
PAY_DATE | CHAR(10) | Date of payment in YYYY-MM-DD format |
PAYED_AMOUNT | NUMBER(15,2) | Amount of payment. Use dot (".") as the decimal separator |
PAYED_COMMISSION | NUMBER(15,2) | Amount of banking commission |
PAYED_DEBT | NUMBER(15,2) | Including payment of debt. Use dot (".") as the decimal separator |
AUTH_CODE | CHAR(6) | Authorization code for a payment card |
CONTRACT_NUMBER | CHAR(20) | Parameter by which the company and the Portmone.com system have agreed to identify the client |
ATTRIBUTE1 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE2 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE3 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE4 | CHAR(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>