Portmone API Gateway for Partners with PCI DSS level

Glossary

Term	Definition
Merchant, Partner	Organisation which has signed a payment acceptance agreement with Portmone.com
Client, Customer	A person who visits the Merchant's web site in order to learn about the range of goods (services) and to make a purchase
Card, Payment Card	Payment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
Authorization	The process of giving access rights or other powers to the Customer, program or process
Recurring Payments	Automatic payments (no participation of the client and re-entering card details required), which are carried out with the consent of the client
Token	A unique digital identifier of a card, which is generated during the first operation and then used for quick payment. Token can only be used to repeat a similar transaction as at the first payment
SHOPBILLID	A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
CVV2/CVC2	CVV2 (Card Verification Value 2) is a three-digit card security code that helps verify legitimacy of a Visa payment card. The Mastercard payment system has similar card security code called CVC2 (Card Validation Code 2)
Acquiring Bank (Acquirer)	A bank that organizes banking cards acceptance points (terminals, ATM’s) and processes full range of financial operations connected with performing bank settlements and payments by banking cards at that points
Issuing Bank (Issuer)	A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards
3-D Secure	3-D Secure is a protocol which used to secure handling of online bank card payments
PSP	PSP (Payment Service Provider) is a company that provides merchants with online services for accepting electronic payments by various payment methods. For this document this term refers to Portmone.com company
ACS	ACS (Access Control Server) is a tool used by card issuing banks to cardholder authentication (allow customers to verify their identity and offer a more secure transaction to the online merchants)
Client-Side Encryption (CSE)	Client-side encryption is a data protection technique in which information is encrypted on the Client's side using PSP provided Public key before being transmitted to a Merchant’s server. Encrypted data can’t be decrypted on Merchant’s side
IPS	International Payment System

1. Introduction

Portmone Gateway API based on transparent type of integration with "Client-Side Encryption" (CSE) solution. CSE allows to reduce PCI DSS burden for merchant.

Cardholder data is encrypted on client side, so it cannot be read, and then passed to Portmone host. To decrypt the message from merchant’s side the unique client key is used.

Type of communication: host-to-host.

Type of protocol: HTTPS.

Type of messages to exchange the information: XML-messages or JSON notifications.

2. Preconditions

To get started with the API, you need:

• to have a PCI DSS certificate;
• apply for registration in the Portmone.com system;
• provide the URL-address for notifications (URL which will be used by Portmone.com system to send XML-messages by POST method via data parameter or notification in JSON format);
• to append the rsa-co.min.js script on the payment page to use CSE solution.

The next parameters will be provided to the Merchant by Portmone.com after registration:

• payee id;
• login;
• password.

Endpoints

For payment by card or by token the following endpoint is used: https://www.portmone.com.ua/r3/pm/.

Endpoint for requests after the 3DS authorization: https://www.portmone.com.ua/r3/pm-mpi/.

2.1. Card data

To encrypt card data use rsa-co.min.js script. Methods of rsa-co.min.js should be called from PM object.

This script contained next methods:

PM.setPublicKey(publicKey) – sets the value of the public key;

PM.encrypt(cardData) – returns an object with encrypted bank card data;

cardData – object with necessary fields that describe card data, like:

{
    "cardNumber":"4444333322221111",
    "mm":"03",
    "yy":"20",
    "cvv2":"111"
}

<script type="text/javascript"
    src="https://www.portmone.com.ua/r3/resources/services/js/lib/rsa-co.min.js">
</script>
<script type="text/javascript">
(function() {
    PM.setPublicKey('key_value');

  function encryptMyData() {
      var postData = {};
      var cardData = {
          cardNumber : cardNumber,
          mm : mm,
          yy : yy,
          cvv2 : cvv2
      };
      postData['encrypted-data'] = PM.encrypt(cardData);
      // AJAX call or different handling of the post data.
    }
})();
</script>

2.2. 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));

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.

2.3. Asynchronous mode

In case when you are using parameter mode which set in 1111 value in your payment request, you will receive data with format and structure as follows on your notification URL:

Successful response:

{
    "transactionId": "419344443",
    "attemptId": "9m304ghzzl0k8c4cko08soww0sokcws",
    "errorCode": "0",
    "error": ""
}

Parameters description:

Parameter	Description
transactionId	ID of the transaction in the Portmone.com system
attemptId	Request id which initiate payment by card. Randomly generated value, length 31 character (for example, 3wlk66m64q0wokcgkwog4040osw04ks)
errorCode	Error code (0 if payment was successful)
error	Error description

Then, if error not occurred, on URL for the notifications will come the request with structure described in section 9.3 “Notification in JSON format”.

3. Payment methods

3.1. Payment by card

3.1.1. Create new payment

Description:

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

Availability and restrictions:

Portmone.com doesn’t support cross-origin requests (CORS requests). It means that request should be sent from your server only.

Request structure:

Please, refer to "3.1.1 Payment by card request" to study the request structure.

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "card" value	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Payment description (comment to the order/ payment details)	Yes
token	Set empty value	No
cardData	Encrypted value of payment card data (card number, expiration month, expiration year, CVV2)	Yes
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 5 "Reject/Confirm preauth payment"), value "N" is a regular payment without pre-authorization. The default is "N")	No
cvvVerifyFlag	The default is "Y", set "N" for payments without CVV2	No
clientId	Set empty value	No
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)	No
lang	Payment system interface language: uk – Ukrainian, en – English,az – Azerbaijani, kz – Kazakh	No

Response structure:

Please, refer to "3.1.1 Payment by card response" to study the response structure.

Response parameters description:

Parameter	Description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order/ description of payment details
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
authCode	Bank authorization code (added if the order is paid)
status	Order status. Possible values: PAYED, PREAUTH, REJECTED, CREATED
token	Token value for subsequent payments
MD	Parameter which should be sent to acsUrl for 3D Secure check
PaReq	Parameter which should be sent to acsUrl for 3D Secure check
is3DS	3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
acsUrl	The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCode	Error code (0 if payment was successful)
error	Error description

3.1.2. Redirect to ACS

To proceed with 3DS verification Client should be redirected to the Issuing Bank website. To do so Partner should create a form and send it by POST method to Client’s browser.

Example:

var f = document.createElement("form");
f.setAttribute('method',"POST");
f.setAttribute('action',response.acsUrl);
var i = document.createElement("input");
i.setAttribute('type',"hidden");
i.setAttribute('name',"MD");
i.setAttribute('value',response.MD);
var i1 = document.createElement("input");
i1.setAttribute('type',"hidden");
i1.setAttribute('name',"TermUrl");
i1.setAttribute('value',TermUrl);
var i2 = document.createElement("input");
i2.setAttribute('type',"hidden");
i2.setAttribute('name',"PaReq");
i2.setAttribute('value',response.PaReq);
f.appendChild(i);
f.appendChild(i1);
f.appendChild(i2);
document.body.appendChild(f);
f.submit();

