Skip to main content

Portmone API Gateway for Partners with PCI DSS level

Glossary

TermDefinition
Merchant, PartnerOrganisation which has signed a payment acceptance agreement with Portmone.com
Client, CustomerA 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 CardPayment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
AuthorizationThe process of giving access rights or other powers to the Customer, program or process
Recurring PaymentsAutomatic payments (no participation of the client and re-entering card details required), which are carried out with the consent of the client
TokenA unique digital identifier of a card, which is generated during the first operation and then used for quick payment. Token can only be used to repeat a similar transaction as at the first payment
SHOPBILLIDA unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system
CVV2/CVC2CVV2 (Card Verification Value 2) is a three-digit card security code that helps 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 Secure3-D Secure is a protocol which used to secure handling of online bank card payments
PSPPSP (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
ACSACS (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
IPSInternational 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:

ParameterDescription
transactionIdID of the transaction in the Portmone.com system
attemptIdRequest id which initiate payment by card. Randomly generated value, length 31 character (for example, 3wlk66m64q0wokcgkwog4040osw04ks)
errorCodeError code (0 if payment was successful)
errorError 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:

ParameterDescriptionRequired
paymentTypeMust be set "card" valueYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channelNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionPayment description (comment to the order/ payment details)Yes
tokenSet empty valueNo
cardDataEncrypted value of payment card data (card number, expiration month, expiration year, CVV2)Yes
preauthFlagPayment 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
cvvVerifyFlagThe default is "Y", set "N" for payments without CVV2No
clientIdSet empty valueNo
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1111" for asynchronous modeNo
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)No
langPayment system interface language: uk – Ukrainian, en – English,az – Azerbaijani, kz – KazakhNo

Response structure:

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

Response parameters description:

ParameterDescription
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order/ description of payment details
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
authCodeBank authorization code (added if the order is paid)
statusOrder status. Possible values: PAYED, PREAUTH, REJECTED, CREATED
tokenToken value for subsequent payments
MDParameter which should be sent to acsUrl for 3D Secure check
PaReqParameter which should be sent to acsUrl for 3D Secure check
is3DS3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
acsUrlThe card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCodeError code (0 if payment was successful)
errorError 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:

ParameterDescriptionRequired
idOrder ID in the Portmone.com systemYes
PaResThe PaRes value received from the bank to your URLYes
MDThe MD value received from the bank to your URLYes

Response structure:

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

Response parameters description:

ParameterDescription
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order / description of payment details
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
authCodeBank authorization code (added if the order is paid)
statusOrder status
receiptUrlLink to get a receipt
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCodeError code (0 if payment was successful)
errorError description
is3DS3DS-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:

ParameterDescriptionRequired
paymentTypeTo create a Token, you must set the value to "createToken" for this parameterYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channel. Set empty valueNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionPayment description (comment to the order /payment details)Required, identifies the Token in subsequent payments
tokenSet empty valueNo
cardDataEncrypted value of payment card data (card number, expiration month, expiration year, CVV2)Yes
preauthFlagPayment pre-authorization flag. Set empty valueNo
cvvVerifyFlagThe default is "Y", set "N" if need operation without CVV2No
clientIdSet empty valueYes
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
attribute5Used 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:

ParameterDescription
is3DS3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order / description of payment details
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
statusOrder status
tokenToken value for subsequent payments
authCodeBank authorization code (added if the order is paid)
mpiFlag3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCodeError code (0 if payment was successful)
errorError 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:

ParameterDescriptionRequired
paymentTypeSet the value to "token" for this parameterYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channelNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionPayment description (comment to the order /payment details)Yes
tokenSet Token valueYes
cardDataEncrypted value of CVV2Yes
preauthFlagPayment 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
cvvVerifyFlagThe default is "Y", set "N" if need operation without CVV2No
clientIdSet empty valueYes
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1111" for asynchronous modeNo
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
attribute5Used 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:

ParameterDescription
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order /description of payment details
authCodeBank authorization code
receiptUrlLink to get a receipt
tokenToken value
mpiFlagReturn "N"
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
statusPAYED – successful transaction, PREAUTH – successful transaction with pre-authorization
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)
errorCodeError 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:

ParameterDescriptionRequired
paymentTypeMust be set "recurrent" valueYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order (bill) in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channelNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionComment to the order/ description of payment details (should be the same as in initial payment)Yes
tokenSet Token valueYes
cardDataSet empty valueNo
preauthFlagPayment 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
cvvVerifyFlagSet "N" if need operation without CVV2Yes
clientIdSet empty valueYes
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1111" for asynchronous modeNo
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo
attribute5Used to send the split parameters of the payment (see section "Splitting the payment" for details)No

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:

ParameterDescriptionRequired
payee_IdA unique identifier of the PartnerYes
shop_order_numberNumber of paid order (bill) in the Partner’s systemNo
bill_amountAmount of the order. Currency – hryvnia (UAH)Yes
descriptionComment to the order / description of payment detailsYes
langPrivat24 system interface language. Possible values: en – English, uk – UkrainianYes
encodingEncodingYes
success_urlThe Merchant URL address to which the client will be redirected after a successful paymentYes
failure_urlThe Merchant URL address to which the client will be redirected in case of payment rejectionYes

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:

ParameterDescriptionRequired
payee_IdA unique identifier of the PartnerYes
shop_order_numberNumber of paid order (bill) in the Partner’s systemNo
bill_amountAmount of the order. Currency – hryvnia (UAH). Must be set "1" valueYes
descriptionComment to the order / description of payment detailsYes
success_urlThe Merchant URL address to which the client will be redirected after a successful paymentYes
failure_urlThe Merchant URL address to which the client will be redirected in case of payment rejectionYes
revert"Y" – refundYes
langPrivat24 system interface language. Possible values: en – English, uk – UkrainianYes
encodingEncodingYes

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:

ParameterDescriptionRequired
paymentTypeSet the value to "token" for this parameterYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channelNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionPayment description (in case of payment by token description should be the same as in initial payment)Yes
tokenSet Token valueYes
cardDataEncrypted value of CVV2Yes
preauthFlagPayment 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
cvvVerifyFlagThe default is "Y", set "N" if need operation without CVV2No
clientIdSet empty valueYes
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1111" for asynchronous modeNo
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo

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:

ParameterDescriptionRequired
paymentTypeMust be set "recurrent" valueYes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
shopOrderNumberNumber of paid order (bill) in the Partner’s systemNo
billAmountAmount of the paymentYes
emailAddressEmail address of the payerNo
shopSiteIdDigital identifier of a sales channelNo
billCurrencyCurrency of the payment. Default value: UAHNo
descriptionComment to the order/ description of payment details (should be the same as in initial payment)Yes
tokenSet Token valueYes
cardDataSet empty valueNo
preauthFlagPayment 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
cvvVerifyFlagSet "N" if need operation without CVV2Yes
clientIdSet empty valueYes
dtRequest creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
signatureRequest signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature"Yes
modeSet "1111" for asynchronous modeNo
attribute1Service field (for additional order information). Filled at company’s discretionNo
attribute2Service field (for additional order information). Filled at company’s discretionNo
attribute3Service field (for additional order information). Filled at company’s discretionNo
attribute4Service field (for additional order information). Filled at company’s discretionNo

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:

ParameterDescription
loginThe Partner login to access account management
passwordThe Partner password
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store system. Maximum length is 120 symbols
tokenSet token value
postauthAmountAmount of the payment. It can not be more than the amount for which pre-authorization was carried out
idID 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:

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

ParameterDescription
methodRequired parameter to call the cancellation of payment with pre-authorization procedure. Value: rejectPreauth
loginThe Partner login to access account management
passwordThe Partner password
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
idID 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:

ParameterDescription
descriptionOrder description
statusOrder status
attribute1-4Service fields (for additional order information)
commissionThe value of the refunded commission from payment
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code (added if the order is paid)
cardMaskPayer’s Card mask
tokenToken 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:

ParameterDescriptionRequired
methodTo obtain a Token, you must set the value to "getToken" for this parameterYes
loginThe Partner login to access account managementYes
passwordThe Partner passwordYes
shopOrderNumberNumber of paid order (bill) in the Partnet’s system. Maximum length is 120 symbolsYes
idID of the request from the Partner to the Portmone.com systemYes

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:

ParameterDescription
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
billCurrencyCurrency of the payment
tokenToken value for subsequent payments
tokenTypeCARD – in case of card payments, PRIVAT24 – in case of Privat24 payments
idID 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:

ParameterDescriptionRequired
methodMust be set "getTokens" valueYes
loginThe Partner login to access account managementYes
passwordThe Partner passwordYes
descriptionPayment description (comment to the order /payment details)Yes
signatureRequest 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 belowYes
dtRequest creation time. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724)Yes
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com systemYes
idID of the request from the Partner to the Portmone.com systemYes

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:

ParameterDescription
cardMaskPayer’s Card mask
billAmountAmount of the payment
billCurrencyCurrency of the payment. Default value: UAH
tokenToken value
tokenTypeCARD – in case of card payments, PRIVAT24 – in case of Privat24 payments
idID 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:

ParameterDescription
MERCHANT_LOGINMerchant's login in the Portmone system
MERCHANT_PASSWORDMerchant's password in the Portmone system
TOKEN_REFERENCECard token, returned by the Portmone system

Response structure and example (Mastercard):

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

Response key parameters description:

ParameterDescription
TOKEN_TYPEToken type depending on the IPS
idUnique response ID

Response structure and example (Visa):

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

Response key parameters description:

ParameterDescription
TOKEN_TYPEToken type depending on the IPS
idUnique response ID
tokenInfo, cardMetaData, cardDataCard meta data

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:

ParameterDescription
MERCHANT_LOGINMerchant’s login in the Portmone system
MERCHANT_PASSWORDMerchant’s password in the Portmone system
TOKEN_TYPEToken type received using getDataTokenIPS method according to p. 4.5
ASSET_ID:Asset ID received using getDataTokenIPS method according to p. 4.5 (AssetId\guid)

Response structure and example:

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

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:

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

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

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

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

Response structure:

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

Response parameters description:

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

Important! If the response contains status = PAYED, but payeeExportFlag has a value other than Y, it is necessary to request the transaction status from the Portmone.com system (see section 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:

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

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

Description of query parameters:

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

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

Important! If the response contains status = PAYED, but payeeExportFlag has a value other than Y, it is necessary to request the transaction status from the Portmone.com system (see section 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:

ParameterDescriptionRequired
methodRequired parameter to call the return procedure. Value: returnYes
loginThe Partner loginYes
passwordThe Partner passwordYes
shop_bill_idOrder number in the Portmone.com system (should be obtained using the result method described in section 9.1 "Authorization results request")Yes
return_amountReturn amountYes
attribute1Additional optional parameterNo
encodingEncodingYes
langError message languageYes

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:

ParameterDescription
methodRequired parameter to call the return procedure. Value: return
loginThe Partner login
passwordThe Partner password
shop_bill_idOrder number in the Portmone.com system
return_amountReturn amount
attribute1Additional optional parameter
encodingEncoding
langError message language
shop_order_numberNumber of an order (bill) in the Partner’s system. Maximum length is 120 symbols
descriptionOrder description
bill_dateBill date (date the order was created)
pay_datePayment date (date the order was paid)
bill_amountBill amount to return
auth_codeBank authorization code
statusOrder status
error_codeError code (0 if payment was successful)
error_messageError 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:

ParameterDescription
loginThe Partner login to access account management
passwordThe Partner password
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Partner’s system. Maximum length is 120 symbols
returnAmountReturn amount
messageReturn reason
idID of the request

Response structure:

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

Response parameters description:

ParameterDescription
descriptionOrder description
statusOrder status
attribute1-4Service fields (for additional order information)
commissionThe value of the refunded commission from the payment
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of an order (bill) in the Partner’s system. Maximum length is 120 symbols
billAmountBill amount
error_codeError code
error_messageError message
auth_codeBank authorization code (added if the order is paid)
tokenToken value
cardMaskPayer's Card mask

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:

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: result
payee_idA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
loginThe Partner login to access account management
passwordThe Partner password
shop_order_numberNumber of an order in the Partner's system. If you do not specify this value, orders will be selected without reference to their numbers
statusStatus of the order to be included in the report. Possible values:
- PAYED – paid,
- CREATED – created,
- REJECTED – rejected.
By default, orders with all types of statuses are selected.
start_dateStart date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_dateEnd date of the report in dd.mm.yyyy format. By default, it’s the current date

Response structure:

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

Response parameters description:

ParameterDescription
shop_bill_idOrder ID in the Portmone.com system
shop_order_numberNumber of paid order (bill) in the Partner's system
descriptionOrder description
bill_dateBill date
pay_datePayment date
bill_amountBill amount
auth_codeBank authorization code (added if the order is paid)
statusOrder status
error_codeError code
error_messageError message

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:

ParameterDescription
methodRequired parameter to call the report generation procedure. Value: result
loginThe Partner login to access account management
passwordThe Partner password
payeeIdA unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system
shopOrderNumberNumber of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers
statusStatus of the order to be included in the report. Possible values:
- PAYED – paid,
- CREATED – created,
- REJECTED – rejected.
By default, orders with all types of statuses are selected.
start_dateStart date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month
end_dateEnd date of the report in dd.mm.yyyy format. By default, it’s the current date
idId of the request from the Online Store to the Portmone.com system

Response structure:

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

Response parameters description:

ParameterDescription
descriptionOrder description
statusOrder status
attribute1Service field. Filled at company's discretion
attribute2Service field. Filled at company's discretion
attribute3Service field. Filled at company's discretion
attribute4Service field. Filled at company's discretion
commissionThe value of the refunded commission from payment
pay_datePayment date
payee_export_dateDate of sending the payment amount / payment notification to the Partner
payee_export_flagStatus of sending to the Partner (Y – successful, E – error, N or empty value – not sent)
pay_order_dateBank memorial order date
chargebackWhether the chargeback was claimed for transaction or not
shopBillIdOrder ID in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Online Store
billAmountBill amount
errorCodeError code
errorMessageError message
authCodeBank authorization code (added if the order is paid)
cardMaskPayer’s Card mask
tokenToken value for subsequent payments

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

Examples:

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

Examples:

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

ParameterDescription
shopBillIdA unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
shopOrderNumberNumber of paid order (bill) in the Partner’s system
descriptionComment to the order / description of payment details
cardMaskPayer’s Card mask
billAmountTransaction amount sent in request
statusOrder status. Possible values: PAYED, PREAUTH, REJECTED, CREATED
tokenToken value for subsequent payments
tokenTypeToken type. Possible values are:
- CARD - in case of card payments,
- PRIVAT24 - in case of Privat24 payments.
MDParameter which should be sent to acsUrl for 3D Secure check
PaReqParameter which should be sent to acsUrl for 3D Secure check
is3DS3DS-authorization flag ("Y" – 3D Secure check is required, "N" – 3D Secure check is not required)
acsUrlThe card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
attribute1Service field (for additional order information). Filled at company’s discretion
attribute2Service field (for additional order information). Filled at company’s discretion
attribute3Service field (for additional order information). Filled at company’s discretion
attribute4Service field (for additional order information). Filled at company’s discretion
errorCodeError code (0 if payment was successful)
errorError 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:

ParameterDescription
errorCodeError code (0 in case if message processing is successful)
reasonError description. Set it "OK" if error not occurred
responseIdRandomly generated value. Maximum length is 31 character

10. Error codes

ERR_CODEERR_MSGRetrying logic for RC
0SuccessMerchant could retry operation
1Declined by bankMerchant could retry operation
2Transaction is prohibited by acquiring bankMerchant could retry operation
3Transaction is prohibited by issuing bankMerchant should update token
4Technical/communication problemMerchant 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
5Transaction has exceeded the limit by your bankMerchant could retry operation
6Not sufficient fundsMerchant could retry operation
7Invalid CVV or card expiry dateMerchant should update token
8Invalid OTP coden/a
9Invalid 3DS datan/a
10Duplicate transactionsMerchant could retry operation
11Format errorMerchant could retry operation
12Portmone verificationMerchant could retry operation
13System error. Please try again.Merchant could retry operation
14Wrong signatureMerchant could retry operation
15Query time exceededMerchant could retry operation
16Invalid request dataMerchant could retry operation
17Transaction has exceeded system limitsCustomer should contact Portmone.com support. Customer could retry payment
18FraudMerchant should update token
19Order not foundn/a
20Transaction declined. Invalid phone numbern/a
21An error occurred while accessing the operators billing system to verify the phone number
Repeat the operation later
23Cancellation (reject operation) failedPlease perform a return (operation return) for the transaction

Validation error codes

ERR_CODEERR_MSGRetrying logic for RC
511Invalid card numberUpdate card number and retry operation
512Invalid bill amountUpdate amount and retry operation
513Invalid monthUpdate month value and retry operation
514Invalid yearUpdate year value and retry operation
515Invalid CVV2Update CVV2 value and retry operation
516Decryption errorUpdate 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:

cardNumberError code
51000811122233321
51011800000000072
51002900290029093
51007050000000024
41111111111111115
40001600000000046
40026900000000087
46070000000000098
40173400000000039
403550100000000810

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

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

3DS flow diagramm

StepDescription
1Merchant 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)
2Customer enters card details to the form and sends them to the Merchant’s server. Card data is sent to Merchant in encrypted form
3Merchant’s server creates Payment by Card Request and sends it to PSP
4PSP sends a Verify Enrolment Request (VEReq) to the Directory Server
5Directory Server returns Verify Enrolment Response (VERes) to PSP
6PSP returns Payment by Card Response to the Merchant’s server with is3DS = Y
7-8Merchant’s server sends Payer Authentication Request to ACS via Customer’s web browser
9ACS shows 3DS-authorization form to Customer
10Customer complete 3DS-authorization
11-12ACS 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)
13Merchant’s servers sends Complete Payment Request to PSP
14PSP sends payment request to the Acquiring Bank
15Acquirer processes payment and returns answer to PSP
16PSP returns Complete Payment Response to Merchant and sends Notification to Merchant (if needed)