Portmone.com Payment Gateway

Glossary

Term	Definition
Merchant, Online Store or Partner	Organization which has signed a payment acceptance agreement with Portmone.com
Buyer, Client or Customer	A person who visits the Merchant's Online Store in order to learn about the range of goods (services) and to make a purchase
Card, Payment Card	Payment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
Authorization	The process of giving access rights or other powers to the Buyer, program or process
Recurring Payments	Automatic payments (no client actions or re-entering card details required), which are carried out with the consent of the client
Token	A unique digital identifier of a card, which is generated during the first operation and then used for quick payment. Token can only be used to repeat a similar transaction as at the first payment
SHOPBILLID	A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
CVV2/CVC2	CVV2 (Card Verification Value 2) is a three-digit card security code that helps to verify legitimacy of a Visa payment card. The Mastercard payment system has similar card security code called CVC2 (Card Validation Code 2)
Acquiring Bank	A bank that organizes banking cards acceptance points (terminals, ATM’s) and processes full range of financial operations connected with performing bank settlements and payments by banking cards at that points
Issuing Bank (Card Issuing Bank)	A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards
3-D Secure	3-D Secure is a protocol which used to secure handling of online bank card payments
IBAN	International Bank Account Number
IPS	International Payment System

1. Payment acceptance technology

The description of procedure for payment acceptance by payment cards on the Online Store website:

The Buyer chooses a product on a website (or in the mobile application) of a Store, forms the order and selects payment card as a payment method.
The Store redirects the Buyer to the Portmone.com system authorization server, sending a set of necessary parameters like partner Id in the Portmone.com system, order number, its amount, etc.
The Portmone.com authorization server establishes connection with the Buyer using secure protocol (TLS 1.2), verifies the data received from the Store.
The Portmone.com site receives from the Buyer the parameters of his/her Payment Card and ensures the authorization of the Card.
When the 3-D Secure technology is used, the Portmone.com sends the Client to the site of Card Issuing Bank to confirm the transaction.
The authorization request is sent through closed banking networks to the Buyer's Card Issuing Bank or to the processing center authorized by the Issuing Bank.
- The Bank sends a positive authorization result to the Portmone.com authorization server.
- The Portmone.com authorization server checks the cryptographic integrity of the data received, adds the information to the database.
- Portmone.com redirects the Client to the Online Store page to confirm successful payment.
- The Store checks the status of the transaction in the Portmone.com system and delivers the goods (provides service).
- Within the terms specified in the contract, Portmone.com will transfer funds (excluding the acquiring fee) to the Store account. Funds are transferred via single payment covering all transactions for the specified day.
If card authorization failed (authorization was rejected):
- The Bank sends the payment rejection message to the Portmone.com authorization server.
- The Portmone.com authorization server checks the cryptographic integrity of the data received, adds the information to the database.
- The Portmone.com redirects the request to the previously configured page of the Online Store for failed payment.
In case of successful payment, the paid order number and the payment data are transmitted by the POST method to the Online Store page.
The Online Store must additionally check the status and amount of the order by one of the methods described in section 8 "Getting authorization results".

2. Test mode

The test mode of the payment gateway means that the Portmone.com system checks the validity of entered data from the Online Store and its Client, creates an order, but payment card authorization is not performed. The Portmone.com payment gateway may provide the different response (successful or failed), depending on what is necessary for the Online Store employees who perform integration.

Please contact our Account Managers for Online Stores to enable and disable test mode

Email: [email protected]

The Portmone.com system provides partners with two test options:

1. Successful payment test

To get a successful response on the Portmone.com default payment page use following payment card details:

Card number: 4444333322221111 Expiry date: Any but not earlier than current day CVV2: Any

2. Failed payment test

To get an error on the Portmone.com default payment page use following payment card details:

Card number: 4111111111111111 Expiry date: Any but not earlier than current day CVV2: Any

Important! Before starting the payment acceptance system into operation, make sure that the test mode is disabled!

3. Order payment

3.1. POST request

Description:

To accept payments by Payment cards, you should send a request using the POST method to the payment gateway page – https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "3.1 POST order payment request" to study the request structure.

Request parameters description:

Parameter	Description	Required	Value
payee_id	A unique identifier of the Online Store	Yes	Assigned to each Partner individually when connected to the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store. Order 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
bill_amount	Amount of the order. Currency is hryvnia (UAH). The decimal separator is the dot symbol "."	Yes	For example: 1.50
bill_currency	Currency of the payment	No	Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT
description	Comment to the order / description of payment details	No	Maximum length is 250 symbols
success_url	The URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after successful payment. After successful payment of the order Portmone.com will send `shop_order_number` and the payment data to this address using the POST method. Upon calling this page on the website of the Online Store, you can verify the status and the amount of the transaction in the Portmone.com system. These procedures are described below (see section 8 "Getting authorization results")	No	For example: http://example.com/success.html
failure_url	The URL of the Online Store to which the client will be redirected in case of payment rejection	No	For example: http://example.com/failure.html
lang	Payment system interface language	No	uk – Ukrainian, en – English
encoding	Encoding	No	The default is UTF-8
preauth_flag	Sets the pre-authorization mode when funds are only blocked on the Client’s card, but not actually charged from the client’s account	No	"Y" – enable pre-authorization mode, "N" – disable pre-authorization mode (the default is "N")
attribute1-4	Service field	No	Filled at company's discretion
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No	Filled in the next format: Desc1:payeeID1;amount1; Desc2:payeeID2;amount2; where Desc1 – description of the order for the first recipient company, payeeID1 – ID of the first recipient company, amount1 – amount to be enrolled to the account of the first recipient, Desc2 – description of the order for the second recipient company, payeeID2 – ID of the second recipient company, amount2 – amount to be enrolled to the account of the second recipient. The number of recipient companies for a single payment request with splitting is limited to the length of the line (up to 500 characters)
exp_time	Sets the interval during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid	No	Filled in seconds
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	Yes
signature	Signature of the request	Yes

Response structure:

Please, refer to "3.1 POST order payment response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (Id) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 128 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Payer’s Card mask
ATTRIBUTE1	Service field. Filled at company’s discretion
ATTRIBUTE2	Service field. Filled at company’s discretion
ATTRIBUTE3	Service field. Filled at company’s discretion
ATTRIBUTE4	Service field. Filled at company’s discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details. Maximum length is 250 symbols
IPSTOKEN	A unique Visa token
ERRORIPSCODE	Error code if Visa token was not created
ERRORIPSMESSAGE	Error message if Visa token was not created

3.2. JSON request

Description:

To make a payment you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "3.2 JSON order payment request" to study the request structure.

Parameters for generating JSON-structure of request:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	Yes
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	Yes
signature	Signature of the request	Yes
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details). Maximum number of characters 250	No
shopOrderNumber	Number of a paid order in the Partner’s system. Maximum length is 128 symbols	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
preauthConfirm	Date of automatic withdrawal for payments with pre-authorization. Can be used when the `preauthFlag = Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is confirmed automatically). It can not be less than the current date	No
preauthReject	Date of automatic cancellation of pre-authorization. Can be used when the `preauthFlag = Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is cancelled automatically). It can not be less than the current date	No
billCurrency	Currency of the payment. Default value: UAH	No
expTime	Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company’s discretion	No
attribute2	Service field. Filled at company’s discretion	No
attribute3	Service field. Filled at company’s discretion	No
attribute4	Service field. Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Visa Click to Pay	No
privat	Payment via LiqPay, with choosing a card from the Privat24 Internet Banking Pay attention! Pre-authorization functionality does not work when paying via Privat24	No
gpay	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account	No
createtokenonly	Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card")	No
gpayonly	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account (if this option is enabled, other methods are not displayed – only the "Buy with GPay" button is displayed on the payment page)	No
applepay	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account	No
applepayonly	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account (if this option is enabled, other methods are not displayed – only the "Apple Pay" button is displayed on the payment page)	No
kyivstar	Payment from Kyivstar mobile account balance (for prepaid numbers only)	No
installment	Installment payment	No
link	Payment by the BankPay method (using the payer's Bank). The method works if the following parameters are passed: expTime та "showEmail": "Y"	No

Important! Due to internal security policies of Google and Apple, Google Pay and Apple Pay wallets can be unstable when opening a payment page in WebView.
For correct operation, we recommend direct integration of Google Pay and Apple Pay If you have an application, we recommend integrating SDKiOS, SDKAndroid

installmentPlan – installment payment parameters (see section 3.7 “Installment Payments”).
autopayment – this block allows you to set up automatic payments.

The automatic payments functionality allows customers to sign up for automatic monthly / quarterly / semiannual / annual charges. You can manage the client’s subscription parameters by yourself or provide the Client with the possibility to set up the parameters of autopayment.

To get started with automatic payments, you need to get credentials in your Personal Area.

Important! When changing the password, the Partner must generate new credentials.

After setting up:

A subscription to automatic payments from a Client’s Card will be created. The Portmone.com system controls and processes payments. The Client can disable the service by contacting the Portmone.com customer support or an employee of the Online Store (you can delete the client's subscription in the Personal Area).
All subsequent payments will be made on the same description as the first payment.
The order number for automatic payments will be formed as follows:

Order number at first payment_RECURENT_Date of automatic payment

Parameter	Description	Required
show	Displaying the details of the autopayment subscription to the client on the payment page. Possible values: Y – the client can go to a separate page and see the subscription details; N – the client is unable to view subscription details (only the "Make this payment regular" checkbox is displayed) (see fig. 1)	No
edit	Editing automatic payment settings by client. Possible values: Y – all settings can be edited on the subscription details page, the client can save settings (see fig. 2); N – the automatic payment settings provided by the Online Store are displayed and cannot be edited	No
settings	A block of parameters for setting up automatic payments	No
credentials	Authorization parameters	Yes
changeCheckboxState	value Y	Yes
defaultCheckboxState	value: Y – the checkbox "Make payment regular" is autofilled,N – the client independently fills in the "Make regular payment" checkbox	No

The settings block structure:

Parameter	Description	Required
period	Frequency of automatic payments. Takes the following values: 1 – monthly, 2 – quarterly, 3 – semiannually, 4 – annually	Yes
payDate	Day of the month for automatic payment. Can takes value from 1 to 28	No
startDate	Automatic payments start date. Should be sent in the following format: DD.MM.YYYY. If not specified, yesterday's date is automatically set	No
endDate	Automatic payments end date. Should be sent in the following format: DD.MM.YYYY. If not specified, the `startDate` + 3 years is automatically set (or the current payment date is set, if `startDate` is not specified)	No
amount	Amount of the payment. The decimal separator is the dot symbol (".")	Yes

An example of payment page without displaying the details of the autopayment subscription

Fig. 1 – an example of payment page without displaying the details of the autopayment subscription

An example of displaying editable automatic payment parameters

Fig. 2 – an example of displaying editable automatic payment parameters

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token (see section 4 "Order payment using a payment Token")

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take data processing into account)	Required for payment by Token
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Required for payment by Token
cardMask	Card mask	Required for payment by Token
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	No

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No
showEmail	"Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y")	No

Depending on the sent values of the emailAddress and showEmail parameters, there are 4 options for displaying the "e-mail" field on the payment page:

Option	emailAddress	showEmail	Displaying on the payment page
1	empty value	Y	An empty "e-mail" field is displayed
2	valid e-mail	Y	A prefilled "e-mail" field is displayed that can be edited
3	empty value	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity
4	valid e-mail	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity. However, the e-mail sent in the request is processed and a payment receipt is sent to it

shipping – this block contains shipping information

Nova Poshta Delivery

This functionality allows you to enable Nova Poshta delivery.

Parameter	Description	Required
state	Y - enables delivery, N - disables delivery	Yes
source	The name of the delivery service. Accepts the value `novaposhta`	Yes

Example of an array in the request:

"shipping": {
        "collect": {
            "state": "Y",
            "source": "novaposhta"
        }

To pre-fill the fields on the checkout page, you need to pass the Customer’s data in the block payer

"payer": {
        "lang": "uk",
        "emailAddress": "[email protected]",
        "showEmail": "Y",
        "phoneNumber": "660000000",
        "fullName": "Прізвище Ім'я"
    }

Parameter	Description	Required
lang	Language of the payment page interface. Possible values: uk – Ukrainian, en – English	No
emailAddress	The payer’s email address (used to send a receipt for a successful payment; not returned in the response)	Yes
showEmail	Accepts the value "Y"	Yes
phoneNumber	Customer’s phone number. Must be passed in the format `660000000`	Yes
fullName	Customer’s last name and first name	Yes

Three delivery types are available:

To a branch
To a parcel locker
By courier

The fields “City”, “Street”, “Branch”, and “Parcel Locker” are dropdown lists with search functionality on the checkout page. The search begins after entering 3 characters. You can edit the delivery details by clicking the "Back" button.

Ukrposhta Delivery

Parameter	Description	Required
services	Shipping services	Yes
ukrposhta	Carrier name (name of the company that delivers the order to the recipient)	Yes
deliveryTypes	Available delivery methods: W2D – courier delivery to the recipient's address; W2W – delivery to the carrier office/warehouse	Yes
senderClientId	A unique identifier of the Online Store in the carrier system. Created in the merchant's Personal area	Yes
senderAddressId	A unique identifier of the Online Store address in the carrier system. Created in the merchant's Personal area	Yes
senderPostCode	Postal code of the sender	Yes
type	Parcel delivery type. Possible values: STANDARD, EXPRESS	Yes
parcelWeight	Parcel weight in grams. Maximum allowed value – 30000	Yes
parcelLength	The length of the largest side of the parcel stated in centimeters. Numbers only	Yes
parcelWidth	The width of a parcel in centimeters	Yes
parcelHeight	The height of a parcel in centimeters	Yes
parcelDeclaredPrice	The declared cost of a parcel in UAH	Yes
parcelDescription	Description of a parcel	No
fragile	Parcel fragility mark. Possible values: Y, N	No
checkOnDelivery	Checking the contents of the parcel on receiving is needed. Possible values: Y, N	No
bees	Indicates that bees are sent. Possible values: Y, N	No
payer	Indicates who pays for delivery – sender or recipient. Default value: client	Yes
sms	Notify the client via SMS. Possible values: Y, N	No
withDeliveryNotification	Notify the client using the notification service of the carrier company. Possible values: Y, N	No
enable	Enable the displaying of delivery form. Possible values: Y, N	Yes
required	Filling the delivery form is required. Possible values: Y, N	Yes

style – configuration of payment page styles (see section 3.3. Managing a view of a payment page).
goods – Block Containing an Array of Fiscalization Data

Parameter	Description	Required
internalCode	Seller's code	Yes
manufacturerCode	Manufacturer's code	No
govClassificationCode	UKTZED code	Yes
name	Product/service name	Yes
name_en	Product/service name in English	No
description	Product/service description	No
description_en	Product/service description in English	No
price	Price (per unit)	Yes
quantity	Quantity	Yes
uomCode	Unit of measure (optional, default is unit)	No
amount	Amount	Yes
serviceFlag	Service indicator (N - product)	No
taxRateCodes	Numeric tax rate code (pre-programmed in the tax agent's dashboard). For multiple taxes, separate by commas	Yes
descriptionUrl	Product description URL	No
imageUrl	Product image URL	No

Show an example of the JSON structure for the goods block

{
  "goods": [
    {
      "internalCode": "123456",
      "manufacturerCode": "123456",
      "govClassificationCode": "123456",
      "name": "",
      "name_en": "",
      "description": "",
      "description_en": "",
      "price": "100",
      "quantity": "2",
      "uomCode": "",
      "amount": "200",
      "serviceFlag": "N",
      "taxRateCodes": "1",
      "descriptionUrl": "",
      "imageUrl": ""
    }
  ]
}

Response structure:

Please, refer to "3.2 JSON order payment response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 128 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Payer’s Card mask
ATTRIBUTE1	Service field. Filled at company’s discretion
ATTRIBUTE2	Service field. Filled at company’s discretion
ATTRIBUTE3	Service field. Filled at company’s discretion
ATTRIBUTE4	Service field. Filled at company’s discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details. Maximum length is 250 symbols
IPSTOKEN	A unique Visa token
ERRORIPSCODE	Error code if Visa token was not created
ERRORIPSMESSAGE	Error message if Visa token was not created

3.3. Managing a view of a payment page

You can customize the view of the payment page using the style parameter.

Description of the style parameter fields:

Field	Description	Page style type, for which a field can be used
type	Sets the style type of a page: • portmone – default value (standard Portmone.com style, see fig. 3); • brand – full page styling for a partner (see fig. 4); • co-brand – partner’s logo is displayed on the page along with the Portmone.com logo (see fig. 5); • light – the version to display as a frame (see fig. 6). For instructions on how to embed the payment page in a frame, see below
logo	Contains a link to the partner's logo. Supports only link with https scheme. Image format is SVG and PNG only. It is recommended to use an image with a minimum plot indent from all edges	brand, co-brand
logoWidth	Parameter defining the width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300px	brand, co-brand
logoHeight	Parameter defining 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	Sets the colour of a header section on the page. The input format is HEX (for example, #ff0000)	brand, light
backgroundColorButtons	Sets the colour of buttons. The input format is HEX (for example, #ff0000)	brand, light
colorTextAndIcons	Sets text and icon colour. The input format is HEX (for example, #ff0000)	brand, light
borderColorList	Sets the colour of lines in the list of payment methods. The input format is HEX (for example, #ff0000)	brand, light
bcMain	Specifies the colour to fill page background. The input format is HEX (for example, #ff0000)	brand, light
privatButtonPosition	When using the "privat" payment method, this parameter defines the placement of the Privat24 button on the payment form. The button's position can be set to one of three options: "top" (at the top of the payment form), "middle" (in the middle of the payment form), or "bottom" (at the bottom of the payment form). The default value is "bottom".	portmone, brand, light, co-brand

Examples of Privat24 button placement options

Show an example of the Privat24 button placed at the top of the page

Show an example of the Privat24 button placed in the middle of the page

Show an example of the Privat24 button placed at the bottom of the page

Embedding the payment page in a frame

Important! Due to internal security policies of Google and Apple, Google Pay and Apple Pay wallets can be unstable when opening a payment page in WebView.
For correct operation, we recommend direct integration of Google Pay and Apple Pay If you have an application, we recommend integrating SDKiOS, SDKAndroid

To run IFRAME on your site, do the following:

Organise the opportunity to send a payment request on your checkout page, for example, by plasing a form as following:

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="myFrame"
>
  <input
    type="hidden"
    name="bodyRequest"
    value='{
    "paymentTypes": {
        "card": "Y",
        "portmone": "Y",
        "token": "N",
        "clicktopay": "Y",
        "createtokenonly": "N"
    },
    "priorityPaymentTypes": {
        "card": "1",
        "portmone": "2",
        "token": "0",
        "clicktopay": "1",
        "createtokenonly": "0"
    },
    "payee": {
        "payeeId": "1185",
        "login": "",
        "dt": "",
        "signature": "",
        "shopSiteId": ""
    },
    "order": {
        "description": "Test Payment",
        "shopOrderNumber": "SHP-00445401",
        "billAmount": "10",
        "attribute1": "1",
        "attribute2": "2",
        "attribute3": "3",
        "attribute4": "4",
        "attribute5": "",
        "successUrl": "",
        "failureUrl": "",
        "preauthFlag": "N",
        "billCurrency": "UAH",
        "encoding": ""
    },
    "token": {
        "tokenFlag": "N",
        "returnToken": "N",
        "token": "",
        "cardMask": "",
        "otherPaymentMethods": "Y",
        "sellerToken": ""
    },
    "payer": {
        "lang": "uk",
        "emailAddress": "[email protected]"
    },
    "style": {
        "type": "light",
        "logo": "",
        "backgroundColorHeader": "",
        "backgroundColorButtons": "",
        "colorTextAndIcons": "",
        "borderColorList": "",
        "bcMain": ""
    }
}'
  />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" />
</form>

Refer to section 3.2 "JSON request" to study the request structure and parameters.

To display a frame in the light style, you should set the value to light for the type field of the style parameter.

At the target parameter of the form specify the frame in which the payment page will be displayed (in the example above, this is a frame called "myFrame").

Add the IFRAME element to the DOM model of the page. The name parameter value must be equal to the target parameter value from the previous step.

<div>
  <iframe name="myFrame" width="50%" height="70%"  frameborder="0" ></iframe>
</div>

You can customize the width and the height parameters of the frame as desired.

After submitting the request, the response will be displayed in the specified frame.

Ways to display payment page

Portmone.com standard style

Fig. 3 – Portmone.com standard style

Fig. 4 – partner style for the entire page

Partner’s logo is displayed on the page along with the Portmone.com logo

Fig. 5 – partner’s logo is displayed on the page along with the Portmone.com logo

The version to display as a frame on the Online Store website

Fig. 6 – the version to display as a frame on the Online Store website

Purpose: The payment widget allows you to accept payments without redirecting the customer to a separate Portmone page. The checkout takes place on the merchant’s website in a user-friendly format.

The widget supports two display modes:

Modal window (popup): after clicking the button, a separate browser popup opens with the Portmone checkout page.
Embedded frame (iframe): the payment form is rendered directly on the merchant’s page inside an embedded iframe.

Availability & limitations: No limitations.

Integrating the payment button: In order to place Portmone payment button on your checkout page, you have to determine a button location on the page and include some JS code.

After the pg.min.js script loads, the payment button will be rendered inside the same container where the script tag is placed

Example:

<div class="span4">
  <script src="https://www.portmone.com.ua/r3/resources/pg/js/asset/pg.min.js?v=15092019"></script>
  <script type="text/javascript" id="portmone-script">
    var data = {};
    var brand = {
      height: "40px",
      width: "150px",
      buttoncolor: "#FF0000",
      fontfamily: "Open Sans",
      textcolor: "#FFF",
      lang: "uk",
      padding: "5px",
      border: "1px solid grey",
      fontsize: "14px",
      closemodal: "Y",
    };
    PG.success(function (data) {
      console.log(JSON.stringify(data));
    });
    PG.paymentData("gateway", data);
    PG.brandButton(brand);
  </script>
</div>

Branding the payment button: The brand object controls the appearance of the “Pay” button that triggers the checkout window.

Parameter	Description	Required
height	Sets the button height. By default, it accepts the button style set on the page	No
width	Sets the button width. By default, it accepts the button style set on the page	No
buttoncolor	Sets the button colour. By default, it accepts the button style set on the page	No
fontfamily	Sets the button font type. By default, it accepts the button style set on the page	No
textcolor	Sets the button font colour. By default, it accepts the button style set on the page	No
lang	Sets the language for displaying the text of the "Pay" / "Download receipt" button. Default value: uk – Ukrainian	No
padding	Sets the value of the padding around the button's content. By default, it accepts the button style set on the page	No
border	Allows you to specify the style, width and colour of the button's border. By default, it accepts the button style set on the page	No
fontsize	Sets the button font size. By default, it accepts the button style set on the page	No
closemodal	Determines whether to close a modal window after making a payment. If set to "N", the window is not closed and successful payment notification is displayed in the modal. If set to "Y", the window is closed and the payment data is sent to the merchant's processing function. The default value is "Y"	No

Widget initialization: To run the widget, pass a data object that contains merchant information, order parameters, and payment methods.

See the example data object in section "3.4.1 Example of the data object for popup mode"

Parameters of the data object:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details) Max 250 symbols	No
shopOrderNumber	Number of a paid order in the Partner’s system. Maximum length is 128 symbols	No
billAmount	Amount of the payment	Yes
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
preauthConfirm	Date of automatic withdrawal for payments with pre-authorization. Can be used when the `preauthFlag = Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is confirmed automatically). It can not be less than the current date	No
preauthReject	Date of automatic cancellation of pre-authorization. Can be used when the `preauthFlag=Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is cancelled automatically). It can not be less than the current date	No
billCurrency	Currency of the payment. Default value: UAH	No
expTime	Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute2	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute3	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute4	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment"). Maximum length is 500 symbols	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Visa Click to Pay	No
privat	Payment via LigPay, with choosing a card from the Privat24 Internet Banking	No
gpay	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account	No
createtokenonly	Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card")	No
gpayonly	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account (if this option is enabled, other methods are not displayed – only the "Buy with GPay" button is displayed on the payment page)	No
applepay	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account	No
applepayonly	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account (if this option is enabled, other methods are not displayed – only the "Apple Pay" button is displayed on the payment page)	No
link	Payment by the BankPay method (using the payer's Bank). The method works if the following parameters are passed: expTime та "showEmail": "Y"	No

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token (see section 4 "Order payment using a payment Token")

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take data processing into account)	Required for payment by Token
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Required for payment by Token
cardMask	Card mask	Required for payment by Token
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	No

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No
showEmail	"Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y")	No

Depending on the sent values of the emailAddress and showEmail parameters, there are 4 options for displaying the "e-mail" field on the payment page:

Option	emailAddress	showEmail	Displaying on the payment page
1	empty value	Y	An empty "e-mail" field is displayed
2	valid e-mail	Y	A prefilled "e-mail" field is displayed that can be edited
3	empty value	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity
4	valid e-mail	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity. However, the e-mail sent in the request is processed and a payment receipt is sent to it

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
goods — optional array with fiscalization data.

Parameter	Description	Required
internalCode	Seller's code	Yes
manufacturerCode	Manufacturer's code	No
govClassificationCode	UKTZED code	Yes
name	Product/service name	Yes
name_en	Product/service name in English	No
description	Product/service description	No
description_en	Product/service description in English	No
price	Price (per unit)	Yes
quantity	Quantity	Yes
uomCode	Unit of measure (optional, default is unit)	No
amount	Amount	Yes
serviceFlag	Service indicator (N - product)	No
taxRateCodes	Numeric tax rate code (pre-programmed in the tax agent's dashboard). For multiple taxes, separate by commas	Yes
descriptionUrl	Product description URL	No
imageUrl	Product image URL	No

Service functions:

PG.success – this function takes the data object that describes the payment made. In case the Merchant does not process the data, the payment button changes its state and name, and payer can download the payment receipt upon clicking on it.
PG.brandButton – this function takes an object that describes and stylizes a payment button.
PG.paymentData – this function initializes and places the payment button on the Merchant's page.

This function takes the following parameters:

PG.paymentData(typePayment, data, typeView);

Where:

1) typePayment – a string that characterizes the payment type used. Can take the following values:

Value	Desctiption
gateway	This type of payment allows you to create and process a typical payment based on the transmitted data. The *data* object is generated as for a regular JSON-based request
stock	This type of payment is used to process a payment based on the product identifier, which was created in the Merchant’s Personal Area. In this case the *data* object has the follwing structure: `var data = { "id":"303429c03b3a743bdf8ee02" };`
terminal	This type of payment saves the processing of the *data* object properties, which are transferred when paying using the *terminal* type, but allows you to leave `billAmount`, `description`, `attribute1`, `attribute2`, `attribute3`, `attribute4` fields blank to further initialization this data by the payer
p2p	This type of payment allows you to process a payment with crediting funds to the Merchant's card, which has been verified and added to the Merchant's Personal Area. In this case the *data* object has the follwing structure: `var data = { "hash":"" };`, where `hash` – value from the payment link

2) typeView – а string that characterizes the modal window type:

modal – opens the payment window in a new browser window with the specified sizes (see fig. 7).
frame – opens the payment window in a frame (see fig. 8);

PG.create – this function creates a payment frame based on the data passed into the PG. paymentData function. The function can be used when Merchant creates its own mechanisms for calling a payment frame. Does not contain any parameters.
PG.setButtonId – this function can be used for cases when Merchant stylizes the frame call button himself and initializes his own text on the button. The function takes the id attribute used for the Merchant's button HTML element as an argument. For example: PG.setButtonId('paymentButton');. After that, when the button is pressed, the Portmone payment frame opens to the Merchant.

This function should be used in combination with the PG.create function.

Example:

a frame creating based on settings from the PG. paymentData function

PG.paymentData("gateway",data,"frame"); PG.create();

Merchant's button id setting

PG.setButtonId('paymentButton');

Response structure:

If Merchant initialize the data processing on its side through the PG.success function after making a payment by the client, it is necessary to implement the processing of data that will be passed to the processing function.

Description of parameters passed to the processing function:

Parameter	Description
status	Transaction status. Takes the value PAYED
errorCode	Error Code
error	Remains unfilled
shopBillId	A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
billAmount	Amount of the payment
shopOrderNumber	Number of paid order (bill) in the Merchant's system.
cardMask	Payer’s Card mask
attribute1	Service field
attribute2	Service field
attribute3	Service field
attribute4	Service field
receiptLink	Link to get a receipt
lang	Payment system interface language. Possible values: uk – Ukrainian, en – English
description	Comment to the order / description of payment details.
token	Card token
commission	The value of the commission from payment
payeeName	Merchant name
billCurrency	Currency of the payment
IPSTokenValue	A unique Visa token
errorIPSCode	Error code if Visa token was not created
errorIPSMessage	Error message if Visa token was not created

An example of opening the payment window in a new browser window with the specified sizes

Fig. 7 – an example of opening the payment window in a new browser window with the specified sizes

3.4.2 Payment in an embedded frame (iframe)

Technical requirements and Apple Pay configuration: For Apple Pay, there are browser-level limitations: within an embedded iframe, the Apple Pay button may function inconsistently or fail to appear entirely. This is due to Apple’s security policy, which requires direct user interaction and merchant domain verification.

To ensure stable operation of Apple Pay in an iframe, you must:

Create Apple certificates and complete domain verification according to the instructions.
In the data initialization object, within the payee block, pass additional parameters that identify the merchant in Apple’s system: appleMerchantName — a unique Merchant ID created in your Apple Developer account during Apple Pay setup. appleMerchantLabel — the name displayed to the user in the Apple Pay window when selecting a card.

For Apple Pay with QR code, include the official apple-pay-js library. Apple documentation

<head>
  <script
    crossorigin
    src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"
    crossorigin="anonymous"
  ></script>
</head>

Place the iframe high in the DOM tree. Steps:

Create a div and assign it a unique id.
Place this div near the top levels of the DOM structure.
In the payment initialization data object, pass frameHolderId equal to that id.

Apple Pay certificate setup & domain verification guide:

Check out the video guide that explains in detail how to set up Apple Pay on your website.
Watch the video guide at this link: Detailed Apple Pay Setup Video Guide.

1. Registering a Merchant ID
A Merchant ID uniquely identifies you in Apple Pay as a merchant capable of accepting payments. A Merchant ID never expires, and you can use the same one for multiple applications.

Log in to your Apple Developer Account.
Go to the Certificates, Identifiers & Profiles section.
Click Identifiers in the sidebar, then click the add button (+) in the top left corner.
Select Merchant IDs, then click Continue.
Enter Description and Identifier*, then click Continue.
Review the settings and click Register.
Send your Merchant ID to Portmone at [email protected].
Receive a CSR file from Portmone, which is required for creating the Apple Pay Payment Processing Certificate.

Note:
Description – merchant description.
Identifier – your domain in reverse order, prefixed with "merchant" (e.g., for shop.ua, the Identifier will be merchant.ua.shop).

2. Creating an Apple Pay Payment Processing Certificate

The Apple Pay Payment Processing Certificate is associated with your Merchant ID and is used to encrypt payment information. The Payment Processing Certificate expires every 25 months. If the certificate is revoked, you can recreate it.

Log in to your Apple Developer Account.
In Certificates, Identifiers & Profiles, click Identifiers in the sidebar.
Use the filter in the top-right corner to select Merchant IDs.
On the right, select your Merchant ID.
Under Apple Pay Payment Processing Certificate, click Create Certificate.
Upload the CSR file received from Portmone by clicking Choose File, then click Continue.
Click Download.
Send the downloaded certificate (apple_pay.cer) to Portmone at [email protected].

Note:
If a banner appears at the top of the page requiring you to accept an agreement, click Review Agreement and follow the instructions before proceeding.

3. Registering and Verifying a Domain

Log in to your Apple Developer Account.
In Certificates, Identifiers & Profiles, click Identifiers in the sidebar, then select Merchant IDs in the top-right dropdown menu.
Select your Merchant ID.
Under Merchant Domains, click Add Domain.
Enter your domain name and click Save.
Download the apple-developer-merchantid-domain-association.txt file.

Place the file in the root directory of your domain under the following path:

https://<your-domain>/.well-known/apple-developer-merchantid-domain-association.txt

Ensure the file is accessible via browser at the specified URL.
Click Verify.
If everything is set up correctly, the domain status will change to Verified.

Note:
The domain must support HTTPS.

4. Creating an Apple Pay Merchant Identity Certificate
The Merchant Identity Certificate is required for working with Apple Pay. It ensures secure operations and identifies the merchant. This certificate is also necessary for creating an Apple Pay Payment Session during merchant validation.

Before creating the Apple Pay Merchant Identity Certificate, you need to obtain a Certificate Signing Request (CSR). This can be done in several ways:

Obtaining a CSR and private key from Portmone (Recommended Method)
Send a request to [email protected] for a CSR to create the Apple Pay Merchant Identity Certificate. In response, receive a prepared CSR file that complies with Apple's requirements, along with a private key. This method is recommended as it simplifies the process and ensures compatibility.
Generating the CSR and private key yourself

There are several ways to generate a CSR and private key yourself: using Keychain Access on macOS (Apple's guide) or OpenSSL. Below is the instruction for creating a CSR using Keychain Access:

Open Keychain Access, located in /Applications/Utilities.
In the menu, select: Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority.
In the pop-up window, fill in the fields:
- User Email Address: enter your email address.
- Common Name: enter the key name.
- CA Email Address: leave it blank.
Select the option I will provide the key pair information to manually create the key pair required for the CSR.
Select the option Saved to disk and click Continue. Save the file with the .certSigningRequest extension.
Use the algorithm and key size: RSA(2048). Apple Pay on the Web troubleshooting guide / Create a merchant identity certificate

After obtaining the CSR, follow these steps to create the certificate:

Log in to your Apple Developer Account.
In Certificates, Identifiers & Profiles, click Identifiers in the sidebar, then select Merchant IDs in the top-right dropdown menu.
Find the created Merchant ID and click on it.
Under Apple Pay Merchant Identity Certificate, click Create Certificate.
Upload the CSR file by clicking Choose File, select the file, and click Continue.
Complete the process by clicking Download to save the certificate.
Send the generated certificate (merchant_id.cer) and private key (if you generated it yourself) to Portmone at [email protected].

Integrating the payment button: To place the Portmone payment button on the merchant’s page, choose the target location and insert the JavaScript code to load the script and initialize the widget.

After pg.min.js loads, the payment button will be rendered in the same container where the script tag is placed.

Example:

<div class="span4">
  <script src="https://www.portmone.com.ua/r3/resources/pg/js/asset/pg.min.js?v=15092019"></script>
  <script type="text/javascript" id="portmone-script">
    var data = {};
    var brand = {
      height: "40px",
      width: "150px",
      buttoncolor: "#FF0000",
      fontfamily: "Open Sans",
      textcolor: "#FFF",
      lang: "uk",
      padding: "5px",
      border: "1px solid grey",
      fontsize: "14px",
      closemodal: "Y",
    };
    PG.success(function (data) {
      console.log(JSON.stringify(data));
    });
    PG.paymentData("gateway", data);
    PG.brandButton(brand);
  </script>
</div>

Branding the payment button: The brand object controls the appearance of the “Pay” button that triggers the checkout window.

Parameter	Description	Required
height	Sets the button height. By default, it accepts the button style set on the page	No
width	Sets the button width. By default, it accepts the button style set on the page	No
buttoncolor	Sets the button colour. By default, it accepts the button style set on the page	No
fontfamily	Sets the button font type. By default, it accepts the button style set on the page	No
textcolor	Sets the button font colour. By default, it accepts the button style set on the page	No
lang	Sets the language for displaying the text of the "Pay" / "Download receipt" button. Default value: uk – Ukrainian	No
padding	Sets the value of the padding around the button's content. By default, it accepts the button style set on the page	No
border	Allows you to specify the style, width and colour of the button's border. By default, it accepts the button style set on the page	No
fontsize	Sets the button font size. By default, it accepts the button style set on the page	No
closemodal	Determines whether to close a modal window after making a payment. If set to "N", the window is not closed and successful payment notification is displayed in the modal. If set to "Y", the window is closed and the payment data is sent to the merchant's processing function. The default value is "Y"	No

Widget initialization: To run the widget, pass a data object that contains merchant information, order parameters, and payment methods.

See the example data object in section "3.4.2 Example of the data object for iframe mode"

Parameters of the data object:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
appleMerchantName	Apple Merchant Identifier — Merchant ID.	Yes
appleMerchantLabel	The name that will be displayed to the customer in Apple Pay when selecting a card.	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details) Max 250 symbols	No
shopOrderNumber	Number of a paid order in the Partner’s system. Maximum length is 128 symbols	No
billAmount	Amount of the payment	Yes
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
preauthConfirm	Date of automatic withdrawal for payments with pre-authorization. Can be used when the `preauthFlag = Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is confirmed automatically). It can not be less than the current date	No
preauthReject	Date of automatic cancellation of pre-authorization. Can be used when the `preauthFlag=Y` parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is cancelled automatically). It can not be less than the current date	No
billCurrency	Currency of the payment. Default value: UAH	No
expTime	Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute2	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute3	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute4	Service field. Filled at company’s discretion. Maximum length is 1000 symbols	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment"). Maximum length is 500 symbols	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Visa Click to Pay	No
privat	Payment via LigPay, with choosing a card from the Privat24 Internet Banking	No
gpay	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account	No
createtokenonly	Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card")	No
gpayonly	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account (if this option is enabled, other methods are not displayed – only the "Buy with GPay" button is displayed on the payment page)	No
applepay	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account	No
applepayonly	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account (if this option is enabled, other methods are not displayed – only the "Apple Pay" button is displayed on the payment page)	No
link	Payment by the BankPay method (using the payer's Bank). The method works if the following parameters are passed: expTime та "showEmail": "Y"	No

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token (see section 4 "Order payment using a payment Token")

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take data processing into account)	Required for payment by Token
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Required for payment by Token
cardMask	Card mask	Required for payment by Token
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	No

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No
showEmail	"Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y")	No

Depending on the sent values of the emailAddress and showEmail parameters, there are 4 options for displaying the "e-mail" field on the payment page:

Option	emailAddress	showEmail	Displaying on the payment page
1	empty value	Y	An empty "e-mail" field is displayed
2	valid e-mail	Y	A prefilled "e-mail" field is displayed that can be edited
3	empty value	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity
4	valid e-mail	N	The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity. However, the e-mail sent in the request is processed and a payment receipt is sent to it

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page"). You can customize the view of the payment page using the style parameter.

Description of the style parameter fields:

Field	Description	Page style type, for which a field can be used
type	Sets the style type of a page: • portmone – default value (standard Portmone.com style, see fig. 3); • brand – full page styling for a partner (see fig. 4); • co-brand – partner’s logo is displayed on the page along with the Portmone.com logo (see fig. 5); • light – the version to display as a frame (see fig. 6). For instructions on how to embed the payment page in a frame, see below
logo	Contains a link to the partner's logo. Supports only link with https scheme. Image format is SVG and PNG only. It is recommended to use an image with a minimum plot indent from all edges	brand, co-brand
logoWidth	Parameter defining the width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300px	brand, co-brand
logoHeight	Parameter defining 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	Sets the colour of a header section on the page. The input format is HEX (for example, #ff0000)	brand, light
backgroundColorButtons	Sets the colour of buttons. The input format is HEX (for example, #ff0000)	brand, light
colorTextAndIcons	Sets text and icon colour. The input format is HEX (for example, #ff0000)	brand, light
borderColorList	Sets the colour of lines in the list of payment methods. The input format is HEX (for example, #ff0000)	brand, light
bcMain	Specifies the colour to fill page background. The input format is HEX (for example, #ff0000)	brand, light
privatButtonPosition	When using the "privat" payment method, this parameter defines the placement of the Privat24 button on the payment form. The button's position can be set to one of three options: "top" (at the top of the payment form), "middle" (in the middle of the payment form), or "bottom" (at the bottom of the payment form). The default value is "bottom".	portmone, brand, light, co-brand
closeVisible	Allows you to control the visibility of the “Close” button in the payment frame. Accepts values `"Y"` or `"N"`.	portmone, brand, light, co-brand

goods — optional array with fiscalization data.

Parameter	Description	Required
internalCode	Seller's code	Yes
manufacturerCode	Manufacturer's code	No
govClassificationCode	UKTZED code	Yes
name	Product/service name	Yes
name_en	Product/service name in English	No
description	Product/service description	No
description_en	Product/service description in English	No
price	Price (per unit)	Yes
quantity	Quantity	Yes
uomCode	Unit of measure (optional, default is unit)	No
amount	Amount	Yes
serviceFlag	Service indicator (N - product)	No
taxRateCodes	Numeric tax rate code (pre-programmed in the tax agent's dashboard). For multiple taxes, separate by commas	Yes
descriptionUrl	Product description URL	No
imageUrl	Product image URL	No

Service functions:

PG.success – this function takes the data object that describes the payment made. In case the Merchant does not process the data, the payment button changes its state and name, and payer can download the payment receipt upon clicking on it.
PG.brandButton – this function takes an object that describes and stylizes a payment button.
PG.paymentData – this function initializes and places the payment button on the Merchant's page.

This function takes the following parameters:

PG.paymentData(typePayment, data, typeView);

Where:

1) typePayment – a string that characterizes the payment type used. Can take the following values:

Value	Desctiption
gateway	This type of payment allows you to create and process a typical payment based on the transmitted data. The *data* object is generated as for a regular JSON-based request
stock	This type of payment is used to process a payment based on the product identifier, which was created in the Merchant’s Personal Area. In this case the *data* object has the follwing structure: `var data = { "id":"303429c03b3a743bdf8ee02" };`
terminal	This type of payment saves the processing of the *data* object properties, which are transferred when paying using the *terminal* type, but allows you to leave `billAmount`, `description`, `attribute1`, `attribute2`, `attribute3`, `attribute4` fields blank to further initialization this data by the payer
p2p	This type of payment allows you to process a payment with crediting funds to the Merchant's card, which has been verified and added to the Merchant's Personal Area. In this case the *data* object has the follwing structure: `var data = { "hash":"" };`, where `hash` – value from the payment link

2) typeView – а string that characterizes the modal window type:

modal – opens the payment window in a new browser window with the specified sizes (see fig. 7).
frame – opens the payment window in a frame (see fig. 8);

PG.create – this function creates a payment frame based on the data passed into the PG. paymentData function. The function can be used when Merchant creates its own mechanisms for calling a payment frame. Does not contain any parameters.
PG.setButtonId – this function can be used for cases when Merchant stylizes the frame call button himself and initializes his own text on the button. The function takes the id attribute used for the Merchant's button HTML element as an argument. For example: PG.setButtonId('paymentButton');. After that, when the button is pressed, the Portmone payment frame opens to the Merchant.

This function should be used in combination with the PG.create function.

Example:

a frame creating based on settings from the PG. paymentData function

PG.paymentData("gateway",data,"frame"); PG.create();

Merchant's button id setting

PG.setButtonId('paymentButton');

Additional capabilities:

Mount the frame into a specific page element

Create a div with a unique id.
Place it high in the DOM tree.
In the data initialization object, pass frameHolderId equal to that id.

"frameHolderId": "paymentFrame1"

Control the "Close" button in the payment frame In the style block of the data object, set the parameter closeVisible: "Y" — show the Close button (default)
"N" — hide the Close button

To handle the frame-close event, use the PG.onClose() callback:

PG.onClose(function () {
  console.log("close event");
});

Response structure:

Description of parameters passed to the processing function:

Parameter	Description
status	Transaction status. Takes the value PAYED
errorCode	Error Code
error	Remains unfilled
shopBillId	A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
billAmount	Amount of the payment
shopOrderNumber	Number of paid order (bill) in the Merchant's system. Maximum length is 128 symbols
cardMask	Payer’s Card mask
attribute1	Service field
attribute2	Service field
attribute3	Service field
attribute4	Service field
receiptLink	Link to get a receipt
lang	Payment system interface language. Possible values: uk – Ukrainian, en – English
description	Comment to the order / description of payment details. Maximum length is 250 symbols
token	Card token
commission	The value of the commission from payment
payeeName	Merchant name
billCurrency	Currency of the payment
IPSTokenValue	A unique Visa token
errorIPSCode	Error code if Visa token was not created
errorIPSMessage	Error message if Visa token was not created

Example of payment window displayed in a frame

Fig. 8 – Example of a payment window displayed in a frame on the merchant’s website

3.5. Signature

The rule to create a value for the signature field (example for PHP):

$login = 'WDISHOP';
$payeeId = '1185';
$shopOrderNumber = 'test';
$billAmount='1';
$key = 'BDFC166F8AE2F5323A557DB6CA16758D';
$dt = date("YmdHis");
$strToSignature = $payeeId.$dt.bin2hex($shopOrderNumber).$billAmount;
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));

echo $signature;

Parameter	Description	Required
login	Company login	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Merchant's system	No
billAmount	Amount of the payment	Yes
key	The key that is provided to each Partner individually when connecting to the Portmone.com system	Yes
dt	date	Yes

The set of fields to create a signature may vary for different methods. In case of differences from the example above, the set of fields involved in the signature generation will be given directly in the description of the method.

3.6. Exchange rate

Description: This method allows you to get information about the exchange rate

Request should be sent at:https://www.portmone.com.ua/r3/api/gateway

Request structure:

Please, refer to "3.6 Exchange rate" to study the request structure.

Parameters for generating JSON-structure of request:

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
date	date	Yes

Response structure:

Please, refer to "3.6 Exchange rate" to study the response structure.

Response parameters description:

Parameter	Description
key	Currency name
value	exchange rate

Important:

If the currency exchange rate is not set, an error is returned

"code": 500 "message": "Не знайдено курсу валют за вашими налаштуваннями. Зверніться до менеджера за уточненням деталей."

If the request is for an incorrect date, an error is returned

"code": 500 "message": "Не валідний параметр date. Формат для запиту: dd-mm-yyyy"

3.7 Installment Payments

Installment payments allow customers to pay for their orders gradually, in several parts, through Portmone partner banks.
This payment method is configured using the installmentPlan block. If the installmentPlan block is not provided, but the paymentTypes block contains the parameter installment=Y, all available installment options will be displayed on the payment page with default settings.

To specify the number of installment months for each bank, add the installmentPlan object to the request body (see sections 3.2. JSON Request and 12.5. Creating a Payment Link) in the following format:

"installmentPlan": {
    "privat24": {
        "parts": "3"
    },
    "oschad": {
        "parts": "5"
    },
    "monobank": {
        "parts": "8"
    },
    "pumb": {
        "parts": "03"
    }
}

Parameter	Description	Required
privat24	Installment payment from PrivatBank	No
oschad	Installment payment from Oschadbank	No
monobank	Installment payment from Monobank	No
pumb	Installment payment from PUMB	No
parts	Sets the maximum number of months for installments	No

Installment from Privat Bank

To display installments on the payment page, you need to pass the installment=Y parameter in the paymentTypes block and specify the order of method location in the priorityPaymentTypes block, for example: "installment":"3"

An example of a payment in installments page from PrivatBank

An example of payment in installments from PrivatBank

To connect this method, the merchant must have an account in Privat Bank, and the payer must have a card.

Installment from Monobank

To be able to transfer the payer's phone number, you need to transfer the parameter phoneNumber=635337143 in the format 635337143 in the payer block

An example of a payment in installments page from Monobank

An example of payment in installments from Monobank

Installment from Oschadbank

An example of payment in installments from Oschadbank An example of a payment in installments page from Oschadbank

Example of payment by installments from Oschadbank

Installment from PUMB

An example of payment in installments from PUMB An example of a payment in installments page from PUMB

Example of payment by installments from PUMB

4. Order payment using a payment Token

4.1. Token creation

Description:

This method allows you to get a value of the Token and the Client’s card mask. After performing this payment method, you will get the Token value and the mask of the Client’s Payment Card, which you can offer to the Client as a payment method on your resource. In the process of performing token creation operation, Portmone.com will perform authorization hold for 1 hryvnia on the Client's card, with the subsequent return of this amount to the Client's card.

Request should be sent at: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

The description field sent by this method is the key to further payments by Token. It must be the same for further transactions as was provided in the first transaction. If this parameter is changed in further payments by Token, Client will receive an error message.

Request structure:

Please, refer to "4.1 Token creation request" to study the request structure.

Parameters for generating JSON-structure of request:

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).

Parameter	Description	Required
createtokenonly	To create a Token, you must set the value to "Y" for this parameter	Yes

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page

Parameter	Description	Required
createtokenonly	To create a Token, you must set the value to "1" for this parameter	Yes

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details)	Required, identifies the Token in subsequent payments
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment (set the value to "1" (in UAH) to get the Token)	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
preauthFlag	Payment pre-authorization flag. Mandatory value to receive a Token – "N" (a regular payment without pre-authorization)	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1-4	Service fields. Filled at company’s discretion	No

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Required for payment by Token
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Leave empty
cardMask	Card mask	Leave empty
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	Mandatory value is "N"

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

Please, refer to "4.1 Token creation response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Payer’s Card mask
ATTRIBUTE1	Service field. Filled at company's discretion
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details. Maximum length is 250 symbols

4.2. Payment by Token

4.2.1. POST request

Description:

To make a payment via Token you should send a request using the POST method to the payment gateway page – https://www.portmone.com.ua/r3/token/secure/token.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.2.1 Payment by Token. POST request" to study the request structure.

Request parameters description:

Parameter	Description
payee_id	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store. Maximum length is 120 symbols
bill_amount	Amount of the order. Currency – hryvnia (UAH). The decimal separator is the dot symbol "."
description	Comment to the order / description of payment. Maximum length is 250 symbols
application_url	The URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after a successful card authorization. After successful payment of the order Portmone.com will send `shop_order_number` and the payment data to this address using the POST method
lang	Payment system interface language. Possible values: uk – Ukrainian, en – English
token	You must set the value of the token obtained in the previous step
attribute1-4	Service fields. Filled at company’s discretion
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")

Response structure:

Please, refer to "4.2.1 Payment by Token. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
BILL_AMOUNT	Transaction amount sent in request
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
RECEIPT_URL	Link to get a receipt
TOKEN	Token value for subsequent payments
CARD_PAYMENT_SYSTEM	The value of the payment system (VISA, MASTERCARD, PROSTIR)
CARD_LAST_DIGITS	Last 4 digits of Payment Card number
RESULT	The result of the operation (if successful = 0)

4.2.2. JSON request

Description:

To make a payment via Token you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.2.2 Payment by Token. JSON request" to study the request structure.

Parameters to generate the data:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details)	No
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company's discretion	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Visa Click to Pay	No
qr	Adds a tab to generate payment QR-code	No

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Yes
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Yes
cardMask	Card mask	Yes
otherPaymentMethods	Allows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable)	No

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

Please, refer to "4.2.2 Payment by Token. Example of successful response to the JSON request" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Payer’s Card mask
ATTRIBUTE1	Service field. Filled at company's discretion
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details. Maximum length is 250 symbols

4.3. Payment by Token without CVV2 (recurring payment)

Description:

To make a payment by Token without CVV2 you should send a request to the following URL: https://www.portmone.com.ua/r3/recurrent/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.3 Recurring payment request" to study the request structure.

Request parameters description:

Parameter	Description
login	The Online Store login to access account management
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
token	You must set the value of the token obtained in the previous step
description	Comment to the order / description of payment details. Maximum length is 250 symbols
billAmount	Amount of the payment. The decimal separator is the dot symbol "."
billCurrency	Currency of the payment. Default value: UAH
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)
id	ID of the request from the Online Store to the Portmone.com system

Response structure:

Please, refer to "4.3 Recurring payment request" to study the response structure

Response parameters description:

Parameter	Description
result	Order status attribute. Possible values: PAYED, CREATED, REJECTED.
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
description	Comment to the order / description of payment details. Maximum length is 250 symbols
id	ID of the request from the Online Store to the Portmone.com system

Important! If you receive an error on a token request, we recommend making the next request no earlier than 72 hours later.

4.4. Forming an order (payment message) in Viber Bot

Description:

A request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.

Availability and restrictions:

Operation is possible only for those users who are registered in Portmone Viber Bot.

JSON request structure:

{
  "method":"initViberPayment",
  "params":{
    "data":{
      "payeeId":"11344",
      "billAmount":"1",
      "shopOrderNumber":"shp_0001",
      "description":"test",
      "msisdnClient":"+380630000000",
      "paymentMessage":"test message",
      "attribute1":"",
      "attribute2":"",
      "attribute3":"",
      "attribute4":"",
      "attribute5":"",
      "preauthFlag":"N",
      "emailAddress":"[email protected]",
      "credentials":""
    }
  },
    "id":"1"
}

Request parameters description:

Parameter	Description
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
billAmount	Amount of the payment. The decimal separator is the dot symbol “.”
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
description	Comment to the order / description of payment details. Maximum length is 250 symbols
msisdnClient	Client's phone number
paymentMessage	Message for the client in Viber Bot. Maximum 250 symbols
attribute1, attribute2, attribute3, attribute4, attribute5	Attributes of the operation, optional
preauthFlag	Should be N
emailAddress	Client's Email
credentials	Required authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptions
id	ID of the request from the Online Store to the Portmone.com system

Response structure:

{
    "result": {
        "errorCode": "0",
        "error": "",
        "linkqr": "",
        "linkbot": ""
    },
    "id": "1"
}

Response parameters description:

Parameter	Description
errorCode	Error code
error	Error description is empty in case of a successful response. If the client was not found, the text "Client not found" will be returned
linkqr	Link to the QR code of the chat bot
linkbot	Link to the chat bot
id	ID of the request from the Online Store to the Portmone.com system

4.5. Getting IPS data by Portmone token

Description:

The request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.

Availability and restrictions:

Available after a card payment is made.

JSON request structure:

{
   "method":"getDataTokenIPS",
   "params":{
       "data":{
           "login":${MERCHANT_LOGIN},
           "password":${MERCHANT_PASSWORD},
           "tokenType":"PORTMONE",
           "tokenReference":${TOKEN_REFERENCE}
       }
   },
   "id":"1"
}

Request parameters description:

Parameter	Description
MERCHANT_LOGIN	Merchant's login in the Portmone system
MERCHANT_PASSWORD	Merchant's password in the Portmone system
TOKEN_REFERENCE	Card token, returned by the Portmone system

Response structure and example (Mastercard):

{
    "result": {
        "token_type": "M4M",
        "token_info": {
            "tokenUniqueReference": "DM4MMC0000****ed8d7249e",
            "panUniqueReference": "FM4MMC000012971373*****6a75a3cf",
            "productConfig": {
                "termsAndConditionsUrl": "",
                "issuerName": ",
                "cardBackgroundCombinedAssetId": "954e89****8655a",
                "iconAssetId": "7fcf53be****cf1fbfe",
                "foregroundColor": "ffffff",
                "issuerLogoAssetId": "cd90eb72****5cc1",
                "shortDescription": "",
                "customerServiceEmail": "",
                "customerServicePhoneNumber": "",
                "customerServiceUrl": "",
                "isCoBranded": "false",
                "brandLogoAssetId": "3789637f****c509"
            },
            "tokenInfo": {
                "tokenPanSuffix": "4444",
                "accountPanSuffix": "4444",
                "tokenExpiry": "0823",
                "accountPanExpiry": "",
                "productCategory": "DEBIT",
                "dsrpCapable": true,
                "tokenAssuranceLevel": ""
            }
        }
    },
    "id": "1"
}

Response key parameters description:

Parameter	Description
TOKEN_TYPE	Token type depending on the IPS
id	Unique response ID

Response structure and example (Visa):

{
 "result": {
   "token_type": "VTS",
   "token_info": {
     "vPanEnrollmentID": "724bfc****38701",
     "paymentInstrument": {
       "expirationDate": {
         "month": "11",
         "year": "2023"
       },
       "last4": "1111",
       "cvv2PrintedInd": "Y",
       "expDatePrintedInd": "Y",
       "enabledServices": {
         "merchantPresentedQR": "N"
       }
     },
     "cardMetaData": {
       "backgroundColor": "0xffff00",
       "foregroundColor": "0x000000",
       "labelColor": "0x000000",
       "contactWebsite": "https://www.aval.ua",
       "contactEmail": "[email protected]",
       "contactNumber": "+380444908888",
       "contactName": "Raiffeisen Bank Aval",
       "privacyPolicyURL": "https://www.aval.ua/storage/files/politika-konfidencijnosti-04042019_1554448866.pdf",
       "termsAndConditionsURL": "https://aval.ua/storage/files/wallet-pi.pdf",
       "shortDescription": "Visa Classic",
       "cardData": [
         {
           "guid": "8407fa4e5****d705f6cb07",
           "contentType": "cardSymbol",
           "content": [
             {
               "mimeType": "image/png",
               "width": "100",
               "height": "100"
             }
           ]
         },
         {
           "guid": "09e037d****c17995ddf6",
           "contentType": "digitalCardArt",
           "content": [
             {
               "mimeType": "image/png",
               "width": "1536",
               "height": "969"
             }
           ]
         }
       ],
       "issuerFlags": {
         "deviceBinding": false,
         "cardholderVerification": false,
         "trustedBeneficiaryEnrollment": false,
         "delegatedAuthenticationSupported": true
       }
     },
     "vProvisionedTokenID": "ebc77cd5****bcc8885e01",
     "tokenInfo": {
       "tokenRequestorID": "1111111111",
       "tokenStatus": "ACTIVE",
       "last4": "",
       "expirationDate": {
         "month": "",
         "year": ""
       }
     }
   }
 },
 "id": "1"
}

Response key parameters description:

Parameter	Description
TOKEN_TYPE	Token type depending on the IPS
id	Unique response ID
tokenInfo, cardMetaData, cardData	Card meta data

4.6. Getting an asset by the unique IPS ID

Description:

The request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.

Availability and restrictions:

Available after getting the IPS ID using getDataTokenIPS method according to p. 4.5. For getting an asset of each type it is necessary to make unique request containing the corresponding ID.

JSON request structure and example:

{
  "method":"getMetaDataTokenIPS",
  "params":{
    "data":{
      "login":${MERCHANT_LOGIN},
      "password":${MERCHANT_PASSWORD},
      "tokenType":${TOKEN_TYPE},
      "metaDataId":${ASSET_ID}
    }
  },
  "id":"1"
}

Request parameters description:

Parameter	Description
MERCHANT_LOGIN	Merchant’s login in the Portmone system
MERCHANT_PASSWORD	Merchant’s password in the Portmone system
TOKEN_TYPE	Token type received using getDataTokenIPS method according to p. 4.5
ASSET_ID:	Asset ID received using getDataTokenIPS method according to p. 4.5 (AssetId\guid)

Response structure and example:

{
 "result": {
   "mediaContents": [
     {
       "data": "",   //Base64 encoded content
       "width": 1536,
       "type": "image\/png",
       "height": 969
     }
   ]
 },
 "id": "1"
}

4.7. Payment by Token with 3D Secure without CVV2 (recurring payment)

Description:

To make a payment by Token without CVV2 you should send a request to the following URL: https://www.portmone.com.ua/r3/recurrent/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.7 Recurring payment request" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Value: paywith3ds	Yes
password	The Online Store password	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols	No
token	You must set the value of the token obtained in the previous step	Yes
description	Comment to the order / description of payment details. Maximum length is 250 symbols	Yes
billAmount	Amount of the payment. The decimal separator is the dot symbol "."	Yes
billCurrency	Currency of the payment. Default value: UAH	No
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment	No
attribute1	Service field. Filled at company's discretion	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No
id	ID of the request from the Online Store to the Portmone.com system	Yes

Response structure if 3D Secure check is required:

Please, refer to "4.7.1 response if 3D Secure check is required" to study the response structure

Response parameters description:

Parameter	Description
status	Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected.
shopbillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
description	Comment to the order / description of payment details. Maximum length is 250 symbols
pdfUrl	It remains empty
authCode	Bank authorization code (added if the order is paid)
isNeed3DS	3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required)
actionMPI	The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
id	ID of the request from the Online Store to the Portmone.com system

Response structure:

Please, refer to "4.7.2 Response to return after 3D Secure" to study the response structure.

Response parameters description:

Parameter	Description
shopbillId	Order ID in the Portmone.com system
status	Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected.
billAmount	Amount of the payment. The decimal separator is the dot symbol "."
billNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
payeeName
authCode	Bank authorization code (added if the order is paid)
commission	The value of the commission from payment
pdfUrl	It remains empty
payeeId	A unique identifier of the Online Store
payDate	Date of payment
description	Comment to the order / description of payment details. Maximum length is 250 symbols
cardMask	Card mask
errorMessage	Error message
errorCode	Error code

A successful response structure when no 3Ds need to be passed:

Please, refer to "4.7.3 successful response" to study the response structure.

Response parameters description:

Parameter	Description
status	Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected.
shopbillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
description	Comment to the order / description of payment details. Maximum length is 250 symbols
pdfUrl	Link to receipt
authCode	Bank authorization code (added if the order is paid)
isNeed3DS	3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required
actionMPI	The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
id	ID of the request from the Online Store to the Portmone.com system

Structure of a failed response:

Please, refer to "4.7.4 failed response" to study the response structure.

Response parameters description:

Parameter	Description
Code	Error code
Message	Error message
id	ID of the request from the Online Store to the Portmone.com system

4.8 Token payment with the appearance of the card without CVV2

Description:

To make Token payment with the appearance of the card without CVV2 a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.8 Payment by Token. JSON request" to study the request structure.

Parameters to generate the data:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
credentials	Required authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptions	Yes

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details)	No
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company's discretion	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
token	Payment by Token (if this option is enabled, other methods are not displayed)	Yes

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Yes
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Yes
cardMask	Card mask	Yes
otherPaymentMethods	Allows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable)	No

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No
showEmail	"Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y")	No

5. Money transfer from card to card

The Portmone.com payment system makes it possible to transfer money from card to card of any Ukrainian bank.

The transfer can be made:

Between Card Tokens without entering sender and recipient card numbers (sender Card Token and recipient Card Token are created one-time in advance).

Interaction scheme:

The sender (Client) performs one-off registration of his card in the Portmome.com system (performs a transaction for 1 UAH with the subsequent return of this amount to the Client's card within 30 minutes). The Online Store receives an identifier (Token) of this Card, which can be stored in its system (see section 5.1. "Card token receiving").
The recipient (Client or Merchant) performs one-off registration of his card in the Portmome.com system (performs a transaction for 1 UAH with the subsequent return of this amount to the Client's card within 30 minutes). The Online Store receives an identifier (Token) of this Card, which can be stored in its system (see section 5.1. "Card token receiving").
When the sender wants to transfer money to the recipient, the Online Store sends a request in JSON-format to the Portmone.com system with the following information: the sender's Card Token and the sender's Card mask, the recipient Card Token and the recipient Card mask, and the amount of payment (see section 5.2. "Creating a request to transfer funds between card tokens").

2. From the sender's Card Token to the recipient's Card number (see section 5.3 "Request to transfer funds from token to card").

3. From the sender's Card Token to the current account and from the current account to the recipient's Card Token (see section 5.4 "Transfer of funds from card to account and from account to card").

5.1. Card token receiving

Description:

To receive a Token (for any of the participants – both for the sender and for the recipient) you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.1 Token creation request" to study the request structure.

Parameters for generating JSON-structure of the request:

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).

Parameter	Description	Required
createtokenonly	To create a Token, set the value to "Y" for this parameter	Yes

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order / payment details)	No
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment (to receive the Token the value should be set to 1 UAH)	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute2-4	Service fields. Filled at company’s discretion	No

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Mandatory value is "N"
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	Mandatory value is "Y"
token	Token value	Leave empty
cardMask	Card mask	Leave empty
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	Mandatory value is "N"
sellerToken	Recipient’s Card Token	Leave empty

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	E-mail address of the payer	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

Please, refer to "5.1 Token creation response" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Card mask
ATTRIBUTE1	Service field. Filled at company's discretion
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details. Maximum length is 250 symbols

5.2. Creating a request to transfer funds between card tokens

Description:

To transfer funds from the sender’s card Token to the recipient’s card Token you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.2 Request to transfer funds between card tokens" to study the request structure.

Request parameters description:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Recipient’s Card mask	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Click to Pay	No

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Yes
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Sender’s card Token value	Yes
cardMask	Sender’s card mask	Yes
otherPaymentMethods	Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)	No
sellerToken	Recipient’s card Token	Yes

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

5.3. Request to transfer funds from token to card

Description:

The method allows you to transfer money from the sender's Card Token to the recipient's Card number.

To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

When calling the method, the Portmone.com payment page opens, where the Client enters the recipient’s Card number, CVV-code of the sender’s Card and Surname First name of the sender.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.3 Request to transfer funds from token to card" to study the request structure.

Request parameters description:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
checkParams	The value should be set to "Y" for this parameter	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Recipient’s card number	No
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).

Parameter	Description	Required
token	Transfer from Token to Card	Yes

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Yes
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Sender’s card Token value	Yes
cardMask	Sender’s card mask	Yes
otherPaymentMethods	Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)	Yes

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

Please, refer to "5.3 Transfer of funds from token to card. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Sender's card mask
ATTRIBUTE1	Service field.
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Recipient’s card mask

5.4. Transfer of funds from card to account and from account to card

The method allows you to perform money transfer between sender's and recipient's cards tokens in two steps (from the sender's card Token to the current account and from the current account to the recipient's card Token).

5.4.1. Transfer from the sender's card token to account

Description:

To transfer funds you should send request to the following URL: https://www.portmone.com.ua/gateway/.

When calling the method, the Portmone.com payment page opens, where the Client enters CVV-code of the sender’s Card and submit the form to confirm the transfer.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.4.1 Request to transfer funds from card token to account" to study the request structure.

Request parameters description:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
checkParams	The value should be set to "N" for this parameter	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
billCurrency	Currency of the payment. Default value: UAH	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute2	Service field. Filled at company's discretion	No
attribute3	Service field. Filled at company's discretion	No
attribute4	Service field. Filled at company's discretion	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).

Parameter	Description	Required
token	Transfer from Token to account	Yes

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account)	Yes
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Sender’s card Token value	Yes
cardMask	Sender’s card mask	Yes
otherPaymentMethods	Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)	Yes

payer – this block describes payer settings

Parameter	Description	Required
lang	Payment page interface language. Possible values: uk – Ukrainian, en – English	No
emailAddress	Email address of the payer	No
showEmail	"Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y")	No

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

Please, refer to "5.4.1 Transfer of funds from card token to account. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Sender’s card mask
ATTRIBUTE1	Service field.
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Comment to the order / description of payment details

5.4.2. Transfer from account to the recipient's card token

Description:

The Merchant initiates transfer of funds from the current account to the recipient's Card Token.

To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.4.2 Request to transfer funds from account to card token" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the procedure for transferring funds from the account to recipient's Card Token. Value: confirmp2p
login	The Online Store login
password	The Online Store password
shopBillId	Order number in the Portmone.com system (should be obtained from the response to the request described in section 5.4.1 "Transfer from the sender's card token to account")
token	Recipient's card Token, for which funds should be credited
id	ID of the request from the Online Store to the Portmone.com system

Response structure:

Please, refer to "5.4.2 Transfer of funds from account to card token. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
SHOPBILLID	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBER	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODE	Authorization code
BILL_AMOUNT	Transaction amount sent in request
TOKEN	Token value for subsequent payments
RESULT	The result of the operation (if successful = 0)
CARD_MASK	Sender’s card mask
ATTRIBUTE1	Service field.
ATTRIBUTE2	Service field. Filled at company's discretion
ATTRIBUTE3	Service field. Filled at company's discretion
ATTRIBUTE4	Service field. Filled at company's discretion
RECEIPT_URL	Link to get a receipt
LANG	Payment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTION	Recipient's card mask

6. Payments with pre-authorization

6.1. Pre-authorization of payment (funds blocking)

The Portmone.com payment system allows you to make payments with pre-authorization.
Pre-authorization is blocking of funds on the customer's Card without actual financial withdrawal of funds from the Client’s account. In order for funds to be withdrawn from the Card and transferred to the Merchant, the latter has to send a payment confirmation request for each pre-authorization (perform post-authorization procedure, see section 6.2 "Confirmation of payment made with pre-authorization"). Thus, payment for a product/service with pre-authorization consists of consecutive operations within a single order – Blocking funds on the Card, Obtaining the results of a transaction in the Portmone.com system, and the Post-authorization procedure.

** Important! **According the rules of International payment system such as Visa and MasterCard you block money only on a 7 days. After this period issue bank could unblock money and you will not have an opportunity to confirm

To preauthorize the payment Merchant should pass the preauth_flag=Y parameter in POST request (the preauthFlag = Y parameter for JSON request). For description of request format and parameters see section 3 "Order payment".

6.2. Confirmation of payment made with pre-authorization (post-authorization procedure)

6.2.1. POST request

Description:

To complete payments with pre-authorization (payments for which the preauth_flag = Y parameter was used), a post-authorization procedure should be performed.

URL for the request: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "6.2.1 Post-authorization procedure. POST request" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Value: preauth	Yes
login	The Online Store login	Yes
password	The Online Store password	Yes
action	The identifier of the action that must be performed for this order – confirmation of the funds blocking (possibly with the amount change). Value: set_paid	Yes
shop_bill_id	Number of the order in the Portmone.com system (should be obtained using the *result* method described in section 8.2 "Authorization results request")	No
postauth_amount	Amount of payment. Sent if `action = set_paid`. It cannot exceed the amount for which pre-authorization was carried out
encoding	Encoding	No
lang	Error messages language	No

Response structure:

Please, refer to "6.2.1 Response for post-authorization procedure (successful)" to study the response structure.

The <request> result section can be used for debugging – tags correspond to actually received request parameters. If there is no tag in <request>, it means that this parameter was not sent in the request.

If error occurs when calling a method (for example, incorrect login, etc.), the <order> section will consist of two tags only – <error_code> and <error_message> (see "6.2.1 Response for post-authorization procedure (failure)").

6.2.2. JSON request

Description:

To confirm the payment you should send the request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "6.2.2 Post-authorization procedure. JSON request" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Value: confirmPreauth	Yes
login	The Online Store login to access account management	Yes
password	The Online Store password	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	No
shopbillId	Order ID in the Portmone.com system. Optional parameter	No
postauthAmount	Amount of payment. It cannot exceed the amount for which pre-authorization was carried out	Yes
id	ID of the request from the Online Store to the Portmone.com system	Yes

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "6.2.2 Response format" to study the response structure.

Response parameters description:

Parameter	Description
shop_bill_id	Order ID in the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store. Maximum length is 120 symbols
description	Order description
bill_date	Bill date
pay_date	Payment date
pay_order_date	Bank memorial order date
bill_amount	Bill amount
auth_code	Bank authorization code
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
error_code	Error code
error_message	Error message

6.3. Cancellation of payment with pre-authorization

6.3.1. POST request

Description:

To cancel a payment with pre-authorization you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "6.3.1 Cancellation of payment with pre-authorization. POST request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the post-authorization procedure. Value: preauth
login	The Online Store login
password	The Online Store password
action	The identifier of the action that must be performed for this order – rejection of the funds blocking. Value: reject
shop_bill_id	Order number in the Portmone.com system (should be obtained using the *result* method described in section 8.2. "Authorization results request")
encoding	Encoding
lang	Error messages language

Response structure:

Please, refer to "6.3.1 Response for cancellation of payment with pre-authorization (POST request)" to study the response structure.

Response parameters description:

Parameter	Description
shop_bill_id	Order ID in the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store. Maximum length is 120 symbols
description	Order description
bill_date	Bill date
pay_date	Payment date
pay_order_date	Bank memorial order date
bill_amount	Bill amount
auth_code	Bank authorization code
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
error_code	Error code
error_message	Error message

6.3.2. JSON request

Description:

To cancel a payment you should send a request to the following address: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "6.3.2 Cancellation of payment with pre-authorization. JSON request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the cancellation of payment with pre-authorization procedure. Value: rejectPreauth
login	The Online Store login
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
shopbillId	Order ID in the Portmone.com system. Optional parameter
id	ID of the request from the Online Store to the Portmone.com system

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "6.3.2 Cancellation of payment with pre-authorization. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
shop_bill_id	Order ID in the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store. Maximum length is 120 symbols
description	Order description
bill_amount	Bill amount
status	Order status
bank_id	name of bank
terminal_id	terminal id in the bank
merchant_id	merchant id in the bank
rrn	identificator of transaction in banks system
auth_code	Bank authorization code
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
error_code	Error code
error_message	Error message

7. Splitting the payment

The Portmone.com system allows you to split a single payment made by card for multiple recipients (legal entities). First, the full amount is withdrawn from the Client's Card, then the transfer is made with separate transactions to each recipient's account which you've sent in the request. Splitting the payment is available for recipient companies registered in Portmone.com system.

Interaction scheme:

Each of the recipient companies registers in the Portmone.com system.
The Client makes an order on the Main Company's website.
The Main Company (the company that initiates the split) sends the split parameters in the attribute 5 field of the payment request:

• description of the order for each of the recipients (Desc);

• company's Id for each of the recipients (payeeID);

• amount, which needs to be enrolled to each recipient's account (amount).

The attribute5 field is filled in the next format:

Desc1:payeeID1;amount1;Desc2:payeeID2;amount2;...

The number of recipient companies for a single payment request with splitting is limited to the length of the line (up to 500 characters).

Portmone.com sends the Main Company an XML-message with the authorization result for the full amount of the order.

Request structure:

This request is similar to standard payment by card/payment by token requests, but should also contain additional data with information on how to split a payment in the attribute 5 field.

Please, refer to "7 Split payment request" to study the request example.

8. Getting authorization results

Online Stores can receive authorization results in several ways:

when Client returns to Merchant’s website after payment;
at Merchant’s Personal Area: https://www.portmone.com.ua/b2b_dash/;
by sending XML-request to the Portmone.com system;
by XML-message from the Portmone.com system to the Online Store with the result of authorization (XML-notification of payment);
by XML-message from the Portmone.com system to the Online Store about a payment order (XML-notification of transactions financial coverage);
by email messages.

8.1. Getting statements with authorization results in the Personal Area

Personal Area of the Portmone.com payment system is a specialized site with a set of pages and interactive forms, where the authorized user can receive necessary information and carry out other operations in the Portmone.com system.

For authorization in the Personal Area, go to https://www.portmone.com.ua/b2b_dash and enter your login and password in the window that appears. Credentials (login and password) to access your Personal Area can be obtained from Portmone.com by request (phone or email).

Information about operations can be obtained at the "Orders" page. The statement can be formed for any period of time, by filtering transactions by availability of a payment document, order number, operation result (all, successful, failure or returns) or authorization code.

An example of page with a statement in the Personal Area

8.2. Authorization results request

8.2.1. POST request

Description:

To receive payment status you should send a POST request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

The maximum request period should not exceed 31 days.

Request structure:

Please, refer to "8.2.1 POST authorization results request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the report generation procedure. Value: result
payee_id	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
login	The Online Store login to access account management
password	The Online Store password
shop_order_number	Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
status	Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected, - RETURN – returned. By default, orders with all types of statuses are selected.
start_date	Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_date	End date of the report in dd.mm.yyyy format. By default, it’s the current date

Response structure:

Please, refer to "8.2.1 POST authorization results response" to study the response structure.

Response parameters description:

Parameter	Description
shop_bill_id	Order ID in the Portmone.com system
shop_order_number	Number of paid order (bill) in the Online Store
description	Order description
bill_date	Bill date
pay_date	Payment date
pay_order_date	Payment order date
bill_amount	Bill amount
auth_code	Bank authorization code (added if the order is paid)
status	Order status
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
error_code	Error code
error_message	Error message

8.2.2. JSON request

Description:

To receive payment status or a list of transactions for a company you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "8.2.2 JSON authorization results request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the report generation procedure. Value: result
login	The Online Store login to access account management
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
shopbillId	Order ID in the Portmone.com system. Optional parameter
status	Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. By default, orders with all types of statuses are selected.
start_date	Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_date	End date of the report in dd.mm.yyyy format. By default, it’s the current date
id	Id of the request from the Online Store to the Portmone.com system

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "8.2.2 JSON authorization results response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
payeeId	A unique identifier of the Online Store
description	Order description
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
attribute5	shows payment splitting
distribution_payee_id	shows payment splitting
commission	The value of the refunded commission from payment
bank_id	name of bank
terminal_id	terminal id in the bank
merchant_id	merchant id in the bank
rrn	identificator of transaction in banks system
pay_date	Payment date
payee_export_date	Date of sending the payment amount / payment notification to the Partner
payee_export_flag	With successful payment takes the value Y
chargeback	Whether the chargeback was claimed for transaction or not
payee_name	Name of the merchant
payee_commission	Commissar from the merchant
pay_order_date	Bank memorial order date
pay_order_number	Account number
pay_order_amount	Bill amount
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code (added if the order is paid)
cardMask	Payer’s Card mask
cardBankName	Name of the issuing bank
token	Token value for subsequent payments
payeeExportResult	Description of the error
gateType	Payment method identifier
cardTypeName	The name of IPS

8.2.2.1. Request for authorization results when using installment payments from Monobank in JSON format

Description:

To receive payment status or a list of transactions for a company you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

To be able to make a request, it is necessary to send a corresponding letter from the registered e-mail address to the managers of Portmone.com for cooperation with online stores at the address [email protected]

Request structure:

Please, refer to "8.2.2.1 JSON authorization results request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the report generation procedure. Value: result
login	The Online Store login to access account management
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
shopbillId	Order ID in the Portmone.com system. Optional parameter
status	Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. By default, orders with all types of statuses are selected.
start_date	Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_date	End date of the report in dd.mm.yyyy format. By default, it’s the current date
id	Id of the request from the Online Store to the Portmone.com system

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "8.2.2.1 JSON authorization results response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
description	Order description
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
commission	The value of the refunded commission from payment
bank_id	name of bank
terminal_id	terminal id in the bank
merchant_id	merchant id in the bank
rrn	identificator of transaction in banks system
pay_date	Payment date
payee_export_date	Date of sending the payment amount / payment notification to the Partner
pay_order_date	Bank memorial order date
chargeback	Whether the chargeback was claimed for transaction or not
payee_commission	Commissar from the merchant
payee_name	Name of the merchant
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code (added if the order is paid)
cardMask	Payer’s Card mask
token	Token value for subsequent payments
gateType	Payment method identifier

8.2.2.2. Example of a successful response for "Nova Poshta" delivery in JSON format

Description of response parameters (key parameters):

Parameter	Description
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
description	Order description
shopBillId	Order ID in the Portmone.com system
delivery_id	Internal delivery number
pib	Recipient's full name
phone_number	Recipient's phone number
delivery_type	Delivery type: `WarehouseWarehouse` - branch or parcel locker, `WarehouseDoors` - courier
warehouse_description	Branch name
warehouse_short_address	Short branch address
city_name	City/Town name
street_name	Street name
creation_date	Delivery creation date
delivery_company	Delivery service

Example of response for delivery to a Branch (key parameters)

[
    {
        "payee_id": "123000",
        "description": "Viddilennya",
        ...
        "shopBillId": "2026463560",
        ...
        "delivery": {
            "delivery_id": "81",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseWarehouse",
            "warehouse_description": "Відділення №49 (до 30 кг): вул. Йорданська, 1, озеро\"Вербне\"(Оболонь)",
            "warehouse_short_address": "Київ, Йорданська, 1",
            "city_name": "м. Київ, Київська обл.",
            "street_name": null,
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

Example of response for delivery to a Parcel Locker (key parameters)

[
    {
        "payee_id": "123000",
        "description": "Poshtomat",
        ...
        "shopBillId": "2026463560",
        ...
        "delivery": {
            "delivery_id": "82",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseWarehouse",
            "warehouse_description": "Поштомат \"Нова Пошта\" №1526: вул. Йорданська, 9, під'їзд №1 (ТІЛЬКИ ДЛЯ МЕШКАНЦІВ)",
            "warehouse_short_address": "Київ, Йорданська, 9, під'їзд №1 (ТІЛЬКИ ДЛЯ МЕШКАНЦІВ)",
            "city_name": "м. Київ, Київська обл.",
            "street_name": null,
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

Example of response for delivery by Courier (key parameters)

[
    {
        "payee_id": "123000",
        "description": "Kurier",
        "status": "PAYED",
        ...
        "shopBillId": "2026477024",
        ...
        "delivery": {
            "delivery_id": "83",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseDoors",
            "warehouse_description": null,
            "warehouse_short_address": null,
            "city_name": "м. Київ, Київська обл.",
            "street_name": "просп. Оболонський",
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

8.3. Notification of the Online Store server about the authorization result

Notification for successful payment – BILLS message

Description:

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

Please, refer to "8.3 Notification for successful payment – BILLS message" to study the message structure.

Message BILLS – 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`. It is equal to the `SHOPBILLID` parameter (see section 3 "Order payment").
BILL_NUMBER	CHAR(120)	Bill number. It is equal to the `shop_order_number` parameter (if sent; see section 3 "Order payment").
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)	Commissar from the merchant
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 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
DISTRIBUTION_ID	NUMBER	ID payment distribution
NAME	CHAR	Recipient company name for payment distribution
CODE	CHAR	Recipient company code for payment distribution
EDRPOU	CHAR	EDRPOU code of the recipient company for payment distribution
IBAN	CHAR	Recipient company bank account
AMOUNT	NUMBER	Distribution amount
DESCRIPTION	CHAR	Distribution description

Examples:

See "8.3 BILLS message example".

Notification about bank payment – PAY_ORDERS message

Description:

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

Please, refer to "8.3 Notification about bank payment – PAY_ORDERS message" to study the message structure.

Message PAY_ORDERS – 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`. It is equal to the `SHOPBILLID` parameter (see section 3 "Order payment")
BILL_NUMBER	CHAR(120)	Bill number. It is equal to the `shop_order_number` parameter (if sent; see section 3 "Order payment").
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 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

Examples:

See "8.3 PAY_ORDERS message example".

Confirmation of payment information receipt – RESULT message

Description:

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

Message structure:

Please, refer to "8.3 Confirmation of payment information receipt – RESULT message" to study the message structure.

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

Examples:

See "8.3 RESULT message example".

8.4. Receiving statements with authorization results by e-mail

Statements are sent to the stores immediately after the successful authorization of the card. There are two options for sending statements:

Sending two e-mail messages to Partner’s e-mail address — one with a statement in text format and another one with a statement in the form of an XML-message (see "8.4 Example of statement with authorization results in XML format");
Sending the statement to Partner's e-mail in text format only.

Example of statement in text form:

В системі Portmone.com оплачено замовлення / Order payed in Portmone.com system: Номер замовлення / Order number: 305966 Дата замовлення / Order date: 18.03.2010 Коментар / Comment: 50908: покриття по платіжним карткам (payment cards coverage) Сума / Amount: 108.98 Валюта / Currency: UAH Код авторизації / Authorization code: 87446Z Тип авторизації/ Authorization type: 3DSECURE

Message is sent in Ukrainian. Fields names were translated into English for information only.

8.5. Notification in JSON format

Notification for successful payment in JSON format

Description:

This notification is sent by Portmone.com to the company in case of successful transaction. The company shall provide URL-address to which the Portmone.com system will send messages in JSON format.

Message structure:

Please, refer to "8.5 Notification for successful payment in JSON format" to study the message structure.

Parameters description:

Parameter	Description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order / description of payment details
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
status	Order status. Possible values: PAYED, PREAUTH, REJECTED, CREATED. In case of successful operation, takes the value PAYED or PREAUTH
token	Token value for subsequent payments
authCode	Bank authorization code
receiptUrl	An empty value
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
errorCode	Error code
error	Error description
notificationType	Notification status
cardType	Card type
bank_name	Name of the acquiring bank
terminal_id	Acquire terminal number
merchant_id	Terminal name
rrn	Transaction identifierї (RRN)

Confirmation of receipt of payment notification in JSON format

Description:

This message is sent by the company to the Portmone.com system in response to the notification for successful payment in JSON format.

Message structure:

Please, refer to "8.5 Confirmation of receipt of payment notification in JSON format" to study the message structure.

Parameters description:

Parameter	Description
errorCode	Error code
reason	Error description. Set it "OK" if error not occurred
responseId	Randomly generated value. Maximum length is 31 character

8.6. Sending a message about payment order (text notification by email about the financial coverage of transactions)

The next day after the bank has transferred the financial coverage to the store's current account, the Portmone.com system sends an e-mail to the store with a text file containing a list of orders covered by this payment order.

The letter contains the following information (message is sent in Ukrainian; fields names were translated into English for information only):

Агент/Agent: ТОВ "ПОРТМОНЕ" Довіритель/Client ТОВ Квіточка Реєстр отриманих оплат "Райффайзен банк Аваль" МФО 300335 розрахунковий рахунок 29249215 (Registry of payments accepted by "Raiffeisen Bank Aval" MFO 300335 current account 29249215) No п/д 6559503 дата 17.07.2010 (Payment order No 6559503 date 17.07.2010) +---------------------------------------------------------------------------+ |Дата оплати/ |Номер замовлення/ |Код авт./ |Сум. плат./| |Payment date |Order number |Auth. code| Amount| +---------------------------------------------------------------------------+ |14.07.2014 00:08 | 141192| 171363| 191.00| |14.07.2014 02:10 | 141205| 29797B| 104.00| |14.07.2014 10:49 | 141225| 432054| 104.00| |14.07.2014 12:40 | 141249| 37614B| 89.00| |14.07.2014 14:47 | 141275| 34502Z| 158.00| |14.07.2014 14:54 | 141281| 083689| 220.00| |14.07.2014 18:52 | 141339| 841013| 290.50| |14.07.2014 19:26 | 141348| 587414| 91.00| |14.07.2014 19:35 | 141353| 389922| 141.50| |14.07.2014 19:56 | 141361| 638960| 74.00| |14.07.2014 22:08 | 141405| 61791B| 249.00| |14.07.2014 22:47 | 141418| 013761| 131.00| +---------------------------------------------------------------------------+ Всього оплат на суму/Total payments amount 1843.00 грн. Комісія/Commission 36.86 грн. Всього за день/Day total 1843.00 грн. Комісія/Commission 36.86 грн. Перераховується одержувачу/Transferred to recipient 1806.14 грн.

8.7. Getting a link to the receipt

Description:

Using this method, you can obtain the following receipts:

a receipt for a successful payment;
a refund receipt (if a refund was processed).

To get a link to the receipt you should send a JSON request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "8.7 Request for getting a link to the receipt" to study the request structure.

Request parameters description:

Parameter	Description
login	The Online Store login to access account management
password	The Online Store password
shopOrderNumber	Number of an order (bill) in the Online Store system
id	ID of the request from the Online Store to the Portmone.com system

Response structure:

Please, refer to "8.7 Example of successful response" to study the response structure.

Response parameters description:

Parameter	Description
linkPdf	receipt for successful payment
linksPdfReturn	refund receipt (if a refund was processed)
id	constant

9. Refund

9.1.1 Return POST request

Description:

URL for the request: https://www.portmone.com.ua/gateway/.

Request format: HTTPS POST

Availability and restrictions:

Due to individual refund and cancellation policies of acquiring banks, it is recommended to initiate full or partial refunds no earlier than 24 hours after the original payment.

For additional information, please contact: [email protected]

Request structure:

Please, refer to "9.1 POST refund request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the return procedure. Value: return
login	The Online Store login
password	The Online Store password
shop_bill_id	Order number in the Portmone.com system (should be obtained using the result method described in section 8.2 "Authorization results request")
return_amount	Refund amount. Partial and full refund is possible
attribute1	Additional optional parameter
attribute5	It is used when splitting the payment
encoding	Encoding
lang	Error message language

Response structure:

Please, refer to "9.1 POST refund response (successful) " to study the response structure.

If error occurs when calling a method (for example, incorrect login, etc.), the <order> section will consist of two tags only – <error_code> and <error_message> (see "9.1 POST refund response (failure)").

9.1.2. Return JSON request

Description:

To return funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

Due to individual refund and cancellation policies of acquiring banks, it is recommended to initiate full or partial refunds no earlier than 24 hours after the original payment.

For additional information, please contact: [email protected]

Request structure:

Please, refer to "9.1.2 JSON refund request" to study the request structure.

Request parameters description:

Parameter	Description
login	The Online Store login to access account management
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
shopbillId	Order ID in the Portmone.com system. Optional parameter
returnAmount	Refund amount. Partial and full refund is possible
attribute5	It is used when splitting the payment
message	Comment to the refund

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "9.1.2 Response format" to study the response structure.

Response parameters description:

Parameter	Description
description	Order description
status	Order status
bank_id	code the bank
terminal_id	terminal id in the bank
merchant_id	merchant id in the bank
rrn	identificator of transaction in banks system
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
attribute5	It is used when splitting the payment
commission	The value of the refunded commission from payment
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Online Store. Maximum length is 120 symbols
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code
cardMask	Card mask
token	Token value
gateType	Payment method identifier

9.2. Cancellation of payment JSON request

Description:

To return funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

The request can be used on the condition that it takes place on the day of payment.

Request structure:

Please, refer to "9.2 JSON refund request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the report generation procedure. Value: reject
login	The Online Store login to access account management
password	The Online Store password
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopbillId	Order ID in the Portmone.com system. Optional parameter
returnAmount	Refund amount
attribute5	It is used when splitting the payment
message	Comment to the refund

Important! The search can be performed on parameter shopOrderNumber or shopbillId. If both parameters are passed, the search will be performed on shopbillId parameter. If none of the parameters has been passed, an error will occur.

Response structure:

Please, refer to "9.2 Response format" to study the response structure.

Response parameters description:

Parameter	Description
description	Order description
status	Order status
bank_id	code the bank
terminal_id	terminal id in the bank
merchant_id	merchant id in the bank
rrn	identificator of transaction in banks system
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
commission	The value of the refunded commission from payment
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Online Store. Maximum length is 120 symbols
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code
cardMask	Card mask
token	Token value
gateType	Payment method identifier

11. Using Gateway for mobile application

You can use custom-URL mechanisms to integrate the Potrmone.com payment gateway into mobile applications (for example, iOS or Android). They allow you to call the payment gateway page with the necessary parameters from the application and to get control back to the application after the payment.

An example of how it can be done for iOS applications:

Call the URL for payment using the GET method (! not the POST method) with transferring of all parameters specified in our Online Store connection documentation.

For success_url and failure_url parameters it is necessary to specify URLs, which contain the custom url type registered in iOS-application of Online Store, instead of https protocol.

For example, if the following url type: “customurl” is registered in the iOS-application, then success_url and failure_url parameters will look as following:

success_url = “customurl://success” failure_url = “customurl://failure”

URL for calling the Portmone.com service will be as follows:

https://www.portmone.com.ua/gateway/?payee_id=1185&bill_amount=123.56 &shop_order_number=shopordernumber1&description=My%20test &success_url=customurl://success&failure_url=customurl://failure

where:

payee_id = 1185 – Online Store ID

bill_amount = 123.56 – Amount to pay by the order

shop_order_number = shopordernumber – Order number

description = “My test” – Notes to the order

As a result of this call, a browser with a standard order payment page will be opened, where the card details should be entered. Based on payment results, either success_url or failure_url from the Online Store primary request parameters will be called, and the transition to the Online Store's iOS-application will be executed accordingly.

This is how the page optimized for mobile screens looks like:

Appearance of the payment page on the smartphone screen

12. Invoicing customers

The Portmone.com payment gateway allows to send invoices (orders) for payment by e-mail or SMS.

12.1. Sending invoice by e-mail

To send an invoice by e-mail you should call the form with the following parameters:

Parameter	Description	Required
login	The Online Store login to access account management	Yes
password	The Online Store password	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	No
namePayer	Name of the Client	No
comment	Payment comment	No
amount	Amount of the payment	Yes
emailRecipient	E-mail address of the Client	Yes
lang	E-mail language	No
cc_email	E-mail address to which a copy of the invoice will be sent	No
preauth_flag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
bill_currency	Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT	No
exp_date	Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

Examples:

See "12.1 Form to send invoices by e-mail".

12.2. Sending invoice via SMS

To send an invoice via SMS you should call the form with the following parameters:

Parameter	Description	Required
login	The Online Store login to access account management	Yes
password	The Online Store password	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	No
namePayer	Name of the Client	No
comment	Payment comment	No
amount	Amount of the payment	Yes
phoneRecipient	Number of the Client’s mobile phone	Yes
lang	SMS language	No
preauth_flag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
bill_currency	Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT)	No
expDate	Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

Examples:

See "12.2 Form to send invoices via SMS".

Upon receiving this invoice, the Client will be notified as follows:

Message example

When clicking on a hypertext payment link, the Client will open a payment page with the following content:

Appearance of the payment page on the smartphone screen

12.3. Mass invoicing by e-mail or SMS

Description:

For mass invoicing by e-mail or SMS you should send a request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.

Availability and restrictions:

The data block must contain at least 5 required parameters, filled in a strict order (see the table with the description of the request parameters). There are 4 additional parameters which are filled in if necessary.

Maximum 100 invoices can be set up at a time.

Request structure:

Please, refer to "12.3 Mass invoicing request" to study the request structure.

Request parameters description:

Sequence in the data block	Parameter	Description	Required
1	Name of a recipient	Name of the Client that will be displayed in the received invoice	Yes
2	Recipient’s e-mail or mobile phone	Client’s e-mail address or mobile phone number. Mobile number should be in the "+380ХХХХХХХХХ" format	Yes
3	Order number	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	Yes
4	Payment details	Comment to the order / description of payment details	Yes
5	Amount	Amount of the payment	Yes
6	Currency	Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT	No
7	Pre-authorization	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization. "N" is default value)	No
8	Invoice language	The language of the e-mail or SMS. Possible values: uk – Ukrainian, en – English. If the parameter is not sent, the invoice is issued in Ukrainian	No
9	Invoice validity time	Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	No

Response structure:

Please, refer to "12.3 Mass invoicing response (successful)" to study the response structure.

12.4. Getting a payment link

Description:

To get a payment link you should send a request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "12.4 Request for getting a payment link" to study the request structure.

Request parameters description:

Parameter	Description	Required
login	The Online Store login to access account management	Yes
password	The Online Store password	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
amount	Amount of the payment	Yes
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	No
emailRecipient	E-mail address of the Client	No
comment	Payment comment	No
preauth_flag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
bill_currency	Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT	No
expDate	Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	No
attribute1	Service field. Filled at company’s discretion	No
attribute2	Service field. Filled at company’s discretion	No
attribute3	Service field. Filled at company’s discretion	No
attribute4	Service field. Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

goods – Block Containing an Array of Fiscalization Data

Parameter	Description	Required
internalCode	Seller's code	Yes
manufacturerCode	Manufacturer's code	No
govClassificationCode	UKTZED code	Yes
name	Product/service name	Yes
name_en	Product/service name in English	No
description	Product/service description	No
description_en	Product/service description in English	No
price	Price (per unit)	Yes
quantity	Quantity	Yes
uomCode	Unit of measure (optional, default is unit)	No
amount	Amount	Yes
serviceFlag	Service indicator (N - product)	No
taxRateCodes	Numeric tax rate code (pre-programmed in the tax agent's dashboard). For multiple taxes, separate by commas	Yes
descriptionUrl	Product description URL	No
imageUrl	Product image URL	No

Response structure:

Please, refer to "12.4 Getting a payment link response (successful) " to study the response structure.

12.5. Creating a payment link

Description:

This method allows you to create a payment link and get it to the merchant's server. Suitable for use on Instagram, Facebook.

To create a payment link you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "12.5 Request for creating a payment link" to study the request structure.

Request parameters description:

payee – this block is required for partner identification

Parameter	Description	Required
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
login	Company’s login. Used to verify a signature (required if the `signature` parameter is sent)	No
dt	Request creation time. Used to verify a signature (required if the `signature` parameter is sent)	No
signature	Signature of the request	No
shopSiteId	Digital identifier of a sales channel	No

order – this block contains the order data

Parameter	Description	Required
description	Payment description (comment to the order/ payment details)	No
shopOrderNumber	Number of a paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
successUrl	The URL of the Online Store to which the client will be redirected after a successful payment. Maximum number of characters 250	No
failureUrl	The URL of the Online Store to which the client will be redirected in case of payment rejection. Maximum number of characters 250	No
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization)	No
billCurrency	Currency of the payment. Default value: UAH	No
expTime	Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid	No
encoding	Encoding (encodes the request text from the set encoding to UTF-8)	No
attribute1	Service field. Filled at company’s discretion	No
attribute2	Service field. Filled at company’s discretion	No
attribute3	Service field. Filled at company’s discretion	No
attribute4	Service field. Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section 7 "Splitting the payment")	No

paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".

Parameter	Description	Required
card	Payment by Card	No
portmone	Payment via Portmone.com wallet	No
token	Payment by Token (if this option is enabled, other methods are not displayed)	No
clicktopay	Payment using Visa Click to Pay	No
privat	Payment via LiqPay, with choosing a card from the Privat24 Internet Banking Pay attention! Pre-authorization functionality does not work when paying via Privat24	No
gpay	Payment via Google Pay, with choosing a card from previously stored in the Google Pay account	No
createtokenonly	Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card")	No
applepay	Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account	No
link	Payment by the BankPay method (using the payer's Bank). The method works if the following parameters are passed: expTime та "showEmail": "Y"	No

installmentPlan – installment payment parameters (see section 3.7 “Installment Payments”).
autopayment – this block allows you to set up automatic payments.

To get started with automatic payments, you need to get credentials in your Personal Area.

Important! When changing the password, the Partner must generate new credentials.

After setting up:

A subscription to automatic payments from a Client’s Card will be created. The Portmone.com system controls and processes payments. The Client can disable the service by contacting the Portmone.com customer support or an employee of the Online Store (you can delete the client's subscription in the Personal Area).
All subsequent payments will be made on the same description as the first payment.
The order number for automatic payments will be formed as follows:

Order number at first payment_RECURENT_Date of automatic payment

Parameter	Description	Required
show	Displaying the details of the autopayment subscription to the client on the payment page. Possible values: Y – the client can go to a separate page and see the subscription details; N – the client is unable to view subscription details (only the "Make this payment regular" checkbox is displayed) (see fig. 1)	No
edit	Editing automatic payment settings by client. Possible values: Y – all settings can be edited on the subscription details page, the client can save settings (see fig. 2); N – the automatic payment settings provided by the Online Store are displayed and cannot be edited	No
settings	A block of parameters for setting up automatic payments	No
credentials	Authorization parameters	Yes
changeCheckboxState	value Y	Yes
defaultCheckboxState	value: Y – the checkbox "Make payment regular" is autofilled,N – the client independently fills in the "Make regular payment" checkbox	No

The settings block structure:

Parameter	Description	Required
period	Frequency of automatic payments. Takes the following values: 1 – monthly, 2 – quarterly, 3 – semiannually, 4 – annually	Yes
payDate	Day of the month for automatic payment. Can takes value from 1 to 28	No
startDate	Automatic payments start date. Should be sent in the following format: DD.MM.YYYY. If not specified, yesterday's date is automatically set	No
endDate	Automatic payments end date. Should be sent in the following format: DD.MM.YYYY. If not specified, the `startDate` + 3 years is automatically set (or the current payment date is set, if `startDate` is not specified)	No
amount	Amount of the payment. The decimal separator is the dot symbol (".")	Yes

An example of payment page without displaying the details of the autopayment subscription

Fig. 1 – an example of payment page without displaying the details of the autopayment subscription

An example of displaying editable automatic payment parameters

Fig. 2 – an example of displaying editable automatic payment parameters

priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.

Important! In paymentTypes the payment method must have the "Y" value, in the priorityPaymentTypes it must have a numeric value other than 0 ("0" disables the display on the payment page).

token – settings to work with a Token (see section 4 "Order payment using a payment Token")

Parameter	Description	Required
tokenFlag	Enables payment by Token ("N" – do not enable, "Y" – take data processing into account)	Required for payment by Token
returnToken	"Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page	No
token	Token value	Required for payment by Token
cardMask	Card mask	Required for payment by Token
otherPaymentMethods	Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)	No

shipping – this block contains shipping information

Nova Poshta Delivery

This functionality allows you to enable Nova Poshta delivery.

Parameter	Description	Required
state	Y - enables delivery, N - disables delivery	Yes
source	The name of the delivery service. Accepts the value `novaposhta`	Yes

Example of an array in the request:

"shipping": {
        "collect": {
            "state": "Y",
            "source": "novaposhta"
        }

To pre-fill the fields on the checkout page, you need to pass the Customer’s data in the block payer

"payer": {
        "lang": "uk",
        "emailAddress": "[email protected]",
        "showEmail": "Y",
        "phoneNumber": "660000000",
        "fullName": "Прізвище Ім'я"
    }

Parameter	Description	Required
lang	Language of the payment page interface. Possible values: uk – Ukrainian, en – English	No
emailAddress	The payer’s email address (used to send a receipt for a successful payment; not returned in the response)	Yes
showEmail	Accepts the value "Y"	Yes
phoneNumber	Customer’s phone number. Must be passed in the format `660000000`	Yes
fullName	Customer’s last name and first name	Yes

Three delivery types are available:

To a branch
To a parcel locker
By courier

style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
goods – Block Containing an Array of Fiscalization Data

Parameter	Description	Required
internalCode	Seller's code	Yes
manufacturerCode	Manufacturer's code	No
govClassificationCode	UKTZED code	Yes
name	Product/service name	Yes
name_en	Product/service name in English	No
description	Product/service description	No
description_en	Product/service description in English	No
price	Price (per unit)	Yes
quantity	Quantity	Yes
uomCode	Unit of measure (optional, default is unit)	No
amount	Amount	Yes
serviceFlag	Service indicator (N - product)	No
taxRateCodes	Numeric tax rate code (pre-programmed in the tax agent's dashboard). For multiple taxes, separate by commas	Yes
descriptionUrl	Product description URL	No
imageUrl	Product image URL	No

Show an example of the JSON structure for the goods block

{
  "goods": [
    {
      "internalCode": "123456",
      "manufacturerCode": "123456",
      "govClassificationCode": "123456",
      "name": "",
      "name_en": "",
      "description": "",
      "description_en": "",
      "price": "100",
      "quantity": "2",
      "uomCode": "",
      "amount": "200",
      "serviceFlag": "N",
      "taxRateCodes": "1",
      "descriptionUrl": "",
      "imageUrl": ""
    }
  ]
}

Response structure:

Please, refer to "12.5 Creating a payment link response (successful) " to study the response structure.

12.6. Сlose Invoice

Description:

The method allows you to close the Invoice account in CREATED and REJECTED status.

To create a payment link you should send a request to the following URL: https://www.portmone.com.ua/gateway/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "12.6 Request to close the invoice" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Value: `closeInvoice`	Yes
login	Company’s login.	Yes
password	Company’s password	Yes
payeeId	A unique identifier of the Company. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols	Yes

Response structure:

Please, refer to "12.6 to close the invoice response (successful) " to study the response structure.

Response parameters description:

Parameter	Description
description	Order description
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
commission	The value of the refunded commission from payment
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code (added if the order is paid)
cardMask	Payer’s Card mask
token	Token value for subsequent payments
gateType	Payment method identifier

13. Transfer of funds from account to card (token)

Description: Allows you to transfer funds from an account to a Card or a Card Token. Merchant needs to sign an agreement with Bank.

** Important! ** When using this service, merchants become tax agents and are obliged to pay taxes (Income tax, SSC, Military tax). Exceptions are companies that have a license to carry out a special type of activity such as: MFIs (microcredit organizations), insurance companies .

13.1 Transfer of funds from account to card

Description:

To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/r3/pm/.

Availability and restrictions:

The method works in synchronous mode only (mode = 1101).

Request structure:

Please, refer to "13.1 Request to transfer funds from account to card" to study the request structure.

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "a2c_1" value	Yes
description	recipient's card number	Yes
attribute1	Service field (for additional order information). Set empty value	No
attribute2	Service field (for additional order information). The information about tax for transfer on a card	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No
billAmount	Amount of the payment	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
cvvVerifyFlag	The default is "Y", set "N" for payments without CVV2	No
token	Set empty value	No
billCurrency	Currency of the payment. Default value: UAH	No
shopSiteId	Digital identifier of a sales channel	No
cardData	Encrypted value of payment card data (card number, expiration month, expiration year, CVV2)	No
dt	Request creation time. Used to verify the signature. Should be sent in the following format:yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1101" for synchronous mode	Yes

In case of tax payment in attribute2 it is necessary to transfer the following parameters: "attribute2": "" client_id \ ": " Ivanov Ivan \ ", " taxes \ ": {"income\ ": 20, " social ": 10,"military": 5},"identification": {"general": {"tax_id":"1234567890 "}} ",

Description of query parameters: | Option | Description | Required | | -------- | -------- |: ----------: | | client_id | Recipient's name | Yes | | Income | The amount of income tax in coins| Yes | | Social | The amount of SSC in coins | Yes | | military | The amount of military tax in coins | Yes | | tax_id | TIN of the recipient of funds | Yes |

** Important! ** In case of cashback (bonuses) it is not necessary to transfer the social parameter.

Response structure:

Please, refer to "13.1 Transfer funds from account to card. Response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
status	Order status. Possible values: REJECTED, PAYED
errorCode	Error code
error	Error description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
billAmount	Transaction amount sent in request
billNumber	Number of paid order (bill) in the Partner’s system
attribute1	Service field (for additional order information). Set empty value
attribute2	Service field (for additional order information). The information about tax for transfer on a card
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
authCode	Bank authorization code (added if the order is paid)
payeeExportFlag	Transaction status in the acquiring bank (Y – successful, E – error, N or empty value – not sent)
receiptLink	Link to get a receipt
billCurrency	Currency of the payment
transactionId	Transaction ID in the acquirer system

Important! If the response contains status = PAYED, but payeeExportFlag has a value other than Y, it is necessary to request the transaction status from the Portmone.com system (see section 8.2 "JSON request"). If the response contains status = PAYED and payee_export_flag = Y, the transaction is successful.

14. Fiscalization

Опис:

Дозволяє здіснювати реєстрації розрахункових операцій та передачу інформації про фінансові транзакції до державних податкових органів.

Terms and Definitions

Term	Definition
Fiscalization	The process of registering sales transactions and transmitting financial transaction information to government tax authorities.
Tax Rate	The tax rate applied to the sale of goods or services, determined by governmental authorities and may vary depending on the type of product or service, the region in which the transaction takes place, and other factors.
Shift	The data transmission period to the tax authorities, starting from the first payment fiscalization after the last Z-report and ending with the next Z-report formation.
Fiscal Receipt	A document generated as a result of a registered sales transaction. It contains information about the financial transaction between the payer and the merchant, including the date and time of the transaction, the product or service name, quantity, price, total payment amount, and tax details.
УКТзЕД Code	A coding system used for classifying goods in international trade, regulated by the State Customs Service of Ukraine and listed in the "Classifier of Goods of Foreign Economic Activity".

14.1 Retrieving PRRO Tax Rates

Description: This method allows retrieving PRRO tax rates for further use in fiscalization.

Request URL: https://www.portmone.com.ua/r3/api/gateway

Request Structure

JSON Request Structure Parameters:

Parameter	Description	Required
login	Internet store login for account management access	Yes
password	Internet store password	Yes
id	Constant	Yes

Request Example:

{
  "method": "getListTaxes",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451"
    }
  },
  "id": "1"
}

Response Structure

Response Parameter Descriptions:

Parameter	Description
uuid	Unique identifier in UUID format
code	Numeric tax rate code
label	Tax rate name
symbol	Tax rate alphabetic code
rate	Tax rate in percentage
extra_rate	Additional rate in percentage
included	Tax type, included/added (true/false). When using an included tax, the tax amount is part of the product’s total amount. An added tax means the product amount excludes tax, and the tax is calculated separately.
created_at	Tax rate creation timestamp in ISO 8601 format as YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
updated_at	Last modification timestamp in ISO 8601 format as YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
no_vat	Tax indicator, tax excluded/included (true/false)
advanced_code	Internal information field (not used)
decimal_rate	Decimal tax rate
decimal_extra_rate	Decimal additional rate
id	Constant

Response Example:

{
  "result": [
    {
      "uuid": "16edb3d1-8669-4006-b16d-c483a92c33eb",
      "code": "1",
      "label": "Без ПДВ",
      "symbol": "Є",
      "rate": "0",
      "extra_rate": null,
      "included": "true",
      "created_at": "18-JUL-24 05.57.37.637059000 PM +03:00",
      "updated_at": null,
      "no_vat": "true",
      "advanced_code": null,
      "decimal_rate": "0",
      "decimal_extra_rate": null
    }
  ],
  "id": "1"
}

14.2 Manual Payment Fiscalization / Refund Fiscalization

Description: This method allows for manual payment fiscalization or refund fiscalization.

Request URL: https://www.portmone.com.ua/r3/api/gateway

Request Structure

JSON Request Structure Parameters:

Parameter	Description	Required
login	Internet store login for account management access	Yes
password	Internet store password	Yes
shopBillId	Transaction identifier in Portmone payment system	Yes
payeeId	Internet store identifier, assigned individually to each partner upon connection	Yes
sendFiscalReceipt	Fiscal receipt dispatch parameter. Can take values: - Y - dispatch, - N - do not dispatch	Yes
id	Constant	Yes

Request Example:

{
  "method": "createFiscalReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopBillId": "1776344335",
      "payeeId": "1185",
      "sendFiscalReceipt": "Y"
    }
  },
  "id": "1"
}

Response Structure

Response Parameter Descriptions:

Parameter	Description
shopBillId	Transaction identifier (payment document) in the Portmone.com online payment system in Ukraine
fiscalized	Fiscalization status. Possible values: : - Y - fiscalized, - N – not fiscalized
fiscalCode	Fiscal receipt number
billAmount	Transaction amount
fiscalUrl	URL link to the fiscal receipt image
id	Constant

Response Example:

{
  "result": {
    "shopBillId": "1776341932",
    "fiscalized": "Y",
    "fiscalCode": "TEST-QlJczi",
    "billAmount": "3.2",
    "fiscalUrl": "https://check.checkbox.ua/TEST-QlJczi"
  },
  "id": "1"
}

14.3 Sending Fiscal Receipt to User Email

Description: This method allows sending a fiscal receipt by specifying the user's email parameter.

Request URL: https://www.portmone.com.ua/r3/api/gateway

Request Structure

JSON Request Structure Parameters:

Parameter	Description	Required
login	Internet store login for account management access	Yes
password	Internet store password	Yes
shopBillId	Transaction identifier in Portmone payment system	Yes
payeeId	Internet store identifier	Yes
emails	Payer's email address	Yes
id	Constant	Yes

Request Example:

{
  "method": "sendFiscalReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopBillId": "1775990208",
      "emails": "[email protected]"
    }
  },
  "id": "1"
}

Response Structure

Response Parameter Descriptions:

Parameter	Description
status	Dispatch status. Possible values: SUCCESS - dispatched, FAILURE - not dispatched
id	Constant

Response Example:

{
  "result": {
    "status": "sucess"
  },
  "id": "1"
}

14.4 Querying Fiscalization Status

Description: This method allows querying the status of a payment's fiscalization. Request URL: https://www.portmone.com.ua/gateway/

Request Structure

JSON Request Structure Parameters:

Parameter	Description	Required
login	Internet store login for account management access	Yes
password	Internet store password	Yes
shopBillId	Transaction identifier in Portmone payment system	Yes

Request Example:

{
  "method": "getFiscalStatus",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopBillId": "1776341308"
    }
  }
}

Response Structure

Response Parameter Descriptions

Parameter	Description
shopBillId	Transaction identifier (payment document) in the Portmone.com online payment system in Ukraine
billAmount	Transaction amount
fiscalized	Fiscalization status. Possible values: : - Y - fiscalized, - N – not fiscalized
receiptNumber	Fiscal receipt number
fiscalUrl	URL link to the fiscal receipt image

Response Example:

{
  "shopBillId": "1776341308",
  "billAnount": "3.2",
  "fiscalized": "Y",
  "receiptNumber": "TEST-NOupeS",
  "fiscalUrl": "https://check.checkbox.ua/TEST-NOupeS"
}

Examples

To Section 3 "Order payment"

3.1 POST order payment request

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="payee_id" value="1185" />
  <input type="hidden" name="shop_order_number" value="76575j65465464161hhhh" />
  <input type="hidden" name="bill_amount" value="1" />
  <input type="hidden" name="description" value="Order description" />
  <input
    type="hidden"
    name="success_url"
    value="http://example.com/success.html"
  />
  <input
    type="hidden"
    name="failure_url"
    value="http://example.com/failure.html"
  />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="encoding" value="UTF-8" />
  <input type="hidden" name="exp_time" value="400" />
  <input type="hidden" name="signature" value="9579C33D36C5BC98627BAA1E38C3DDFC039F682B03785BC3F6D728FED45A5CB9" />  
  <input type="hidden" name="dt" value="20220512022427"/>
</form>

3.1 POST order payment response (successful)

SHOPBILLID: 420651576 SHOPORDERNUMBER: 123456789qwe APPROVALCODE: TESTPM
BILL_AMOUNT: 1 TOKEN: RESULT: 0 CARD_MASK: 444433******1111 ATTRIBUTE1: null
ATTRIBUTE2: null ATTRIBUTE3: null ATTRIBUTE4: null RECEIPT_URL:
https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/
353472d8de85c380d94e49e592050631486e357ebdcedf374ccd07c89682f31d181076bbd1f2d920b4d00b3e
11983dfb8777ccee0a19a9a00cd7cb5c1262c83c LANG: en DESCRIPTION: 999999 IPSTOKEN:
null ERRORIPSCODE: null ERRORIPSMESSAGE: null

3.2 JSON order payment request

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Pay through Portmone.com" style="width: 350px;" class="button_green" />
</form>

where $data – json structure, as follows:

{
  "paymentTypes": {
    "card": "Y",
    "portmone": "Y",
    "token": "N",
    "clicktopay": "Y",
    "createtokenonly": "N"
  },
  "autopayment": {
    "show": "Y",
    "edit": "N",
    "defaultCheckboxState": "N",
    "changeCheckboxState": "Y",
    "settings": {
      "period": "1",
      "payDate": "27",
      "startDate": "",
      "endDate": "01.01.2021",
      "amount": "1.22"
    },
    "credentials": "393433af5c5c46bb776878f8208fae4ad91f4ca450a28e4b558386e4c30325e3f5673522b2929adfe39655d5a530fc193094cb089a9bac58137c4533edcfa08a4c299d27a8fc060b2d671d1b63a32e66f8fc1db433185d0788fe145b93faaa75e60713d99673e4bd"
  },
  "priorityPaymentTypes": {
    "card": "1",
    "portmone": "2",
    "qr": "0",
    "token": "0",
    "clicktopay": "4",
    "createtokenonly": "5"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "shopSiteId": ""
  },
  "order": {
    "description": "test",
    "shopOrderNumber": "123456",
    "billAmount": "2500",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "attribute5": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "EUR",
    "expTime": "1000",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "N",
    "token": "18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C611A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77",
    "cardMask": "516874******5179",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]",
    "showEmail": "N"
  },
  "shipping": {
    "services": {
      "ukrposhta": {
        "deliveryTypes": ["W2D", "W2W"],
        "senderClientId": "91cfddfe-5c94-44d0-9410-c78e2a877512",
        "senderAddressId": "2651676",
        "senderPostCode": "08040",
        "type": "STANDARD",
        "parcelWeight": "600",
        "parcelLength": "50",
        "parcelWidth": "50",
        "parcelHeight": "50",
        "parcelDeclaredPrice": "25",
        "parcelDescription": "",
        "fragile": "",
        "checkOnDelivery": "",
        "bees": "",
        "payer": "client",
        "sms": "Y",
        "withDeliveryNotification": ""
      }
    },
    "enable": "Y",
    "required": "N"
  },
  "style": {
    "type": "light",
    "logo": "",
    "backgroundColorHeader": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": "",
    "borderColorList": "",
    "logoWidth": "",
    "logoHeight": "",
    "bcMain": ""
  }
}

3.2 JSON order payment response (successful)

'SHOPBILLID'          => '411587640',
'SHOPORDERNUMBER'     => 'SHP-000000002792',
'APPROVALCODE'        => '366999',
'BILL_AMOUNT'         => '1',
'TOKEN'               => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE016
44F39F009A3EDDEF992C6A5E22ACD01AE91D1CB491B645B530EDCE8C289778611A37D0D045D650DE3495E84',
'RESULT'              => '0',
'CARD_MASK'           => '516874******5179',
'ATTRIBUTE1'          => '49026347',
'ATTRIBUTE2'          => '2',
'ATTRIBUTE3'          => '3',
'ATTRIBUTE4'          => '4',
'RECEIPT_URL'         => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc
92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'                => 'uk',
'DESCRIPTION'         => 'test',
'IPSTOKEN'            => 'null',
'ERRORIPSCODE'        => 'null',
'ERRORIPSMESSAGE'     => 'null'

3.4.1 Example of the data object for popup mode

var data = {
  paymentTypes: {
    card: "Y",
    gpay: "Y",
    applepay: "Y",
  },
  priorityPaymentTypes: {
    card: "1",
    gpay: "2",
    applepay: "3",
  },
  payee: {
    payeeId: "1185",
    signature:
      "7DE75312FCBFCB7A3BA0248C4ED6E1255780CE38248C4E462E170295CE382DC1",
    login: "shop",
    dt: "20250919174335",
    shopSiteId: "",
  },
  payer: {
    lang: "uk",
    emailAddress: "",
  },
  order: {
    billAmount: "4269",
    shopOrderNumber: "2833398",
    attribute1: "19.09.2025",
    attribute2: "Test Payment Test",
  },
  goods: [
    {
      internalCode: "customer",
      name: "Personal discount 10%",
      price: -1.0,
      quantity: 1,
      amount: -1.0,
      taxRateCodes: 1,
      govClassificationCode: "",
    },
    {
      internalCode: "001017",
      name: "Marvis Toothbrush Black Medium",
      price: 10,
      quantity: 1,
      amount: 10,
      taxRateCodes: 1,
      govClassificationCode: "3306200000",
    },
  ],
  style: {
    type: "light",
    backgroundColorButtons: "#2F2F82",
    colorTextAndIcons: "#2F2F82",
    bcMain: "#ffffff",
  },
};

3.4.2 Example of the data object for iframe mode

var data = {
  paymentTypes: { card: "Y", gpay: "Y" },
  priorityPaymentTypes: { card: "1", gpay: "2" },
  payee: {
    payeeId: "1185",
  },
  payer: {
    lang: "uk",
  },
  goods: [
    {
      internalCode: "ЦБ208406",
      manufacturerCode: "92949",
      govClassificationCode: "8708803598",
      name: "Front right suspension arm Logan II",
      name_en: "something Logan II",
      description: "Gray, iron",
      description_en: "Gray, iron",
      price: "1.6",
      quantity: "2",
      uomCode: "",
      amount: "3.2",
      serviceFlag: "N",
      taxRateCodes: "A",
      descriptionUrl: "",
      imageUrl: "",
    },
  ],
  order: { billAmount: "3.2" },
  closeModal: "N",
  frameHolderId: "paymentFrame1",
};

3.6. Exchange rate

Request

{
    "method":"getRateCurrencies",
    "params":{
        "data":{
        "payeeId":"72276", - payeeId мерчанта в системі Портмоне
        "date":"21-11-2022" - дата, за яку треба отримати курс
        }
    },
    "id":"1"
}

Response

{
  "result": {
    "currencies": [
      {
        "key": "AUD",
        "value": "24.5503"
      },
      {
        "key": "EUR",
        "value": "37.8906"
      },
      {
        "key": "GBP",
        "value": "43.5239"
      },
      {
        "key": "KZT",
        "value": "0.079196"
      },
      {
        "key": "PLN",
        "value": "8.0569"
      },
      {
        "key": "USD",
        "value": "36.5686"
      }
    ],
    "notice": "Portmone не здійснює купівлі, продажу, обміну, конвертації та визначення курсу безготівкової іноземної валюти. Розрахунок вартості товарів та послуг на поточну дату здійснюється на підставі даних, отриманих з сервісу розрахунку курсу валют, обраного Отримувачем. Portmone не несе відповідальності за працездатність цього сервісу"
  },
  "id": "1"
}

To Section 4 "Order payment using a payment Token"

4.1 Token creation request

{
  "paymentTypes": {
    "createtokenonly": "Y"
  },
  "priorityPaymentTypes": {
    "createtokenonly": "1"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "shopSiteId": ""
  },
  "order": {
    "description": "testPayment",
    "shopOrderNumber": "SHP-000000002792",
    "billAmount": "1",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "N",
    "token": "",
    "cardMask": "",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]"
  },
  "style": {
    "type": "",
    "logo": "",
    "backgroundColorHeader": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": "",
    "borderColorList": ""
  }
}

Place the JSON structure in the "bodyRequest" field, and add the "typeRequest" parameter with the value "json".

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="JSON STRUCTURE" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" />
</form>

4.1 Token creation response (successful)

'SHOPBILLID'          => '411587640',
'SHOPORDERNUMBER'     => 'SHP-000000002792',
'APPROVALCODE'        => '366999',
'BILL_AMOUNT'         => '1',
'TOKEN'               => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644
F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT'              => '0',
'CARD_MASK'           => '516874******5179',
'ATTRIBUTE1'          => '49026347',
'ATTRIBUTE2'          => '2',
'ATTRIBUTE3'          => '3',
'ATTRIBUTE4'          => '4',
'RECEIPT_URL'         => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc9
2084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'                => 'uk',
'DESCRIPTION'         => 'test'

4.2.1 Payment by Token. POST request

<form method="POST" action="https://www.portmone.com.ua/r3/token/secure/token/">
  <input type="text" value="1185" name="payee_id" />
  <input type="text" value="test_123" name="description" />
  <input type="text" value="1" name="bill_amount" />
  <input type="text" value="test_1" name="shop_order_number" />
  <input
    type="text"
    value="https://www.portmone.com.ua/r3/ecommerce/test/"
    name="application_url"
  />
  <input type="text" value="en" name="lang" />
  <input
    type="text"
    value="183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510
A1EF2E1965DFEF0F1E5421D0CE264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491
E66"
    name="token"
  />
  <input type="text" value="" name="attribute1" />
  <input type="text" value="" name="attribute2" />
  <input type="text" value="" name="attribute3" />
  <input type="text" value="" name="attribute4" />
</form>

4.2.1 Payment by Token. Response (successful)

BILL_AMOUNT=45& SHOPORDERNUMBER=test_2& APPROVALCODE=TESTPM&
RECEIPT_URL=https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts
%2Fshop-bill-id%2F35348409d793c705eb6250a1576451abad87d010699109d1a6578e81a4f9b40e70d67
085deb9e94e54a62093a09ff92062953366caa6e80f64025449318491ec&
TOKEN=183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510A1EF2E1965DFEF0F1E5421D0C
E264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491E66&
CARD_PAYMENT_SYSTEM=VISA& CARD_LAST_DIGITS=1111& RESULT=0

4.2.2 Payment by Token. JSON request

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
  }} class="button_green" />
</form>

where $data – json structure, as follows:

{
        "paymentTypes":
        {
          "card":"N",
          "portmone":"N",
          "token":"N",
          "clicktopay":"N"
        },
        "priorityPaymentTypes":
        {
          "card":"4",
          "portmone":"1"
          "token":"8",
          "clicktopay":"4",
        },
        "payee":
        {
          "payeeId":"1185",
          "login":"",
          "dt":"",
          "signature":"",
          "shopSiteId":""
        },
        "order":
        {
          "description":"191237564",
          "shopOrderNumber":"SHP-00000111",
          "billAmount":"1",
          "attribute1":"1",
          "attribute2":"2",
          "attribute3":"3",
          "attribute4":"4",
          "successUrl":"",
          "failureUrl":"",
          "preauthFlag":"N",
          "billCurrency":"UAH",
          "encoding":""
        },
        "token":
        {
          "tokenFlag":"Y",
          "returnToken":"Y",
          "token":"1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84",
          "cardMask":"516874******5179",
          "otherPaymentMethods":"N"
        },
        "payer":
        {
          "lang":"uk",
          "emailAddress":""
        },
        "style":
        {
          "type":"brand",
          "logo":",
          "logoWidth":"171px",
          "logoHeight":"41px"*,
          "backgroundColorHeader":"#009DE0",
          "backgroundColorButtons":"#009DE0",
          "colorTextAndIcons":"#1e282c",
          "borderColorList":"#1e282c"
        }
}

4.2.2 Payment by Token. Example of successful response to the JSON request

'module'          => 'ecommerce',
'controller'      => 'test',
'action'          => 'success',
'SHOPBILLID'      => '421606955',
'SHOPORDERNUMBER' => 'SHP-00000000279210',
'APPROVALCODE'    => '416477',
'BILL_AMOUNT'     => '1',
'TOKEN'           => '18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C6
11A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77',
'RESULT'          => '0',
'CARD_MASK'       => '516874******5179',
'ATTRIBUTE1'      => '1',
'ATTRIBUTE2'      => '2',
'ATTRIBUTE3'      => '3',
'ATTRIBUTE4'      => '4',
'RECEIPT_URL'     => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/35343ea3aabe8b49a35f95b78dba465ec24d36e9794f27ce97d9b1d9080b930ed
e870ed357a32212de9b5dda00c158a37ce9877be5c7a279cf2ed2114849c779',
'LANG'            => 'uk',
'DESCRIPTION'     => '191237564'

4.3 Recurring payment request

Request example:

$jsoncontent = '{
  "method": "pay",
  "params": {
    "login": "SHP_**",
    "password": "******",
    "payeeId": "1185",
    "shopOrderNumber": "123456",
    "token": "1834373930303635***FCC",
    "description": "Опис замовлення",
    "billAmount": "1.24",
    "billCurrency": "EUR",
    "preauthFlag": "Y"
  },
  "id": "1"
}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_URL, "https://www.portmone.com.ua/r3/recurrent/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsoncontent);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$result = curl_exec($ch);
$curl_info = curl_getinfo($ch);
print_r($result);
curl_close($ch);

Response example for successful payment:

{
  "result": {
    "result": "PAYED",
    "shopOrderNumber": "P1728563684",
    "description": "",
    "receipt": "",
    "shopBillId": "1728563684"
  },
  "id": "1"
}

4.7 Recurring payment request

Request example:

{
    "method": "paywith3ds",
    "params": {
        "data": {
            "login": "SHP_333",
            "password": "22222222",
            "payeeId": "30481",
            "shopOrderNumber": "test_0000001",
            "token": "203131393132332393039128CFE98552764426D1D5A285E4CF64130AB19CDB6336481E5878DA66F03BD7C807ABAE08464CFA7EFC6F56106E480F002669E7CDC901554499787573FFC6AC57",
            "description": "test",
            "billAmount": "1",
            "preauthFlag": "N",
            "billCurrency": "UAH",
            "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form/"
            "attribute1": "",
            "attribute2": "",
            "attribute3": "",
            "attribute4": ""
        }
    },
    "id": "1"
    }

4.7.1 An example of response if 3D Secure check is required:

Response example:

{
  "result": {
    "shopBillId": "1191240800",
    "status": "CREATED",
    "shopOrderNumber": "test_0000001",
    "description": "test",
    "pdfUrl": "",
    "authCode": "",
    "isNeed3DS": "Y",
    "actionMPI": "https://portmone2.com/r3/tothreeds?data=2053A3B7BCF9347FF04F6B4D3E338F96FDC604F3F3C522D47EB43A50FAB904AC90AFCA2A5BB0E04171426F56D81DBFE7042E2A24FF3FC24A8F38A9B76116DF17319FE4FE028FD17660B322AE733D5A7"
  },
  "id": "1"
}

4.7.2 Response to return after 3D Secure

Response example:

shopBillId: 1191240666
status: PAYED
billAmount: 1
billNumber: test_0000001
payeeName: 333
authCode: 453750
commission: 0
pdfUrl: ""
payeeId: 30481
payDate: 15.06.2022 03:32:27
description: test
cardMask: 454788******1119
errorMessage:
errorCode: 0

4.7.3 An example of successful response (No 3D Secure verification is required)

Response example:

{
  "result": {
    "shopBillId": "1213000727",
    "status": "PAYED",
    "shopOrderNumber": "test_0000001",
    "description": "test_001",
    "pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35375cadedf354dd63444c7a0dba795fb044b138f323b42c51309f05929d20198733ce5ca     85866a0512487643306b1b3143e0c07f93961e8c69fb06e5275d2e6426fea",
    "authCode": "158709",
    "isNeed3DS": "N",
    "actionMPI": ""
  },
  "id": "1"
}

4.7.4 Unsuccessful response

Response example:

{
  "error": {
    "code": 10,
    "message": "Операція відхилена. Повторна транзакція",
    "data": {}
  },
  "id": "1"
}

4.8 Token payment with the appearance of the card without CVV2

Request example:

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
  }} class="button_green" />
</form>

where $data – json structure, as follows:

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "11344",
    "credentials": "3932b2bb0fb55509027abd365e0deab4e2ab149f419fa167a2441a3d289da1f48a2f16092c2300fa76d415a6e76fb8283e6c0e77305ce4622e10e5383f1030ceed470e9239ce4fc7ccccc442ea739123cb721f78a6dd0703beecfa0085e0eebfad6c36791268"
  },
  "order": {
    "description": "test",
    "shopOrderNumber": "",
    "billAmount": "1",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "N",
    "token": "20313234333633313538391280E7B5BCFFAE793EA6226F02E9D1263AD5652E804EACC8A4F3C4852CFB2FB6BA6C7053E034427E3FEFFA985ACC331C6DA961D384C5E4914505DABDFF01840",
    "cardMask": "414949******2244",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]",
    "showEmail": "N"
  }
}

To Section 5 "Money transfer from card to card"

5.1 Token creation request

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<? = $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
  }} class="button_green" />
</form>

where $data – json structure, as follows:

{
  "paymentTypes":
  {
    "card":"N",
    "portmone":"N",
    "token":"N",
    "clicktopay":"N"
  },
  "priorityPaymentTypes":
  {
    "card":"0",
    "portmone":"0"
    "token":"0",
    "clicktopay":"0"
  },
  "payee":
  {
    "payeeId":"1185",
    "login":"",
    "dt":"",
    "signature":"",
    "shopSiteId":""
  },
  "order":
  {
    "description":"тест",
    "shopOrderNumber":"111145",
    "billAmount":"1",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "successUrl":"",
    "failureUrl":"",
    "preauthFlag":"N",
    "billCurrency":"UAH",
    "encoding":""
  },
  "token":
  {
    "tokenFlag":"N",
    "returnToken":"Y",
    "token":"",
    "cardMask":"",
    "otherPaymentMethods":"N",
    "sellerToken":""
  },
  "payer":
  {
    "lang":"uk"
  },
  style":
  {
    "type":"portmone",
    "logo":"",
    "backgroundColorHeader":"",
    "backgroundColorButtons":"",
    "colorTextAndIcons":"",
    "borderColorList":""
  }
}

5.1 Token creation response

'SHOPBILLID'      => '411587640',
'SHOPORDERNUMBER' => 'SHP-000000002792',
'APPROVALCODE'    => '366999',
'BILL_AMOUNT'     => '1',
'TOKEN'           => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F3
9F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT'          => '0',
'CARD_MASK'       => '516874******5179',
'ATTRIBUTE1'      => '49026347',
'ATTRIBUTE2'      => '2',
'ATTRIBUTE3'      => '3',
'ATTRIBUTE4'      => '4',
'RECEIPT_URL'     => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e67
6f58cc92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'            => 'uk',
'DESCRIPTION'     => '516874******5179'

5.2 Request to transfer funds between card tokens

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<? = $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
  }} class="button_green" />
</form>

where $data – json structure, as follows:

{
  "paymentTypes":
  {
    "card":"Y",
    "portmone":"Y",
    "token":"Y",
    "clicktopay":"Y"
  },
  "priorityPaymentTypes":
  {
    "card":"1",
    "portmone":"2"
    "token":"2",
    "clicktopay":"0"
  },
  "payee":
  {
    "payeeId":"1185",
    "login":"",
    "dt":"",
    "signature":"",
    "shopSiteId":""
  },
  "order":
  {
    "description":"444433******1111",
    "shopOrderNumber":"SHP-0101000110002792",
    "billAmount":"1",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "successUrl":"",
    "failureUrl":"",
    "preauthFlag":"N",
    "billCurrency":"UAH",
    "encoding":""
  },
  "token":
  {
    "tokenFlag":"Y",
    "returnToken":"N",
    "token":"183434303730373432331283F04364806355F5E7479D903A9518BC9DC4A23336E07B696BE09B713D6ADD71603966FCF9A4E40C88265E1180017127653EB541CF76176EF5FECC6B269B949DE",
    "cardMask":"111122******4444",
    "otherPaymentMethods":"N",
    "sellerToken":"18343430373037373330128746FED8954F0E0A83315F409D8BE23767C0573C9AFE796C2B403031F8B7379307B201DB7D3E7B5F32B2E33A8B7FC284999D47396CB8D1AE485D89A6452CC8B1D"
  },
  "payer":
  {
    "lang":"uk",
    "emailAddress":[email protected]
  },
  "style":
  {
    "type":"portmone",
    "logo":"https://i1.rozetka.ua/logos/0/99.png",
    "backgroundColorHeader":"#fff",
    "backgroundColorButtons":"#4bbe3f",
    "colorTextAndIcons":"#4bbe3f",
    "borderColorList":"#3e77aa"
  }
}

5.3 Request to transfer funds from token to card

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "1185",
    "checkParams": "Y"
  },
  "order": {
    "description": "4444333322221111",
    "shopOrderNumber": "65",
    "billAmount": "1",
    "successUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/success",
    "failureUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/error",
    "encoding": "UTF-8",
    "attribute2": "",
    "attribute3": "",
    "attribute4": ""
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "Y",
    "token": "18343836373232313531096EE3BB03559659C0F64E6BB61C642902AE0570EA189661F2CF59102681BC3D741E03540B292BB9A4D3B04D91496F0C8D9",
    "cardMask": "410232******5594",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  },
  "style": {
    "type": "",
    "bcMain": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": ""
  }
}

5.3 Transfer of funds from token to card. Response (successful)

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN:
183438363734343037351287D5A3C90A1880888F785B34726EA1A106E6F40C2C0C30930F904FE3AE66B
C5173AB6386E12C118F91F41A500F7756A1A39D0CA3DB0F0BA38138556083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037e
f335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594

5.4.1 Request to transfer funds from card token to account

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "18930",
    "checkParams": "N"
  },
  "order": {
    "shopOrderNumber": "ttgyy1701090211",
    "billAmount": "1.23",
    "successUrl": "https://portmone2.com/r3/ecommerce/test/",
    "failureUrl": "",
    "preauthFlag": "N",
    "encoding": "UTF-8",
    "attribute2": "xtra"
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "N",
    "token": "1834383438393836********DECB2DD7679AE245BD8E4B69C95C67401CA89",
    "cardMask": "516874******5179",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  },
  "style": {
    "type": "light",
    "bcMain": "#fff",
    "backgroundColorButtons": "#0f51a6",
    "colorTextAndIcons": "#0f51a6"
  }
}

5.4.1 Transfer of funds from card token to account. Response (successful)

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52
c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6 LANG: uk
DESCRIPTION: null

5.4.2 Request to transfer funds from account to card token

{
  "method": "confirmp2p",
  "params": {
    "authData": {
      "login": "SHP_333333",
      "password": "333333"
    },
    "data": {
      "shopBillId": "484991476",
      "token": "1834383438393838391286A60BED7182634F41FC3DFC64D1713959E1B0DA3C05C7F18B6F474535FC554F02B78AD6C1F051616907E2F5D6E624B6746A163FFC64EF050B4907201AFA3D1CD"
    }
  },
  "id": "1"
}

5.4.2 Transfer of funds from account to card token. Response (successful)

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594

To Section 6 "Payments with pre-authorization"

6.2.1 Post-authorization procedure. POST request

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="preauth" />
  <input type="hidden" name="action" value="set_paid" />
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="shop_bill_id" value="87834981" />
  <input type="hidden" name="postauth_amount" value="99.00" />
  <input type="hidden" name="encoding" value="utf-8" />
  <input type="hidden" name="lang" value="uk" />
</form>

6.2.1 Response for post-authorization procedure (successful)

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <method>preauth</method>
        <action>set_paid</action>
        <login>shp_login</login>
        <password>******</password>
        <shop_bill_id>87834981</shop_bill_id>
        <postauth_amount>99.00</postauth_amount>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>87834981</shop_bill_id>
        <shop_order_number><![CDATA[1234]]></shop_order_number>
        <description><![CDATA[Payment of order №1234]]></description>
        <bill_date>15.11.2013</bill_date>
        <pay_date>15.11.2013 22:21:51</pay_date>
        <bill_amount>99.00</bill_amount>
        <auth_code>123456</auth_code>
        <status>PAYED</status>
        <error_code>0</error_code>
        <error_message><![CDATA[]]></error_message>
    </order>
</portmoneresult>

6.2.1 Response for post-authorization procedure (failure)

<order>
    <error_code>5</error_code>
    <error_message><![CDATA[Bill payment confirmation error
    [SHOP_BILL_ID = 87834981]ORA-20001:Determining payment terminal details error.
    [pay_terminal_id=]]]></error_message>
</order>

6.2.2 Post-authorization procedure. JSON request

{
  "method": "confirmPreauth",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopOrderNumber": "test_1SAB1",
      "shopbillId": 395584061,
      "postauthAmount": "1"
    }
  },
  "id": "1"
}

6.2.2 Response format

{
  "shop_bill_id": "395584061",
  "shop_order_number": "test_1SAB1",
  "description": "Description замовлення",
  "bill_date": "31.07.2018",
  "pay_date": "31.07.2018 15:30:30",
  "pay_order_date": null,
  "bill_amount": "1",
  "auth_code": "882311",
  "status": "PAYED",
  "attribute1": null,
  "attribute2": null,
  "error_code": "0",
  "error_message": ""
}

6.3.1 Cancellation of payment with pre-authorization. POST request

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="preauth" />
  <input type="hidden" name="action" value="reject" />
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="shop_bill_id" value="87834981" />
  <input type="hidden" name="encoding" value="utf-8" />
  <input type="hidden" name="lang" value="uk" />
</form>

6.3.1 Response for cancellation of payment with pre-authorization (POST request)

<?xml version="1.0" encoding="utf-8"?>
<portmoneresult lang="uk">
    <request>
        <method>preauth</method>
        <action>reject</action>
        <login>SHP_FLOWERSQUICKER</login>
        <password>********</password>
        <shop_bill_id>421592544</shop_bill_id>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>421592544</shop_bill_id>
        <shop_order_number>test_1nvnvnvbnvb15</shop_order_number>
        <description><![CDATA[Order description]]></description>
        <bill_date>17.10.2018</bill_date>
        <pay_date>17.10.2018</pay_date>
        <pay_order_date></pay_order_date>
        <bill_amount>1</bill_amount>
        <auth_code>523067</auth_code>
        <status>REJECTED</status>
        <attribute1></attribute1>
        <attribute2></attribute2>
        <error_code>0</error_code>
        <error_message><![CDATA[]]></error_message>
    </order>
</portmoneresult>

6.3.2 Cancellation of payment with pre-authorization. JSON request

{
  "method": "rejectPreauth",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopOrderNumber": "SHP-00000015",
      "shopbillId": 395587649
    }
  },
  "id": "1"
}

6.3.2 Cancellation of payment with pre-authorization. Response (successful)

{
  "shop_bill_id": "395587649",
  "shop_order_number": "SHP-00000015",
  "description": "Order description",
  "bill_amount": "1",
  "status": "REJECTED",
  "bank_id": "1042",
  "terminal_id": "4269955",
  "merchant_id": "20905416",
  "rrn": "0000000000",
  "auth_code": "882311",
  "attribute1": null,
  "attribute2": null,
  "attribute3": null,
  "attribute4": null,
  "attribute6": "444433******1111",
  "commission": "0",
  "error_code": "0",
  "error_message": null,
  "token": null
}

To Section 7 "Splitting the payment"

Split payment request

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input
    type="hidden"
    name="bodyRequest"
    value='{
   "paymentTypes":{
      "card":"Y",
      "portmone":"N",
      "token":"N",
      "clicktopay":"N",
      "createtokenonly":"N"
   },
   "priorityPaymentTypes":{
      "card":"1",
      "portmone":"0",
      "qr":"0",
      "token":"0",
      "clicktopay":"0",
      "createtokenonly":"0"
   },
   "payee":{
      "payeeId":"3048",
      "login":"",
      "dt":"",
      "signature":"",
      "shopSiteId":""
   },
   "order":{
      "description":"Test Payment",
      "shopOrderNumber":"",
      "billAmount":"3",
      "attribute1":"",
      "attribute2":"",
      "attribute3":"",
      "attribute4":"",
      "attribute5":"Water:3048;2;Souvenir:11344;1;",
      "successUrl":"",
      "failureUrl":"",
      "preauthFlag":"N",
      "billCurrency":"UAH",
      "encoding":"",
      "expTime":""
   },
   "token":{
      "tokenFlag":"Y",
      "returnToken":"Y",
      "token":"",
      "cardMask":"",
      "otherPaymentMethods":"Y",
      "sellerToken":""
   },
   "payer":{
      "lang":"uk",
      "emailAddress":"[email protected]",
      "showEmail":"N"
   },
   "style":{
      "type":"",
      "logo":"",
      "backgroundColorButtons":"",
      "colorTextAndIcons":"",
      "logoHeight":""
   }
}'
  />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" style={{ width: '350px' }}
  class="button_green" />
</form>

To Section 8 "Getting authorization results"

8.2.1 POST authorization results request

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="result" />
  <input type="hidden" name="payee_id" value="1185" />
  <input type="hidden" name="login" value=" preauth_flag" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="shop_order_number" value="123456" />
  <input type="hidden" name="status" value="PAYED" />
  <input type="hidden" name="start_date" value="01.01.2016" />
  <input type="hidden" name="end_date" value="30.01.2016" />
</form>

8.2.1 POST authorization results response

<?xml version="1.0" encoding="utf-8"?>
<portmoneresult lang="ru">
    <request>
        <payee_id>1185</payee_id>
        <shop_order_number>7852547316_905992780_439915</shop_order_number>
        <status>%</status>
        <start_date>01.08.2025</start_date>
        <end_date>01.09.2025</end_date>
    </request>
    <orders type="list">
        <order>
            <shop_bill_id>2085828976</shop_bill_id>
            <shop_order_number>7852547316_905992780_439915</shop_order_number>
            <description>Telegram payment</description>
            <bill_date>01.09.2025</bill_date>
            <pay_date>01.09.2025 12:27:50</pay_date>
            <pay_order_date></pay_order_date>
            <bill_amount>40</bill_amount>
            <auth_code>TESTPM</auth_code>
            <status>PAYED</status>
            <attribute1></attribute1>
            <attribute2></attribute2>
            <error_code>0</error_code>
            <error_message></error_message>
        </order>
    </orders>
</portmoneresult>

8.2.2 JSON authorization results request

{
  "method": "result",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopOrderNumber": "005311590_783211_29.01.2019.202527",
      "shopbillId": 455025419,
      "status": "",
      "startDate": "30.03.2019",
      "endDate": "31.03.2019"
    }
  },
  "id": "1"
}

8.2.2 JSON authorization results response (successful)

[
  {
    "payee_id": "1185",
    "description": "",
    "status": "PAYED",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "attribute5": "Вода:3048;2;Сувенір:1185;1;",
    "commission": 0,
    "distribution_payee_id": "1185",
    "bank_name": "ГУ Ощадбанку м.Київ",
    "terminal_id": "4269955",
    "merchant_id": "20905416",
    "rrn": "0000000000",
    "pay_date": "20.08.2024 11:43:11",
    "payee_export_date": "27.08.2024 15:40:45",
    "payee_export_flag": "Y",
    "chargeback": "N",
    "payee_name": "ФОП WDISHOP",
    "payee_commission": ".07",
    "pay_order_date": "",
    "pay_order_number": "",
    "pay_order_amount": "",
    "shopBillId": "1750101779",
    "shopOrderNumber": "P1750101779",
    "billAmount": "1",
    "errorCode": "",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "cardBankName": "TEST",
    "token": "20313735303130313737390965B1D7FB63513942C95B286B6DE2045B896B971395C9298E34926640CB6AEA6D8E70F63AFD84584ED9FDB668342E7762E",
    "payeeExportResult": "",
    "gateType": "Card",
    "cardTypeName": "Visa"
  }
]

8.3 Notification for successful payment – BILLS message

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

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

8.3 Notification about bank payment – PAY_ORDERS message

<?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>
                <DISTRIBUTIONS>
  <DISTRIBUTION>
    <DISTRIBUTION_ID>ID payment distribution</DISTRIBUTION_ID>
    <PAYEE>
      <NAME>Recipient company name for payment distribution</NAME>
      <CODE>Recipient company code for payment distribution</CODE>
      <EDRPOU>EDRPOU code of the recipient company for payment distribution</EDRPOU>
      <IBAN>Recipient company bank account</IBAN>
    </PAYEE>
    <AMOUNT>Distribution amount</AMOUNT>
    <DESCRIPTION>Distribution description</DESCRIPTION>
  </DISTRIBUTION>
</DISTRIBUTIONS>
            </BILL>
        </BILLS>
    </PAY_ORDER>
</PAY_ORDERS>

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

8.3 Confirmation of payment information receipt – RESULT message

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

8.3 RESULT message example

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

8.4 Example of statement with authorization results in XML format

<?xml version='1.0' encoding='windows-1251' standalone='yes'?>
  <portmoneresult>
  <request>
    <shopordernumber>305966</shopordernumber>
    <shop_id>7364</shop_id>
    <paymenttype>1</paymenttype>
    <startdate>18/03/2010</startdate>
    <enddate>18/03/2010</enddate>
    <success>1</success>
  </request>
  <orders>
    <order>
      <shopordernumber>305966</shopordernumber>
      <pay_date>18/03/2010</pay_date>
      <description>50908: payment cards coverage</description>
      <bill_amount>108.98</bill_amount>
      <error_code>000</error_code>
      <error_message></error_message>
      <status>PAYED</status>
      <pay_order_number></pay_order_number>
      <pay_order_date></pay_order_date>
    </order>
    </orders>
  </portmoneresult>

8.5 Example of a Successful Payment Notification in JSON Format

{
    "shopBillId":"",
    "shopOrderNumber":"",
    "description":"",
    "cardMask":"",
    "expDate":"",
    "billAmount":"",
    "status":"",
    "authCode":"",
    "token":"",
    "receiptUrl":"",
    "attribute1":"",
    "attribute2":"",
    "attribute3":"",
    "attribute4":"",
    "errorCode":"",
    "error":"",
    "notificationType":"",
    "cardType":"",
    "bank_name":"",
    "terminal_id":"",
    "merchant_id":"",
    "rrn":""
}

8.5 Confirmation of Payment Information Receipt in JSON Format

{
  "errorCode": "0",
  "reason": "OK",
  "responseId": "123456789"
}

8.7 Request for getting a link to the receipt

{
  "method": "getReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopOrderNumber": "SD12342"
    }
  },
  "id": "1"
}

8.7 Example of successful response

{
    "result": {
        "linkPdf": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/303035350a9befc6705b76fe308ed5567664582c1b830b8dcd85cbb0eb3dcf1621d11131ad428b16c9ec3e5c84ae67baba7222d688d985969bfa13b82dde9a6fc5bd7f",
        "linksPdfReturn": [
            "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/30303535e835780e2ca637197c4f44a14f450cca1af76da7034369cc1e546fe7ae193c9767e9545bed49d72873dd10508f0964aa3ec9d96c7a36953eb5605c9d2618b2"
        ]
    },
    "id": "1"
}

To Section 9 "Refund"

9.1.1 POST refund request

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="return" />
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="shop_bill_id" value="87834981" />
  <input type="hidden" name="return_amount" value="99.00" />
  <input type="hidden" name="encoding" value="utf-8" />
  <input type="hidden" name="lang" value="uk" />
</form>

9.1.1 POST refund response (successful)

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <method>return</method>
        <login>shp_login</login>
        <password>******</password>
        <shop_bill_id>87834981</shop_bill_id>
        <return_amount>99.00</return_amount>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>87834981</shop_bill_id>
        <shop_order_number><![CDATA[1234]]></shop_order_number>
        <description><![CDATA[Payment of order №1234]]></description>
        <bill_date>15.11.2013</bill_date>
        <pay_date>15.11.2013 22:21:51</pay_date>
        <bill_amount>-99.00</bill_amount>
        <auth_code>123456</auth_code>
        <status>RETURN</status>
        <error_code>0</error_code>
        <error_message><![CDATA[]]></error_message>
    </order>
</portmoneresult>

9.1.1 POST refund response (failure)

<order>
    <error_code>5</error_code>
    <error_message><![CDATA[Bill return error [SHOP_BILL_ID = 87834981]ORA-20001:
    Determining payment terminal details error.[pay_terminal_id=]]]> </error_message>
</order>

9.1.2 JSON refund request

{
  "method": "return",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopbillId": 594890029,
      "returnAmount": "1",
      "message": "test return by shopbillId"
    }
  },
  "id": 1
}

9.1.2 Response format

[
  {
    "description": "",
    "status": "RETURN",
    "bank_id": "1000",
    "terminal_id": "68611",
    "merchant_id": "AVAL_TEST",
    "rrn": "",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "commission": 0,
    "shopBillId": "1035983328",
    "shopOrderNumber": "P1029355342",
    "billAmount": "-.5",
    "errorCode": "0",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "token": "",
    "gateType": ""
  }
]

9.2 JSON refund request

{
  "method": "reject",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopbillId": 594890029,
      "returnAmount": "1",
      "message": "test return by shopbillId"
    }
  },
  "id": 1
}

9.2 Response format

[
  {
    "description": "",
    "status": "REJECTED",
    "bank_id": "1000",
    "terminal_id": "68611",
    "merchant_id": "AVAL_TEST",
    "rrn": "",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "commission": 0,
    "shopBillId": "1035983328",
    "shopOrderNumber": "P1029355342",
    "billAmount": "-.5",
    "errorCode": "0",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "token": "",
    "gateType": ""
  }
]

To Section 12 "Invoicing customers by e-mail or SMS (е-invoicing)"

12.1 Form to send invoices by e-mail

<form
  action="https://www.portmone.com.ua/r3/services/invoice/email/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="payeeId" value="1185" />
  <input type="hidden" name="shopOrderNumber" value="12345" />
  <input type="hidden" name="namePayer" value="Ivanov Ivan" />
  <input type="hidden" name="comment" value="Hello man!!!" />
  <input type="hidden" name="amount" value="150" />
  <input type="hidden" name="emailRecipient" value="[email protected]" />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="cc_email" value="" />
  <input type="hidden" name="preauth_flag" value="N" />
  <input type="hidden" name="bill_currency" value="UAH" />
  <input type="hidden" name="expDate" value="20190122140200" />
</form>

12.2 Form to send invoices via SMS

<form
  action="https://www.portmone.com.ua/r3/services/invoice/sms/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="payeeId" value="1185" />
  <input type="hidden" name="shopOrderNumber" value="12345" />
  <input type="hidden" name="namePayer" value="Ivanov Ivan" />
  <input type="hidden" name="comment" value="Hello man!!!" />
  <input type="hidden" name="amount" value="150" />
  <input type="hidden" name="phoneRecipient" value="+380XXXXXXXXX" />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="preauth_flag" value="N" />
  <input type="hidden" name="bill_currency" value="UAH" />
  <input type="hidden" name="expDate" value="20190122140200" />
</form>

12.3 Mass invoicing request

{
  "method": "invoices",
  "id": "1",
  "params": {
    "authData": {
      "login": "wdishop",
      "password": "********",
      "payeeId": "1185"
    },

    "data": {
      "0": [
        "Petrov Ivan",
        "[email protected]",
        "123",
        "тест 1",
        "1",
        "UAH",
        "N",
        "uk",
        "20190208132000"
      ],
      "1": [
        "Tamara Nykolaevna",
        "[email protected]",
        "124",
        "тест 2",
        "1.02",
        "UAH",
        "Y",
        "en",
        "20190208132000"
      ],
      "2": [
        "Aleksey Petrovych",
        "[email protected]",
        "125",
        "тест 3",
        "1.03",
        "EUR",
        "Y",
        "en",
        "20190208132000"
      ],
      "3": [
        "Ivan Fedorovych",
        "+380930000000",
        "126",
        "тест 4",
        "1.04",
        "UAH",
        "Y",
        "",
        "20190208132000"
      ],
      "4": [
        "Nikolay Vasylevych",
        "+380930000000",
        "127",
        "тест 5",
        "1.05",
        "",
        "N",
        "uk",
        "20190208132000"
      ],
      "5": [
        "Poddubnaia Aleksandra Serheevna",
        "+380930000000",
        "128",
        "тест 6",
        "1.06",
        "",
        "N",
        "",
        "20190208132000"
      ],
      "6": [
        "Vaska",
        "[email protected]",
        "129",
        "тест 7",
        "10.07",
        "",
        "N",
        "",
        "20190208132000"
      ]
    }
  }
}

12.3 Mass invoicing response (successful)

{
  "result": {
    "0": {
      "shopBillId": "448808680",
      "payeeId": "1185",
      "shopBillNumber": "123",
      "description": "test 1",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1",
      "error": "",
      "errorCode": "0"
    },
    "1": {
      "shopBillId": "448808686",
      "payeeId": "1185",
      "shopBillNumber": "124",
      "description": "test 2",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.02",
      "error": "",
      "errorCode": "0"
    },
    "2": {
      "shopBillId": "448808698",
      "payeeId": "1185",
      "shopBillNumber": "125",
      "description": "test 3",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": ".44",
      "error": "",
      "errorCode": "0"
    },
    "3": {
      "shopBillId": "448808699",
      "payeeId": "1185",
      "shopBillNumber": "126",
      "description": "test 4",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.04",
      "error": "",
      "errorCode": "0"
    },
    "4": {
      "shopBillId": "448808701",
      "payeeId": "1185",
      "shopBillNumber": "127",
      "description": "test 5",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.05",
      "error": "",
      "errorCode": "0"
    },
    "5": {
      "shopBillId": "448808703",
      "payeeId": "1185",
      "shopBillNumber": "128",
      "description": "test 6",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.06",
      "error": "",
      "errorCode": "0"
    },
    "6": {
      "shopBillId": "448808704",
      "payeeId": "1185",
      "shopBillNumber": "129",
      "description": "test 7",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "10.07",
      "error": "",
      "errorCode": "0"
    }
  },
  "id": "1"
}

12.4 Request for getting a payment link

{
  "method": "getLinkInvoice",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "amount": "15",
      "shopOrderNumber": "123ppps31",
      "emailRecipient": "[email protected]",
      "comment": "test",
      "expDate": "20210217175959",
      "billCurrency": "USD",
      "preauthFlag": "N",
      "attribute1": "1",
      "attribute2": "2",
      "attribute3": "3",
      "attribute4": "4",
      "attribute5": "5",
      "goods": [
        {
          "internalCode": "123456",
          "manufacturerCode": "123456",
          "govClassificationCode": "123456",
          "name": "",
          "name_en": "",
          "description": "",
          "description_en": "",
          "price": "100",
          "quantity": "2",
          "uomCode": "",
          "amount": "200",
          "serviceFlag": "N",
          "taxRateCodes": "1",
          "descriptionUrl": "",
          "imageUrl": ""
        }
      ]
    }
  },
  "id": "1"
}

12.4 Getting a payment link response (successful)

{
  "result": {
    "linkInvoice": "https://www.portmone.com.ua/r3/uk/i/nzgi2W8pvK"
  },
  "id": "1"
}

12.5 Request for getting a payment link

{
  "method": "createLinkPayment",
  "paymentTypes": {
    "clicktopay": "Y",
    "createtokenonly": "N",
    "token": "N",
    "privat": "N",
    "gpay": "Y",
    "card": "Y"
  },
  "priorityPaymentTypes": {
    "token": "6",
    "gpay": "2",
    "clicktopay": "4",
    "privat": "5",
    "card": "1"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "shopSiteId": ""
  },
  "order": {
    "description": "",
    "shopOrderNumber": "578970",
    "billAmount": "44",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "attribute5": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "Y",
    "token": "",
    "cardMask": "",
    "otherPaymentMethods": ""
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  }
}

12.5 Getting a payment link response (successful)

{
  "linkPayment": "https://prt.mn/KYbE_AKxyR",
  "error": "",
  "errorCode": "0"
}

12.6 Request for getting a payment link

{
  "method": "closeInvoice",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8"
    }
  }
}

12.6 Getting a payment link response (successful)

{
  "description": "",
  "status": "REJECTED",
  "attribute1": "",
  "attribute2": "",
  "attribute3": "",
  "attribute4": "",
  "commission": 0,
  "shopBillId": "1715616657",
  "shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8",
  "billAmount": "1459",
  "errorCode": "",
  "errorMessage": "Order payment time has expired or invoice was closed.  ",
  "authCode": "",
  "cardMask": "",
  "token": "",
  "gateType": ""
}

To Section 13 "Transfer of funds from account to card (token)"

13.1 Request to transfer funds from account to card

{
  "paymentType": "a2c",
  "description": "4444333322221111",
  "attribute1": "",
  "attribute2": "552aa24c46c807a05bb0fc32477c19f0",
  "attribute3": "3",
  "attribute4": "4",
  "billAmount": "1.33",
  "payeeId": "17553",
  "shopOrderNumber": "SHP-27810-20190913045941",
  "cvvVerifyFlag": "N",
  "token": "",
  "billCurrency": "UAH",
  "shopSiteId": "",
  "cardData": "",
  "dt": "20190913165941",
  "signature": "7B82D64E6CC226E3A5036F6020E77BD71F517C5D49F5FF80EA24289FEDBC56AE",
  "mode": "1101"
}

13.1 Transfer funds from account to card. Response (successful)

{
  "status": "PAYED",
  "errorCode": "0",
  "error": "",
  "shopBillId": "544917852",
  "billAmount": "1.33",
  "billNumber": "SHP-21251-20190913032725",
  "attribute1": "58661656",
  "attribute2": "552aa24c46c807a05bb0fc32477c19f0",
  "attribute3": "838622",
  "attribute4": "925615124384",
  "authCode": "000000",
  "payeeExportFlag": "Y",
  "receiptLink": "https://portmone2.com/r3/services/receipts/get-receipts/shop-bill-id/35354f5f1297395f0d47613cb8098865636cfcd1584bd40241d634ae36efde97184b631cc0a1e8ed1c3546365bd4ce3860ac7b5b0ec0748c5236b25af3b926a624",
  "billCurrency": null,
  "transactionId": "ZEM_1647320190913032726"
}

Glossary​

1. Payment acceptance technology​

2. Test mode​

3. Order payment​

3.1. POST request​

3.2. JSON request​

Response structure:​

3.3. Managing a view of a payment page​

Examples of Privat24 button placement options​

Embedding the payment page in a frame​

Ways to display payment page​

3.4. Payment Widget​

3.4.1 Payment in a modal window (popup)​

3.4.2 Payment in an embedded frame (iframe)​

3.5. Signature​

3.6. Exchange rate​

3.7 Installment Payments​

4. Order payment using a payment Token​

4.1. Token creation​

4.2. Payment by Token​

4.2.1. POST request​

4.2.2. JSON request​

4.3. Payment by Token without CVV2 (recurring payment)​

4.4. Forming an order (payment message) in Viber Bot​

4.5. Getting IPS data by Portmone token​

4.6. Getting an asset by the unique IPS ID​

4.7. Payment by Token with 3D Secure without CVV2 (recurring payment)​

4.8 Token payment with the appearance of the card without CVV2​

5. Money transfer from card to card​

5.1. Card token receiving​

5.2. Creating a request to transfer funds between card tokens​

5.3. Request to transfer funds from token to card​

5.4. Transfer of funds from card to account and from account to card​

5.4.1. Transfer from the sender's card token to account​

5.4.2. Transfer from account to the recipient's card token​

6. Payments with pre-authorization​

6.1. Pre-authorization of payment (funds blocking)​

6.2. Confirmation of payment made with pre-authorization (post-authorization procedure)​

6.2.1. POST request​

6.2.2. JSON request​

6.3. Cancellation of payment with pre-authorization​

6.3.1. POST request​

6.3.2. JSON request​

7. Splitting the payment​

8. Getting authorization results​

8.1. Getting statements with authorization results in the Personal Area​

8.2. Authorization results request​

8.2.1. POST request​

8.2.2. JSON request​

8.2.2.1. Request for authorization results when using installment payments from Monobank in JSON format​

8.2.2.2. Example of a successful response for "Nova Poshta" delivery in JSON format​

8.3. Notification of the Online Store server about the authorization result​

8.4. Receiving statements with authorization results by e-mail​

8.5. Notification in JSON format​

Notification for successful payment in JSON format​

Confirmation of receipt of payment notification in JSON format​

8.6. Sending a message about payment order (text notification by email about the financial coverage of transactions)​

8.7. Getting a link to the receipt​

9. Refund​

9.1.1 Return POST request​

9.1.2. Return JSON request​

9.2. Cancellation of payment JSON request​

11. Using Gateway for mobile application​

12. Invoicing customers​

12.1. Sending invoice by e-mail​

12.2. Sending invoice via SMS​

12.3. Mass invoicing by e-mail or SMS​

12.4. Getting a payment link​

12.5. Creating a payment link​

12.6. Сlose Invoice​

13. Transfer of funds from account to card (token)​

13.1 Transfer of funds from account to card​

14. Fiscalization​

14.1 Retrieving PRRO Tax Rates​

14.2 Manual Payment Fiscalization / Refund Fiscalization​

14.3 Sending Fiscal Receipt to User Email​

14.4 Querying Fiscalization Status​

Examples​

To Section 3 "Order payment"​

To Section 4 "Order payment using a payment Token"​

Glossary

1. Payment acceptance technology

2. Test mode

3. Order payment

3.1. POST request

3.2. JSON request

Response structure:

3.3. Managing a view of a payment page

Examples of Privat24 button placement options

Embedding the payment page in a frame

Ways to display payment page

3.4. Payment Widget

3.4.1 Payment in a modal window (popup)

3.4.2 Payment in an embedded frame (iframe)

3.5. Signature

3.6. Exchange rate

3.7 Installment Payments

4. Order payment using a payment Token

4.1. Token creation

4.2. Payment by Token

4.2.1. POST request

4.2.2. JSON request

4.3. Payment by Token without CVV2 (recurring payment)

4.4. Forming an order (payment message) in Viber Bot

4.5. Getting IPS data by Portmone token

4.6. Getting an asset by the unique IPS ID

4.7. Payment by Token with 3D Secure without CVV2 (recurring payment)

4.8 Token payment with the appearance of the card without CVV2

5. Money transfer from card to card

5.1. Card token receiving

5.2. Creating a request to transfer funds between card tokens

5.3. Request to transfer funds from token to card

5.4. Transfer of funds from card to account and from account to card

5.4.1. Transfer from the sender's card token to account

5.4.2. Transfer from account to the recipient's card token

6. Payments with pre-authorization

6.1. Pre-authorization of payment (funds blocking)

6.2. Confirmation of payment made with pre-authorization (post-authorization procedure)

6.2.1. POST request

6.2.2. JSON request

6.3. Cancellation of payment with pre-authorization

6.3.1. POST request

6.3.2. JSON request

7. Splitting the payment

8. Getting authorization results

8.1. Getting statements with authorization results in the Personal Area

8.2. Authorization results request

8.2.1. POST request

8.2.2. JSON request

8.2.2.1. Request for authorization results when using installment payments from Monobank in JSON format

8.2.2.2. Example of a successful response for "Nova Poshta" delivery in JSON format

8.3. Notification of the Online Store server about the authorization result

8.4. Receiving statements with authorization results by e-mail

8.5. Notification in JSON format

Notification for successful payment in JSON format

Confirmation of receipt of payment notification in JSON format

8.6. Sending a message about payment order (text notification by email about the financial coverage of transactions)

8.7. Getting a link to the receipt

9. Refund

9.1.1 Return POST request

9.1.2. Return JSON request

9.2. Cancellation of payment JSON request

11. Using Gateway for mobile application

12. Invoicing customers

12.1. Sending invoice by e-mail

12.2. Sending invoice via SMS

12.3. Mass invoicing by e-mail or SMS

12.4. Getting a payment link

12.5. Creating a payment link

12.6. Сlose Invoice

13. Transfer of funds from account to card (token)

13.1 Transfer of funds from account to card

14. Fiscalization

14.1 Retrieving PRRO Tax Rates

14.2 Manual Payment Fiscalization / Refund Fiscalization

14.3 Sending Fiscal Receipt to User Email

14.4 Querying Fiscalization Status

Examples

To Section 3 "Order payment"

To Section 4 "Order payment using a payment Token"