where acsUrl, MD, PaReq – values received in PSP response, TermUrl – your result URL to return from the bank page.

As soon as 3DS-check is passed and Client is returned on TermUrl link, Complete Payment Request to PSP should be sent (see section 3.1.3 "Complete payment").

3.1.3. Complete payment

Description:

To complete a payment you should send a request to the following URL: https://www.portmone.com.ua/r3/pm-mpi/.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "3.1.3 Complete payment request" to study the request structure.

Request parameters description:

Parameter	Description	Required
id	Order ID in the Portmone.com system	Yes
PaRes	The PaRes value received from the bank to your URL	Yes
MD	The MD value received from the bank to your URL	Yes

Response structure:

Please, refer to "3.1.3 Complete payment response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order / description of payment details
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
authCode	Bank authorization code (added if the order is paid)
status	Order status
receiptUrl	Link to get a receipt
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCode	Error code (0 if payment was successful)
error	Error description
is3DS	3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)

3.2. Create Token

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 UAH 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/r3/pm/.

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 "3.2 createToken request" to study the request structure.

Request parameters description:

Parameter	Description	Required
paymentType	To create a Token, you must set the value to "createToken" for this parameter	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel. Set empty value	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Payment description (comment to the order /payment details)	Required, identifies the Token in subsequent payments
token	Set empty value	No
cardData	Encrypted value of payment card data (card number, expiration month, expiration year, CVV2)	Yes
preauthFlag	Payment pre-authorization flag. Set empty value	No
cvvVerifyFlag	The default is "Y", set "N" if need operation without CVV2	No
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)	No

Response structure:

Please, refer to "3.2 createToken response" to study the response structure.

Response parameters description:

Parameter	Description
is3DS	3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order / description of payment details
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
status	Order status
token	Token value for subsequent payments
authCode	Bank authorization code (added if the order is paid)
mpiFlag	3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCode	Error code (0 if payment was successful)
error	Error description

3.3. Payment by Token

Description:

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

Availability and restrictions:

The description field should be the same as in initial payment (see section 3.2 "Create Token").

Request structure:

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

Request parameters description:

Parameter	Description	Required
paymentType	Set the value to "token" for this parameter	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Payment description (comment to the order /payment details)	Yes
token	Set Token value	Yes
cardData	Encrypted value of CVV2	Yes
preauthFlag	Payment pre-authorization flag (the value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 5 "Reject/Confirm preauth payment"), the value "N" is a regular payment without pre-authorization. The default is "N")	No
cvvVerifyFlag	The default is "Y", set "N" if need operation without CVV2	No
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)	No

Response structure:

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

Response parameters description:

Parameter	Description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order /description of payment details
authCode	Bank authorization code
receiptUrl	Link to get a receipt
token	Token value
mpiFlag	Return "N"
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
status	PAYED – successful transaction, PREAUTH – successful transaction with pre-authorization
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCode	Error code (0 if payment was successful)

3.4. Payment by Token without CVV2 (recurring payment)

Description:

To make a recurring payment 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 "3.4 Recurring payment request" to study the request structure.

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "recurrent" value	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Comment to the order/ description of payment details (should be the same as in initial payment)	Yes
token	Set Token value	Yes
cardData	Set empty value	No
preauthFlag	Payment pre-authorization flag (the value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 5 "Reject/Confirm preauth payment"), the value "N" is a regular payment without pre-authorization. The default is "N")	No
cvvVerifyFlag	Set "N" if need operation without CVV2	Yes
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No
attribute5	Used to send the split parameters of the payment (see section "Splitting the payment" for details)	No

3.5. Processing payment by MPS token

3.5.1. Processing payment with 3D Secure authentication

Description:

To process a payment using an MPS Token, you must send a request to the following URL: https://www.portmone.com.ua/r3/pm/.

Availability and restrictions:

Available for synchronous and asynchronous modes (corresponding mode values 1101 and 1111).

Request structure:

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "ips_token" value	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Partner’s system	No
billAmount	Amount of the payment	Yes
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Comment to the order/ description of payment details (should be the same as in initial payment)	Yes
token	Set Token value	Yes
cardData	Payment data	Yes
cardNumber	Card number	Yes
mm	Card expiry (month)	Yes
yy	Card expiry (year)	Yes
cvv2	Cryptogram	Yes
ipsTokenType	MPS identifier: MasterCard M4M, Visa VTS	Yes
cvvVerifyFlag	Set "N" if need operation without CVV2	Yes
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No

Example of a request:

{
    "description": "test",
    "paymentType": "ips_token",
    "billAmount": "1.1",
    "billCurrency": "UAH",
    "payeeId": "1185",
    "shopOrderNumber": "1424371175",
    "cvvVerifyFlag": "N",
    "token": "<MPS_TOKEN>",
    "cardData": {
        "cardNumber": "5622734587535180",
        "mm": "08",
        "yy": "28",
        "cvv2": "AIL3Y/7Yh7r1AIKьssPUAAADFA==",
        "ipsTokenType": "M4M"
    },
    "dt": "20251002170015",
    "signature": "652431DD041F8B4B5CDD384B1C33BA5776E39DF45095CBCC5692BE2E8BE5B98F",
    "mode": "1101"
}

Response structure:

Examples of responses and their analysis are described in «3.1. Payment by card»

3.5.2. Processing a recurring payment using an MPS Token

Description:

To process a payment using an MPS Token without CVV2, you must send a request to the following URL: https://www.portmone.com.ua/r3/pm/.

Availability and restrictions:

Available for synchronous and asynchronous modes (corresponding mode values 1101 and 1111).

Request structure:

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "ips_token_recurrent" value	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Partner’s system	No
billAmount	Amount of the payment	Yes
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Comment to the order/ description of payment details (should be the same as in initial payment)	Yes
token	Set Token value	Yes
cardData	Payment data	Yes
cardNumber	Card number	Yes
mm	Card expiry (month)	Yes
yy	Card expiry (year)	Yes
cvv2	Cryptogram	Yes
ipsTokenType	MPS identifier: MasterCard M4M, Visa VTS	Yes
cvvVerifyFlag	Set "N" if need operation without CVV2	Yes
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No

Example of a request:

{
    "description": "test",
    "paymentType": "ips_token",
    "billAmount": "1.1",
    "billCurrency": "UAH",
    "payeeId": "1185",
    "shopOrderNumber": "1424371175",
    "cvvVerifyFlag": "N",
    "token": "<MPS_TOKEN>",
    "cardData": {
        "cardNumber": "4322734587535180",
        "mm": "08",
        "yy": "28",
        "cvv2": "AIL3Y/7Yh7r1AIKьssPUAAADFA==",
        "ipsTokenType": "VTS"
    },
    "dt": "20251002170015",
    "signature": "652431DD041F8B4B5CDD384B1C33BA5776E39DF45095CBCC5692BE2E8BE5B98F",
    "mode": "1101"
}

