Skip to main content

Portmone.com Payment Gateway

Glossary

TermDefinition
Merchant, Online Store or PartnerOrganization which has signed a payment acceptance agreement with Portmone.com
Buyer, Client or CustomerA person who visits the Merchant's Online Store in order to learn about the range of goods (services) and to make a purchase
Card, Payment CardPayment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
AuthorizationThe process of giving access rights or other powers to the Buyer, program or process
Recurring PaymentsAutomatic payments (no client actions or re-entering card details required), which are carried out with the consent of the client
TokenA 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
SHOPBILLIDA unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
CVV2/CVC2CVV2 (Card Verification Value 2) is a three-digit card security code that helps to verify legitimacy of a Visa payment card. The Mastercard payment system has similar card security code called CVC2 (Card Validation Code 2)
Acquiring BankA bank that organizes banking cards acceptance points (terminals, ATM’s) and processes full range of financial operations connected with performing bank settlements and payments by banking cards at that points
Issuing Bank (Card Issuing Bank)A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards
3-D Secure3-D Secure is a protocol which used to secure handling of online bank card payments
IBANInternational Bank Account Number
IPSInternational Payment System

1. Payment acceptance technology

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

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

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

  3. The Portmone.com authorization server establishes connection with the Buyer using secure protocol (TLS 1.2), verifies the data received from the Store.

  4. The Portmone.com site receives from the Buyer the parameters of his/her Payment Card and ensures the authorization of the Card.

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

  6. 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.
  7. 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.
  8. In case of successful payment, the paid order number and the payment data are transmitted by the POST method to the Online Store page.

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

ParameterDescriptionRequiredValue
payee_idA unique identifier of the Online StoreYesAssigned to each Partner individually when connected to the Portmone.com system
shop_order_numberNumber 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.NoMaximum length is 120 symbols
bill_amountAmount of the order. Currency is hryvnia (UAH). The decimal separator is the dot symbol "."YesFor example: 1.50
bill_currencyCurrency of the paymentNoPossible values: UAH (default value), USD, EUR, GBP, PLN, KZT
descriptionComment to the order / description of payment detailsNoMaximum length is 250 symbols
success_urlThe 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")
NoFor example: http://example.com/success.html
failure_urlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNoFor example: http://example.com/failure.html
langPayment system interface languageNouk – Ukrainian, en – English
encodingEncodingNoThe default is UTF-8
preauth_flagSets the pre-authorization mode when funds are only blocked on the Client’s card, but not actually charged from the client’s accountNo"Y" – enable pre-authorization mode, "N" – disable pre-authorization mode (the default is "N")
attribute1-4Service fieldNoFilled at company's discretion
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")NoFilled 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_timeSets 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 paidNoFilled in seconds

Response structure:

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

Response parameters description:

ParameterDescription
SHOPBILLIDA unique identifier (Id) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKPayer’s Card mask
ATTRIBUTE1Service field. Filled at company’s discretion
ATTRIBUTE2Service field. Filled at company’s discretion
ATTRIBUTE3Service field. Filled at company’s discretion
ATTRIBUTE4Service field. Filled at company’s discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment to the order / description of payment details. Maximum length is 250 symbols
IPSTOKENA unique Visa token
ERRORIPSCODEError code if Visa token was not created
ERRORIPSMESSAGEError 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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)Yes
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)Yes
signatureSignature of the requestYes
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)No
shopOrderNumberNumber of a paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
preauthFlagPayment 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
preauthConfirmDate 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 dateNo
preauthRejectDate 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 dateNo
billCurrencyCurrency of the payment. Default value: UAHNo
expTimeSets 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 paidNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1Service field. Filled at company’s discretionNo
attribute2Service field. Filled at company’s discretionNo
attribute3Service field. Filled at company’s discretionNo
attribute4Service field. Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No
  1. 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".
ParameterDescriptionRequired
cardPayment by CardNo
portmonePayment via Portmone.com walletNo
tokenPayment by Token (if this option is enabled, other methods are not displayed)No
clicktopayPayment using Visa Click to PayNo
privatPayment via LiqPay, with choosing a card from the Privat24 Internet Banking
Pay attention! Pre-authorization functionality does not work when paying via Privat24
No
gpayPayment via Google Pay, with choosing a card from previously stored in the Google Pay accountNo
createtokenonlyCreates 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
gpayonlyPayment 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
applepayPayment via Apple Pay, with choosing a card from previously stored in the Apple Pay accountNo
applepayonlyPayment 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
kyivstarPayment from Kyivstar mobile account balance (for prepaid numbers only)No
installmentInstallment paymentNo

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

  1. installmentPlan – this block allows you to manage installment payments. If the parameters are not specified, but installment=Y is passed in the paymentTypes block, all available installment types with default settings will be displayed.

In order to be able to specify the number of installment months for the payer, it is necessary to add the installmentPlan block, the following array

"installmentPlan": {
"privat24": {
"parts": "3"
},
"oschad": {
"parts": "5"
},
"monobank": {
"parts": "8"
}
}
ParameterDescriptionRequired
privat24Payment in parts from PrivatBankNo
oschadPayment in parts from OschadbankNo
monobankPayment in parts from MonobankNo
partsSets the maximum number of months for installmentsNo

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 a payment in installments page from PrivatBank

An example of payment in installments 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 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"

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 a payment in installments page from Monobank

An example of payment in installments from Monobank

An example of payment in installments from Monobank

Installment from Oschadbank

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"

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 payment in installments from Oschadbank