4. Payment via Privat24

4.1. Payment by card

Description:

To make a transaction through the Privat24 system you should send a request to the following URL: https://www.portmone.com.ua/r3/secure/gate/liq-pay.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.1 Payment by card request" to study the request structure.

Request parameters description:

Parameter	Description	Required
payee_Id	A unique identifier of the Partner	Yes
shop_order_number	Number of paid order (bill) in the Partner’s system	No
bill_amount	Amount of the order. Currency – hryvnia (UAH)	Yes
description	Comment to the order / description of payment details	Yes
lang	Privat24 system interface language. Possible values: en – English, uk – Ukrainian	Yes
encoding	Encoding	Yes
success_url	The Merchant URL address to which the client will be redirected after a successful payment	Yes
failure_url	The Merchant URL address to which the client will be redirected in case of payment rejection	Yes

4.2. Create Token

Description:

To create a Token through the Privat24 system you should send a request to the following URL: https://www.portmone.com.ua/r3/secure/gate/liq-pay.

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "4.2 Create token request" to study the request structure.

Request parameters description:

Parameter	Description	Required
payee_Id	A unique identifier of the Partner	Yes
shop_order_number	Number of paid order (bill) in the Partner’s system	No
bill_amount	Amount of the order. Currency – hryvnia (UAH). Must be set "1" value	Yes
description	Comment to the order / description of payment details	Yes
success_url	The Merchant URL address to which the client will be redirected after a successful payment	Yes
failure_url	The Merchant URL address to which the client will be redirected in case of payment rejection	Yes
revert	"Y" – refund	Yes
lang	Privat24 system interface language. Possible values: en – English, uk – Ukrainian	Yes
encoding	Encoding	Yes

4.3. Payment by Token

Description:

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

Availability and restrictions:

No restrictions.

Request structure:

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

Request parameters description:

Parameter	Description	Required
paymentType	Set the value to "token" for this parameter	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Payment description (in case of payment by token description should be the same as in initial payment)	Yes
token	Set Token value	Yes
cardData	Encrypted value of CVV2	Yes
preauthFlag	Payment pre-authorization flag (the value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 5 "Reject/Confirm preauth payment"), the value "N" is a regular payment without pre-authorization. The default is "N")	No
cvvVerifyFlag	The default is "Y", set "N" if need operation without CVV2	No
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No

4.4. Payment by Token without CVV2 (recurring payment)

Description:

To make a recurring payment 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 "3.4 Recurring payment request" to study the request structure.

Request parameters description:

Parameter	Description	Required
paymentType	Must be set "recurrent" value	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
shopOrderNumber	Number of paid order (bill) in the Partner’s system	No
billAmount	Amount of the payment	Yes
emailAddress	Email address of the payer	No
shopSiteId	Digital identifier of a sales channel	No
billCurrency	Currency of the payment. Default value: UAH	No
description	Comment to the order/ description of payment details (should be the same as in initial payment)	Yes
token	Set Token value	Yes
cardData	Set empty value	No
preauthFlag	Payment pre-authorization flag (the value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 5 "Reject/Confirm preauth payment"), the value "N" is a regular payment without pre-authorization. The default is "N")	No
cvvVerifyFlag	Set "N" if need operation without CVV2	Yes
clientId	Set empty value	Yes
dt	Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"	Yes
mode	Set "1111" for asynchronous mode	No
attribute1	Service field (for additional order information). Filled at company’s discretion	No
attribute2	Service field (for additional order information). Filled at company’s discretion	No
attribute3	Service field (for additional order information). Filled at company’s discretion	No
attribute4	Service field (for additional order information). Filled at company’s discretion	No

5. Reject/Confirm preauth payment

5.1. Confirm preauth payment

Description:

To confirm preauth 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 "5.1 confirmPreauth request" to study the request structure.

Request parameters description:

Parameter	Description
login	The Partner login to access account management
password	The Partner password
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols
token	Set token value
postauthAmount	Amount of the payment. It can not be more than the amount for which pre-authorization was carried out
id	ID of the request from the Partner to the Portmone.com system

Response structure:

Please, refer to "5.1 confirmPreauth response" to study the response structure.

Response parameters description:

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

5.2.Reject preauth payment

Description:

If the transaction has status "PREAUTH" use this method to move the transaction to "REJECTED" status.

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

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "5.2 rejectPreauth request" to study the request structure.

Request parameters description:

Parameter	Description
method	Required parameter to call the cancellation of payment with pre-authorization procedure. Value: rejectPreauth
login	The Partner login to access account management
password	The Partner password
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
id	ID of the request from the Partner to the Portmone.com system

Response structure:

Please, refer to "5.2 rejectPreauth response (successful)" to study the response structure.

Response parameters description:

Parameter	Description
description	Order description
status	Order status
attribute1-4	Service fields (for additional order information)
commission	The value of the refunded commission from payment
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code (added if the order is paid)
cardMask	Payer’s Card mask
token	Token value

6. Receipt of payment token after payment

6.1. getToken

Description:

This method is used to obtain the Token by order number (shopOrderNumber).

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 "6.1 getToken request (example for PHP)" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	To obtain a Token, you must set the value to "getToken" for this parameter	Yes
login	The Partner login to access account management	Yes
password	The Partner password	Yes
shopOrderNumber	Number of paid order (bill) in the Partnet’s system. Maximum length is 120 symbols	Yes
id	ID of the request from the Partner to the Portmone.com system	Yes

Response structure:

Please, refer to "6.1 getToken response (tokenType: CARD)" and to "6.1 getToken response (tokenType: PRIVAT24)" to study the response structure.

Response parameters description:

Parameter	Description
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
billCurrency	Currency of the payment
token	Token value for subsequent payments
tokenType	CARD – in case of card payments, PRIVAT24 – in case of Privat24 payments
id	ID of the request from the Partner to the Portmone.com system

6.2. getTokens

Description:

This method is used to obtain all tokens by description (description).

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 "6.2 getTokens request (example for PHP)" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Must be set "getTokens" value	Yes
login	The Partner login to access account management	Yes
password	The Partner password	Yes
description	Payment description (comment to the order /payment details)	Yes
signature	Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature" and use fields from the example of signature below	Yes
dt	Request creation time. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)	Yes
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system	Yes
id	ID of the request from the Partner to the Portmone.com system	Yes

Example of signature [PHP]:

$strToSignature = $payeeId.$dt.bin2hex($clientId);
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));

Response structure:

Please, refer to "6.2 getTokens response to study the response structure.

Response parameters description:

Parameter	Description
cardMask	Payer’s Card mask
billAmount	Amount of the payment
billCurrency	Currency of the payment. Default value: UAH
token	Token value
tokenType	CARD – in case of card payments, PRIVAT24 – in case of Privat24 payments
id	ID of the request from the Partner to the Portmone.com system

6.3. Getting IPS data by Portmone token

Description:

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

Availability and restrictions:

Available after a card payment is made.

JSON request structure:

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

Request parameters description:

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

Response structure and example (Mastercard):

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

Response key parameters description:

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

Response structure and example (Visa):

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

Response key parameters description:

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

6.4. Getting an asset by the unique IPS ID

Description:

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

Availability and restrictions:

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

JSON request structure and example:

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

Request parameters description:

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

Response structure and example:

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

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

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

Request parameters description:

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

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

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

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

Response structure:

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

Response parameters description:

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

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

7.2 Transfer of funds from account to card token

Description: To get card token you can use paragraph 3.2 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 "7.2 Request to transfer funds from account to card" to study the request structure.

Request parameters description:

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

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

Description of query parameters:

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

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

Response structure:

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

Response parameters description:

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

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

8. Return

8.1 POST request

Description:

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

Request format: HTTPS POST

Availability and restrictions:

This method is available for transactions with status "PAYED" during 31 days after payment was made.

Request structure:

Please, refer to "8.1 POST return request" to study the request structure.

Request parameters description:

Parameter	Description	Required
method	Required parameter to call the return procedure. Value: return	Yes
login	The Partner login	Yes
password	The Partner password	Yes
shop_bill_id	Order number in the Portmone.com system (should be obtained using the result method described in section 9.1 "Authorization results request")	Yes
return_amount	Return amount	Yes
attribute1	Additional optional parameter	No
encoding	Encoding	Yes
lang	Error message language	Yes

Response structure:

Please, refer to "8.1 POST return response (successful)" to study the response structure.

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

Response parameters description:

Parameter	Description
method	Required parameter to call the return procedure. Value: return
login	The Partner login
password	The Partner password
shop_bill_id	Order number in the Portmone.com system
return_amount	Return amount
attribute1	Additional optional parameter
encoding	Encoding
lang	Error message language
shop_order_number	Number of an order (bill) in the Partner’s system. Maximum length is 120 symbols
description	Order description
bill_date	Bill date (date the order was created)
pay_date	Payment date (date the order was paid)
bill_amount	Bill amount to return
auth_code	Bank authorization code
status	Order status
error_code	Error code (0 if payment was successful)
error_message	Error message

8.2. JSON request

Description:

This method returns money by the transaction and it is better to call it the next day after the transaction. This method initiates new transaction in Portmone.com, which returns the money to the Client, and id of this transaction returns as shopBillId with status RETURN.

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

Availability and restrictions:

No restrictions.

Request structure:

Please, refer to "8.2 JSON return request" to study the request structure.

Request parameters description:

Parameter	Description
login	The Partner login to access account management
password	The Partner password
payeeId	A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Partner’s system. Maximum length is 120 symbols
returnAmount	Return amount
message	Return reason
id	ID of the request

Response structure:

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

Response parameters description:

Parameter	Description
description	Order description
status	Order status
attribute1-4	Service fields (for additional order information)
commission	The value of the refunded commission from the payment
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of an order (bill) in the Partner’s system. Maximum length is 120 symbols
billAmount	Bill amount
error_code	Error code
error_message	Error message
auth_code	Bank authorization code (added if the order is paid)
token	Token value
cardMask	Payer's Card mask

8.3. 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 "8.3 JSON refund request" to study the request structure.

Request parameters description:

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

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

Response structure:

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

Response parameters description:

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

9. Getting authorization results

Merchants can receive authorization results in several ways:

• when Client returns to Merchant’s website after payment;
• by sending XML-request to the Portmone.com system;
• by XML-message from the Portmone.com system to the Partner with the result of authorization (XML-notification of payment);
• by XML-message from the Portmone.com system to the Partner about a payment order (XML-notification of transactions financial coverage);
• by JSON-request from the Portmone.com system to the Partner.

9.1. Authorization results request

9.1.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 "9.1.1 POST authorization results request" to study the request structure.

Request parameters description:

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

Response structure:

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

Response parameters description:

Parameter	Description
shop_bill_id	Order ID in the Portmone.com system
shop_order_number	Number of paid order (bill) in the Partner's system
description	Order description
bill_date	Bill date
pay_date	Payment date
bill_amount	Bill amount
auth_code	Bank authorization code (added if the order is paid)
status	Order status
error_code	Error code
error_message	Error message

9.1.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 "9.1.2 JSON authorization results request" to study the request structure.

Request parameters description:

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

Response structure:

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

Response parameters description:

Parameter	Description
description	Order description
status	Order status
attribute1	Service field. Filled at company's discretion
attribute2	Service field. Filled at company's discretion
attribute3	Service field. Filled at company's discretion
attribute4	Service field. Filled at company's discretion
commission	The value of the refunded commission from payment
pay_date	Payment date
payee_export_date	Date of sending the payment amount / payment notification to the Partner
payee_export_flag	Status of sending to the Partner (Y – successful, E – error, N or empty value – not sent)
pay_order_date	Bank memorial order date
chargeback	Whether the chargeback was claimed for transaction or not
shopBillId	Order ID in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Online Store
billAmount	Bill amount
errorCode	Error code
errorMessage	Error message
authCode	Bank authorization code (added if the order is paid)
cardMask	Payer’s Card mask
token	Token value for subsequent payments

9.2. XML-notifications

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 "9.2 Notification for successful payment – BILLS message" to study the message structure.

Message BILLS – fields description:

Field name	Data type	Description
PAYEE\NAME	CHAR(100)	Name of a payee’s company
PAYEE\CODE	NUMBER(15,0)	Company code (provided by Portmone.com system)
BANK\NAME	CHAR(100)	Name of sender's bank
BANK\CODE	CHAR(6)	MFO of sender's bank
BANK\ACCOUNT	CHAR(20)	Sender's bank account number
BILL_ID	NUMBER(15,0)	Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID
BILL_NUMBER	CHAR(120)	Bill number
BILL_DATE	CHAR(10)	Bill date in YYYY-MM-DD format
BILL_PERIOD	CHAR(4)	Bill period in MMYY (month and year) format
PAY_DATE	CHAR(10)	Date of payment in YYYY-MM-DD format
PAYED_AMOUNT	NUMBER(15,2)	Amount of payment. Use dot (".") as the decimal separator
PAYED_COMMISSION	NUMBER(15,2)	Amount of banking commission. Always equal to 0
PAYED_DEBT	NUMBER(15,2)	Including payment of debt. Use dot (".") as the decimal separator
AUTH_CODE	CHAR(6)	Authorization code for a payment card
CONTRACT_NUMBER	CHAR(20)	Parameter by which the company and the Portmone.com system agreed to identify the client
ATTRIBUTE1	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE2	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE3	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE4	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message

Examples:

See "9.2 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> …..