An example of a payment in installments page from Oschadbank

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

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

  2. All subsequent payments will be made on the same description as the first payment.

  3. The order number for automatic payments will be formed as follows:

    Order number at first payment_RECURENT_Date of automatic payment

ParameterDescriptionRequired
showDisplaying 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
editEditing 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 editedNo
settingsA block of parameters for setting up automatic paymentsNo
credentialsAuthorization parametersYes
changeCheckboxStatevalue YYes
defaultCheckboxStatevalue: Y – the checkbox "Make payment regular" is autofilled,N – the client independently fills in the "Make regular payment" checkboxNo

The settings block structure:

ParameterDescriptionRequired
periodFrequency of automatic payments. Takes the following values: 1 – monthly,
2 – quarterly, 3 – semiannually, 4 – annually
Yes
payDateDay of the month for automatic payment. Can takes value from 1 to 28No
startDateAutomatic payments start date. Should be sent in the following format: DD.MM.YYYY. If not specified, yesterday's date is automatically setNo
endDateAutomatic 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
amountAmount 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

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

  1. token – settings to work with a Token (see section 4 "Order payment using a payment Token")
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenToken valueRequired for payment by Token
cardMaskCard maskRequired for payment by Token
otherPaymentMethodsAllows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)No
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
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:

OptionemailAddressshowEmailDisplaying on the payment page
1empty valueYAn empty "e-mail" field is displayed
2valid e-mailYA prefilled "e-mail" field is displayed that can be edited
3empty valueNThe "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
4valid e-mailNThe "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
  1. shipping – this block contains shipping information
ParameterDescriptionRequired
servicesShipping servicesYes
ukrposhtaCarrier name (name of the company that delivers the order to the recipient)Yes
deliveryTypesAvailable delivery methods: W2D – courier delivery to the recipient's address; W2W – delivery to the carrier office/warehouseYes
senderClientIdA unique identifier of the Online Store in the carrier system. Created in the merchant's Personal areaYes
senderAddressIdA unique identifier of the Online Store address in the carrier system. Created in the merchant's Personal areaYes
senderPostCodePostal code of the senderYes
typeParcel delivery type. Possible values: STANDARD, EXPRESSYes
parcelWeightParcel weight in grams. Maximum allowed value – 30000Yes
parcelLengthThe length of the largest side of the parcel stated in centimeters. Numbers onlyYes
parcelWidthThe width of a parcel in centimetersYes
parcelHeightThe height of a parcel in centimetersYes
parcelDeclaredPriceThe declared cost of a parcel in UAHYes
parcelDescriptionDescription of a parcelNo
fragileParcel fragility mark. Possible values: Y, NNo
checkOnDeliveryChecking the contents of the parcel on receiving is needed. Possible values: Y, NNo
beesIndicates that bees are sent. Possible values: Y, NNo
payerIndicates who pays for delivery – sender or recipient. Default value: clientYes
smsNotify the client via SMS. Possible values: Y, NNo
withDeliveryNotificationNotify the client using the notification service of the carrier company. Possible values: Y, NNo
enableEnable the displaying of delivery form. Possible values: Y, NYes
requiredFilling the delivery form is required. Possible values: Y, NYes
  1. style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

Response structure:

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

Response parameters description:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKPayer’s Card mask
ATTRIBUTE1Service field. Filled at company’s discretion
ATTRIBUTE2Service field. Filled at company’s discretion
ATTRIBUTE3Service field. Filled at company’s discretion
ATTRIBUTE4Service field. Filled at company’s discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment to the order / description of payment details. Maximum length is 250 symbols
IPSTOKENA unique Visa token
ERRORIPSCODEError code if Visa token was not created
ERRORIPSMESSAGEError 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:

FieldDescriptionPage style type, for which a field can be used
typeSets 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
logoContains 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 edgesbrand, co-brand
logoWidthParameter defining the width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300pxbrand, co-brand
logoHeightParameter 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
backgroundColorHeaderSets the colour of a header section on the page. The input format is HEX (for example, #ff0000)brand, light
backgroundColorButtonsSets the colour of buttons. The input format is HEX (for example, #ff0000)brand, light
colorTextAndIconsSets text and icon colour. The input format is HEX (for example, #ff0000)brand, light
borderColorListSets the colour of lines in the list of payment methods. The input format is HEX (for example, #ff0000)brand, light
bcMainSpecifies the colour to fill page background. The input format is HEX (for example, #ff0000)brand, light

Embedding the payment page in a frame

To run IFRAME on your site, do the following:

  1. 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":"3048","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").

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

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

Partner style for the entire page

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

3.4. JSON request for PaymentGatewayCheckout

Description:

The service provides possibility to call a payment window without redirecting the client to the Portmone site. Clicking the Portmone payment button on the merchant's checkout page opens a modal window in which the customer enters payment information.

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.

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>

After loading the pg.min.js script, the payment button will be located in the block in which the code for loading the script is placed.

Availability and restrictions:

No restrictions.

Request structure:

Parameters for generating JSON-structure of request:

The data array describes the merchant's information, order data and payment methods (please, refer to "3.2 JSON order payment request" to see the array structure).

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)No
shopOrderNumberNumber of a paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
preauthFlagPayment 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
preauthConfirmDate 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 dateNo
preauthRejectDate 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 dateNo
billCurrencyCurrency of the payment. Default value: UAHNo
expTimeSets 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 paidNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1Service field. Filled at company’s discretionNo
attribute2Service field. Filled at company’s discretionNo
attribute3Service field. Filled at company’s discretionNo
attribute4Service field. Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No
  1. 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".
ParameterDescriptionRequired
cardPayment by CardNo
portmonePayment via Portmone.com walletNo
tokenPayment by Token (if this option is enabled, other methods are not displayed)No
clicktopayPayment using Visa Click to PayNo
privatPayment via LigPay, with choosing a card from the Privat24 Internet BankingNo
gpayPayment via Google Pay, with choosing a card from previously stored in the Google Pay accountNo
createtokenonlyCreates 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
gpayonlyPayment 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
applepayPayment via Apple Pay, with choosing a card from previously stored in the Apple Pay accountNo
applepayonlyPayment 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
  1. 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).

  1. token – settings to work with a Token (see section 4 "Order payment using a payment Token")
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenToken valueRequired for payment by Token
cardMaskCard maskRequired for payment by Token
otherPaymentMethodsAllows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)No
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
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:

OptionemailAddressshowEmailDisplaying on the payment page
1empty valueYAn empty "e-mail" field is displayed
2valid e-mailYA prefilled "e-mail" field is displayed that can be edited
3empty valueNThe "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
4valid e-mailNThe "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
  1. style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").

The brand array is determine how the "Pay" button looks, that opens the modal window.

ParameterDescriptionRequired
heightSets the button height. By default, it accepts the button style set on the pageNo
widthSets the button width. By default, it accepts the button style set on the pageNo
buttoncolorSets the button colour. By default, it accepts the button style set on the pageNo
fontfamilySets the button font type. By default, it accepts the button style set on the pageNo
textcolorSets the button font colour. By default, it accepts the button style set on the pageNo
langSets the language for displaying the text of the "Pay" / "Download receipt" button. Default value: uk – UkrainianNo
paddingSets the value of the padding around the button's content. By default, it accepts the button style set on the pageNo
borderAllows you to specify the style, width and colour of the button's border. By default, it accepts the button style set on the pageNo
fontsizeSets the button font size. By default, it accepts the button style set on the pageNo
closemodalDetermines 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

Functions:

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

  2. PG.brandButton – this function takes an object that describes and stylizes a payment button.

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

ValueDesctiption
gatewayThis 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
stockThis 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" };
terminalThis 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
p2pThis 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:

  • frame – opens the payment window in a frame (see fig. 7);
  • modal – opens the payment window in a new browser window with the specified sizes (see fig. 8).
  1. 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.

  2. 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');

An example of opening the payment window in a frame

Fig. 7 – an example of opening the payment window in a frame on the Online Store website

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

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

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:

ParameterDescription
statusTransaction status. Takes the value PAYED
errorCodeError Code
errorRemains unfilled
shopBillIdA unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
billAmountAmount of the payment
shopOrderNumberNumber of paid order (bill) in the Merchant's system
cardMaskPayer’s Card mask
attribute1Service field
attribute2Service field
attribute3Service field
attribute4Service field
receiptLinkLink to get a receipt
langPayment system interface language. Possible values: uk – Ukrainian, en – English
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
tokenCard token
commissionThe value of the commission from payment
payeeNameMerchant name
billCurrencyCurrency of the payment
IPSTokenValueA unique Visa token
errorIPSCodeError code if Visa token was not created
errorIPSMessageError message if Visa token was not created

3.5. Signature

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

$login = 'wdishop';
$payeeId = '1185';
$password = 'wdi451';
$shopOrderNumber = 'test123';
$billAmount='150';
$key = 'BDFC166F8AE2F5323A557DB6CA16758D';
$dt = date("YmdHis");
$strToSignature = $payeeId.$dt.bin2hex($shopOrderNumber).$billAmount;
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));
ParameterDescriptionRequired
loginЛогін компаніїТак
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
passwordThe Online Store passwordYes
shopOrderNumberNumber of paid order (bill) in the Merchant's systemNo
billAmountAmount of the paymentYes
keyThe key that is provided to each Partner individually when connecting to the Portmone.com systemYes
dtdateYes

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:

ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
datedateYes

Response structure:

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

Response parameters description:

ParameterDescription
keyCurrency name
valueexchange 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"

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:

  1. paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
ParameterDescriptionRequired
createtokenonlyTo create a Token, you must set the value to "Y" for this parameterYes
  1. priorityPaymentTypes – this block allows you to manage placement of payment methods on a page
ParameterDescriptionRequired
createtokenonlyTo create a Token, you must set the value to "1" for this parameterYes
  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)Required, identifies the Token in subsequent payments
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the payment (set the value to "1" (in UAH) to get the Token)Yes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
preauthFlagPayment pre-authorization flag. Mandatory value to receive a Token – "N" (a regular payment without pre-authorization)No
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1-4Service fields. Filled at company’s discretionNo
  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenToken valueLeave empty
cardMaskCard maskLeave empty
otherPaymentMethodsAllows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)Mandatory value is "N"
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
  1. 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKPayer’s Card mask
ATTRIBUTE1Service field. Filled at company's discretion
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment 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:

ParameterDescription
payee_idA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Online Store. Maximum length is 120 symbols
bill_amountAmount of the order. Currency – hryvnia (UAH). The decimal separator is the dot symbol "."
descriptionComment to the order / description of payment. Maximum length is 250 symbols
application_urlThe 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
langPayment system interface language. Possible values: uk – Ukrainian, en – English
tokenYou must set the value of the token obtained in the previous step
attribute1-4Service fields. Filled at company’s discretion
attribute5Used 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:

ParameterDescription
BILL_AMOUNTTransaction amount sent in request
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
RECEIPT_URLLink to get a receipt
TOKENToken value for subsequent payments
CARD_PAYMENT_SYSTEMThe value of the payment system (VISA, MASTERCARD, PROSTIR)
CARD_LAST_DIGITSLast 4 digits of Payment Card number
RESULTThe 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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)No
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
preauthFlagPayment 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
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1Service field. Filled at company's discretionNo
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No
  1. 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".
ParameterDescriptionRequired
cardPayment by CardNo
portmonePayment via Portmone.com walletNo
tokenPayment by Token (if this option is enabled, other methods are not displayed)No
clicktopayPayment using Visa Click to PayNo
qrAdds a tab to generate payment QR-codeNo
  1. 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).

  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenToken valueYes
cardMaskCard maskYes
otherPaymentMethodsAllows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable)No
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
  1. 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKPayer’s Card mask
ATTRIBUTE1Service field. Filled at company's discretion
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment 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:

ParameterDescription
loginThe Online Store login to access account management
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
tokenYou must set the value of the token obtained in the previous step
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
billAmountAmount of the payment. The decimal separator is the dot symbol "."
billCurrencyCurrency of the payment. Default value: UAH
preauthFlagPayment 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)
idID 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:

ParameterDescription
resultOrder status attribute. Possible values: PAYED, CREATED, REJECTED.
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
idID 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:

ParameterDescription
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
billAmountAmount of the payment. The decimal separator is the dot symbol “.”
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
msisdnClientClient's phone number
paymentMessageMessage for the client in Viber Bot. Maximum 250 symbols
attribute1, attribute2, attribute3, attribute4, attribute5Attributes of the operation, optional
preauthFlagShould be N
emailAddressClient's Email
credentialsRequired authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptions
idID 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:

ParameterDescription
errorCodeError code
errorError description is empty in case of a successful response. If the client was not found, the text "Client not found" will be returned
linkqrLink to the QR code of the chat bot
linkbotLink to the chat bot
idID 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:

ParameterDescription
MERCHANT_LOGINMerchant's login in the Portmone system
MERCHANT_PASSWORDMerchant's password in the Portmone system
TOKEN_REFERENCECard 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:

ParameterDescription
TOKEN_TYPEToken type depending on the IPS
idUnique 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:

ParameterDescription
TOKEN_TYPEToken type depending on the IPS
idUnique response ID
tokenInfo, cardMetaData, cardDataCard 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:

ParameterDescription
MERCHANT_LOGINMerchant’s login in the Portmone system
MERCHANT_PASSWORDMerchant’s password in the Portmone system
TOKEN_TYPEToken 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:

ParameterDescriptionRequired
methodValue: paywith3dsYes
passwordThe Online Store passwordYes
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbolsNo
tokenYou must set the value of the token obtained in the previous stepYes
descriptionComment to the order / description of payment details. Maximum length is 250 symbolsYes
billAmountAmount of the payment. The decimal separator is the dot symbol "."Yes
billCurrencyCurrency of the payment. Default value: UAHNo
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
attribute1Service field. Filled at company's discretionNo
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
idID of the request from the Online Store to the Portmone.com systemYes

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:

ParameterDescription
statusOrder status.Possible values:
- PAYED – paid,
- CREATED – created,
- REJECTED – rejected.
shopbillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
pdfUrlIt remains empty
authCodeBank authorization code (added if the order is paid)
isNeed3DS3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required)
actionMPIThe card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
idID 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:

ParameterDescription
shopbillIdOrder ID in the Portmone.com system
statusOrder status.Possible values:
- PAYED – paid,
- CREATED – created,
- REJECTED – rejected.
billAmountAmount of the payment. The decimal separator is the dot symbol "."
billNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
payeeName
authCodeBank authorization code (added if the order is paid)
commissionThe value of the commission from payment
pdfUrlIt remains empty
payeeIdA unique identifier of the Online Store
payDateDate of payment
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
cardMaskCard mask
errorMessageError message
errorCodeError 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:

ParameterDescription
statusOrder status.Possible values:
- PAYED – paid,
- CREATED – created,
- REJECTED – rejected.
shopbillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
descriptionComment to the order / description of payment details. Maximum length is 250 symbols
pdfUrlLink to receipt
authCodeBank authorization code (added if the order is paid)
isNeed3DS3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required
actionMPIThe card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
idID 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:

ParameterDescription
CodeError code
MessageError message
idID 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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
credentialsRequired authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptionsYes
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)No
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
preauthFlagPayment 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
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1Service field. Filled at company's discretionNo
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No
  1. 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".
ParameterDescriptionRequired
tokenPayment by Token (if this option is enabled, other methods are not displayed)Yes
  1. 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).

  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenToken valueYes
cardMaskCard maskYes
otherPaymentMethodsAllows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable)No
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
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:

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

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

  2. 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").

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

  1. paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
ParameterDescriptionRequired
createtokenonlyTo create a Token, set the value to "Y" for this parameterYes
  1. 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).

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order / payment details)No
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the payment (to receive the Token the value should be set to 1 UAH)Yes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute2-4Service fields. Filled at company’s discretionNo
  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageMandatory value is "Y"
tokenToken valueLeave empty
cardMaskCard maskLeave empty
otherPaymentMethodsAllows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable)Mandatory value is "N"
sellerTokenRecipient’s Card TokenLeave empty
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressE-mail address of the payerNo
  1. 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKCard mask