Message PAY_ORDERS 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 "9.2 Notification about bank payment – PAY_ORDERS message" to study the message structure.

Message PAY_ORDERS – fields description:

Field name	Data type	Description
PAY_ORDER_ID	NUMBER(15,0)	Payment order ID. The company must verify that the PAY_ORDER_ID is unique and should not allow to register two messages with the same PAY_ORDER_ID
PAY_ORDER_DATE	CHAR(10)	Date of payment order in YYYY-MM-DD format
PAY_ORDER_NUMBER	CHAR(20)	Number of payment order
PAY_ORDER_AMOUNT	NUMBER(15,2)	The amount of payment order. Use dot (".") as the decimal separator
PAYEE\NAME	CHAR(100)	Name of a payee’s company
PAYEE\CODE	NUMBER(15,0)	Company code (provided by the Portmone.com system)
BANK\NAME	CHAR(100)	Name of sender's bank
BANK\CODE	CHAR(6)	MFO of sender's bank
BANK\ACCOUNT	CHAR(20)	Sender's bank account number
BILL_ID	NUMBER(15,0)	Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID
BILL_NUMBER	CHAR(120)	Bill number
BILL_DATE	CHAR(10)	Bill date in YYYY-MM-DD format
BILL_PERIOD	CHAR(4)	Bill period in MMYY (month and year) format
PAY_DATE	CHAR(10)	Date of payment in YYYY-MM-DD format
PAYED_AMOUNT	NUMBER(15,2)	Amount of payment. Use dot (".") as the decimal separator
PAYED_COMMISSION	NUMBER(15,2)	Amount of banking commission
PAYED_DEBT	NUMBER(15,2)	Including payment of debt. Use dot (".") as the decimal separator
AUTH_CODE	CHAR(6)	Authorization code for a payment card
CONTRACT_NUMBER	CHAR(20)	Parameter by which the company and the Portmone.com system agreed to identify the client
ATTRIBUTE1	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE2	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE3	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message
ATTRIBUTE4	CHAR(20)	Additional client identification parameter. If it is not required for client identification, it will not be sent in a message

Examples:

See "9.2 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 "9.2 Confirmation of payment information receipt – RESULT message" to study the message structure.

Message RESULT – fields description:

Field name	Data type	Description
ERROR_CODE	NUMBER(15,0)	Error code (0 in case if message processing is successful)
REASON	CHAR(250)	Error description

Examples:

See "9.2 RESULT message example".

9.3. 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 "9.3 Notification for successful payment in JSON format" to study the message structure.

Parameters description:

Parameter	Description
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumber	Number of paid order (bill) in the Partner’s system
description	Comment to the order / description of payment details
cardMask	Payer’s Card mask
billAmount	Transaction amount sent in request
status	Order status. Possible values: PAYED, PREAUTH, REJECTED, CREATED
token	Token value for subsequent payments
tokenType	Token type. Possible values are: - CARD - in case of card payments, - PRIVAT24 - in case of Privat24 payments.
MD	Parameter which should be sent to acsUrl for 3D Secure check
PaReq	Parameter which should be sent to acsUrl for 3D Secure check
is3DS	3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
acsUrl	The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
attribute1	Service field (for additional order information). Filled at company’s discretion
attribute2	Service field (for additional order information). Filled at company’s discretion
attribute3	Service field (for additional order information). Filled at company’s discretion
attribute4	Service field (for additional order information). Filled at company’s discretion
errorCode	Error code (0 if payment was successful)
error	Error description

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 "9.3 Confirmation of receipt of payment notification in JSON format" to study the message structure.

Parameters description:

Parameter	Description
errorCode	Error code (0 in case if message processing is successful)
reason	Error description. Set it "OK" if error not occurred
responseId	Randomly generated value. Maximum length is 31 character

10. Error codes

ERR_CODE	ERR_MSG	Retrying logic for RC
0	Success	Merchant could retry operation
1	Declined by bank	Merchant could retry operation
2	Transaction is prohibited by acquiring bank	Merchant could retry operation
3	Transaction is prohibited by issuing bank	Merchant should update token
4	Technical/communication problem	Merchant could retry operation. If the error text "Token transferred for payment is blocked in the Portmone.com system", then you need to update the Token
5	Transaction has exceeded the limit by your bank	Merchant could retry operation
6	Not sufficient funds	Merchant could retry operation
7	Invalid CVV or card expiry date	Merchant should update token
8	Invalid OTP code	n/a
9	Invalid 3DS data	n/a
10	Duplicate transactions	Merchant could retry operation
11	Format error	Merchant could retry operation
12	Portmone verification	Merchant could retry operation
13	System error. Please try again.	Merchant could retry operation
14	Wrong signature	Merchant could retry operation
15	Query time exceeded	Merchant could retry operation
16	Invalid request data	Merchant could retry operation
17	Transaction has exceeded system limits	Customer should contact Portmone.com support. Customer could retry payment
18	Fraud	Merchant should update token
19	Order not found	n/a
20	Transaction declined. Invalid phone number	n/a
21	An error occurred while accessing the operators billing system to verify the phone number
Repeat the operation later
23	Cancellation (reject operation) failed	Please perform a return (operation return) for the transaction

Validation error codes

ERR_CODE	ERR_MSG	Retrying logic for RC
511	Invalid card number	Update card number and retry operation
512	Invalid bill amount	Update amount and retry operation
513	Invalid month	Update month value and retry operation
514	Invalid year	Update year value and retry operation
515	Invalid CVV2	Update CVV2 value and retry operation
516	Decryption error	Update cardData value and retry operation

11. Test environment

The test mode of the payment gateway means that the Portmone.com system checks the validity of entered data from the Partner's website 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 Partner 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!

If you want to get callback with the errors from 1 to 10 (see Section 10 "Error codes"), use the following data:

1. Install endpoint: https://www.portmone.com.ua/r3/pm-uat/.

2. The value of the cardNumber parameter:

cardNumber	Error code
5100081112223332	1
5101180000000007	2
5100290029002909	3
5100705000000002	4
4111111111111111	5
4000160000000004	6
4002690000000008	7
4607000000000009	8
4017340000000003	9
4035501000000008	10

Examples

To Section 3 "Payment methods"

3.1.1 Payment by card request

{
    "paymentType": "card",
    "description": "testPayment",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "billAmount": "1",
    "payeeId": "15553",
    "shopOrderNumber": "1334946951",
    "cvvVerifyFlag": "Y",
    "token": "",
    "billCurrency": "",
    "preauthFlag": "",
    "shopSiteId": "",
    "lang":"en",
    "dt": "20181011170545",
    "cardData": "b512d42452e089436045baad776e8399b9169c7213ce4f02044eee60a0118a1e6df6b2f2a385a73bd1336a4b8d88db5236c2bc85eb059edb950dc32ea6f9c5b5e3abadc6d83a3294c6b2dd76c132df91a9c57e8e87ca8b7c59e7e8e76eae949667d6e4b66426795cc9878d44accbc5ed5e19d05e33895bce31c7db447bd325d69648d89259ad4700536c046b32e2d156ece33df29570cf962745bc1ae22bff02eabef1e4531e9830dcc6c5aa27b887f4fdc5b2bf537f7de46e2711cd9a55834021cc6774630c6d620d0daea796ba2cd58e97e1ff151668f8505cd102436fc94f412c997360bdb235e66acff6f62bc99b908a8e06bdb06b41f2859185c5e37865",
    "mode": "1111",
    "signature": "BA167AC7ADD29EAF99B254720002C109F4E76DDC3ECF7FACDD1983E216EE7FBF"
}

3.1.1 Payment by card response

An example of successful response:

{
    "notificationType": "success",
    "shopBillId": "419339918",
    "shopOrderNumber": "659560339",
    "description": null,
    "cardMask": "414951******9158",
    "billAmount": "1",
    "status": "PAYED",
    "token": "18343139333339393138096FEA6055F55A699A090EF5611C3A838713A4694A653254778FAC93FCE5996C44FEAA2B649239CC0740222ABB7838D9913",
    "authCode": "313277",
    "is3DS": "N",
    "receiptUrl": "",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "errorCode": "0",
    "error": ""
}

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

{
    "notificationType":"success",
    "shopBillId": "419339918",
    "shopOrderNumber": "659560339",
    "description": null,
    "cardMask": "414951******9158",
    "billAmount": "1",
    "status": "CREATED",
    "token": "",
    "MD": "156885793",
    "PaReq": "eJxVUmFvgjAQ/SuG76Mtgi3mrMHhNpMhZmPJvjJolGQULCBsv36tots+kNy7e3n3+g5YDuXn5CRUU1RyYREbWxMhsyov5H5hvSUPd8xackgOSojwVWSdEhwi0TTpXkyKfGHt0hdxJN7Ud+jMpZRQSmeEUc/ViDDsT13qOxaHXaB5HMZNXC+yHUBXqCVVdkhlyyHNjqvNlrvE9T0MaIRQCrUJ+cyhjsc8QBcIMi0F38UvSRRv1/Z9HNnx8zugcxuyqpOt+uIMu4CuADr1yQ9tWzdzhPq+t+tKtWUlhZ1Vpd2lgAwB0K+hXWeqRgsORc6jMOj1N8Thuo+S9RC/Yhx977+3yXoByDAgT1vBHUwYwYRMyGzu0rlHAZ37kJbGiQnAvO4CoDY7gnFiBn8boFNX+ihf3Gd6dEMghlob1wyd5K0G9Gv4/snkmbU6KvyAsStl9MGy1amd5sfaDx/ZYxUEwTnlM8koFjok4uOLpAGAjAwaD4jG4+vq30/xA8mWvMM=",
    "is3DS": "Y",
    "acsUrl": "https://acs.upc.ua/acs/pa/0/0F004nnMb8cBvt3dqp9DG8GoAAA0/",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "errorCode": "0",
    "error": ""
}

An example of response in case of an error:

{
    "shopBillId":"4001212321",
    "shopOrderNumber":"654565465",
    "description":"Test",
    "cardMask":"516874******5179",
    "billAmount":"1.01",
    "status":"REJECTED",
    "token":"",
    "tokenType":"",
    "acsUrl":"",
    "MD":"",
    "PaReq":"",
    "is3DS":"",
    "attribute1":"some",
    "attribute2":"some",
    "attribute3":"some",
    "attribute4":"some",
    "errorCode":"1",
    "error":"Declined by bank"
}

3.1.3 Complete payment request

{
    "PaRes": "eJzNWVnPo0iy/Sulmkerm91Ay/WNSPbVgNnfMGB2sA0Ym19/sV1b95TuLFcaXUvImUFmEJkRcU4G7P5+b5tPt+w6lH335TPyO/z5U9YlfVp2",
    "id": "419339918",
    "MD": "156885793"
}

3.1.3 Complete payment response (successful)

{
    "notificationType":"success",
    "shopBillId":"354033144",
    "shopOrderNumber":"5464654654564",
    "description":"testPayment",
    "cardMask":"535557******3083",
    "billAmount":"1",
    "authCode":"211234",
    "status":"PAYED",
    "token":"183335343033333134341287B427D11C7A9D8184196F4C4827B01C81A8E197D87AE06F66E37D1A0A375976818813EDD8E9A1BBB031CAAF32ED3878D51D58DCFC540BC878E91E835C585574B",
    "receiptUrl":"https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3534278394690908a0fc44e7a7c5cdd7282277e1b20df78d8c515a4c71dd405f88577d27c8e5c59c25acc6b345ec45c01feb5d6da00a9a541be3742dc8a66b85",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "is3DS":"N",
    "errorCode":"0" ,
    "error": ""
}

3.2 createToken request