ATTRIBUTE1Service field. Filled at company's discretion
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment 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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionRecipient’s Card maskYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
  1. 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".
ParameterDescriptionRequired
cardPayment by CardNo
portmonePayment via Portmone.com walletNo
tokenPayment by Token (if this option is enabled, other methods are not displayed)No
clicktopayPayment using Click to PayNo
  1. 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).

  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenSender’s card Token valueYes
cardMaskSender’s card maskYes
otherPaymentMethodsAllows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)No
sellerTokenRecipient’s card TokenYes
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
  1. 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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
checkParamsThe value should be set to "Y" for this parameterYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionRecipient’s card numberNo
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
  1. paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
ParameterDescriptionRequired
tokenTransfer from Token to CardYes
  1. 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).

  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenSender’s card Token valueYes
cardMaskSender’s card maskYes
otherPaymentMethodsAllows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)Yes
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
  1. 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKSender's card mask
ATTRIBUTE1Service field.
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONRecipient’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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
checkParamsThe value should be set to "N" for this parameterYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
billCurrencyCurrency of the payment. Default value: UAHNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute2Service field. Filled at company's discretionNo
attribute3Service field. Filled at company's discretionNo
attribute4Service field. Filled at company's discretionNo
  1. paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
ParameterDescriptionRequired
tokenTransfer from Token to accountYes
  1. 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).

  1. token – settings to work with a Token
ParameterDescriptionRequired
tokenFlagEnables 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 pageNo
tokenSender’s card Token valueYes
cardMaskSender’s card maskYes
otherPaymentMethodsAllows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable)Yes
  1. payer – this block describes payer settings
ParameterDescriptionRequired
langPayment page interface language. Possible values: uk – Ukrainian, en – EnglishNo
emailAddressEmail address of the payerNo
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
  1. 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKSender’s card mask
ATTRIBUTE1Service field.
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONComment 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:

ParameterDescription
methodRequired parameter to call the procedure for transferring funds from the account to recipient's Card Token. Value: confirmp2p
loginThe Online Store login
passwordThe Online Store password
shopBillIdOrder 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")
tokenRecipient's card Token, for which funds should be credited
idID 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:

ParameterDescription
SHOPBILLIDA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
SHOPORDERNUMBERNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
APPROVALCODEAuthorization code
BILL_AMOUNTTransaction amount sent in request
TOKENToken value for subsequent payments
RESULTThe result of the operation (if successful = 0)
CARD_MASKSender’s card mask
ATTRIBUTE1Service field.
ATTRIBUTE2Service field. Filled at company's discretion
ATTRIBUTE3Service field. Filled at company's discretion
ATTRIBUTE4Service field. Filled at company's discretion
RECEIPT_URLLink to get a receipt
LANGPayment system interface language. Possible values: uk – Ukrainian, en – English
DESCRIPTIONRecipient'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:

ParameterDescriptionRequired
methodValue: preauthYes
loginThe Online Store loginYes
passwordThe Online Store passwordYes
actionThe identifier of the action that must be performed for this order – confirmation of the funds blocking (possibly with the amount change). Value: set_paidYes
shop_bill_idNumber 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_amountAmount of payment. Sent if action = set_paid. It cannot exceed the amount for which pre-authorization was carried out
encodingEncodingNo
langError messages languageNo

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:

ParameterDescriptionRequired
methodValue: confirmPreauthYes
loginThe Online Store login to access account managementYes
passwordThe Online Store passwordYes
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbolsNo
shopbillIdOrder ID in the Portmone.com system. Optional parameterNo
postauthAmountAmount of payment. It cannot exceed the amount for which pre-authorization was carried outYes
distributionDistribution of pre-authorization. Provides an opportunity to confirm a smaller number of recipients than was the case when requesting payment (clause 7 of split payment)Yes
idID of the request from the Online Store to the Portmone.com systemYes

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:

ParameterDescription
shop_bill_idOrder ID in the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Online Store. Maximum length is 120 symbols
descriptionOrder description
bill_dateBill date
pay_datePayment date
pay_order_dateBank memorial order date
bill_amountBill amount
auth_codeBank authorization code
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
error_codeError code
error_messageError 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:

ParameterDescription
methodRequired parameter to call the post-authorization procedure. Value: preauth
loginThe Online Store login
passwordThe Online Store password
actionThe identifier of the action that must be performed for this order – rejection of the funds blocking. Value: reject
shop_bill_idOrder number in the Portmone.com system (should be obtained using the result method described in section 8.2. "Authorization results request")
encodingEncoding
langError 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:

ParameterDescription
shop_bill_idOrder ID in the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Online Store. Maximum length is 120 symbols
descriptionOrder description
bill_dateBill date
pay_datePayment date
pay_order_dateBank memorial order date
bill_amountBill amount
auth_codeBank authorization code
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
error_codeError code
error_messageError 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:

ParameterDescription
methodRequired parameter to call the cancellation of payment with pre-authorization procedure. Value: rejectPreauth
loginThe Online Store login
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
shopbillIdOrder ID in the Portmone.com system. Optional parameter
idID 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:

ParameterDescription
shop_bill_idOrder ID in the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Online Store. Maximum length is 120 symbols
descriptionOrder description
bill_amountBill amount
statusOrder status
bank_idname of bank
terminal_idterminal id in the bank
merchant_idmerchant id in the bank
rrnidentificator of transaction in banks system
auth_codeBank authorization code
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
error_codeError code
error_messageError 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:

  1. Each of the recipient companies registers in the Portmone.com system.

  2. The Client makes an order on the Main Company's website.

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

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

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: result
payee_idA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
loginThe Online Store login to access account management
passwordThe Online Store password
shop_order_numberNumber of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
statusStatus 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_dateStart date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_dateEnd 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:

ParameterDescription
shop_bill_idOrder ID in the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Online Store
descriptionOrder description
bill_dateBill date
pay_datePayment date
bill_amountBill amount
auth_codeBank authorization code (added if the order is paid)
statusOrder status
error_codeError code
error_messageError 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:

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: result
loginThe Online Store login to access account management
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
shopbillIdOrder ID in the Portmone.com system. Optional parameter
statusStatus 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_dateStart date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_dateEnd date of the report in dd.mm.yyyy format. By default, it’s the current date
idId 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:

ParameterDescription
payeeIdA unique identifier of the Online Store
descriptionOrder description
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
attribute5shows payment splitting
distribution_payee_idshows payment splitting
commissionThe value of the refunded commission from payment
bank_idname of bank
terminal_idterminal id in the bank
merchant_idmerchant id in the bank
rrnidentificator of transaction in banks system
pay_datePayment date
payee_export_dateDate of sending the payment amount / payment notification to the Partner
payee_export_flagWith successful payment takes the value Y
chargebackWhether the chargeback was claimed for transaction or not
payee_nameName of the merchant
payee_commissionCommissar from the merchant
pay_order_dateBank memorial order date
pay_order_numberAccount number
pay_order_amountBill amount
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code (added if the order is paid)
cardMaskPayer’s Card mask
cardBankNameName of the issuing bank
tokenToken value for subsequent payments
payeeExportResultDescription of the error
gateTypePayment method identifier
cardTypeNameThe 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:

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: result
loginThe Online Store login to access account management
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
shopbillIdOrder ID in the Portmone.com system. Optional parameter
statusStatus 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_dateStart date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_dateEnd date of the report in dd.mm.yyyy format. By default, it’s the current date
idId 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:

ParameterDescription
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
descriptionOrder description
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
commissionThe value of the refunded commission from payment
bank_idname of bank
terminal_idterminal id in the bank
merchant_idmerchant id in the bank
rrnidentificator of transaction in banks system
pay_datePayment date
payee_export_dateDate of sending the payment amount / payment notification to the Partner
pay_order_dateBank memorial order date
chargebackWhether the chargeback was claimed for transaction or not
payee_commissionCommissar from the merchant
payee_nameName of the merchant
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code (added if the order is paid)
cardMaskPayer’s Card mask
tokenToken value for subsequent payments
gateTypePayment method identifier

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

Examples:

See "8.3 BILLS message example".

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

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 nameData typeDescription
ERROR_CODENUMBER(15,0)Error code (0 in case if message processing is successful)
REASONCHAR(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:

  1. 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");
  2. 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:

ParameterDescription
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order / description of payment details
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
statusOrder status. Possible values: PAYED, PREAUTH, REJECTED, CREATED
tokenToken value for subsequent payments
authCodeBank authorization code
receiptUrlAn empty value
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
errorCodeError code
errorError description
notificationTypeNotification status
cardTypeCard type
bank_nameName of the acquiring bank
terminal_idAcquire terminal number
merchant_idTerminal name
rrnTransaction 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:

ParameterDescription
errorCodeError code
reasonError description. Set it "OK" if error not occurred
responseIdRandomly 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 грн.

Description:

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:

ParameterDescription
loginThe Online Store login to access account management
passwordThe Online Store password
shopOrderNumberNumber of an order (bill) in the Online Store system
idID 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.

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:

No restrictions.

Request structure:

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

Request parameters description:

ParameterDescription
methodRequired parameter to call the return procedure. Value: return
loginThe Online Store login
passwordThe Online Store password
shop_bill_idOrder number in the Portmone.com system (should be obtained using the result method described in section 8.2 "Authorization results request")
return_amountRefund amount. Partial and full refund is possible
attribute1Additional optional parameter
attribute5It is used when splitting the payment
encodingEncoding
langError message language

Response structure:

Please, refer to "9.1 POST refund response (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 "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:

No restrictions.

Request structure:

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

Request parameters description:

ParameterDescription
loginThe Online Store login to access account management
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
shopbillIdOrder ID in the Portmone.com system. Optional parameter
returnAmountRefund amount. Partial and full refund is possible
attribute5It is used when splitting the payment
messageComment 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:

ParameterDescription
descriptionOrder description
statusOrder status
bank_idcode the bank
terminal_idterminal id in the bank
merchant_idmerchant id in the bank
rrnidentificator of transaction in banks system
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
attribute5It is used when splitting the payment
commissionThe value of the refunded commission from payment
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Online Store. Maximum length is 120 symbols
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code
cardMaskCard mask
tokenToken value
gateTypePayment 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:

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: reject
loginThe Online Store login to access account management
passwordThe Online Store password
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbols
shopbillIdOrder ID in the Portmone.com system. Optional parameter
returnAmountRefund amount. Partial and full refund is possible
attribute5It is used when splitting the payment
messageComment 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:

ParameterDescription
descriptionOrder description
statusOrder status
bank_idcode the bank
terminal_idterminal id in the bank
merchant_idmerchant id in the bank
rrnidentificator of transaction in banks system
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
commissionThe value of the refunded commission from payment
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Online Store. Maximum length is 120 symbols
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code
cardMaskCard mask
tokenToken value
gateTypePayment 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:

ParameterDescriptionRequired
loginThe Online Store login to access account managementYes
passwordThe Online Store passwordYes
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbolsNo
namePayerName of the ClientNo
commentPayment commentNo
amountAmount of the paymentYes
emailRecipientE-mail address of the ClientYes
langE-mail languageNo
cc_emailE-mail address to which a copy of the invoice will be sentNo
preauth_flagPayment 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_currencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZTNo
expDateDate 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
attribute5Used 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:

ParameterDescriptionRequired
loginThe Online Store login to access account managementYes
passwordThe Online Store passwordYes
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbolsNo
namePayerName of the ClientNo
commentPayment commentNo
amountAmount of the paymentYes
phoneRecipientNumber of the Client’s mobile phoneYes
langSMS languageNo
preauth_flagPayment 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_currencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT)No
expDateDate 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
attribute5Used 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 blockParameterDescriptionRequired
1Name of a recipientName of the Client that will be displayed in the received invoiceYes
2Recipient’s e-mail or mobile phoneClient’s e-mail address or mobile phone number. Mobile number should be in the "+380ХХХХХХХХХ" formatYes
3Order numberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbolsYes
4Payment detailsComment to the order / description of payment detailsYes
5AmountAmount of the paymentYes
6CurrencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZTNo
7Pre-authorizationPayment 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
8Invoice languageThe language of the e-mail or SMS. Possible values: uk – Ukrainian, en – English. If the parameter is not sent, the invoice is issued in UkrainianNo
9Invoice validity timeDate 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.

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:

ParameterDescriptionRequired
loginThe Online Store login to access account managementYes
passwordThe Online Store passwordYes
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
amountAmount of the paymentYes
shopOrderNumberNumber of an order (bill) in the Online Store system. Maximum length is 120 symbolsNo
emailRecipientE-mail address of the ClientNo
commentPayment commentNo
preauth_flagPayment 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_currencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZTNo
expDateDate 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
attribute1Service field. Filled at company’s discretionNo
attribute2Service field. Filled at company’s discretionNo
attribute3Service field. Filled at company’s discretionNo
attribute4Service field. Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No

Response structure:

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

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:

  1. payee – this block is required for partner identification
ParameterDescriptionRequired
payeeIdA unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com systemYes
loginCompany’s login. Used to verify a signature (required if the signature parameter is sent)No
dtRequest creation time. Used to verify a signature (required if the signature parameter is sent)No
signatureSignature of the requestNo
shopSiteIdDigital identifier of a sales channelNo
  1. order – this block contains the order data
ParameterDescriptionRequired
descriptionPayment description (comment to the order/ payment details)No
shopOrderNumberNumber of a paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
successUrlThe URL of the Online Store to which the client will be redirected after a successful paymentNo
failureUrlThe URL of the Online Store to which the client will be redirected in case of payment rejectionNo
preauthFlagPayment 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
billCurrencyCurrency of the payment. Default value: UAHNo
expTimeSets 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 paidNo
encodingEncoding (encodes the request text from the set encoding to UTF-8)No
attribute1Service field. Filled at company’s discretionNo
attribute2Service field. Filled at company’s discretionNo
attribute3Service field. Filled at company’s discretionNo
attribute4Service field. Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section 7 "Splitting the payment")No
  1. 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".
ParameterDescriptionRequired
cardPayment by CardNo
portmonePayment via Portmone.com walletNo
tokenPayment by Token (if this option is enabled, other methods are not displayed)No
clicktopayPayment using Visa Click to PayNo
privatPayment via LiqPay, with choosing a card from the Privat24 Internet Banking
Pay attention! Pre-authorization functionality does not work when paying via Privat24
No
gpayPayment via Google Pay, with choosing a card from previously stored in the Google Pay accountNo
createtokenonlyCreates 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
applepayPayment via Apple Pay, with choosing a card from previously stored in the Apple Pay accountNo

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 | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | :------: | --- | | login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | 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 | Yes | = |

Response structure:

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

Response parameters description:

ParameterDescription
descriptionOrder description
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
commissionThe value of the refunded commission from payment
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code (added if the order is paid)
cardMaskPayer’s Card mask
tokenToken value for subsequent payments
gateTypePayment 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:

ParameterDescriptionRequired
paymentTypeMust be set "a2c_1" valueYes
descriptionrecipient's card numberYes
attribute1Service field (for additional order information). Set empty valueNo
attribute2Service field (for additional order information). The information about tax for transfer on a cardNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
billAmountAmount of the paymentYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
cvvVerifyFlagThe default is "Y", set "N" for payments without CVV2No
tokenSet empty valueNo
billCurrencyCurrency of the payment. Default value: UAHNo
shopSiteIdDigital identifier of a sales channelNo
cardDataEncrypted value of payment card data (card number, expiration month, expiration year, CVV2)No
dtRequest creation time. Used to verify the signature. Should be sent in the following format:yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1101" for synchronous modeYes

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:

ParameterDescription
statusOrder status. Possible values: REJECTED, PAYED
errorCodeError code
errorError description
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
billAmountTransaction amount sent in request
billNumberNumber of paid order (bill) in the Partner’s system
attribute1Service field (for additional order information). Set empty value
attribute2Service field (for additional order information). The information about tax for transfer on a card
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
authCodeBank authorization code (added if the order is paid)
payeeExportFlagTransaction status in the acquiring bank (Y – successful, E – error, N or empty value – not sent)
receiptLinkLink to get a receipt
billCurrencyCurrency of the payment
transactionIdTransaction 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.