{
	"paymentType":"createToken",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "clientId":"",
    "cardData":
    {
"0165479628fced26f2b51d180d444b0d957cff1ae664ab85ca44e186b9b381928a6356f0dbd5098f307b52b066d8ca9ad394edc34e63f19d14e74536f0548cc39d272f71fb630b991337f44253f966b9f6a6ddb3fc834a54e3acffb0a062397c268e212be36cc47cb9111f1f2bdeae638a3942e927c1aca42e5e47f05ed5779a94863bd86ea07a13b0f8f321b60ddb0b7290a3b8dc3f59867b70c92a8b2995c156ce0aa96c10706a99fdeeb0dabbdad7ade5e6240a9f8afc559c9132ae8d01f5d96ed6f2cd75c28a7635a4f17adab6a11340eb5adfd30c169b2911057455ca8d5c4b63a75b44c771820b01ed7a015bbeb8464b677dc86333beb66805292b9db4"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B"
}

3.2 createToken response (successful)

{
    "notificationType":"success",
    "is3DS":"N",
    "shopBillId":"453139862",
    "shopOrderNumber":"593309194",
    "description":"testPayment",
    "cardMask":"414951******9158",
    "billAmount":"1",
    "status":"PAYED",
    "token":"183435333133393836321281633D3D7E4EE2FC1BC6E08FA9C015361CB699712297DEFDDB622851153A1A624AE765D1742F233FF1AF180C9488160851954AA1A3357D9BF5B8E15F54E9F9DD7",
    "authCode":"931641",
    "mpiFlag":"N",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "errorCode":"0",
    "error": ""
}

3.3 Payment by Token request

{
    "paymentType":"token",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData":
    {
"2a30d5839547765061ea534ca9083f54c5c0c135afa5c51360832d13bf901fca557d3eb2819ef3a39b03aafa06b48190e5623d17ab7f1a578f1d2463f09f6e1b9ff6ee320d466fc85f8ba9d87606967f1dd54287b08a21adfa9cd1bd057805467813926f11a07b51531bd79d68a2ca0744c6ae689bddfbfac1c546aef7f39cff29df0d565f5b8ebad1fc3a84804f3cd65b70b9c9cc87400014036d9f90043d7d3ea87d6bffffe2f7536fbf033ea0f982f4a47a6fbabf91ffdf6ff72d2ec28d4f2a17d0418876fb68b1ce2143e4b66aa6215d9b5cc24b7a8560815403975c4289fd519c8b0d289c77ca574fd20c3f190f4c3c6cac10c0b76dbedbce81d8d23fc3"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":"1101"
}

3.3 Payment by Token response (successful)

{
    "shopBillId":"354033144",
    "shopOrderNumber":"5464654654564",
    "description":"testPayment",
    "cardMask":"535557******3083",
    "billAmount":"1",
    "authCode":"211234",
    "status":"PAYED",
    "token":"183335343033333134341287B427D11C7A9D8184196F4C4827B01C81A8E197D87AE06F66E37D1A0A375976818813EDD8E9A1BBB031CAAF32ED3878D51D58DCFC540BC878E91E835C585574B",
    "receiptUrl":"https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3534278394690908a0fc44e7a7c5cdd7282277e1b20df78d8c515a4c71dd405f88577d27c8e5c59c25acc6b345ec45c01feb5d6da00a9a541be3742dc8a66b85",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "mpiFlag":"N",
    "errorCode":"0"
}

3.4 Recurring payment request

{
    "paymentType":"recurrent",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
	"attribute5":"Вода:3048;2;Сувенір:11344;1;",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"N",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData": "",
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":""
}

To Section 4 "Payment via Privat24"

4.1 Payment by card request

<form action="https://www.portmone.com.ua/r3/secure/gate/liq-pay" method="post">
    <input type="hidden" name="payee_id" value="1185">
    <input type="hidden" name="shop_order_number" value="SHP-121113555111654">
    <input type="hidden" name="bill_amount" value="2">
    <input type="hidden" name="description" value="test">
    <input type="hidden" name="success_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/success/">
    <input type="hidden" name="failure_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/failure/">
    <input type="hidden" name="lang" value="uk">
    <input type="hidden" name="encoding" value="UTF-8">
</form>

4.2 Create token request

<form action="https://www.portmone.com.ua/r3/secure/gate/liq-pay" method="post">
    <input type="hidden" name="payee_id" value="1185">
    <input type="hidden" name="shop_order_number" value="SHP-121113555111654">
    <input type="hidden" name="bill_amount" value="1">
    <input type="hidden" name="description" value="test">
    <input type="hidden" name="success_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/success/">
    <input type="hidden" name="failure_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/failure/">
    <input type="hidden" name="revert" value="Y">
    <input type="hidden" name="lang" value="uk">
    <input type="hidden" name="encoding" value="UTF-8">
</form>

4.3 Payment by Token request

{
    "paymentType":"token",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData":
    {
"2a30d5839547765061ea534ca9083f54c5c0c135afa5c51360832d13bf901fca557d3eb2819ef3a39b03aafa06b48190e5623d17ab7f1a578f1d2463f09f6e1b9ff6ee320d466fc85f8ba9d87606967f1dd54287b08a21adfa9cd1bd057805467813926f11a07b51531bd79d68a2ca0744c6ae689bddfbfac1c546aef7f39cff29df0d565f5b8ebad1fc3a84804f3cd65b70b9c9cc87400014036d9f90043d7d3ea87d6bffffe2f7536fbf033ea0f982f4a47a6fbabf91ffdf6ff72d2ec28d4f2a17d0418876fb68b1ce2143e4b66aa6215d9b5cc24b7a8560815403975c4289fd519c8b0d289c77ca574fd20c3f190f4c3c6cac10c0b76dbedbce81d8d23fc3"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":"1111"
}

To Section 5 "Reject/Confirm preauth payment"

5.1 confirmPreauth request

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

5.1 confirmPreauth response

{
    "shop_bill_id":"395584061",
    "shop_order_number":"test_1SAB1",
    "description":"Order 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":""
}

5.2 rejectPreauth request

{
    "method":"rejectPreauth",
    "params":
    {
        "data":
        {
            "login": "",
            "password": "",
            "payeeId":"",
            "shopOrderNumber":""
        }
    },
    "id":"1"
}

5.2 rejectPreauth response (successful)

[
    {
        "description":"78765432",
        "status":"REJECTED",
        "attribute1":"1",
        "attribute2":"2",
        "attribute3":"3",
        "attribute4":"4",
        "commission":"1",
        "shopBillId":"411423303",
        "shopOrderNumber":"333-000000116",
        "billAmount":"1",
        "errorCode":"0",
        "errorMessage":"",
        "authCode":"204984",
        "cardMask":"516874******5179",
        "token":"18343131343233333033096C58E59899FA962C4189B243EFB3798FBC400EC43E5EB89BEEB9D4727FEB7E7F8006F2DB3343733E517647A604C3298EE"
    }
]

To Section 6 "Receipt of payment token after payment"

6.1 getToken request (example for PHP)

$jsoncontent = '{"method": "getToken", "params": {"login": "shp_", "password": "
", "shopOrderNumber":"test_1s4s4s4"}, "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);
curl_close($ch);

6.1 getToken response (tokenType: CARD)

{
    "result":
    {
        "cardMask":"411111******1111",
        "billAmount":"100",
        "billCurrency":"UAH",
        "token":"183139323139323737380965F710436F9AFA2B1BCC0322ABAE2A9D39863DF9B028A578451A6CF9188490331C6A9C63D0E4749A257119DE5CF4A33B4",
        "tokenType":"CARD"
    },
    "id":"1"
}

6.1 getToken response (tokenType: PRIVAT24)

{
    "result":
    {
        "cardMask":"516874*79",
        "billAmount":"1.01",
        "billCurrency":"UAH",
        "token":"18333837353838353131096F85F1E5B0E1E4619D8BE4DE5B6B68ACAE9A3BA0486F4F2144048AD176B3BF2716D7D41731D6EC273DD501BD97CB07377",
        "tokenType":"PRIVAT24"
    },
    "id":"1"
}

6.2 getTokens request (example for PHP)

$jsoncontent = '{
"method": "getTokens",
"params":
{
"data": {
"login": "wdishop",
"password": "wdi451",
"description":"'.$description.'",
"payeeId":"'.$payeeId.'",
"dt":"'.$dt.'",
"signature":"'.$signature.'"
}
},
"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/api/gateway/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsoncontent);
$result = curl_exec($ch);
$curl_info = curl_getinfo($ch);
print_r($curl_info);
print_r($result);
curl_close($ch);
$file = 'test.txt';
file_put_contents($file, $result);

6.2 getTokens response

{
    "result":
    [
        {
            "token":"183337303236353831340641B61B7FA4D9F338B94439BC256FCF060A1C03A7394185AC0B6A015E9C0334EAD",
            "cardMask":"411111******1111",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333834333834313435096EFADEC52B8BE117819FD0C9731B116E3A4ACE1D2AA4BC513DC9FC9F4888F37190A843EAF9C082F1E6B3DAB46983105E7",
            "cardMask":"418837******4707",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"183337333430383238380960405F352CF119FC1A46009328B2981340618B236208A7464071C52D13A63C12EF6FB256D9BBFE04AACFE01896776C3C2",
            "cardMask":"487411******0840",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"1833373536353135333306425DC368C39A4878A915B5D26429D9783705BDC420373BE0CED15FE9EC2B6C2EF",
            "cardMask":"410232******5594",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333730353836333830064056BCF6795D8109FFB3C0B9EAA2293E83B9A3113CBFC80FE330FE00F106C6E23",
            "cardMask":"535557******3083",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333834363634323837128E83990641E033F70060C770993546C253A2329D9A6ABB3F8864684EC56824470F402D1C4AE118D15589CB784AE4D203EC1B5D5A0977D51DB710E2D9EF769A021",
            "cardMask":"516874*79",
            "billAmount":"1.02",
            "tokenType":"PRIVAT24",
            "billCurrency":"UAH"
        }
    ],
    "id":"1"
}

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

7.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"
}

7.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"
}