13.2 Transfer of funds from account to card token

Description: To get card token you can use paragraph 4.1 of documentation

** Important! ** Do not fill the description parameter when send request to get a token and request a transfer.

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.2 Request to transfer funds from account to card" to study the request structure.

Request parameters description:

ParameterDescriptionRequired
paymentTypeMust be set "a2t_1» valueYes
descriptionSet empty valueYes
attribute1Service field (for additional order information). Set empty valueNo
attribute2Service field (for additional order information). The information about tax for transfer on a card tokenNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
billAmountAmount of the paymentYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
cvvVerifyFlagThe default is "Y", set "N" for payments without CVV2No
tokenSet empty valueNo
billCurrencyCurrency of the payment. Default value: UAHNo
shopSiteIdDigital identifier of a sales channelNo
cardDataEncrypted value of payment card data (card number, expiration month, expiration year, CVV2)No
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1101" for synchronous modeYes

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:

OptionDescriptionRequired
client_idRecipient's nameYes
IncomeThe amount of income tax in coinsYes
SocialThe amount of SSC in coinsYes
militaryThe amount of military tax in coinsYes
tax_idTIN of the recipient of fundsYes

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

Response structure:

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

Response parameters description:

ParameterDescription
statusOrder status. Possible values: REJECTED, PAYED
errorCodeError code
errorError description
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
billAmountTransaction amount sent in request
billNumberNumber of paid order (bill) in the Partner’s system
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). The information about tax for transfer on a card token
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
authCodeBank authorization code (added if the order is paid)
payeeExportFlagTransaction status in the acquiring bank (Y – successful, E – error, N or empty value – not sent)
receiptLinkLink to get a receipt
billCurrencyCurrency of the payment
transactionIdTransaction 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.

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" />
</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.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",
"qr":"Y",
},
"priorityPaymentTypes":
{
"card":"4",
"portmone":"2",
"qr":"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",
"qr":"N"
},
"priorityPaymentTypes":
{
"card":"0",
"portmone":"0",
"qr":"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",
"qr":"Y"
},
"priorityPaymentTypes":
{
"card":"1",
"portmone":"2",
"qr":"5",
"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": "183438343839383831391286A60BED7182634F41FC3DFC64D1713959E1B0DA3C05C7F18B6F474535FC554F02B78AD6C1F051616907E2F5D6E624B6746A163FFC64EF050B4907201AFA3D1CD"
}
},
"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",
"distribution": "Товар 2 70749:70749;3;"
}
},
"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='windows-1251'?>
<portmoneresult lang='uk'>
<request>
<payee_id><![CDATA[1185]]></payee_id>
<shop_order_number><![CDATA[%]]></shop_order_number>
<status><![CDATA[PAYED]]></status>
<start_date><![CDATA[20.02.2009]]></start_date>
<end_date><![CDATA[20.03.2009]]></end_date>
</request>
<orders type='list' >

<order>
<shop_bill_id>7914993</shop_bill_id>
<shop_order_number><![CDATA[1234]]></shop_order_number>
<description><![CDATA[Payment of order №1234]]></description>
<bill_date>19.03.2009</bill_date>
<pay_date>19.03.2009 22:21:51</pay_date>
<bill_amount>10</bill_amount>
<auth_code>123456</auth_code>
<status>PAYED</status>
<error_code>000</error_code>
<error_message><![CDATA[]]></error_message>
</order>

</orders>

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>
</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.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://portmone2.com/r3/services/receipts/get-receipts/shop-bill-id/3534eff61c20da00195e14a557af25fa9cfb08110cb138958850437dfdff387dcb5ab971e4d45a9430381ee29796e8f6406ec548ad3a67d6ba31071f999a3264"
},
"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

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

9.2 Формат відповіді

[
{
"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": ""
}
]

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"
}
},
"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": "5168742215175179",
"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"
}

13.2 Request to transfer of funds from account to card token

{
"description": "test",
"paymentType": "a2t_1",
"attribute1": "",
"attribute2": "\"client_id\":\"Іванов Іван\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
"attribute3": "3",
"attribute4": "4",
"billAmount": "1",
"payeeId": "18875",
"shopOrderNumber": "SHP-1445284353-20201020025708",
"cvvVerifyFlag": "Y",
"billCurrency": "UAH",
"mode": "1101",
"cardData": "",
"dt": "20201020145708",
"signature": "193955BF02ED0B08D42F8819D4127EB48056B3109AB68DE074A4568BD55AAECB",
"token": "18373333393634343931096442C3FD3DA5C78E03FF93B95339EDA2AA690C6E1FD63C113A431349F33C152E44EA98082AEEF72122638264BF65F9A38"
}

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

{
"status": "PAYED",
"errorCode": "0",
"error": "",
"shopBillId": "866480371",
"billAmount": "1",
"shopOrderNumber": "464354715",
"attribute1": "70456009",
"attribute2": "\"client_id\":\"Ivanov Ivan\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
"attribute3": null,
"attribute4": "4",
"authCode": "000000",
"payeeExportFlag": "N",
"receiptLink": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3535cc3cd0f108cbcbce4967d6501411807b39b0e068fb26a93147adfcc15cf7d5c78d9ab343063e01b82dc7ecb14809772100682ef57b2782095b38c27a03e0ab",
"billCurrency": "UAH",
"transactionId": null
}