7.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"
}

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

To Section 8 "Return"

8.1 POST return 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>

8.1 POST return 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>TEST001</shop_order_number>
        <description>TEST PAYMENT</description>
        <bill_date>15.07.2018</bill_date>
        <pay_date>15.07.2018 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></error_message>
    </order>
</portmoneresult>

8.1 POST return response (failure)

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

8.2 JSON return request

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

8.2 Response format

[
    {
        "description":"78765432",
        "status":"RETURN",
        "attribute1":"",
        "attribute2":"",
        "attribute3":"",
        "attribute4":"",
        "commission":"0",
        "shopBillId":"410343513",
        "shopOrderNumber":"SHP-29174",
        "billAmount":"-1",
        "errorCode":"0",
        "errorMessage":"test return",
        "authCode":"511965",
        "token":"",
        "cardMask":""
    }
]

8.3 JSON refund request

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

8.3 Response format

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

To Section 9 "Getting authorization results"

9.1.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="1085" />
    <input type="hidden" name="login" value="WDISHOP" />
    <input type="hidden" name="password" value="1111111" />
    <input type="hidden" name="shop_order_number" value="TEST001" />
    <input type="hidden" name="status" value="PAYED"/>
    <input type="hidden" name="start_date" value="05.07.2018"/>
    <input type="hidden" name="end_date" value="05.07.2018"/>
</form>

9.1.1 POST authorization results response

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <payee_id>1185</payee_id>
        <shop_order_number>123456</shop_order_number>
        <status>PAYED</status>
        <start_date>05.07.2018</start_date>
        <end_date>05.07.2018</end_date>
    </request>
    <orders type='list' >
        …
        <order>
            <shop_bill_id>387886615</shop_bill_id>
            <shop_order_number>123456</shop_order_number>
            <description>111111</description>
            <bill_date>05.07.2018</bill_date>
            <pay_date>05.07.2018 15:57:44</pay_date>
            <bill_amount>14.28</bill_amount>
            <auth_code>123456</auth_code>
            <status>PAYED</status>
            <error_code>0</error_code>
            <error_message></error_message>
        </order>
        …
    </orders>

9.1.2 JSON authorization results request

{
	"method":"result",
	"params":
	{
		"data":
		{
			"login":"P_DIRECT_CCLOAN",
			"password": "11111111",
			"payeeId":"17553",
			"shopOrderNumber":"SHP-21251-20190913032725",
			"status":"", 
			"startDate":"13.09.2019", 
			"endDate":"13.09.2018"
		}
	},
	"id":"1"
}

9.1.2 JSON authorization results response (successful)

[
	{
		"description":"516874******5179",
		"status":"PAYED",
		"attribute1":"58661656",
		"attribute2":"552aa24c46c807a05bb0fc32477c19f0",
		"attribute3":"838622",
		"attribute4":"925615124384",
		"commission":0,
		"pay_date":"13.09.2019",
		"payee_export_date":"13.09.2019",
		"payee_export_flag":"Y",
		"pay_order_date":"",
		"chargeback":"N",
		"shopBillId":"544917852",
		"shopOrderNumber":"SHP-21251-20190913032725",
		"billAmount":"1.33",
		"errorCode":"0",
		"errorMessage":"",
		"authCode":"000000",
		"cardMask":"000000",
		"token":"1835343439313738353216029F3201DB621287E7931807434FF90895A3414443A7DC4A2FF4E52D26A7A75665400524A1430772A2039748BE34A0D828E52E55255F1C827F421D416626752B7E3422BD6237D736F758CC04F8645E22D"
	}
]

9.2 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> MFО of sending bank</CODE>
          <ACCOUNT> Account number 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>

9.2 BILLS message example

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

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

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

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

9.2 RESULT message example

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

9.3 Notification for successful payment in JSON format

{
    "shopBillId":"",
    "shopOrderNumber":"",
    "description":"",
    "cardMask":"",
    "billAmount":"",
    "status":"",
    "token":"",
    "tokenType":"",
    "acsUrl":"",
    "MD":"",
    "PaReq":"",
    "is3DS":"",
    "attribute1":"",
    "attribute2":"",
    "attribute3":"",
    "attribute4":"",
    "errorCode":"0",
    "error":""
}

9.3 Confirmation of receipt of payment notification in JSON format

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

Appendix 1. 3D-Secure flow description

Step	Description
1	Merchant displays the payment form to Customer (Note: Merchant includes a Portmone-provided JavaScript library to encrypt sensitive fields before the form is sent to Merchant’s server)
2	Customer enters card details to the form and sends them to the Merchant’s server. Card data is sent to Merchant in encrypted form
3	Merchant’s server creates Payment by Card Request and sends it to PSP
4	PSP sends a Verify Enrolment Request (VEReq) to the Directory Server
5	Directory Server returns Verify Enrolment Response (VERes) to PSP
6	PSP returns Payment by Card Response to the Merchant’s server with is3DS = Y
7-8	Merchant’s server sends Payer Authentication Request to ACS via Customer’s web browser
9	ACS shows 3DS-authorization form to Customer
10	Customer complete 3DS-authorization
11-12	ACS creates Payer Authentication Response message with 3DS authorization results and sends it to Merchant’s server via Customer’s web browser (to TermUrl which Merchant sent in step 7)
13	Merchant’s servers sends Complete Payment Request to PSP
14	PSP sends payment request to the Acquiring Bank
15	Acquirer processes payment and returns answer to PSP
16	PSP returns Complete Payment Response to Merchant and sends Notification to Merchant (if needed)