Portmone.com Payment Gateway
Glossary
Term | Definition |
---|---|
Merchant, Online Store or Partner | Organization which has signed a payment acceptance agreement with Portmone.com |
Buyer, Client or Customer | A person who visits the Merchant's Online Store in order to learn about the range of goods (services) and to make a purchase |
Card, Payment Card | Payment cards of Visa, Mastercard international card associations and the National payment system PROSTIR |
Authorization | The process of giving access rights or other powers to the Buyer, program or process |
Recurring Payments | Automatic payments (no client actions or re-entering card details required), which are carried out with the consent of the client |
Token | A unique digital identifier of a card, which is generated during the first operation and then used for quick payment. Token can only be used to repeat a similar transaction as at the first payment |
SHOPBILLID | A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system |
CVV2/CVC2 | CVV2 (Card Verification Value 2) is a three-digit card security code that helps to verify legitimacy of a Visa payment card. The Mastercard payment system has similar card security code called CVC2 (Card Validation Code 2) |
Acquiring Bank | A bank that organizes banking cards acceptance points (terminals, ATM’s) and processes full range of financial operations connected with performing bank settlements and payments by banking cards at that points |
Issuing Bank (Card Issuing Bank) | A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards |
3-D Secure | 3-D Secure is a protocol which used to secure handling of online bank card payments |
IBAN | International Bank Account Number |
IPS | International Payment System |
1. Payment acceptance technology
The description of procedure for payment acceptance by payment cards on the Online Store website:
-
The Buyer chooses a product on a website (or in the mobile application) of a Store, forms the order and selects payment card as a payment method.
-
The Store redirects the Buyer to the Portmone.com system authorization server, sending a set of necessary parameters like partner Id in the Portmone.com system, order number, its amount, etc.
-
The Portmone.com authorization server establishes connection with the Buyer using secure protocol (TLS 1.2), verifies the data received from the Store.
-
The Portmone.com site receives from the Buyer the parameters of his/her Payment Card and ensures the authorization of the Card.
-
When the 3-D Secure technology is used, the Portmone.com sends the Client to the site of Card Issuing Bank to confirm the transaction.
-
The authorization request is sent through closed banking networks to the Buyer's Card Issuing Bank or to the processing center authorized by the Issuing Bank.
- The Bank sends a positive authorization result to the Portmone.com authorization server.
- The Portmone.com authorization server checks the cryptographic integrity of the data received, adds the information to the database.
- Portmone.com redirects the Client to the Online Store page to confirm successful payment.
- The Store checks the status of the transaction in the Portmone.com system and delivers the goods (provides service).
- Within the terms specified in the contract, Portmone.com will transfer funds (excluding the acquiring fee) to the Store account. Funds are transferred via single payment covering all transactions for the specified day.
-
If card authorization failed (authorization was rejected):
- The Bank sends the payment rejection message to the Portmone.com authorization server.
- The Portmone.com authorization server checks the cryptographic integrity of the data received, adds the information to the database.
- The Portmone.com redirects the request to the previously configured page of the Online Store for failed payment.
-
In case of successful payment, the paid order number and the payment data are transmitted by the POST method to the Online Store page.
-
The Online Store must additionally check the status and amount of the order by one of the methods described in section 8 "Getting authorization results".
2. Test mode
The test mode of the payment gateway means that the Portmone.com system checks the validity of entered data from the Online Store and its Client, creates an order, but payment card authorization is not performed. The Portmone.com payment gateway may provide the different response (successful or failed), depending on what is necessary for the Online Store employees who perform integration.
Please contact our Account Managers for Online Stores to enable and disable test mode
Email: [email protected]
The Portmone.com system provides partners with two test options:
1. Successful payment test
To get a successful response on the Portmone.com default payment page use following payment card details:
Card number: 4444333322221111 Expiry date: Any but not earlier than current day CVV2: Any
2. Failed payment test
To get an error on the Portmone.com default payment page use following payment card details:
Card number: 4111111111111111 Expiry date: Any but not earlier than current day CVV2: Any
Important! Before starting the payment acceptance system into operation, make sure that the test mode is disabled!
3. Order payment
3.1. POST request
Description:
To accept payments by Payment cards, you should send a request using the POST method to the payment gateway page – https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "3.1 POST order payment request" to study the request structure.
Request parameters description:
Parameter | Description | Required | Value |
---|---|---|---|
payee_id | A unique identifier of the Online Store | Yes | Assigned to each Partner individually when connected to the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store. Order number must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transaction. | No | Maximum length is 120 symbols |
bill_amount | Amount of the order. Currency is hryvnia (UAH). The decimal separator is the dot symbol "." | Yes | For example: 1.50 |
bill_currency | Currency of the payment | No | Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT |
description | Comment to the order / description of payment details | No | Maximum length is 250 symbols |
success_url | The URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after successful payment. After successful payment of the order Portmone.com will send shop_order_number and the payment data to this address using the POST method.Upon calling this page on the website of the Online Store, you can verify the status and the amount of the transaction in the Portmone.com system. These procedures are described below (see section 8 "Getting authorization results") | No | For example: http://example.com/success.html |
failure_url | The URL of the Online Store to which the client will be redirected in case of payment rejection | No | For example: http://example.com/failure.html |
lang | Payment system interface language | No | uk – Ukrainian, en – English |
encoding | Encoding | No | The default is UTF-8 |
preauth_flag | Sets the pre-authorization mode when funds are only blocked on the Client’s card, but not actually charged from the client’s account | No | "Y" – enable pre-authorization mode, "N" – disable pre-authorization mode (the default is "N") |
attribute1-4 | Service field | No | Filled at company's discretion |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No | Filled in the next format: Desc1:payeeID1;amount1; Desc2:payeeID2;amount2; where Desc1 – description of the order for the first recipient company, payeeID1 – ID of the first recipient company, amount1 – amount to be enrolled to the account of the first recipient, Desc2 – description of the order for the second recipient company, payeeID2 – ID of the second recipient company, amount2 – amount to be enrolled to the account of the second recipient. The number of recipient companies for a single payment request with splitting is limited to the length of the line (up to 500 characters) |
exp_time | Sets the interval during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid | No | Filled in seconds |
Response structure:
Please, refer to "3.1 POST order payment response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (Id) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Payer’s Card mask |
ATTRIBUTE1 | Service field. Filled at company’s discretion |
ATTRIBUTE2 | Service field. Filled at company’s discretion |
ATTRIBUTE3 | Service field. Filled at company’s discretion |
ATTRIBUTE4 | Service field. Filled at company’s discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details. Maximum length is 250 symbols |
IPSTOKEN | A unique Visa token |
ERRORIPSCODE | Error code if Visa token was not created |
ERRORIPSMESSAGE | Error message if Visa token was not created |
3.2. JSON request
Description:
To make a payment you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "3.2 JSON order payment request" to study the request structure.
Parameters for generating JSON-structure of request:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | Yes |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | Yes |
signature | Signature of the request | Yes |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | No |
shopOrderNumber | Number of a paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
preauthConfirm | Date of automatic withdrawal for payments with pre-authorization. Can be used when the preauthFlag = Y parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is confirmed automatically). It can not be less than the current date | No |
preauthReject | Date of automatic cancellation of pre-authorization. Can be used when the preauthFlag = Y parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is cancelled automatically). It can not be less than the current date | No |
billCurrency | Currency of the payment. Default value: UAH | No |
expTime | Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1 | Service field. Filled at company’s discretion | No |
attribute2 | Service field. Filled at company’s discretion | No |
attribute3 | Service field. Filled at company’s discretion | No |
attribute4 | Service field. Filled at company’s discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
card | Payment by Card | No |
portmone | Payment via Portmone.com wallet | No |
token | Payment by Token (if this option is enabled, other methods are not displayed) | No |
clicktopay | Payment using Visa Click to Pay | No |
privat | Payment via LiqPay, with choosing a card from the Privat24 Internet Banking Pay attention! Pre-authorization functionality does not work when paying via Privat24 | No |
gpay | Payment via Google Pay, with choosing a card from previously stored in the Google Pay account | No |
createtokenonly | Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card") | No |
gpayonly | Payment via Google Pay, with choosing a card from previously stored in the Google Pay account (if this option is enabled, other methods are not displayed – only the "Buy with GPay" button is displayed on the payment page) | No |
applepay | Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account | No |
applepayonly | Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account (if this option is enabled, other methods are not displayed – only the "Apple Pay" button is displayed on the payment page) | No |
kyivstar | Payment from Kyivstar mobile account balance (for prepaid numbers only) | No |
installment | Installment payment | No |
Important! Due to internal security policies of Google and Apple,
Google Pay
andApple Pay
wallets can be unstable when opening a payment page in WebView.
For correct operation, we recommend direct integration of Google Pay and Apple Pay If you have an application, we recommend integrating SDKiOS, SDKAndroid
- installmentPlan – this block allows you to manage installment payments. If the parameters are not specified, but
installment=Y
is passed in thepaymentTypes
block, all available installment types with default settings will be displayed.
In order to be able to specify the number of installment months for the payer, it is necessary to add the installmentPlan block, the following array
"installmentPlan": {
"privat24": {
"parts": "3"
},
"oschad": {
"parts": "5"
},
"monobank": {
"parts": "8"
}
}
Parameter | Description | Required |
---|---|---|
privat24 | Payment in parts from PrivatBank | No |
oschad | Payment in parts from Oschadbank | No |
monobank | Payment in parts from Monobank | No |
parts | Sets the maximum number of months for installments | No |
Installment from Privat Bank
To display installments on the payment page, you need to pass the installment=Y
parameter in the paymentTypes
block and specify the order of method location in the priorityPaymentTypes
block, for example: "installment":"3"
An example of a payment in installments page from PrivatBank
An example of payment in installments from PrivatBank
To connect this method, the merchant must have an account in Privat Bank, and the payer must have a card.
Installment from Monobank
To display installments on the payment page, you need to pass the installment=Y
parameter in the paymentTypes
block and specify the order of method location in the priorityPaymentTypes
block, for example: "installment":"3"
To be able to transfer the payer's phone number, you need to transfer the parameter phoneNumber=635337143
in the format 635337143
in the payer
block
An example of a payment in installments page from Monobank
An example of payment in installments from Monobank
Installment from Oschadbank
To display installments on the payment page, you need to pass the installment=Y
parameter in the paymentTypes
block and specify the order of method location in the priorityPaymentTypes
block, for example: "installment":"3"
To be able to transfer the payer's phone number, you need to transfer the parameter phoneNumber=635337143
in the format 635337143
in the payer
block
An example of a payment in installments page from Oschadbank
- autopayment – this block allows you to set up automatic payments.
The automatic payments functionality allows customers to sign up for automatic monthly / quarterly / semiannual / annual charges. You can manage the client’s subscription parameters by yourself or provide the Client with the possibility to set up the parameters of autopayment.
To get started with automatic payments, you need to get credentials
in your Personal Area.
Important! When changing the password, the Partner must generate new
credentials
.
After setting up:
-
A subscription to automatic payments from a Client’s Card will be created. The Portmone.com system controls and processes payments. The Client can disable the service by contacting the Portmone.com customer support or an employee of the Online Store (you can delete the client's subscription in the Personal Area).
-
All subsequent payments will be made on the same
description
as the first payment. -
The order number for automatic payments will be formed as follows:
Order number at first payment_RECURENT_Date of automatic payment
Parameter | Description | Required |
---|---|---|
show | Displaying the details of the autopayment subscription to the client on the payment page. Possible values: Y – the client can go to a separate page and see the subscription details; N – the client is unable to view subscription details (only the "Make this payment regular" checkbox is displayed) (see fig. 1) | No |
edit | Editing automatic payment settings by client. Possible values: Y – all settings can be edited on the subscription details page, the client can save settings (see fig. 2); N – the automatic payment settings provided by the Online Store are displayed and cannot be edited | No |
settings | A block of parameters for setting up automatic payments | No |
credentials | Authorization parameters | Yes |
changeCheckboxState | value Y | Yes |
defaultCheckboxState | value: Y – the checkbox "Make payment regular" is autofilled,N – the client independently fills in the "Make regular payment" checkbox | No |
The settings
block structure:
Parameter | Description | Required |
---|---|---|
period | Frequency of automatic payments. Takes the following values: 1 – monthly, 2 – quarterly, 3 – semiannually, 4 – annually | Yes |
payDate | Day of the month for automatic payment. Can takes value from 1 to 28 | No |
startDate | Automatic payments start date. Should be sent in the following format: DD.MM.YYYY. If not specified, yesterday's date is automatically set | No |
endDate | Automatic payments end date. Should be sent in the following format: DD.MM.YYYY. If not specified, the startDate + 3 years is automatically set (or the current payment date is set, if startDate is not specified) | No |
amount | Amount of the payment. The decimal separator is the dot symbol (".") | Yes |
Fig. 1 – an example of payment page without displaying the details of the autopayment subscription
Fig. 2 – an example of displaying editable automatic payment parameters
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token (see section 4 "Order payment using a payment Token")
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take data processing into account) | Required for payment by Token |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Token value | Required for payment by Token |
cardMask | Card mask | Required for payment by Token |
otherPaymentMethods | Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable) | No |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
showEmail | "Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y") | No |
Depending on the sent values of the emailAddress
and showEmail
parameters, there are 4 options for displaying the "e-mail" field on the payment page:
Option | emailAddress | showEmail | Displaying on the payment page |
---|---|---|---|
1 | empty value | Y | An empty "e-mail" field is displayed |
2 | valid e-mail | Y | A prefilled "e-mail" field is displayed that can be edited |
3 | empty value | N | The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity |
4 | valid e-mail | N | The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity. However, the e-mail sent in the request is processed and a payment receipt is sent to it |
- shipping – this block contains shipping information
Parameter | Description | Required |
---|---|---|
services | Shipping services | Yes |
ukrposhta | Carrier name (name of the company that delivers the order to the recipient) | Yes |
deliveryTypes | Available delivery methods: W2D – courier delivery to the recipient's address; W2W – delivery to the carrier office/warehouse | Yes |
senderClientId | A unique identifier of the Online Store in the carrier system. Created in the merchant's Personal area | Yes |
senderAddressId | A unique identifier of the Online Store address in the carrier system. Created in the merchant's Personal area | Yes |
senderPostCode | Postal code of the sender | Yes |
type | Parcel delivery type. Possible values: STANDARD, EXPRESS | Yes |
parcelWeight | Parcel weight in grams. Maximum allowed value – 30000 | Yes |
parcelLength | The length of the largest side of the parcel stated in centimeters. Numbers only | Yes |
parcelWidth | The width of a parcel in centimeters | Yes |
parcelHeight | The height of a parcel in centimeters | Yes |
parcelDeclaredPrice | The declared cost of a parcel in UAH | Yes |
parcelDescription | Description of a parcel | No |
fragile | Parcel fragility mark. Possible values: Y, N | No |
checkOnDelivery | Checking the contents of the parcel on receiving is needed. Possible values: Y, N | No |
bees | Indicates that bees are sent. Possible values: Y, N | No |
payer | Indicates who pays for delivery – sender or recipient. Default value: client | Yes |
sms | Notify the client via SMS. Possible values: Y, N | No |
withDeliveryNotification | Notify the client using the notification service of the carrier company. Possible values: Y, N | No |
enable | Enable the displaying of delivery form. Possible values: Y, N | Yes |
required | Filling the delivery form is required. Possible values: Y, N | Yes |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "3.2 JSON order payment response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Payer’s Card mask |
ATTRIBUTE1 | Service field. Filled at company’s discretion |
ATTRIBUTE2 | Service field. Filled at company’s discretion |
ATTRIBUTE3 | Service field. Filled at company’s discretion |
ATTRIBUTE4 | Service field. Filled at company’s discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details. Maximum length is 250 symbols |
IPSTOKEN | A unique Visa token |
ERRORIPSCODE | Error code if Visa token was not created |
ERRORIPSMESSAGE | Error message if Visa token was not created |
3.3. Managing a view of a payment page
You can customize the view of the payment page using the style
parameter.
Description of the style
parameter fields:
Field | Description | Page style type, for which a field can be used |
---|---|---|
type | Sets the style type of a page: • portmone – default value (standard Portmone.com style, see fig. 3); • brand – full page styling for a partner (see fig. 4); • co-brand – partner’s logo is displayed on the page along with the Portmone.com logo (see fig. 5); • light – the version to display as a frame (see fig. 6). For instructions on how to embed the payment page in a frame, see below | |
logo | Contains a link to the partner's logo. Supports only link with https scheme. Image format is SVG and PNG only. It is recommended to use an image with a minimum plot indent from all edges | brand, co-brand |
logoWidth | Parameter defining the width of the logo. Should be entered in the "100px" format. Maximum recommended value is 300px | brand, co-brand |
logoHeight | Parameter defining the height of the logo. Should be entered in the "100px" format. Maximum recommended value is 50px (maximum height for PNG – 53px) | brand, co-brand |
backgroundColorHeader | Sets the colour of a header section on the page. The input format is HEX (for example, #ff0000) | brand, light |
backgroundColorButtons | Sets the colour of buttons. The input format is HEX (for example, #ff0000) | brand, light |
colorTextAndIcons | Sets text and icon colour. The input format is HEX (for example, #ff0000) | brand, light |
borderColorList | Sets the colour of lines in the list of payment methods. The input format is HEX (for example, #ff0000) | brand, light |
bcMain | Specifies the colour to fill page background. The input format is HEX (for example, #ff0000) | brand, light |
Embedding the payment page in a frame
To run IFRAME on your site, do the following:
- Organise the opportunity to send a payment request on your checkout page, for example, by plasing a form as following:
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="myFrame"
>
<input
type="hidden"
name="bodyRequest"
value='{
"paymentTypes":{"card":"Y","portmone":"Y","token":"N",
"clicktopay":"Y","createtokenonly":"N"},
"priorityPaymentTypes":{"card":"1","portmone":"2",
"token":"0","clicktopay":"1","createtokenonly":"0"},
"payee":{"payeeId":"3048","login":"","dt":"","signature":"", "shopSiteId":""},
"order":{"description":"Test Payment","shopOrderNumber":"SHP-00445401",
"billAmount":"10","attribute1":"1","attribute2":"2","attribute3":"3",
"attribute4":"4","attribute5":"","successUrl":"","failureUrl":"",
"preauthFlag":"N","billCurrency":"UAH", "encoding":""},
"token":{"tokenFlag":"N","returnToken":"N","token":"","cardMask":"",
"otherPaymentMethods":"Y","sellerToken":""},
"payer":{"lang":"uk", "emailAddress":"[email protected]"},
"style":{"type":"light","logo":"","backgroundColorHeader":"",
"backgroundColorButtons":"","colorTextAndIcons":"",
"borderColorList":"","bcMain":""}
}'
/>
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Portmone.com" />
</form>
Refer to section 3.2 "JSON request" to study the request structure and parameters.
To display a frame in the light style, you should set the value to light for the type
field of the style
parameter.
At the target
parameter of the form specify the frame in which the payment page will be displayed (in the example above, this is a frame called "myFrame").
- Add the IFRAME element to the DOM model of the page. The
name
parameter value must be equal to thetarget
parameter value from the previous step.
<div>
<iframe name="myFrame" width="50%" height="70%" frameborder="0" ></iframe>
</div>
You can customize the width
and the height
parameters of the frame as desired.
- After submitting the request, the response will be displayed in the specified frame.
Ways to display payment page
Fig. 3 – Portmone.com standard style
Fig. 4 – partner style for the entire page
Fig. 5 – partner’s logo is displayed on the page along with the Portmone.com logo
Fig. 6 – the version to display as a frame on the Online Store website
3.4. JSON request for PaymentGatewayCheckout
Description:
The service provides possibility to call a payment window without redirecting the client to the Portmone site. Clicking the Portmone payment button on the merchant's checkout page opens a modal window in which the customer enters payment information.
In order to place Portmone payment button on your checkout page, you have to determine a button location on the page and include some JS code.
Example:
<div class="span4">
<script src="https://www.portmone.com.ua/r3/resources/pg/js/asset/pg.min.js?v=15092019"></script>
<script type="text/javascript" id="portmone-script">
var data = {};
var brand = {
height: "40px",
width: "150px",
buttoncolor: "#FF0000",
fontfamily: "Open Sans",
textcolor: "#FFF",
lang: "uk",
padding: "5px",
border: "1px solid grey",
fontsize: "14px",
closemodal: "Y",
};
PG.success(function (data) {
console.log(JSON.stringify(data));
});
PG.paymentData("gateway", data);
PG.brandButton(brand);
</script>
</div>
After loading the pg.min.js script, the payment button will be located in the block in which the code for loading the script is placed.
Availability and restrictions:
No restrictions.
Request structure:
Parameters for generating JSON-structure of request:
The data
array describes the merchant's information, order data and payment methods (please, refer to "3.2 JSON order payment request" to see the array structure).
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | No |
shopOrderNumber | Number of a paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
preauthConfirm | Date of automatic withdrawal for payments with pre-authorization. Can be used when the preauthFlag = Y parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is confirmed automatically). It can not be less than the current date | No |
preauthReject | Date of automatic cancellation of pre-authorization. Can be used when the preauthFlag=Y parameter is passed in the request. Should be sent in the following format: YYYYMMDDHH24MISS (date and time after which the pre-authorization is cancelled automatically). It can not be less than the current date | No |
billCurrency | Currency of the payment. Default value: UAH | No |
expTime | Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1 | Service field. Filled at company’s discretion | No |
attribute2 | Service field. Filled at company’s discretion | No |
attribute3 | Service field. Filled at company’s discretion | No |
attribute4 | Service field. Filled at company’s discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
card | Payment by Card | No |
portmone | Payment via Portmone.com wallet | No |
token | Payment by Token (if this option is enabled, other methods are not displayed) | No |
clicktopay | Payment using Visa Click to Pay | No |
privat | Payment via LigPay, with choosing a card from the Privat24 Internet Banking | No |
gpay | Payment via Google Pay, with choosing a card from previously stored in the Google Pay account | No |
createtokenonly | Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card") | No |
gpayonly | Payment via Google Pay, with choosing a card from previously stored in the Google Pay account (if this option is enabled, other methods are not displayed – only the "Buy with GPay" button is displayed on the payment page) | No |
applepay | Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account | No |
applepayonly | Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account (if this option is enabled, other methods are not displayed – only the "Apple Pay" button is displayed on the payment page) | No |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token (see section 4 "Order payment using a payment Token")
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take data processing into account) | Required for payment by Token |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Token value | Required for payment by Token |
cardMask | Card mask | Required for payment by Token |
otherPaymentMethods | Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable) | No |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
showEmail | "Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y") | No |
Depending on the sent values of the emailAddress
and showEmail
parameters, there are 4 options for displaying the "e-mail" field on the payment page:
Option | emailAddress | showEmail | Displaying on the payment page |
---|---|---|---|
1 | empty value | Y | An empty "e-mail" field is displayed |
2 | valid e-mail | Y | A prefilled "e-mail" field is displayed that can be edited |
3 | empty value | N | The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity |
4 | valid e-mail | N | The "e-mail" field is not displayed on the payment page. While the payment page opens, no check is performed of whether the Merchant has sent the e-mail address and its validity. However, the e-mail sent in the request is processed and a payment receipt is sent to it |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
The brand
array is determine how the "Pay" button looks, that opens the modal window.
Parameter | Description | Required |
---|---|---|
height | Sets the button height. By default, it accepts the button style set on the page | No |
width | Sets the button width. By default, it accepts the button style set on the page | No |
buttoncolor | Sets the button colour. By default, it accepts the button style set on the page | No |
fontfamily | Sets the button font type. By default, it accepts the button style set on the page | No |
textcolor | Sets the button font colour. By default, it accepts the button style set on the page | No |
lang | Sets the language for displaying the text of the "Pay" / "Download receipt" button. Default value: uk – Ukrainian | No |
padding | Sets the value of the padding around the button's content. By default, it accepts the button style set on the page | No |
border | Allows you to specify the style, width and colour of the button's border. By default, it accepts the button style set on the page | No |
fontsize | Sets the button font size. By default, it accepts the button style set on the page | No |
closemodal | Determines whether to close a modal window after making a payment. If set to "N", the window is not closed and successful payment notification is displayed in the modal. If set to "Y", the window is closed and the payment data is sent to the merchant's processing function. The default value is "Y" | No |
Functions:
-
PG.success – this function takes the data object that describes the payment made. In case the Merchant does not process the data, the payment button changes its state and name, and payer can download the payment receipt upon clicking on it.
-
PG.brandButton – this function takes an object that describes and stylizes a payment button.
-
PG.paymentData – this function initializes and places the payment button on the Merchant's page.
This function takes the following parameters:
PG.paymentData(typePayment, data, typeView);
Where:
1) typePayment – a string that characterizes the payment type used. Can take the following values:
Value | Desctiption |
---|---|
gateway | This type of payment allows you to create and process a typical payment based on the transmitted data. The data object is generated as for a regular JSON-based request |
stock | This type of payment is used to process a payment based on the product identifier, which was created in the Merchant’s Personal Area. In this case the data object has the follwing structure: var data = { "id":"303429c03b3a743bdf8ee02" }; |
terminal | This type of payment saves the processing of the data object properties, which are transferred when paying using the terminal type, but allows you to leave billAmount , description , attribute1 , attribute2 , attribute3 , attribute4 fields blank to further initialization this data by the payer |
p2p | This type of payment allows you to process a payment with crediting funds to the Merchant's card, which has been verified and added to the Merchant's Personal Area. In this case the data object has the follwing structure: var data = { "hash":"" }; , where hash – value from the payment link |
2) typeView – а string that characterizes the modal window type:
- frame – opens the payment window in a frame (see fig. 7);
- modal – opens the payment window in a new browser window with the specified sizes (see fig. 8).
-
PG.create – this function creates a payment frame based on the data passed into the PG. paymentData function. The function can be used when Merchant creates its own mechanisms for calling a payment frame. Does not contain any parameters.
-
PG.setButtonId – this function can be used for cases when Merchant stylizes the frame call button himself and initializes his own text on the button. The function takes the
id
attribute used for the Merchant's button HTML element as an argument. For example:PG.setButtonId('paymentButton');
. After that, when the button is pressed, the Portmone payment frame opens to the Merchant.
This function should be used in combination with the PG.create function.
Example:
- a frame creating based on settings from the PG. paymentData function
PG.paymentData("gateway",data,"frame"); PG.create();
- Merchant's button id setting
PG.setButtonId('paymentButton');
Fig. 7 – an example of opening the payment window in a frame on the Online Store website
Fig. 8 – an example of opening the payment window in a new browser window with the specified sizes
Response structure:
If Merchant initialize the data processing on its side through the PG.success function after making a payment by the client, it is necessary to implement the processing of data that will be passed to the processing function.
Description of parameters passed to the processing function:
Parameter | Description |
---|---|
status | Transaction status. Takes the value PAYED |
errorCode | Error Code |
error | Remains unfilled |
shopBillId | A unique identifier (Id) assigned to every transaction (payment document) in the Portmone.com system |
billAmount | Amount of the payment |
shopOrderNumber | Number of paid order (bill) in the Merchant's system |
cardMask | Payer’s Card mask |
attribute1 | Service field |
attribute2 | Service field |
attribute3 | Service field |
attribute4 | Service field |
receiptLink | Link to get a receipt |
lang | Payment system interface language. Possible values: uk – Ukrainian, en – English |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
token | Card token |
commission | The value of the commission from payment |
payeeName | Merchant name |
billCurrency | Currency of the payment |
IPSTokenValue | A unique Visa token |
errorIPSCode | Error code if Visa token was not created |
errorIPSMessage | Error message if Visa token was not created |
3.5. Signature
The rule to create a value for the signature
field (example for PHP):
$login = 'wdishop';
$payeeId = '1185';
$password = 'wdi451';
$shopOrderNumber = 'test123';
$billAmount='150';
$key = 'BDFC166F8AE2F5323A557DB6CA16758D';
$dt = date("YmdHis");
$strToSignature = $payeeId.$dt.bin2hex($shopOrderNumber).$billAmount;
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));
Parameter | Description | Required |
---|---|---|
login | Логін компанії | Так |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
password | The Online Store password | Yes |
shopOrderNumber | Number of paid order (bill) in the Merchant's system | No |
billAmount | Amount of the payment | Yes |
key | The key that is provided to each Partner individually when connecting to the Portmone.com system | Yes |
dt | date | Yes |
The set of fields to create a
signature
may vary for different methods. In case of differences from the example above, the set of fields involved in thesignature
generation will be given directly in the description of the method.
3.6. Exchange rate
Description: This method allows you to get information about the exchange rate
Request should be sent at:https://www.portmone.com.ua/r3/api/gateway
Request structure:
Please, refer to "3.6 Exchange rate" to study the request structure.
Parameters for generating JSON-structure of request:
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
date | date | Yes |
Response structure:
Please, refer to "3.6 Exchange rate" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
key | Currency name |
value | exchange rate |
Important:
If the currency exchange rate is not set, an error is returned
"code": 500 "message": "Не знайдено курсу валют за вашими налаштуваннями. Зверніться до менеджера за уточненням деталей."
If the request is for an incorrect date, an error is returned
"code": 500 "message": "Не валідний параметр date. Формат для запиту: dd-mm-yyyy"
4. Order payment using a payment Token
4.1. Token creation
Description:
This method allows you to get a value of the Token and the Client’s card mask. After performing this payment method, you will get the Token value and the mask of the Client’s Payment Card, which you can offer to the Client as a payment method on your resource. In the process of performing token creation operation, Portmone.com will perform authorization hold for 1 hryvnia on the Client's card, with the subsequent return of this amount to the Client's card.
Request should be sent at: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
The description
field sent by this method is the key to further payments by Token. It must be the same for further transactions as was provided in the first transaction. If this parameter is changed in further payments by Token, Client will receive an error message.
Request structure:
Please, refer to "4.1 Token creation request" to study the request structure.
Parameters for generating JSON-structure of request:
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
Parameter | Description | Required |
---|---|---|
createtokenonly | To create a Token, you must set the value to "Y" for this parameter | Yes |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page
Parameter | Description | Required |
---|---|---|
createtokenonly | To create a Token, you must set the value to "1" for this parameter | Yes |
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | Required, identifies the Token in subsequent payments |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment (set the value to "1" (in UAH) to get the Token) | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
preauthFlag | Payment pre-authorization flag. Mandatory value to receive a Token – "N" (a regular payment without pre-authorization) | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1-4 | Service fields. Filled at company’s discretion | No |
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Required for payment by Token |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Token value | Leave empty |
cardMask | Card mask | Leave empty |
otherPaymentMethods | Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable) | Mandatory value is "N" |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "4.1 Token creation response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Payer’s Card mask |
ATTRIBUTE1 | Service field. Filled at company's discretion |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details. Maximum length is 250 symbols |
4.2. Payment by Token
4.2.1. POST request
Description:
To make a payment via Token you should send a request using the POST method to the payment gateway page – https://www.portmone.com.ua/r3/token/secure/token.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "4.2.1 Payment by Token. POST request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
payee_id | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store. Maximum length is 120 symbols |
bill_amount | Amount of the order. Currency – hryvnia (UAH). The decimal separator is the dot symbol "." |
description | Comment to the order / description of payment. Maximum length is 250 symbols |
application_url | The URL of the Online Store (internal URL of the mobile application) to which the client will be redirected after a successful card authorization. After successful payment of the order Portmone.com will send shop_order_number and the payment data to this address using the POST method |
lang | Payment system interface language. Possible values: uk – Ukrainian, en – English |
token | You must set the value of the token obtained in the previous step |
attribute1-4 | Service fields. Filled at company’s discretion |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") |
Response structure:
Please, refer to "4.2.1 Payment by Token. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
BILL_AMOUNT | Transaction amount sent in request |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
RECEIPT_URL | Link to get a receipt |
TOKEN | Token value for subsequent payments |
CARD_PAYMENT_SYSTEM | The value of the payment system (VISA, MASTERCARD, PROSTIR) |
CARD_LAST_DIGITS | Last 4 digits of Payment Card number |
RESULT | The result of the operation (if successful = 0) |
4.2.2. JSON request
Description:
To make a payment via Token you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "4.2.2 Payment by Token. JSON request" to study the request structure.
Parameters to generate the data:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | No |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1 | Service field. Filled at company's discretion | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
card | Payment by Card | No |
portmone | Payment via Portmone.com wallet | No |
token | Payment by Token (if this option is enabled, other methods are not displayed) | No |
clicktopay | Payment using Visa Click to Pay | No |
qr | Adds a tab to generate payment QR-code | No |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Yes |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Token value | Yes |
cardMask | Card mask | Yes |
otherPaymentMethods | Allows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable) | No |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "4.2.2 Payment by Token. Example of successful response to the JSON request" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Payer’s Card mask |
ATTRIBUTE1 | Service field. Filled at company's discretion |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details. Maximum length is 250 symbols |
4.3. Payment by Token without CVV2 (recurring payment)
Description:
To make a payment by Token without CVV2 you should send a request to the following URL: https://www.portmone.com.ua/r3/recurrent/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "4.3 Recurring payment request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
login | The Online Store login to access account management |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
token | You must set the value of the token obtained in the previous step |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
billAmount | Amount of the payment. The decimal separator is the dot symbol "." |
billCurrency | Currency of the payment. Default value: UAH |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) |
id | ID of the request from the Online Store to the Portmone.com system |
Response structure:
Please, refer to "4.3 Recurring payment request" to study the response structure
Response parameters description:
Parameter | Description |
---|---|
result | Order status attribute. Possible values: PAYED, CREATED, REJECTED. |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
id | ID of the request from the Online Store to the Portmone.com system |
Important! If you receive an error on a token request, we recommend making the next request no earlier than 72 hours later.
4.4. Forming an order (payment message) in Viber Bot
Description:
A request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.
Availability and restrictions:
Operation is possible only for those users who are registered in Portmone Viber Bot.
JSON request structure:
{
"method":"initViberPayment",
"params":{
"data":{
"payeeId":"11344",
"billAmount":"1",
"shopOrderNumber":"shp_0001",
"description":"test",
"msisdnClient":"+380630000000",
"paymentMessage":"test message",
"attribute1":"",
"attribute2":"",
"attribute3":"",
"attribute4":"",
"attribute5":"",
"preauthFlag":"N",
"emailAddress":"[email protected]",
"credentials":""
}
},
"id":"1"
}
Request parameters description:
Parameter | Description |
---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
billAmount | Amount of the payment. The decimal separator is the dot symbol “.” |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
msisdnClient | Client's phone number |
paymentMessage | Message for the client in Viber Bot. Maximum 250 symbols |
attribute1, attribute2, attribute3, attribute4, attribute5 | Attributes of the operation, optional |
preauthFlag | Should be N |
emailAddress | Client's Email |
credentials | Required authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptions |
id | ID of the request from the Online Store to the Portmone.com system |
Response structure:
{
"result": {
"errorCode": "0",
"error": "",
"linkqr": "",
"linkbot": ""
},
"id": "1"
}
Response parameters description:
Parameter | Description |
---|---|
errorCode | Error code |
error | Error description is empty in case of a successful response. If the client was not found, the text "Client not found" will be returned |
linkqr | Link to the QR code of the chat bot |
linkbot | Link to the chat bot |
id | ID of the request from the Online Store to the Portmone.com system |
4.5. Getting IPS data by Portmone token
Description:
The request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.
Availability and restrictions:
Available after a card payment is made.
JSON request structure:
{
"method":"getDataTokenIPS",
"params":{
"data":{
"login":${MERCHANT_LOGIN},
"password":${MERCHANT_PASSWORD},
"tokenType":"PORTMONE",
"tokenReference":${TOKEN_REFERENCE}
}
},
"id":"1"
}
Request parameters description:
Parameter | Description |
---|---|
MERCHANT_LOGIN | Merchant's login in the Portmone system |
MERCHANT_PASSWORD | Merchant's password in the Portmone system |
TOKEN_REFERENCE | Card token, returned by the Portmone system |
Response structure and example (Mastercard):
{
"result": {
"token_type": "M4M",
"token_info": {
"tokenUniqueReference": "DM4MMC0000****ed8d7249e",
"panUniqueReference": "FM4MMC000012971373*****6a75a3cf",
"productConfig": {
"termsAndConditionsUrl": "",
"issuerName": ",
"cardBackgroundCombinedAssetId": "954e89****8655a",
"iconAssetId": "7fcf53be****cf1fbfe",
"foregroundColor": "ffffff",
"issuerLogoAssetId": "cd90eb72****5cc1",
"shortDescription": "",
"customerServiceEmail": "",
"customerServicePhoneNumber": "",
"customerServiceUrl": "",
"isCoBranded": "false",
"brandLogoAssetId": "3789637f****c509"
},
"tokenInfo": {
"tokenPanSuffix": "4444",
"accountPanSuffix": "4444",
"tokenExpiry": "0823",
"accountPanExpiry": "",
"productCategory": "DEBIT",
"dsrpCapable": true,
"tokenAssuranceLevel": ""
}
}
},
"id": "1"
}
Response key parameters description:
Parameter | Description |
---|---|
TOKEN_TYPE | Token type depending on the IPS |
id | Unique response ID |
Response structure and example (Visa):
{
"result": {
"token_type": "VTS",
"token_info": {
"vPanEnrollmentID": "724bfc****38701",
"paymentInstrument": {
"expirationDate": {
"month": "11",
"year": "2023"
},
"last4": "1111",
"cvv2PrintedInd": "Y",
"expDatePrintedInd": "Y",
"enabledServices": {
"merchantPresentedQR": "N"
}
},
"cardMetaData": {
"backgroundColor": "0xffff00",
"foregroundColor": "0x000000",
"labelColor": "0x000000",
"contactWebsite": "https://www.aval.ua",
"contactEmail": "[email protected]",
"contactNumber": "+380444908888",
"contactName": "Raiffeisen Bank Aval",
"privacyPolicyURL": "https://www.aval.ua/storage/files/politika-konfidencijnosti-04042019_1554448866.pdf",
"termsAndConditionsURL": "https://aval.ua/storage/files/wallet-pi.pdf",
"shortDescription": "Visa Classic",
"cardData": [
{
"guid": "8407fa4e5****d705f6cb07",
"contentType": "cardSymbol",
"content": [
{
"mimeType": "image/png",
"width": "100",
"height": "100"
}
]
},
{
"guid": "09e037d****c17995ddf6",
"contentType": "digitalCardArt",
"content": [
{
"mimeType": "image/png",
"width": "1536",
"height": "969"
}
]
}
],
"issuerFlags": {
"deviceBinding": false,
"cardholderVerification": false,
"trustedBeneficiaryEnrollment": false,
"delegatedAuthenticationSupported": true
}
},
"vProvisionedTokenID": "ebc77cd5****bcc8885e01",
"tokenInfo": {
"tokenRequestorID": "1111111111",
"tokenStatus": "ACTIVE",
"last4": "",
"expirationDate": {
"month": "",
"year": ""
}
}
}
},
"id": "1"
}
Response key parameters description:
Parameter | Description |
---|---|
TOKEN_TYPE | Token type depending on the IPS |
id | Unique response ID |
tokenInfo, cardMetaData, cardData | Card meta data |
4.6. Getting an asset by the unique IPS ID
Description:
The request must be sent to the URL: https://www.portmone.com.ua/r3/api/gateway.
Availability and restrictions:
Available after getting the IPS ID using getDataTokenIPS method according to p. 4.5. For getting an asset of each type it is necessary to make unique request containing the corresponding ID.
JSON request structure and example:
{
"method":"getMetaDataTokenIPS",
"params":{
"data":{
"login":${MERCHANT_LOGIN},
"password":${MERCHANT_PASSWORD},
"tokenType":${TOKEN_TYPE},
"metaDataId":${ASSET_ID}
}
},
"id":"1"
}
Request parameters description:
Parameter | Description |
---|---|
MERCHANT_LOGIN | Merchant’s login in the Portmone system |
MERCHANT_PASSWORD | Merchant’s password in the Portmone system |
TOKEN_TYPE | Token type received using getDataTokenIPS method according to p. 4.5 |
ASSET_ID: | Asset ID received using getDataTokenIPS method according to p. 4.5 (AssetId\guid) |
Response structure and example:
{
"result": {
"mediaContents": [
{
"data": "", //Base64 encoded content
"width": 1536,
"type": "image\/png",
"height": 969
}
]
},
"id": "1"
}
4.7. Payment by Token with 3D Secure without CVV2 (recurring payment)
Description:
To make a payment by Token without CVV2 you should send a request to the following URL: https://www.portmone.com.ua/r3/recurrent/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "4.7 Recurring payment request" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
method | Value: paywith3ds | Yes |
password | The Online Store password | Yes |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols | No |
token | You must set the value of the token obtained in the previous step | Yes |
description | Comment to the order / description of payment details. Maximum length is 250 symbols | Yes |
billAmount | Amount of the payment. The decimal separator is the dot symbol "." | Yes |
billCurrency | Currency of the payment. Default value: UAH | No |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
attribute1 | Service field. Filled at company's discretion | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
id | ID of the request from the Online Store to the Portmone.com system | Yes |
Response structure if 3D Secure check is required:
Please, refer to "4.7.1 response if 3D Secure check is required" to study the response structure
Response parameters description:
Parameter | Description |
---|---|
status | Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. |
shopbillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
pdfUrl | It remains empty |
authCode | Bank authorization code (added if the order is paid) |
isNeed3DS | 3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required) |
actionMPI | The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure |
id | ID of the request from the Online Store to the Portmone.com system |
Response structure:
Please, refer to "4.7.2 Response to return after 3D Secure" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
shopbillId | Order ID in the Portmone.com system |
status | Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. |
billAmount | Amount of the payment. The decimal separator is the dot symbol "." |
billNumber | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
payeeName | |
authCode | Bank authorization code (added if the order is paid) |
commission | The value of the commission from payment |
pdfUrl | It remains empty |
payeeId | A unique identifier of the Online Store |
payDate | Date of payment |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
cardMask | Card mask |
errorMessage | Error message |
errorCode | Error code |
A successful response structure when no 3Ds need to be passed:
Please, refer to "4.7.3 successful response" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
status | Order status.Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. |
shopbillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
description | Comment to the order / description of payment details. Maximum length is 250 symbols |
pdfUrl | Link to receipt |
authCode | Bank authorization code (added if the order is paid) |
isNeed3DS | 3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required |
actionMPI | The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure |
id | ID of the request from the Online Store to the Portmone.com system |
Structure of a failed response:
Please, refer to "4.7.4 failed response" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
Code | Error code |
Message | Error message |
id | ID of the request from the Online Store to the Portmone.com system |
4.8 Token payment with the appearance of the card without CVV2
Description:
To make Token payment with the appearance of the card without CVV2 a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "4.8 Payment by Token. JSON request" to study the request structure.
Parameters to generate the data:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
credentials | Required authorization data, can be obtained as a hash string here (in the cabinet) - https://www.portmone.com.ua/b2b_dash/request/subscriptions | Yes |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | No |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1 | Service field. Filled at company's discretion | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
token | Payment by Token (if this option is enabled, other methods are not displayed) | Yes |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Yes |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Token value | Yes |
cardMask | Card mask | Yes |
otherPaymentMethods | Allows you to enable other payment methods when the Token is passed ("N" - disable, "Y" - enable) | No |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
showEmail | "Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y") | No |
5. Money transfer from card to card
The Portmone.com payment system makes it possible to transfer money from card to card of any Ukrainian bank.
The transfer can be made:
- Between Card Tokens without entering sender and recipient card numbers (sender Card Token and recipient Card Token are created one-time in advance).
Interaction scheme:
-
The sender (Client) performs one-off registration of his card in the Portmome.com system (performs a transaction for 1 UAH with the subsequent return of this amount to the Client's card within 30 minutes). The Online Store receives an identifier (Token) of this Card, which can be stored in its system (see section 5.1. "Card token receiving").
-
The recipient (Client or Merchant) performs one-off registration of his card in the Portmome.com system (performs a transaction for 1 UAH with the subsequent return of this amount to the Client's card within 30 minutes). The Online Store receives an identifier (Token) of this Card, which can be stored in its system (see section 5.1. "Card token receiving").
-
When the sender wants to transfer money to the recipient, the Online Store sends a request in JSON-format to the Portmone.com system with the following information: the sender's Card Token and the sender's Card mask, the recipient Card Token and the recipient Card mask, and the amount of payment (see section 5.2. "Creating a request to transfer funds between card tokens").
2. From the sender's Card Token to the recipient's Card number (see section 5.3 "Request to transfer funds from token to card").
3. From the sender's Card Token to the current account and from the current account to the recipient's Card Token (see section 5.4 "Transfer of funds from card to account and from account to card").
5.1. Card token receiving
Description:
To receive a Token (for any of the participants – both for the sender and for the recipient) you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "5.1 Token creation request" to study the request structure.
Parameters for generating JSON-structure of the request:
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
Parameter | Description | Required |
---|---|---|
createtokenonly | To create a Token, set the value to "Y" for this parameter | Yes |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order / payment details) | No |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment (to receive the Token the value should be set to 1 UAH) | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute2-4 | Service fields. Filled at company’s discretion | No |
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Mandatory value is "N" |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | Mandatory value is "Y" |
token | Token value | Leave empty |
cardMask | Card mask | Leave empty |
otherPaymentMethods | Allows you to enable other payment methods when the Token is sent ("N" – disable, "Y" – enable) | Mandatory value is "N" |
sellerToken | Recipient’s Card Token | Leave empty |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | E-mail address of the payer | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "5.1 Token creation response" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of paid order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Card mask |
ATTRIBUTE1 | Service field. Filled at company's discretion |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details. Maximum length is 250 symbols |
5.2. Creating a request to transfer funds between card tokens
Description:
To transfer funds from the sender’s card Token to the recipient’s card Token you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "5.2 Request to transfer funds between card tokens" to study the request structure.
Request parameters description:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Recipient’s Card mask | Yes |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
card | Payment by Card | No |
portmone | Payment via Portmone.com wallet | No |
token | Payment by Token (if this option is enabled, other methods are not displayed) | No |
clicktopay | Payment using Click to Pay | No |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Yes |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Sender’s card Token value | Yes |
cardMask | Sender’s card mask | Yes |
otherPaymentMethods | Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable) | No |
sellerToken | Recipient’s card Token | Yes |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
5.3. Request to transfer funds from token to card
Description:
The method allows you to transfer money from the sender's Card Token to the recipient's Card number.
To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
When calling the method, the Portmone.com payment page opens, where the Client enters the recipient’s Card number, CVV-code of the sender’s Card and Surname First name of the sender.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "5.3 Request to transfer funds from token to card" to study the request structure.
Request parameters description:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
checkParams | The value should be set to "Y" for this parameter | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Recipient’s card number | No |
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
Parameter | Description | Required |
---|---|---|
token | Transfer from Token to Card | Yes |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Yes |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Sender’s card Token value | Yes |
cardMask | Sender’s card mask | Yes |
otherPaymentMethods | Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable) | Yes |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "5.3 Transfer of funds from token to card. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Sender's card mask |
ATTRIBUTE1 | Service field. |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Recipient’s card mask |
5.4. Transfer of funds from card to account and from account to card
The method allows you to perform money transfer between sender's and recipient's cards tokens in two steps (from the sender's card Token to the current account and from the current account to the recipient's card Token).
5.4.1. Transfer from the sender's card token to account
Description:
To transfer funds you should send request to the following URL: https://www.portmone.com.ua/gateway/.
When calling the method, the Portmone.com payment page opens, where the Client enters CVV-code of the sender’s Card and submit the form to confirm the transfer.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "5.4.1 Request to transfer funds from card token to account" to study the request structure.
Request parameters description:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
checkParams | The value should be set to "N" for this parameter | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
shopOrderNumber | Number of paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
billCurrency | Currency of the payment. Default value: UAH | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute2 | Service field. Filled at company's discretion | No |
attribute3 | Service field. Filled at company's discretion | No |
attribute4 | Service field. Filled at company's discretion | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable).
Parameter | Description | Required |
---|---|---|
token | Transfer from Token to account | Yes |
- priorityPaymentTypes – this block allows you to manage placement of payment methods on a page. If the value near the payment method name is 0, a tab with the payment method is not displayed, otherwise is placed in ascending order: 1 – at the top of the list, 2 – at the second position, 3 – at the third position, etc.
Important! In
paymentTypes
the payment method must have the "Y" value, in thepriorityPaymentTypes
it must have a numeric value other than 0 ("0" disables the display on the payment page).
- token – settings to work with a Token
Parameter | Description | Required |
---|---|---|
tokenFlag | Enables payment by Token ("N" – do not enable, "Y" – take the data processing into account) | Yes |
returnToken | "Y" – enables the option to return the Token to the partner on the success page, "N" or empty value – the Token is not returned on the success page | No |
token | Sender’s card Token value | Yes |
cardMask | Sender’s card mask | Yes |
otherPaymentMethods | Allows you to enable other payment methods when the Token is passed ("N" – disable, "Y" – enable) | Yes |
- payer – this block describes payer settings
Parameter | Description | Required |
---|---|---|
lang | Payment page interface language. Possible values: uk – Ukrainian, en – English | No |
emailAddress | Email address of the payer | No |
showEmail | "Y" or empty value – enables displaying the "e-mail" field on the payment page, "N" – hides the "e-mail" field on the payment page (default value is "Y") | No |
- style – setup of payment page styles (see section 3.3. "Managing a view of a payment page").
Response structure:
Please, refer to "5.4.1 Transfer of funds from card token to account. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Sender’s card mask |
ATTRIBUTE1 | Service field. |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Comment to the order / description of payment details |
5.4.2. Transfer from account to the recipient's card token
Description:
The Merchant initiates transfer of funds from the current account to the recipient's Card Token.
To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "5.4.2 Request to transfer funds from account to card token" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the procedure for transferring funds from the account to recipient's Card Token. Value: confirmp2p |
login | The Online Store login |
password | The Online Store password |
shopBillId | Order number in the Portmone.com system (should be obtained from the response to the request described in section 5.4.1 "Transfer from the sender's card token to account") |
token | Recipient's card Token, for which funds should be credited |
id | ID of the request from the Online Store to the Portmone.com system |
Response structure:
Please, refer to "5.4.2 Transfer of funds from account to card token. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
SHOPBILLID | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
SHOPORDERNUMBER | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
APPROVALCODE | Authorization code |
BILL_AMOUNT | Transaction amount sent in request |
TOKEN | Token value for subsequent payments |
RESULT | The result of the operation (if successful = 0) |
CARD_MASK | Sender’s card mask |
ATTRIBUTE1 | Service field. |
ATTRIBUTE2 | Service field. Filled at company's discretion |
ATTRIBUTE3 | Service field. Filled at company's discretion |
ATTRIBUTE4 | Service field. Filled at company's discretion |
RECEIPT_URL | Link to get a receipt |
LANG | Payment system interface language. Possible values: uk – Ukrainian, en – English |
DESCRIPTION | Recipient's card mask |
6. Payments with pre-authorization
6.1. Pre-authorization of payment (funds blocking)
The Portmone.com payment system allows you to make payments with pre-authorization.
Pre-authorization is blocking of funds on the customer's Card without actual financial withdrawal of funds from the Client’s account. In order for funds to be withdrawn from the Card and transferred to the Merchant, the latter has to send a payment confirmation request for each pre-authorization (perform post-authorization procedure, see section 6.2 "Confirmation of payment made with pre-authorization"). Thus, payment for a product/service with pre-authorization consists of consecutive operations within a single order – Blocking funds on the Card, Obtaining the results of a transaction in the Portmone.com system, and the Post-authorization procedure.
** Important! **According the rules of International payment system such as Visa and MasterCard you block money only on a 7 days. After this period issue bank could unblock money and you will not have an opportunity to confirm
To preauthorize the payment Merchant should pass the preauth_flag=Y
parameter in POST request (the preauthFlag = Y
parameter for JSON request). For description of request format and parameters see section 3 "Order payment".
6.2. Confirmation of payment made with pre-authorization (post-authorization procedure)
6.2.1. POST request
Description:
To complete payments with pre-authorization (payments for which the preauth_flag = Y
parameter was used), a post-authorization procedure should be performed.
URL for the request: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "6.2.1 Post-authorization procedure. POST request" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
method | Value: preauth | Yes |
login | The Online Store login | Yes |
password | The Online Store password | Yes |
action | The identifier of the action that must be performed for this order – confirmation of the funds blocking (possibly with the amount change). Value: set_paid | Yes |
shop_bill_id | Number of the order in the Portmone.com system (should be obtained using the result method described in section 8.2 "Authorization results request") | No |
postauth_amount | Amount of payment. Sent if action = set_paid . It cannot exceed the amount for which pre-authorization was carried out | |
encoding | Encoding | No |
lang | Error messages language | No |
Response structure:
Please, refer to "6.2.1 Response for post-authorization procedure (successful)" to study the response structure.
The <request>
result section can be used for debugging – tags correspond to actually received request parameters. If there is no tag in <request>
, it means that this parameter was not sent in the request.
If error occurs when calling a method (for example, incorrect login, etc.), the <order>
section will consist of two tags only – <error_code>
and <error_message>
(see "6.2.1 Response for post-authorization procedure (failure)").
6.2.2. JSON request
Description:
To confirm the payment you should send the request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "6.2.2 Post-authorization procedure. JSON request" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
method | Value: confirmPreauth | Yes |
login | The Online Store login to access account management | Yes |
password | The Online Store password | Yes |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | No |
shopbillId | Order ID in the Portmone.com system. Optional parameter | No |
postauthAmount | Amount of payment. It cannot exceed the amount for which pre-authorization was carried out | Yes |
distribution | Distribution of pre-authorization. Provides an opportunity to confirm a smaller number of recipients than was the case when requesting payment (clause 7 of split payment) | Yes |
id | ID of the request from the Online Store to the Portmone.com system | Yes |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "6.2.2 Response format" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
shop_bill_id | Order ID in the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store. Maximum length is 120 symbols |
description | Order description |
bill_date | Bill date |
pay_date | Payment date |
pay_order_date | Bank memorial order date |
bill_amount | Bill amount |
auth_code | Bank authorization code |
status | Order status |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
error_code | Error code |
error_message | Error message |
6.3. Cancellation of payment with pre-authorization
6.3.1. POST request
Description:
To cancel a payment with pre-authorization you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "6.3.1 Cancellation of payment with pre-authorization. POST request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the post-authorization procedure. Value: preauth |
login | The Online Store login |
password | The Online Store password |
action | The identifier of the action that must be performed for this order – rejection of the funds blocking. Value: reject |
shop_bill_id | Order number in the Portmone.com system (should be obtained using the result method described in section 8.2. "Authorization results request") |
encoding | Encoding |
lang | Error messages language |
Response structure:
Please, refer to "6.3.1 Response for cancellation of payment with pre-authorization (POST request)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
shop_bill_id | Order ID in the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store. Maximum length is 120 symbols |
description | Order description |
bill_date | Bill date |
pay_date | Payment date |
pay_order_date | Bank memorial order date |
bill_amount | Bill amount |
auth_code | Bank authorization code |
status | Order status |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
error_code | Error code |
error_message | Error message |
6.3.2. JSON request
Description:
To cancel a payment you should send a request to the following address: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "6.3.2 Cancellation of payment with pre-authorization. JSON request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the cancellation of payment with pre-authorization procedure. Value: rejectPreauth |
login | The Online Store login |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
shopbillId | Order ID in the Portmone.com system. Optional parameter |
id | ID of the request from the Online Store to the Portmone.com system |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "6.3.2 Cancellation of payment with pre-authorization. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
shop_bill_id | Order ID in the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store. Maximum length is 120 symbols |
description | Order description |
bill_amount | Bill amount |
status | Order status |
bank_id | name of bank |
terminal_id | terminal id in the bank |
merchant_id | merchant id in the bank |
rrn | identificator of transaction in banks system |
auth_code | Bank authorization code |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
error_code | Error code |
error_message | Error message |
7. Splitting the payment
The Portmone.com system allows you to split a single payment made by card for multiple recipients (legal entities). First, the full amount is withdrawn from the Client's Card, then the transfer is made with separate transactions to each recipient's account which you've sent in the request. Splitting the payment is available for recipient companies registered in Portmone.com system.
Interaction scheme:
-
Each of the recipient companies registers in the Portmone.com system.
-
The Client makes an order on the Main Company's website.
-
The Main Company (the company that initiates the split) sends the split parameters in the
attribute 5
field of the payment request:• description of the order for each of the recipients (
Desc
);• company's Id for each of the recipients (
payeeID
);• amount, which needs to be enrolled to each recipient's account (
amount
).
The attribute5
field is filled in the next format:
Desc1:payeeID1;amount1;Desc2:payeeID2;amount2;...
The number of recipient companies for a single payment request with splitting is limited to the length of the line (up to 500 characters).
- Portmone.com sends the Main Company an XML-message with the authorization result for the full amount of the order.
Request structure:
This request is similar to standard payment by card/payment by token requests, but should also contain additional data with information on how to split a payment in the attribute 5
field.
Please, refer to "7 Split payment request" to study the request example.
8. Getting authorization results
Online Stores can receive authorization results in several ways:
- when Client returns to Merchant’s website after payment;
- at Merchant’s Personal Area: https://www.portmone.com.ua/b2b_dash/;
- by sending XML-request to the Portmone.com system;
- by XML-message from the Portmone.com system to the Online Store with the result of authorization (XML-notification of payment);
- by XML-message from the Portmone.com system to the Online Store about a payment order (XML-notification of transactions financial coverage);
- by email messages.
8.1. Getting statements with authorization results in the Personal Area
Personal Area of the Portmone.com payment system is a specialized site with a set of pages and interactive forms, where the authorized user can receive necessary information and carry out other operations in the Portmone.com system.
For authorization in the Personal Area, go to https://www.portmone.com.ua/b2b_dash and enter your login and password in the window that appears. Credentials (login and password) to access your Personal Area can be obtained from Portmone.com by request (phone or email).
Information about operations can be obtained at the "Orders" page. The statement can be formed for any period of time, by filtering transactions by availability of a payment document, order number, operation result (all, successful, failure or returns) or authorization code.
8.2. Authorization results request
8.2.1. POST request
Description:
To receive payment status you should send a POST request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
The maximum request period should not exceed 31 days.
Request structure:
Please, refer to "8.2.1 POST authorization results request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the report generation procedure. Value: result |
payee_id | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
login | The Online Store login to access account management |
password | The Online Store password |
shop_order_number | Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers |
status | Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected, - RETURN – returned. By default, orders with all types of statuses are selected. |
start_date | Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month |
end_date | End date of the report in dd.mm.yyyy format. By default, it’s the current date |
Response structure:
Please, refer to "8.2.1 POST authorization results response" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
shop_bill_id | Order ID in the Portmone.com system |
shop_order_number | Number of paid order (bill) in the Online Store |
description | Order description |
bill_date | Bill date |
pay_date | Payment date |
bill_amount | Bill amount |
auth_code | Bank authorization code (added if the order is paid) |
status | Order status |
error_code | Error code |
error_message | Error message |
8.2.2. JSON request
Description:
To receive payment status or a list of transactions for a company you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "8.2.2 JSON authorization results request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the report generation procedure. Value: result |
login | The Online Store login to access account management |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers |
shopbillId | Order ID in the Portmone.com system. Optional parameter |
status | Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. By default, orders with all types of statuses are selected. |
start_date | Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month |
end_date | End date of the report in dd.mm.yyyy format. By default, it’s the current date |
id | Id of the request from the Online Store to the Portmone.com system |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "8.2.2 JSON authorization results response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
payeeId | A unique identifier of the Online Store |
description | Order description |
status | Order status |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
attribute5 | shows payment splitting |
distribution_payee_id | shows payment splitting |
commission | The value of the refunded commission from payment |
bank_id | name of bank |
terminal_id | terminal id in the bank |
merchant_id | merchant id in the bank |
rrn | identificator of transaction in banks system |
pay_date | Payment date |
payee_export_date | Date of sending the payment amount / payment notification to the Partner |
payee_export_flag | With successful payment takes the value Y |
chargeback | Whether the chargeback was claimed for transaction or not |
payee_name | Name of the merchant |
payee_commission | Commissar from the merchant |
pay_order_date | Bank memorial order date |
pay_order_number | Account number |
pay_order_amount | Bill amount |
shopBillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store |
billAmount | Bill amount |
errorCode | Error code |
errorMessage | Error message |
authCode | Bank authorization code (added if the order is paid) |
cardMask | Payer’s Card mask |
cardBankName | Name of the issuing bank |
token | Token value for subsequent payments |
payeeExportResult | Description of the error |
gateType | Payment method identifier |
cardTypeName | The name of IPS |
8.2.2.1. Request for authorization results when using installment payments from Monobank in JSON format
Description:
To receive payment status or a list of transactions for a company you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
To be able to make a request, it is necessary to send a corresponding letter from the registered e-mail address to the managers of Portmone.com for cooperation with online stores at the address [email protected]
Request structure:
Please, refer to "8.2.2.1 JSON authorization results request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the report generation procedure. Value: result |
login | The Online Store login to access account management |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of an order in the Online Store. If you do not specify this value, orders will be selected without reference to their numbers |
shopbillId | Order ID in the Portmone.com system. Optional parameter |
status | Status of the order to be included in the report. Possible values: - PAYED – paid, - CREATED – created, - REJECTED – rejected. By default, orders with all types of statuses are selected. |
start_date | Start date of the report in dd.mm.yyyy format. By default, it’s the current date of the last month |
end_date | End date of the report in dd.mm.yyyy format. By default, it’s the current date |
id | Id of the request from the Online Store to the Portmone.com system |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "8.2.2.1 JSON authorization results response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
description | Order description |
status | Order status |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
commission | The value of the refunded commission from payment |
bank_id | name of bank |
terminal_id | terminal id in the bank |
merchant_id | merchant id in the bank |
rrn | identificator of transaction in banks system |
pay_date | Payment date |
payee_export_date | Date of sending the payment amount / payment notification to the Partner |
pay_order_date | Bank memorial order date |
chargeback | Whether the chargeback was claimed for transaction or not |
payee_commission | Commissar from the merchant |
payee_name | Name of the merchant |
shopBillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store |
billAmount | Bill amount |
errorCode | Error code |
errorMessage | Error message |
authCode | Bank authorization code (added if the order is paid) |
cardMask | Payer’s Card mask |
token | Token value for subsequent payments |
gateType | Payment method identifier |
8.3. Notification of the Online Store server about the authorization result
Notification for successful payment – BILLS message
Description:
The system of XML-messages transferred by HTTPS protocol is used to exchange the information. The Portmone.com system is always the initiator of such exchange. The company shall provide URL-address to which the Portmone.com system will send XML-messages using POST method via data
parameter.
Example:
data=<?xml version="1.0" encoding="UTF-8"?><BILLS> …..
The BILLS message is sent by Portmone.com to the company in case of successful transaction. Intended to receive information about the accepted payment, without waiting for the funds to be transferred to the company’s current account. Message contains information about a single paid bill.
Message structure:
Please, refer to "8.3 Notification for successful payment – BILLS message" to study the message structure.
Message BILLS – fields description:
Field name | Data type | Description |
---|---|---|
PAYEE\NAME | CHAR(100) | Name of a payee’s company |
PAYEE\CODE | NUMBER(15,0) | Company code (provided by Portmone.com system) |
BANK\NAME | CHAR(100) | Name of sender's bank |
BANK\CODE | CHAR(6) | MFO of sender's bank. When the IBAN account number is used in payment details, a "0" (zero) is transferred in the BANK\CODE field |
BANK\ACCOUNT | CHAR(29) | Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document) |
BILL_ID | NUMBER(15,0) | Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID .It is equal to the SHOPBILLID parameter (see section 3 "Order payment"). |
BILL_NUMBER | CHAR(120) | Bill number. It is equal to the shop_order_number parameter (if sent; see section 3 "Order payment"). |
BILL_DATE | CHAR(10) | Bill date in YYYY-MM-DD format |
BILL_PERIOD | CHAR(4) | Bill period in MMYY (month and year) format |
PAY_DATE | CHAR(10) | Date of payment in YYYY-MM-DD format |
PAYED_AMOUNT | NUMBER(15,2) | Amount of payment. Use dot (".") as the decimal separator |
PAYED_COMMISSION | NUMBER(15,2) | Commissar from the merchant |
PAYED_DEBT | NUMBER(15,2) | Including payment of debt. Use dot (".") as the decimal separator |
AUTH_CODE | CHAR(6) | Authorization code for a payment card |
CONTRACT_NUMBER | CHAR(20) | Parameter by which the company and the Portmone.com system agreed to identify the client |
ATTRIBUTE1 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE2 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE3 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE4 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
Examples:
See "8.3 BILLS message example".
Notification about bank payment – PAY_ORDERS message
Description:
The system of XML-messages transferred by HTTPS protocol is used to exchange the information. The Portmone.com system is always the initiator of such exchange. The company shall provide URL-address to which the Portmone.com system will send XML-messages using POST method via data
parameter.
Example:
data=<?xml version="1.0" encoding="UTF-8"?><PAY_ORDERS> …..
The PAY_ORDERS message is sent by the Portmone.com system to the company and contains information about bank payments. This message is used to compare BILLS messages with funds transferred by the bank to the current account of the company. It contains information about a single paid bill.
Message structure:
Please, refer to "8.3 Notification about bank payment – PAY_ORDERS message" to study the message structure.
Message PAY_ORDERS – fields description:
Field name | Data type | Description |
---|---|---|
PAY_ORDER_ID | NUMBER(15,0) | Payment order ID. The company must verify that the PAY_ORDER_ID is unique and should not allow to register two messages with the same PAY_ORDER_ID |
PAY_ORDER_DATE | CHAR(10) | Date of payment order in YYYY-MM-DD format |
PAY_ORDER_NUMBER | CHAR(20) | Number of payment order |
PAY_ORDER_AMOUNT | NUMBER(15,2) | The amount of payment order. Use dot (".") as the decimal separator |
PAYEE\NAME | CHAR(100) | Name of a payee’s company |
PAYEE\CODE | NUMBER(15,0) | Company code (provided by the Portmone.com system) |
BANK\NAME | CHAR(100) | Name of sender's bank |
BANK\CODE | CHAR(6) | MFO of sender's bank. When the IBAN account number is used in payment details, a "0" (zero) is transferred in the BANK\CODE field |
BANK\ACCOUNT | CHAR(29) | Sender's bank account number or IBAN of a sender (depending on payment details filled out in money transfer document) |
BILL_ID | NUMBER(15,0) | Unique bill ID in the Portmone system. The company must verify that the BILL_ID is unique and should not allow to register two messages with the same BILL_ID .It is equal to the SHOPBILLID parameter (see section 3 "Order payment") |
BILL_NUMBER | CHAR(120) | Bill number. It is equal to the shop_order_number parameter (if sent; see section 3 "Order payment"). |
BILL_DATE | CHAR(10) | Bill date in YYYY-MM-DD format |
BILL_PERIOD | CHAR(4) | Bill period in MMYY (month and year) format |
PAY_DATE | CHAR(10) | Date of payment in YYYY-MM-DD format |
PAYED_AMOUNT | NUMBER(15,2) | Amount of payment. Use dot (".") as the decimal separator |
PAYED_COMMISSION | NUMBER(15,2) | Amount of banking commission |
PAYED_DEBT | NUMBER(15,2) | Including payment of debt. Use dot (".") as the decimal separator |
AUTH_CODE | CHAR(6) | Authorization code for a payment card |
CONTRACT_NUMBER | CHAR(20) | Parameter by which the company and the Portmone.com system agreed to identify the client |
ATTRIBUTE1 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE2 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE3 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
ATTRIBUTE4 | CHAR(20) | Additional client identification parameter. If it is not required for client identification, it will not be sent in a message |
Examples:
See "8.3 PAY_ORDERS message example".
Confirmation of payment information receipt – RESULT message
Description:
The RESULT message is sent by the company to the Portmone.com system in response to the messages PAY_ORDERS and BILLS.
Message structure:
Please, refer to "8.3 Confirmation of payment information receipt – RESULT message" to study the message structure.
Message RESULT – fields description:
Field name | Data type | Description |
---|---|---|
ERROR_CODE | NUMBER(15,0) | Error code (0 in case if message processing is successful) |
REASON | CHAR(250) | Error description |
Examples:
See "8.3 RESULT message example".
8.4. Receiving statements with authorization results by e-mail
Statements are sent to the stores immediately after the successful authorization of the card. There are two options for sending statements:
- Sending two e-mail messages to Partner’s e-mail address — one with a statement in text format and another one with a statement in the form of an XML-message (see "8.4 Example of statement with authorization results in XML format");
- Sending the statement to Partner's e-mail in text format only.
Example of statement in text form:
В системі Portmone.com оплачено замовлення / Order payed in Portmone.com system: Номер замовлення / Order number: 305966 Дата замовлення / Order date: 18.03.2010 Коментар / Comment: 50908: покриття по платіжним карткам (payment cards coverage) Сума / Amount: 108.98 Валюта / Currency: UAH Код авторизації / Authorization code: 87446Z Тип авторизації/ Authorization type: 3DSECURE
Message is sent in Ukrainian. Fields names were translated into English for information only.
8.5. Notification in JSON format
Notification for successful payment in JSON format
Description:
This notification is sent by Portmone.com to the company in case of successful transaction. The company shall provide URL-address to which the Portmone.com system will send messages in JSON format.
Message structure:
Please, refer to "8.5 Notification for successful payment in JSON format" to study the message structure.
Parameters description:
Parameter | Description |
---|---|
shopBillId | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Partner’s system |
description | Comment to the order / description of payment details |
cardMask | Payer’s Card mask |
billAmount | Transaction amount sent in request |
status | Order status. Possible values: PAYED, PREAUTH, REJECTED, CREATED |
token | Token value for subsequent payments |
authCode | Bank authorization code |
receiptUrl | An empty value |
attribute1 | Service field (for additional order information). Filled at company’s discretion |
attribute2 | Service field (for additional order information). Filled at company’s discretion |
attribute3 | Service field (for additional order information). Filled at company’s discretion |
attribute4 | Service field (for additional order information). Filled at company’s discretion |
errorCode | Error code |
error | Error description |
notificationType | Notification status |
cardType | Card type |
bank_name | Name of the acquiring bank |
terminal_id | Acquire terminal number |
merchant_id | Terminal name |
rrn | Transaction identifierї (RRN) |
Confirmation of receipt of payment notification in JSON format
Description:
This message is sent by the company to the Portmone.com system in response to the notification for successful payment in JSON format.
Message structure:
Please, refer to "8.5 Confirmation of receipt of payment notification in JSON format" to study the message structure.
Parameters description:
Parameter | Description |
---|---|
errorCode | Error code |
reason | Error description. Set it "OK" if error not occurred |
responseId | Randomly generated value. Maximum length is 31 character |
8.6. Sending a message about payment order (text notification by email about the financial coverage of transactions)
The next day after the bank has transferred the financial coverage to the store's current account, the Portmone.com system sends an e-mail to the store with a text file containing a list of orders covered by this payment order.
The letter contains the following information (message is sent in Ukrainian; fields names were translated into English for information only):
Агент/Agent: ТОВ "ПОРТМОНЕ" Довіритель/Client ТОВ Квіточка Реєстр отриманих оплат "Райффайзен банк Аваль" МФО 300335 розрахунковий рахунок 29249215 (Registry of payments accepted by "Raiffeisen Bank Aval" MFO 300335 current account 29249215) No п/д 6559503 дата 17.07.2010 (Payment order No 6559503 date 17.07.2010) +---------------------------------------------------------------------------+ |Дата оплати/ |Номер замовлення/ |Код авт./ |Сум. плат./| |Payment date |Order number |Auth. code| Amount| +---------------------------------------------------------------------------+ |14.07.2014 00:08 | 141192| 171363| 191.00| |14.07.2014 02:10 | 141205| 29797B| 104.00| |14.07.2014 10:49 | 141225| 432054| 104.00| |14.07.2014 12:40 | 141249| 37614B| 89.00| |14.07.2014 14:47 | 141275| 34502Z| 158.00| |14.07.2014 14:54 | 141281| 083689| 220.00| |14.07.2014 18:52 | 141339| 841013| 290.50| |14.07.2014 19:26 | 141348| 587414| 91.00| |14.07.2014 19:35 | 141353| 389922| 141.50| |14.07.2014 19:56 | 141361| 638960| 74.00| |14.07.2014 22:08 | 141405| 61791B| 249.00| |14.07.2014 22:47 | 141418| 013761| 131.00| +---------------------------------------------------------------------------+ Всього оплат на суму/Total payments amount 1843.00 грн. Комісія/Commission 36.86 грн. Всього за день/Day total 1843.00 грн. Комісія/Commission 36.86 грн. Перераховується одержувачу/Transferred to recipient 1806.14 грн.
8.7. Getting a link to the receipt
Description:
To get a link to the receipt you should send a JSON request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "8.7 Request for getting a link to the receipt" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
login | The Online Store login to access account management |
password | The Online Store password |
shopOrderNumber | Number of an order (bill) in the Online Store system |
id | ID of the request from the Online Store to the Portmone.com system |
Response structure:
Please, refer to "8.7 Example of successful response" to study the response structure.
9. Refund
9.1.1 Return POST request
Description:
URL for the request: https://www.portmone.com.ua/gateway/.
Request format: HTTPS POST
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "9.1 POST refund request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the return procedure. Value: return |
login | The Online Store login |
password | The Online Store password |
shop_bill_id | Order number in the Portmone.com system (should be obtained using the result method described in section 8.2 "Authorization results request") |
return_amount | Refund amount. Partial and full refund is possible |
attribute1 | Additional optional parameter |
attribute5 | It is used when splitting the payment |
encoding | Encoding |
lang | Error message language |
Response structure:
Please, refer to "9.1 POST refund response (successful) " to study the response structure.
The <request>
result section can be used for debugging – tags correspond to actually received request parameters. If there is no tag in <request>
, it means that this parameter was not sent in the request.
If error occurs when calling a method (for example, incorrect login, etc.), the <order>
section will consist of two tags only – <error_code>
and <error_message>
(see "9.1 POST refund response (failure)").
9.1.2. Return JSON request
Description:
To return funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "9.1.2 JSON refund request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
login | The Online Store login to access account management |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
shopbillId | Order ID in the Portmone.com system. Optional parameter |
returnAmount | Refund amount. Partial and full refund is possible |
attribute5 | It is used when splitting the payment |
message | Comment to the refund |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "9.1.2 Response format" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
description | Order description |
status | Order status |
bank_id | code the bank |
terminal_id | terminal id in the bank |
merchant_id | merchant id in the bank |
rrn | identificator of transaction in banks system |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
attribute5 | It is used when splitting the payment |
commission | The value of the refunded commission from payment |
shopBillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of an order (bill) in the Online Store. Maximum length is 120 symbols |
billAmount | Bill amount |
errorCode | Error code |
errorMessage | Error message |
authCode | Bank authorization code |
cardMask | Card mask |
token | Token value |
gateType | Payment method identifier |
9.2. Cancellation of payment JSON request
Description:
To return funds you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
The request can be used on the condition that it takes place on the day of payment.
Request structure:
Please, refer to "9.2 JSON refund request" to study the request structure.
Request parameters description:
Parameter | Description |
---|---|
method | Required parameter to call the report generation procedure. Value: reject |
login | The Online Store login to access account management |
password | The Online Store password |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols |
shopbillId | Order ID in the Portmone.com system. Optional parameter |
returnAmount | Refund amount. Partial and full refund is possible |
attribute5 | It is used when splitting the payment |
message | Comment to the refund |
Important! The search can be performed on parameter
shopOrderNumber
orshopbillId
. If both parameters are passed, the search will be performed onshopbillId
parameter. If none of the parameters has been passed, an error will occur.
Response structure:
Please, refer to "9.2 Response format" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
description | Order description |
status | Order status |
bank_id | code the bank |
terminal_id | terminal id in the bank |
merchant_id | merchant id in the bank |
rrn | identificator of transaction in banks system |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
commission | The value of the refunded commission from payment |
shopBillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of an order (bill) in the Online Store. Maximum length is 120 symbols |
billAmount | Bill amount |
errorCode | Error code |
errorMessage | Error message |
authCode | Bank authorization code |
cardMask | Card mask |
token | Token value |
gateType | Payment method identifier |
11. Using Gateway for mobile application
You can use custom-URL mechanisms to integrate the Potrmone.com payment gateway into mobile applications (for example, iOS or Android). They allow you to call the payment gateway page with the necessary parameters from the application and to get control back to the application after the payment.
An example of how it can be done for iOS applications:
Call the URL for payment using the GET method (! not the POST method) with transferring of all parameters specified in our Online Store connection documentation.
For success_url
and failure_url
parameters it is necessary to specify URLs, which contain the custom url type registered in iOS-application of Online Store, instead of https protocol.
For example, if the following url type: “customurl” is registered in the iOS-application, then success_url
and failure_url
parameters will look as following:
success_url = “customurl://success” failure_url = “customurl://failure”
URL for calling the Portmone.com service will be as follows:
https://www.portmone.com.ua/gateway/?payee_id=1185&bill_amount=123.56 &shop_order_number=shopordernumber1&description=My%20test &success_url=customurl://success&failure_url=customurl://failure
where:
payee_id = 1185
– Online Store ID
bill_amount = 123.56
– Amount to pay by the order
shop_order_number = shopordernumber
– Order number
description = “My test”
– Notes to the order
As a result of this call, a browser with a standard order payment page will be opened, where the card details should be entered. Based on payment results, either success_url
or failure_url
from the Online Store primary request parameters will be called, and the transition to the Online Store's iOS-application will be executed accordingly.
This is how the page optimized for mobile screens looks like:
12. Invoicing customers
The Portmone.com payment gateway allows to send invoices (orders) for payment by e-mail or SMS.
12.1. Sending invoice by e-mail
To send an invoice by e-mail you should call the form with the following parameters:
Parameter | Description | Required |
---|---|---|
login | The Online Store login to access account management | Yes |
password | The Online Store password | Yes |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | No |
namePayer | Name of the Client | No |
comment | Payment comment | No |
amount | Amount of the payment | Yes |
emailRecipient | E-mail address of the Client | Yes |
lang | E-mail language | No |
cc_email | E-mail address to which a copy of the invoice will be sent | No |
preauth_flag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
bill_currency | Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT | No |
expDate | Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724) | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
Examples:
See "12.1 Form to send invoices by e-mail".
12.2. Sending invoice via SMS
To send an invoice via SMS you should call the form with the following parameters:
Parameter | Description | Required |
---|---|---|
login | The Online Store login to access account management | Yes |
password | The Online Store password | Yes |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | No |
namePayer | Name of the Client | No |
comment | Payment comment | No |
amount | Amount of the payment | Yes |
phoneRecipient | Number of the Client’s mobile phone | Yes |
lang | SMS language | No |
preauth_flag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
bill_currency | Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT) | No |
expDate | Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724) | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
Examples:
See "12.2 Form to send invoices via SMS".
Upon receiving this invoice, the Client will be notified as follows:
When clicking on a hypertext payment link, the Client will open a payment page with the following content:
12.3. Mass invoicing by e-mail or SMS
Description:
For mass invoicing by e-mail or SMS you should send a request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.
Availability and restrictions:
The data block must contain at least 5 required parameters, filled in a strict order (see the table with the description of the request parameters). There are 4 additional parameters which are filled in if necessary.
Maximum 100 invoices can be set up at a time.
Request structure:
Please, refer to "12.3 Mass invoicing request" to study the request structure.
Request parameters description:
Sequence in the data block | Parameter | Description | Required |
---|---|---|---|
1 | Name of a recipient | Name of the Client that will be displayed in the received invoice | Yes |
2 | Recipient’s e-mail or mobile phone | Client’s e-mail address or mobile phone number. Mobile number should be in the "+380ХХХХХХХХХ" format | Yes |
3 | Order number | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | Yes |
4 | Payment details | Comment to the order / description of payment details | Yes |
5 | Amount | Amount of the payment | Yes |
6 | Currency | Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT | No |
7 | Pre-authorization | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization. "N" is default value) | No |
8 | Invoice language | The language of the e-mail or SMS. Possible values: uk – Ukrainian, en – English. If the parameter is not sent, the invoice is issued in Ukrainian | No |
9 | Invoice validity time | Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724) | No |
Response structure:
Please, refer to "12.3 Mass invoicing response (successful)" to study the response structure.
12.4. Getting a payment link
Description:
To get a payment link you should send a request to the following URL: https://www.portmone.com.ua/r3/api/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "12.4 Request for getting a payment link" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
login | The Online Store login to access account management | Yes |
password | The Online Store password | Yes |
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
amount | Amount of the payment | Yes |
shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | No |
emailRecipient | E-mail address of the Client | No |
comment | Payment comment | No |
preauth_flag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
bill_currency | Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, PLN, KZT | No |
expDate | Date and time until which Client is able to pay invoice. After this time passes the invoice gets the "REJECTED" status and cannot be paid. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724) | No |
attribute1 | Service field. Filled at company’s discretion | No |
attribute2 | Service field. Filled at company’s discretion | No |
attribute3 | Service field. Filled at company’s discretion | No |
attribute4 | Service field. Filled at company’s discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
Response structure:
Please, refer to "12.4 Getting a payment link response (successful) " to study the response structure.
12.5. Creating a payment link
Description:
This method allows you to create a payment link and get it to the merchant's server. Suitable for use on Instagram, Facebook.
To create a payment link you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "12.5 Request for creating a payment link" to study the request structure.
Request parameters description:
- payee – this block is required for partner identification
Parameter | Description | Required |
---|---|---|
payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
login | Company’s login. Used to verify a signature (required if the signature parameter is sent) | No |
dt | Request creation time. Used to verify a signature (required if the signature parameter is sent) | No |
signature | Signature of the request | No |
shopSiteId | Digital identifier of a sales channel | No |
- order – this block contains the order data
Parameter | Description | Required |
---|---|---|
description | Payment description (comment to the order/ payment details) | No |
shopOrderNumber | Number of a paid order in the Partner’s system | No |
billAmount | Amount of the payment | Yes |
successUrl | The URL of the Online Store to which the client will be redirected after a successful payment | No |
failureUrl | The URL of the Online Store to which the client will be redirected in case of payment rejection | No |
preauthFlag | Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure (see section 6 "Payments with pre-authorization"), value "N" is a regular payment without pre-authorization) | No |
billCurrency | Currency of the payment. Default value: UAH | No |
expTime | Sets the interval (in seconds) during which the order can be paid. If the parameter value was transferred, then from the moment the payment page was called up, a countdown is displayed, which is visible to the Client on the payment page. After payment time expires, the bill gets the "REJECTED" status and cannot be paid | No |
encoding | Encoding (encodes the request text from the set encoding to UTF-8) | No |
attribute1 | Service field. Filled at company’s discretion | No |
attribute2 | Service field. Filled at company’s discretion | No |
attribute3 | Service field. Filled at company’s discretion | No |
attribute4 | Service field. Filled at company’s discretion | No |
attribute5 | Used to send the split parameters of the payment (see section 7 "Splitting the payment") | No |
- paymentTypes – this block allows you to choose payment methods ("Y" – enable, "N" – do not enable). If the parameters are not specified, then the payment methods assigned to the Online Store in the Portmone.com settings are used, or two main payment methods are used: "card", "portmone".
Parameter | Description | Required |
---|---|---|
card | Payment by Card | No |
portmone | Payment via Portmone.com wallet | No |
token | Payment by Token (if this option is enabled, other methods are not displayed) | No |
clicktopay | Payment using Visa Click to Pay | No |
privat | Payment via LiqPay, with choosing a card from the Privat24 Internet Banking Pay attention! Pre-authorization functionality does not work when paying via Privat24 | No |
gpay | Payment via Google Pay, with choosing a card from previously stored in the Google Pay account | No |
createtokenonly | Creates a Token to make payments by Token (if this option is enabled, other methods are not displayed). This parameter allows you to receive a Card Token without making a real payment (1 UAH is blocked on the account and returned within 30 minutes). Suitable for common payments to the Online Store (see section 4 "Order payment using a payment Token") and for subsequent use for card to card payments (see section 5 "Money transfer from card to card") | No |
applepay | Payment via Apple Pay, with choosing a card from previously stored in the Apple Pay account | No |
Response structure:
Please, refer to "12.5 Creating a payment link response (successful) " to study the response structure.
12.6. Сlose Invoice
Description:
The method allows you to close the Invoice account in CREATED
and REJECTED
status.
To create a payment link you should send a request to the following URL: https://www.portmone.com.ua/gateway/.
Availability and restrictions:
No restrictions.
Request structure:
Please, refer to "12.6 Request to close the invoice" to study the request structure.
Request parameters description:
| Parameter | Description | Required |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | :------: | --- |
| login | Company’s login. Used to verify a signature (required if the signature
parameter is sent) | Yes |
| password | The Online Store password | Yes |
| payeeId | A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
| shopOrderNumber | Number of an order (bill) in the Online Store system. Maximum length is 120 symbols | Yes | = |
Response structure:
Please, refer to "12.6 to close the invoice response (successful) " to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
description | Order description |
status | Order status |
attribute1 | Service field. Filled at company's discretion |
attribute2 | Service field. Filled at company's discretion |
attribute3 | Service field. Filled at company's discretion |
attribute4 | Service field. Filled at company's discretion |
commission | The value of the refunded commission from payment |
shopBillId | Order ID in the Portmone.com system |
shopOrderNumber | Number of paid order (bill) in the Online Store |
billAmount | Bill amount |
errorCode | Error code |
errorMessage | Error message |
authCode | Bank authorization code (added if the order is paid) |
cardMask | Payer’s Card mask |
token | Token value for subsequent payments |
gateType | Payment method identifier |
13. Transfer of funds from account to card (token)
Description: Allows you to transfer funds from an account to a Card or a Card Token. Merchant needs to sign an agreement with Bank.
** Important! ** When using this service, merchants become tax agents and are obliged to pay taxes (Income tax, SSC, Military tax). Exceptions are companies that have a license to carry out a special type of activity such as: MFIs (microcredit organizations), insurance companies .
13.1 Transfer of funds from account to card
Description:
To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/r3/pm/.
Availability and restrictions:
The method works in synchronous mode only (mode = 1101
).
Request structure:
Please, refer to "13.1 Request to transfer funds from account to card" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
paymentType | Must be set "a2c_1" value | Yes |
description | recipient's card number | Yes |
attribute1 | Service field (for additional order information). Set empty value | No |
attribute2 | Service field (for additional order information). The information about tax for transfer on a card | No |
attribute3 | Service field (for additional order information). Filled at company’s discretion | No |
attribute4 | Service field (for additional order information). Filled at company’s discretion | No |
billAmount | Amount of the payment | Yes |
payeeId | A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of paid order in the Partner’s system | No |
cvvVerifyFlag | The default is "Y", set "N" for payments without CVV2 | No |
token | Set empty value | No |
billCurrency | Currency of the payment. Default value: UAH | No |
shopSiteId | Digital identifier of a sales channel | No |
cardData | Encrypted value of payment card data (card number, expiration month, expiration year, CVV2) | No |
dt | Request creation time. Used to verify the signature. Should be sent in the following format:yyyymmddhhmmss (for example, 20181208130724) | Yes |
signature | Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature" | Yes |
mode | Set "1101" for synchronous mode | Yes |
In case of tax payment in attribute2 it is necessary to transfer the following parameters: "attribute2": "" client_id \ ": " Ivanov Ivan \ ", " taxes \ ": {"income\ ": 20, " social ": 10,"military": 5},"identification": {"general": {"tax_id":"1234567890 "}} ",
Description of query parameters: | Option | Description | Required | | -------- | -------- |: ----------: | | client_id | Recipient's name | Yes | | Income | The amount of income tax in coins| Yes | | Social | The amount of SSC in coins | Yes | | military | The amount of military tax in coins | Yes | | tax_id | TIN of the recipient of funds | Yes |
** Important! ** In case of cashback (bonuses) it is not necessary to transfer the social parameter.
Response structure:
Please, refer to "13.1 Transfer funds from account to card. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
status | Order status. Possible values: REJECTED, PAYED |
errorCode | Error code |
error | Error description |
shopBillId | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
billAmount | Transaction amount sent in request |
billNumber | Number of paid order (bill) in the Partner’s system |
attribute1 | Service field (for additional order information). Set empty value |
attribute2 | Service field (for additional order information). The information about tax for transfer on a card |
attribute3 | Service field (for additional order information). Filled at company’s discretion |
attribute4 | Service field (for additional order information). Filled at company’s discretion |
authCode | Bank authorization code (added if the order is paid) |
payeeExportFlag | Transaction status in the acquiring bank (Y – successful, E – error, N or empty value – not sent) |
receiptLink | Link to get a receipt |
billCurrency | Currency of the payment |
transactionId | Transaction ID in the acquirer system |
Important! If the response contains
status = PAYED
, butpayeeExportFlag
has a value other than Y, it is necessary to request the transaction status from the Portmone.com system (see section 8.2 "JSON request"). If the response containsstatus = PAYED
andpayee_export_flag = Y
, the transaction is successful.
13.2 Transfer of funds from account to card token
Description: To get card token you can use paragraph 4.1 of documentation
** Important! ** Do not fill the description parameter when send request to get a token and request a transfer.
To transfer funds you should send a request to the following URL: https://www.portmone.com.ua/r3/pm/.
Availability and restrictions:
The method works in synchronous mode only (mode = 1101
).
Request structure:
Please, refer to "13.2 Request to transfer funds from account to card" to study the request structure.
Request parameters description:
Parameter | Description | Required |
---|---|---|
paymentType | Must be set "a2t_1» value | Yes |
description | Set empty value | Yes |
attribute1 | Service field (for additional order information). Set empty value | No |
attribute2 | Service field (for additional order information). The information about tax for transfer on a card token | No |
attribute3 | Service field (for additional order information). Filled at company’s discretion | No |
attribute4 | Service field (for additional order information). Filled at company’s discretion | No |
billAmount | Amount of the payment | Yes |
payeeId | A unique identifier of the Partner. Assigned to each Partner individually when connected to the Portmone.com system | Yes |
shopOrderNumber | Number of paid order in the Partner’s system | No |
cvvVerifyFlag | The default is "Y", set "N" for payments without CVV2 | No |
token | Set empty value | No |
billCurrency | Currency of the payment. Default value: UAH | No |
shopSiteId | Digital identifier of a sales channel | No |
cardData | Encrypted value of payment card data (card number, expiration month, expiration year, CVV2) | No |
dt | Request creation time. Used to verify the signature. Should be sent in the following format: yyyymmddhhmmss (for example, 20181208130724) | Yes |
signature | Request signature. Required to verify the legality of the request. Description of creating signature see above in section 2.2 "Signature" | Yes |
mode | Set "1101" for synchronous mode | Yes |
In case of tax payment in attribute2 it is necessary to transfer the following parameters: "attribute2": "" client_id \ ": " Ivanov Ivan \ ", " taxes \ ": {" income \ ": 20, " social": 10,"military":5},"identification": {"general": {"tax_id": "1234567890 "}} ",
Description of query parameters:
Option | Description | Required |
---|---|---|
client_id | Recipient's name | Yes |
Income | The amount of income tax in coins | Yes |
Social | The amount of SSC in coins | Yes |
military | The amount of military tax in coins | Yes |
tax_id | TIN of the recipient of funds | Yes |
** Important! ** In case of cashback (bonuses) it is not necessary to transfer the social parameter.
Response structure:
Please, refer to «13.2 Transfer funds from account to card token. Response (successful)" to study the response structure.
Response parameters description:
Parameter | Description |
---|---|
status | Order status. Possible values: REJECTED, PAYED |
errorCode | Error code |
error | Error description |
shopBillId | A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system |
billAmount | Transaction amount sent in request |
billNumber | Number of paid order (bill) in the Partner’s system |
attribute1 | Service field (for additional order information). Filled at company’s discretion |
attribute2 | Service field (for additional order information). The information about tax for transfer on a card token |
attribute3 | Service field (for additional order information). Filled at company’s discretion |
attribute4 | Service field (for additional order information). Filled at company’s discretion |
authCode | Bank authorization code (added if the order is paid) |
payeeExportFlag | Transaction status in the acquiring bank (Y – successful, E – error, N or empty value – not sent) |
receiptLink | Link to get a receipt |
billCurrency | Currency of the payment |
transactionId | Transaction ID in the acquirer system |
Important! If the response contains
status = PAYED
, butpayeeExportFlag
has a value other than Y, it is necessary to request the transaction status from the Portmone.com system (see section 8.2 "JSON request"). If the response containsstatus = PAYED
andpayee_export_flag = Y
, the transaction is successful.
Examples
To Section 3 "Order payment"
3.1 POST order payment request
<form action="https://www.portmone.com.ua/gateway/" method="post">
<input type="hidden" name="payee_id" value="1185" />
<input type="hidden" name="shop_order_number" value="76575j65465464161hhhh" />
<input type="hidden" name="bill_amount" value="1" />
<input type="hidden" name="description" value="Order description" />
<input
type="hidden"
name="success_url"
value="http://example.com/success.html"
/>
<input
type="hidden"
name="failure_url"
value="http://example.com/failure.html"
/>
<input type="hidden" name="lang" value="uk" />
<input type="hidden" name="encoding" value="UTF-8" />
<input type="hidden" name="exp_time" value="400" />
</form>
3.1 POST order payment response (successful)
SHOPBILLID: 420651576 SHOPORDERNUMBER: 123456789qwe APPROVALCODE: TESTPM
BILL_AMOUNT: 1 TOKEN: RESULT: 0 CARD_MASK: 444433******1111 ATTRIBUTE1: null
ATTRIBUTE2: null ATTRIBUTE3: null ATTRIBUTE4: null RECEIPT_URL:
https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/
353472d8de85c380d94e49e592050631486e357ebdcedf374ccd07c89682f31d181076bbd1f2d920b4d00b3e
11983dfb8777ccee0a19a9a00cd7cb5c1262c83c LANG: en DESCRIPTION: 999999 IPSTOKEN:
null ERRORIPSCODE: null ERRORIPSMESSAGE: null
3.2 JSON order payment request
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="<? = $data ?>" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
}} class="button_green" />
</form>
where $data – json structure, as follows:
{
"paymentTypes": {
"card": "Y",
"portmone": "Y",
"token": "N",
"clicktopay": "Y",
"createtokenonly": "N"
},
"autopayment": {
"show": "Y",
"edit": "N",
"defaultCheckboxState": "N",
"changeCheckboxState": "Y",
"settings": {
"period": "1",
"payDate": "27",
"startDate": "",
"endDate": "01.01.2021",
"amount": "1.22"
},
"credentials": "393433af5c5c46bb776878f8208fae4ad91f4ca450a28e4b558386e4c30325e3f5673522b2929adfe39655d5a530fc193094cb089a9bac58137c4533edcfa08a4c299d27a8fc060b2d671d1b63a32e66f8fc1db433185d0788fe145b93faaa75e60713d99673e4bd"
},
"priorityPaymentTypes": {
"card": "1",
"portmone": "2",
"qr": "0",
"token": "0",
"clicktopay": "4",
"createtokenonly": "5"
},
"payee": {
"payeeId": "1185",
"login": "",
"dt": "",
"signature": "",
"shopSiteId": ""
},
"order": {
"description": "test",
"shopOrderNumber": "123456",
"billAmount": "2500",
"attribute1": "1",
"attribute2": "2",
"attribute3": "3",
"attribute4": "4",
"attribute5": "",
"successUrl": "",
"failureUrl": "",
"preauthFlag": "N",
"billCurrency": "EUR",
"expTime": "1000",
"encoding": ""
},
"token": {
"tokenFlag": "N",
"returnToken": "N",
"token": "18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C611A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77",
"cardMask": "516874******5179",
"otherPaymentMethods": "N"
},
"payer": {
"lang": "uk",
"emailAddress": "[email protected]",
"showEmail": "N"
},
"shipping": {
"services": {
"ukrposhta": {
"deliveryTypes": ["W2D", "W2W"],
"senderClientId": "91cfddfe-5c94-44d0-9410-c78e2a877512",
"senderAddressId": "2651676",
"senderPostCode": "08040",
"type": "STANDARD",
"parcelWeight": "600",
"parcelLength": "50",
"parcelWidth": "50",
"parcelHeight": "50",
"parcelDeclaredPrice": "25",
"parcelDescription": "",
"fragile": "",
"checkOnDelivery": "",
"bees": "",
"payer": "client",
"sms": "Y",
"withDeliveryNotification": ""
}
},
"enable": "Y",
"required": "N"
},
"style": {
"type": "light",
"logo": "",
"backgroundColorHeader": "",
"backgroundColorButtons": "",
"colorTextAndIcons": "",
"borderColorList": "",
"logoWidth": "",
"logoHeight": "",
"bcMain": ""
}
}
3.2 JSON order payment response (successful)
'SHOPBILLID' => '411587640',
'SHOPORDERNUMBER' => 'SHP-000000002792',
'APPROVALCODE' => '366999',
'BILL_AMOUNT' => '1',
'TOKEN' => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE016
44F39F009A3EDDEF992C6A5E22ACD01AE91D1CB491B645B530EDCE8C289778611A37D0D045D650DE3495E84',
'RESULT' => '0',
'CARD_MASK' => '516874******5179',
'ATTRIBUTE1' => '49026347',
'ATTRIBUTE2' => '2',
'ATTRIBUTE3' => '3',
'ATTRIBUTE4' => '4',
'RECEIPT_URL' => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc
92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG' => 'uk',
'DESCRIPTION' => 'test',
'IPSTOKEN' => 'null',
'ERRORIPSCODE' => 'null',
'ERRORIPSMESSAGE' => 'null'
3.6. Exchange rate
{
"method":"getRateCurrencies",
"params":{
"data":{
"payeeId":"72276", - payeeId мерчанта в системі Портмоне
"date":"21-11-2022" - дата, за яку треба отримати курс
}
},
"id":"1"
}
{
"result": {
"currencies": [
{
"key": "AUD",
"value": "24.5503"
},
{
"key": "EUR",
"value": "37.8906"
},
{
"key": "GBP",
"value": "43.5239"
},
{
"key": "KZT",
"value": "0.079196"
},
{
"key": "PLN",
"value": "8.0569"
},
{
"key": "USD",
"value": "36.5686"
}
],
"notice": "Portmone не здійснює купівлі, продажу, обміну, конвертації та визначення курсу безготівкової іноземної валюти. Розрахунок вартості товарів та послуг на поточну дату здійснюється на підставі даних, отриманих з сервісу розрахунку курсу валют, обраного Отримувачем. Portmone не несе відповідальності за працездатність цього сервісу"
},
"id": "1"
}
To Section 4 "Order payment using a payment Token"
{
"paymentTypes": {
"createtokenonly": "Y"
},
"priorityPaymentTypes": {
"createtokenonly": "1"
},
"payee": {
"payeeId": "1185",
"login": "",
"dt": "",
"signature": "",
"shopSiteId": ""
},
"order": {
"description": "testPayment",
"shopOrderNumber": "SHP-000000002792",
"billAmount": "1",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"successUrl": "",
"failureUrl": "",
"preauthFlag": "N",
"billCurrency": "UAH",
"encoding": ""
},
"token": {
"tokenFlag": "N",
"returnToken": "N",
"token": "",
"cardMask": "",
"otherPaymentMethods": "N"
},
"payer": {
"lang": "uk",
"emailAddress": "[email protected]"
},
"style": {
"type": "",
"logo": "",
"backgroundColorHeader": "",
"backgroundColorButtons": "",
"colorTextAndIcons": "",
"borderColorList": ""
}
}
Place the JSON structure in the "bodyRequest" field, and add the "typeRequest" parameter with the value "json".
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="JSON STRUCTURE" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Portmone.com" />
</form>
4.1 Token creation response (successful)
'SHOPBILLID' => '411587640',
'SHOPORDERNUMBER' => 'SHP-000000002792',
'APPROVALCODE' => '366999',
'BILL_AMOUNT' => '1',
'TOKEN' => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644
F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT' => '0',
'CARD_MASK' => '516874******5179',
'ATTRIBUTE1' => '49026347',
'ATTRIBUTE2' => '2',
'ATTRIBUTE3' => '3',
'ATTRIBUTE4' => '4',
'RECEIPT_URL' => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc9
2084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG' => 'uk',
'DESCRIPTION' => 'test'
4.2.1 Payment by Token. POST request
<form method="POST" action="https://www.portmone.com.ua/r3/token/secure/token/">
<input type="text" value="1185" name="payee_id" />
<input type="text" value="test_123" name="description" />
<input type="text" value="1" name="bill_amount" />
<input type="text" value="test_1" name="shop_order_number" />
<input
type="text"
value="https://www.portmone.com.ua/r3/ecommerce/test/"
name="application_url"
/>
<input type="text" value="en" name="lang" />
<input
type="text"
value="183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510
A1EF2E1965DFEF0F1E5421D0CE264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491
E66"
name="token"
/>
<input type="text" value="" name="attribute1" />
<input type="text" value="" name="attribute2" />
<input type="text" value="" name="attribute3" />
<input type="text" value="" name="attribute4" />
</form>
4.2.1 Payment by Token. Response (successful)
BILL_AMOUNT=45& SHOPORDERNUMBER=test_2& APPROVALCODE=TESTPM&
RECEIPT_URL=https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts
%2Fshop-bill-id%2F35348409d793c705eb6250a1576451abad87d010699109d1a6578e81a4f9b40e70d67
085deb9e94e54a62093a09ff92062953366caa6e80f64025449318491ec&
TOKEN=183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510A1EF2E1965DFEF0F1E5421D0C
E264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491E66&
CARD_PAYMENT_SYSTEM=VISA& CARD_LAST_DIGITS=1111& RESULT=0
4.2.2 Payment by Token. JSON request
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="<?= $data ?>" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
}} class="button_green" />
</form>
where $data – json structure, as follows:
{
"paymentTypes":
{
"card":"N",
"portmone":"N",
"token":"N",
"clicktopay":"N",
"qr":"Y",
},
"priorityPaymentTypes":
{
"card":"4",
"portmone":"2",
"qr":"1",
"token":"8",
"clicktopay":"4",
},
"payee":
{
"payeeId":"1185",
"login":"",
"dt":"",
"signature":"",
"shopSiteId":""
},
"order":
{
"description":"191237564",
"shopOrderNumber":"SHP-00000111",
"billAmount":"1",
"attribute1":"1",
"attribute2":"2",
"attribute3":"3",
"attribute4":"4",
"successUrl":"",
"failureUrl":"",
"preauthFlag":"N",
"billCurrency":"UAH",
"encoding":""
},
"token":
{
"tokenFlag":"Y",
"returnToken":"Y",
"token":"1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84",
"cardMask":"516874******5179",
"otherPaymentMethods":"N"
},
"payer":
{
"lang":"uk",
"emailAddress":""
},
"style":
{
"type":"brand",
"logo":",
"logoWidth":"171px",
"logoHeight":"41px"*,
"backgroundColorHeader":"#009DE0",
"backgroundColorButtons":"#009DE0",
"colorTextAndIcons":"#1e282c",
"borderColorList":"#1e282c"
}
}
4.2.2 Payment by Token. Example of successful response to the JSON request
'module' => 'ecommerce',
'controller' => 'test',
'action' => 'success',
'SHOPBILLID' => '421606955',
'SHOPORDERNUMBER' => 'SHP-00000000279210',
'APPROVALCODE' => '416477',
'BILL_AMOUNT' => '1',
'TOKEN' => '18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C6
11A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77',
'RESULT' => '0',
'CARD_MASK' => '516874******5179',
'ATTRIBUTE1' => '1',
'ATTRIBUTE2' => '2',
'ATTRIBUTE3' => '3',
'ATTRIBUTE4' => '4',
'RECEIPT_URL' => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/35343ea3aabe8b49a35f95b78dba465ec24d36e9794f27ce97d9b1d9080b930ed
e870ed357a32212de9b5dda00c158a37ce9877be5c7a279cf2ed2114849c779',
'LANG' => 'uk',
'DESCRIPTION' => '191237564'
4.3 Recurring payment request
$jsoncontent = '{
"method": "pay",
"params": {
"login": "SHP_**",
"password": "******",
"payeeId": "1185",
"shopOrderNumber": "123456",
"token": "1834373930303635***FCC",
"description": "Опис замовлення",
"billAmount": "1.24",
"billCurrency": "EUR",
"preauthFlag": "Y"
},
"id": "1"
}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_URL, "https://www.portmone.com.ua/r3/recurrent/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsoncontent);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$result = curl_exec($ch);
$curl_info = curl_getinfo($ch);
print_r($result);
curl_close($ch);
Response example for successful payment:
{
"result": {
"result": "PAYED",
"shopOrderNumber": "P1728563684",
"description": "",
"receipt": "",
"shopBillId": "1728563684"
},
"id": "1"
}
4.7 Recurring payment request
{
"method": "paywith3ds",
"params": {
"data": {
"login": "SHP_333",
"password": "22222222",
"payeeId": "30481",
"shopOrderNumber": "test_0000001",
"token": "203131393132332393039128CFE98552764426D1D5A285E4CF64130AB19CDB6336481E5878DA66F03BD7C807ABAE08464CFA7EFC6F56106E480F002669E7CDC901554499787573FFC6AC57",
"description": "test",
"billAmount": "1",
"preauthFlag": "N",
"billCurrency": "UAH",
"successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form/"
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": ""
}
},
"id": "1"
}
4.7.1 An example of response if 3D Secure check is required:
{
"result": {
"shopBillId": "1191240800",
"status": "CREATED",
"shopOrderNumber": "test_0000001",
"description": "test",
"pdfUrl": "",
"authCode": "",
"isNeed3DS": "Y",
"actionMPI": "https://portmone2.com/r3/tothreeds?data=2053A3B7BCF9347FF04F6B4D3E338F96FDC604F3F3C522D47EB43A50FAB904AC90AFCA2A5BB0E04171426F56D81DBFE7042E2A24FF3FC24A8F38A9B76116DF17319FE4FE028FD17660B322AE733D5A7"
},
"id": "1"
}
4.7.2 Response to return after 3D Secure
shopBillId: 1191240666
status: PAYED
billAmount: 1
billNumber: test_0000001
payeeName: 333
authCode: 453750
commission: 0
pdfUrl: ""
payeeId: 30481
payDate: 15.06.2022 03:32:27
description: test
cardMask: 454788******1119
errorMessage:
errorCode: 0
4.7.3 An example of successful response (No 3D Secure verification is required)
{
"result": {
"shopBillId": "1213000727",
"status": "PAYED",
"shopOrderNumber": "test_0000001",
"description": "test_001",
"pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35375cadedf354dd63444c7a0dba795fb044b138f323b42c51309f05929d20198733ce5ca 85866a0512487643306b1b3143e0c07f93961e8c69fb06e5275d2e6426fea",
"authCode": "158709",
"isNeed3DS": "N",
"actionMPI": ""
},
"id": "1"
}
4.7.4 Unsuccessful response
{
"error": {
"code": 10,
"message": "Операція відхилена. Повторна транзакція",
"data": {}
},
"id": "1"
}
4.8 Token payment with the appearance of the card without CVV2
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="<?= $data ?>" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
}} class="button_green" />
</form>
where $data – json structure, as follows:
{
"paymentTypes": {
"token": "Y"
},
"priorityPaymentTypes": {
"token": "1"
},
"payee": {
"payeeId": "11344",
"credentials": "3932b2bb0fb55509027abd365e0deab4e2ab149f419fa167a2441a3d289da1f48a2f16092c2300fa76d415a6e76fb8283e6c0e77305ce4622e10e5383f1030ceed470e9239ce4fc7ccccc442ea739123cb721f78a6dd0703beecfa0085e0eebfad6c36791268"
},
"order": {
"description": "test",
"shopOrderNumber": "",
"billAmount": "1",
"attribute1": "1",
"attribute2": "2",
"attribute3": "3",
"attribute4": "4",
"successUrl": "",
"failureUrl": "",
"preauthFlag": "N",
"billCurrency": "UAH",
"encoding": ""
},
"token": {
"tokenFlag": "Y",
"returnToken": "N",
"token": "20313234333633313538391280E7B5BCFFAE793EA6226F02E9D1263AD5652E804EACC8A4F3C4852CFB2FB6BA6C7053E034427E3FEFFA985ACC331C6DA961D384C5E4914505DABDFF01840",
"cardMask": "414949******2244",
"otherPaymentMethods": "N"
},
"payer": {
"lang": "uk",
"emailAddress": "[email protected]",
"showEmail": "N"
}
}
To Section 5 "Money transfer from card to card"
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="<? = $data ?>" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
}} class="button_green" />
</form>
where $data – json structure, as follows:
{
"paymentTypes":
{
"card":"N",
"portmone":"N",
"token":"N",
"clicktopay":"N",
"qr":"N"
},
"priorityPaymentTypes":
{
"card":"0",
"portmone":"0",
"qr":"0",
"token":"0",
"clicktopay":"0"
},
"payee":
{
"payeeId":"1185",
"login":"",
"dt":"",
"signature":"",
"shopSiteId":""
},
"order":
{
"description":"тест",
"shopOrderNumber":"111145",
"billAmount":"1",
"attribute1":"1",
"attribute2":"2",
"attribute3":"3",
"attribute4":"4",
"successUrl":"",
"failureUrl":"",
"preauthFlag":"N",
"billCurrency":"UAH",
"encoding":""
},
"token":
{
"tokenFlag":"N",
"returnToken":"Y",
"token":"",
"cardMask":"",
"otherPaymentMethods":"N",
"sellerToken":""
},
"payer":
{
"lang":"uk"
},
style":
{
"type":"portmone",
"logo":"",
"backgroundColorHeader":"",
"backgroundColorButtons":"",
"colorTextAndIcons":"",
"borderColorList":""
}
}
'SHOPBILLID' => '411587640',
'SHOPORDERNUMBER' => 'SHP-000000002792',
'APPROVALCODE' => '366999',
'BILL_AMOUNT' => '1',
'TOKEN' => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F3
9F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT' => '0',
'CARD_MASK' => '516874******5179',
'ATTRIBUTE1' => '49026347',
'ATTRIBUTE2' => '2',
'ATTRIBUTE3' => '3',
'ATTRIBUTE4' => '4',
'RECEIPT_URL' => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e67
6f58cc92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG' => 'uk',
'DESCRIPTION' => '516874******5179'
5.2 Request to transfer funds between card tokens
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input type="hidden" name="bodyRequest" value="<? = $data ?>" />
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Pay through Portmone.com" style={{ width: '350px'
}} class="button_green" />
</form>
where $data – json structure, as follows:
{
"paymentTypes":
{
"card":"Y",
"portmone":"Y",
"token":"Y",
"clicktopay":"Y",
"qr":"Y"
},
"priorityPaymentTypes":
{
"card":"1",
"portmone":"2",
"qr":"5",
"token":"2",
"clicktopay":"0"
},
"payee":
{
"payeeId":"1185",
"login":"",
"dt":"",
"signature":"",
"shopSiteId":""
},
"order":
{
"description":"444433******1111",
"shopOrderNumber":"SHP-0101000110002792",
"billAmount":"1",
"attribute1":"1",
"attribute2":"2",
"attribute3":"3",
"attribute4":"4",
"successUrl":"",
"failureUrl":"",
"preauthFlag":"N",
"billCurrency":"UAH",
"encoding":""
},
"token":
{
"tokenFlag":"Y",
"returnToken":"N",
"token":"183434303730373432331283F04364806355F5E7479D903A9518BC9DC4A23336E07B696BE09B713D6ADD71603966FCF9A4E40C88265E1180017127653EB541CF76176EF5FECC6B269B949DE",
"cardMask":"111122******4444",
"otherPaymentMethods":"N",
"sellerToken":"18343430373037373330128746FED8954F0E0A83315F409D8BE23767C0573C9AFE796C2B403031F8B7379307B201DB7D3E7B5F32B2E33A8B7FC284999D47396CB8D1AE485D89A6452CC8B1D"
},
"payer":
{
"lang":"uk",
"emailAddress":[email protected]
},
"style":
{
"type":"portmone",
"logo":"https://i1.rozetka.ua/logos/0/99.png",
"backgroundColorHeader":"#fff",
"backgroundColorButtons":"#4bbe3f",
"colorTextAndIcons":"#4bbe3f",
"borderColorList":"#3e77aa"
}
}
5.3 Request to transfer funds from token to card
{
"paymentTypes": {
"token": "Y"
},
"priorityPaymentTypes": {
"token": "1"
},
"payee": {
"payeeId": "1185",
"checkParams": "Y"
},
"order": {
"description": "4444333322221111",
"shopOrderNumber": "65",
"billAmount": "1",
"successUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/success",
"failureUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/error",
"encoding": "UTF-8",
"attribute2": "",
"attribute3": "",
"attribute4": ""
},
"token": {
"tokenFlag": "Y",
"returnToken": "Y",
"token": "18343836373232313531096EE3BB03559659C0F64E6BB61C642902AE0570EA189661F2CF59102681BC3D741E03540B292BB9A4D3B04D91496F0C8D9",
"cardMask": "410232******5594",
"otherPaymentMethods": "N"
},
"payer": {
"lang": "uk",
"emailAddress": "",
"showEmail": "N"
},
"style": {
"type": "",
"bcMain": "",
"backgroundColorButtons": "",
"colorTextAndIcons": ""
}
}
5.3 Transfer of funds from token to card. Response (successful)
SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN:
183438363734343037351287D5A3C90A1880888F785B34726EA1A106E6F40C2C0C30930F904FE3AE66B
C5173AB6386E12C118F91F41A500F7756A1A39D0CA3DB0F0BA38138556083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037e
f335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594
5.4.1 Request to transfer funds from card token to account
{
"paymentTypes": {
"token": "Y"
},
"priorityPaymentTypes": {
"token": "1"
},
"payee": {
"payeeId": "18930",
"checkParams": "N"
},
"order": {
"shopOrderNumber": "ttgyy1701090211",
"billAmount": "1.23",
"successUrl": "https://portmone2.com/r3/ecommerce/test/",
"failureUrl": "",
"preauthFlag": "N",
"encoding": "UTF-8",
"attribute2": "xtra"
},
"token": {
"tokenFlag": "Y",
"returnToken": "N",
"token": "1834383438393836********DECB2DD7679AE245BD8E4B69C95C67401CA89",
"cardMask": "516874******5179",
"otherPaymentMethods": "N"
},
"payer": {
"lang": "uk",
"emailAddress": "",
"showEmail": "N"
},
"style": {
"type": "light",
"bcMain": "#fff",
"backgroundColorButtons": "#0f51a6",
"colorTextAndIcons": "#0f51a6"
}
}
5.4.1 Transfer of funds from card token to account. Response (successful)
SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52
c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6 LANG: uk
DESCRIPTION: null
5.4.2 Request to transfer funds from account to card token
{
"method": "confirmp2p",
"params": {
"authData": {
"login": "SHP_333333",
"password": "333333"
},
"data": {
"shopBillId": "484991476",
"token": "183438343839383831391286A60BED7182634F41FC3DFC64D1713959E1B0DA3C05C7F18B6F474535FC554F02B78AD6C1F051616907E2F5D6E624B6746A163FFC64EF050B4907201AFA3D1CD"
}
},
"id": "1"
}
5.4.2 Transfer of funds from account to card token. Response (successful)
SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594
To Section 6 "Payments with pre-authorization"
6.2.1 Post-authorization procedure. POST request
<form action="https://www.portmone.com.ua/gateway/" method="post">
<input type="hidden" name="method" value="preauth" />
<input type="hidden" name="action" value="set_paid" />
<input type="hidden" name="login" value="shp_login" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="shop_bill_id" value="87834981" />
<input type="hidden" name="postauth_amount" value="99.00" />
<input type="hidden" name="encoding" value="utf-8" />
<input type="hidden" name="lang" value="uk" />
</form>
6.2.1 Response for post-authorization procedure (successful)
<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
<request>
<method>preauth</method>
<action>set_paid</action>
<login>shp_login</login>
<password>******</password>
<shop_bill_id>87834981</shop_bill_id>
<postauth_amount>99.00</postauth_amount>
<encoding>utf-8</encoding>
<lang>uk</lang>
</request>
<order>
<shop_bill_id>87834981</shop_bill_id>
<shop_order_number><![CDATA[1234]]></shop_order_number>
<description><![CDATA[Payment of order №1234]]></description>
<bill_date>15.11.2013</bill_date>
<pay_date>15.11.2013 22:21:51</pay_date>
<bill_amount>99.00</bill_amount>
<auth_code>123456</auth_code>
<status>PAYED</status>
<error_code>0</error_code>
<error_message><![CDATA[]]></error_message>
</order>
</portmoneresult>
6.2.1 Response for post-authorization procedure (failure)
<order>
<error_code>5</error_code>
<error_message><![CDATA[Bill payment confirmation error
[SHOP_BILL_ID = 87834981]ORA-20001:Determining payment terminal details error.
[pay_terminal_id=]]]></error_message>
</order>
6.2.2 Post-authorization procedure. JSON request
{
"method": "confirmPreauth",
"params": {
"data": {
"login": "SHP_333",
"password": "22222222",
"payeeId": "3048",
"shopOrderNumber": "test_1SAB1",
"shopbillId": 395584061,
"postauthAmount": "1",
"distribution": "Товар 2 70749:70749;3;"
}
},
"id": "1"
}
{
"shop_bill_id": "395584061",
"shop_order_number": "test_1SAB1",
"description": "Description замовлення",
"bill_date": "31.07.2018",
"pay_date": "31.07.2018 15:30:30",
"pay_order_date": null,
"bill_amount": "1",
"auth_code": "882311",
"status": "PAYED",
"attribute1": null,
"attribute2": null,
"error_code": "0",
"error_message": ""
}
6.3.1 Cancellation of payment with pre-authorization. POST request
<form action="https://www.portmone.com.ua/gateway/" method="post">
<input type="hidden" name="method" value="preauth" />
<input type="hidden" name="action" value="reject" />
<input type="hidden" name="login" value="shp_login" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="shop_bill_id" value="87834981" />
<input type="hidden" name="encoding" value="utf-8" />
<input type="hidden" name="lang" value="uk" />
</form>
6.3.1 Response for cancellation of payment with pre-authorization (POST request)
<?xml version="1.0" encoding="utf-8"?>
<portmoneresult lang="uk">
<request>
<method>preauth</method>
<action>reject</action>
<login>SHP_FLOWERSQUICKER</login>
<password>********</password>
<shop_bill_id>421592544</shop_bill_id>
<encoding>utf-8</encoding>
<lang>uk</lang>
</request>
<order>
<shop_bill_id>421592544</shop_bill_id>
<shop_order_number>test_1nvnvnvbnvb15</shop_order_number>
<description><![CDATA[Order description]]></description>
<bill_date>17.10.2018</bill_date>
<pay_date>17.10.2018</pay_date>
<pay_order_date></pay_order_date>
<bill_amount>1</bill_amount>
<auth_code>523067</auth_code>
<status>REJECTED</status>
<attribute1></attribute1>
<attribute2></attribute2>
<error_code>0</error_code>
<error_message><![CDATA[]]></error_message>
</order>
</portmoneresult>
6.3.2 Cancellation of payment with pre-authorization. JSON request
{
"method": "rejectPreauth",
"params": {
"data": {
"login": "SHP_333",
"password": "22222222",
"payeeId": "3048",
"shopOrderNumber": "SHP-00000015",
"shopbillId": 395587649
}
},
"id": "1"
}
6.3.2 Cancellation of payment with pre-authorization. Response (successful)
{
"shop_bill_id": "395587649",
"shop_order_number": "SHP-00000015",
"description": "Order description",
"bill_amount": "1",
"status": "REJECTED",
"bank_id": "1042",
"terminal_id": "4269955",
"merchant_id": "20905416",
"rrn": "0000000000",
"auth_code": "882311",
"attribute1": null,
"attribute2": null,
"attribute3": null,
"attribute4": null,
"attribute6": "444433******1111",
"commission": "0",
"error_code": "0",
"error_message": null,
"token": null
}
To Section 7 "Splitting the payment"
<form
action="https://www.portmone.com.ua/gateway/"
method="post"
target="_blank"
>
<input
type="hidden"
name="bodyRequest"
value='{
"paymentTypes":{"card":"Y","portmone":"N","token":"N",
"clicktopay":"N", "createtokenonly":"N"},
"priorityPaymentTypes":{"card":"1", "portmone":"0","qr":"0",
"token":"0", "clicktopay":"0", "createtokenonly":"0"},
"payee":{"payeeId":"3048","login":"","dt":"","signature":"", "shopSiteId":""},
"order":{"description":"Test Payment","shopOrderNumber":"","billAmount":"3",
"attribute1":"","attribute2":"","attribute3":"","attribute4":"",
"attribute5":"Water:3048;2;Souvenir:11344;1;","successUrl":"",
"failureUrl":"","preauthFlag":"N", "billCurrency":"UAH", "encoding":"",
"expTime":""},
"token":{"tokenFlag":"Y","returnToken":"Y","token":"","cardMask":"",
"otherPaymentMethods":"Y","sellerToken":""},
"payer":{"lang":"uk", "emailAddress":"[email protected]", "showEmail":"N"},
"style":{"type":"","logo":"", "backgroundColorButtons":"",
"colorTextAndIcons":"","logoHeight":""}
}'
/>
<input type="hidden" name="typeRequest" value="json" />
<input type="submit" value="Portmone.com" style={{ width: '350px' }}
class="button_green" />
</form>
To Section 8 "Getting authorization results"
8.2.1 POST authorization results request
<form action="https://www.portmone.com.ua/gateway/" method="post">
<input type="hidden" name="method" value="result" />
<input type="hidden" name="payee_id" value="1185" />
<input type="hidden" name="login" value=" preauth_flag" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="shop_order_number" value="123456" />
<input type="hidden" name="status" value="PAYED" />
<input type="hidden" name="start_date" value="01.01.2016" />
<input type="hidden" name="end_date" value="30.01.2016" />
</form>
8.2.1 POST authorization results response
<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
<request>
<payee_id><![CDATA[1185]]></payee_id>
<shop_order_number><![CDATA[%]]></shop_order_number>
<status><![CDATA[PAYED]]></status>
<start_date><![CDATA[20.02.2009]]></start_date>
<end_date><![CDATA[20.03.2009]]></end_date>
</request>
<orders type='list' >
…
<order>
<shop_bill_id>7914993</shop_bill_id>
<shop_order_number><![CDATA[1234]]></shop_order_number>
<description><![CDATA[Payment of order №1234]]></description>
<bill_date>19.03.2009</bill_date>
<pay_date>19.03.2009 22:21:51</pay_date>
<bill_amount>10</bill_amount>
<auth_code>123456</auth_code>
<status>PAYED</status>
<error_code>000</error_code>
<error_message><![CDATA[]]></error_message>
</order>
…
</orders>
8.2.2 JSON authorization results request
{
"method": "result",
"params": {
"data": {
"login": "wdishop",
"password": "wdi451",
"payeeId": "1185",
"shopOrderNumber": "005311590_783211_29.01.2019.202527",
"shopbillId": 455025419,
"status": "",
"startDate": "30.03.2019",
"endDate": "31.03.2019"
}
},
"id": "1"
}
8.2.2 JSON authorization results response (successful)
[
{
"payee_id": "1185",
"description": "",
"status": "PAYED",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "Вода:3048;2;Сувенір:1185;1;",
"commission": 0,
"distribution_payee_id": "1185",
"bank_name": "ГУ Ощадбанку м.Київ",
"terminal_id": "4269955",
"merchant_id": "20905416",
"rrn": "0000000000",
"pay_date": "20.08.2024 11:43:11",
"payee_export_date": "27.08.2024 15:40:45",
"payee_export_flag": "Y",
"chargeback": "N",
"payee_name": "ФОП WDISHOP",
"payee_commission": ".07",
"pay_order_date": "",
"pay_order_number": "",
"pay_order_amount": "",
"shopBillId": "1750101779",
"shopOrderNumber": "P1750101779",
"billAmount": "1",
"errorCode": "",
"errorMessage": "",
"authCode": "TESTPM",
"cardMask": "444433******1111",
"cardBankName": "TEST",
"token": "20313735303130313737390965B1D7FB63513942C95B286B6DE2045B896B971395C9298E34926640CB6AEA6D8E70F63AFD84584ED9FDB668342E7762E",
"payeeExportResult": "",
"gateType": "Card",
"cardTypeName": "Visa"
}
]
8.3 Notification for successful payment – BILLS message
<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
<PAYEE>
<NAME>Payee name</NAME>
<CODE> Payee code</CODE>
</PAYEE>
<BANK>
<NAME> Name of sending bank </NAME>
<CODE> MFO of sending bank</CODE>
<ACCOUNT> Account number or IBAN of sending bank </ACCOUNT>
</BANK>
<BILL_ID>Bill ID </BILL_ID>
<BILL_NUMBER> Bill number</BILL_NUMBER>
<BILL_DATE> Bill date</BILL_DATE>
<BILL_PERIOD> Bill period</BILL_PERIOD>
<PAY_DATE>Payment date</PAY_DATE>
<PAYED_AMOUNT> Payment amount</PAYED_AMOUNT>
<PAYED_COMMISSION> Amount of banking commission </PAYED_COMMISSION>
<PAYED_DEBT>Including payment of debt</PAYED_DEBT>
<AUTH_CODE> Card authorization code</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Bill description </CONTRACT_NUMBER>
<ATTRIBUTE1>Additional parameter 1</ATTRIBUTE1>
<ATTRIBUTE2>Additional parameter 2</ATTRIBUTE2>
<ATTRIBUTE3>Additional parameter 3</ATTRIBUTE3>
<ATTRIBUTE4>Additional parameter 4</ATTRIBUTE4>
</PAYER>
</BILL>
</BILLS>
<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
<PAYEE>
<NAME>Public Company “Berezka”</NAME>
<CODE>1001</CODE>
</PAYEE>
<BANK>
<NAME>JSC "Bank "Finance and Credit"</NAME>
<CODE>300131</CODE>
<ACCOUNT>29244020902980</ACCOUNT>
</BANK>
<BILL_ID>14561</BILL_ID>
<BILL_NUMBER>3892/1</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>120.35</PAYED_AMOUNT>
<PAYED_COMMISSION>0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>739280</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Order description </CONTRACT_NUMBER>
<ATTRIBUTE1>12082010</ATTRIBUTE1>
</PAYER>
</BILL>
</BILLS>
8.3 Notification about bank payment – PAY_ORDERS message
<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
<PAY_ORDER>
<PAY_ORDER_ID> Payment order ID</PAY_ORDER_ID>
<PAY_ORDER_DATE> Payment order date</PAY_ORDER_DATE>
<PAY_ORDER_NUMBER>Payment order number</PAY_ORDER_NUMBER>
<PAY_ORDER_AMOUNT>Payment order amount</PAY_ORDER_AMOUNT>
<PAYEE>
<NAME>Payee name</NAME>
<CODE>Payee code</CODE>
</PAYEE>
<BANK>
<NAME>Bank name</NAME>
<CODE>Bank MFO</CODE>
<ACCOUNT>Sender current account or IBAN of a sender</ACCOUNT>
</BANK>
<BILLS>
<BILL>
<BILL_ID>Bill ID </BILL_ID>
<BILL_NUMBER> Bill number</BILL_NUMBER>
<BILL_DATE> Bill date</BILL_DATE>
<BILL_PERIOD> Bill period</BILL_PERIOD>
<PAY_DATE>Payment date</PAY_DATE>
<PAYED_AMOUNT> Payment amount </PAYED_AMOUNT>
<PAYED_COMMISSION> Amount of banking commission
</PAYED_COMMISSION>
<PAYED_DEBT>Including payment of debt</PAYED_DEBT>
<AUTH_CODE> Card authorization code</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>Order description</CONTRACT_NUMBER>
<ATTRIBUTE1>Additional parameter 1</ATTRIBUTE1>
<ATTRIBUTE2>Additional parameter 2</ATTRIBUTE2>
<ATTRIBUTE3>Additional parameter 3</ATTRIBUTE3>
<ATTRIBUTE4>Additional parameter 4</ATTRIBUTE4>
</PAYER>
</BILL>
</BILLS>
</PAY_ORDER>
</PAY_ORDERS>
8.3 PAY_ORDERS message example
<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
<PAY_ORDER>
<PAY_ORDER_ID>26792</PAY_ORDER_ID>
<PAY_ORDER_DATE>2010-02-16</PAY_ORDER_DATE>
<PAY_ORDER_NUMBER>120985735</PAY_ORDER_NUMBER>
<PAY_ORDER_AMOUNT>138.85</PAY_ORDER_AMOUNT>
<PAYEE>
<NAME>Public Company “Berezka”</NAME>
<CODE>1001</CODE>
</PAYEE>
<BANK>
<NAME>JSC “Bank “Finance and Credit”</NAME>
<CODE>300131</CODE>
<ACCOUNT>29244020902980</ACCOUNT>
</BANK>
<BILLS>
<BILL>
<BILL_ID>14561</BILL_ID>
<BILL_NUMBER>3892/1</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>120.35</PAYED_AMOUNT>
<PAYED_COMMISSION>5.0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>739280</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>08967563</CONTRACT_NUMBER>
<ATTRIBUTE1>12082010</ATTRIBUTE1>
</PAYER>
</BILL>
<BILL>
<BILL_ID>14569</BILL_ID>
<BILL_NUMBER>3892/2</BILL_NUMBER>
<BILL_DATE>2010-02-01</BILL_DATE>
<BILL_PERIOD>0110</BILL_PERIOD>
<PAY_DATE>2010-02-15</PAY_DATE>
<PAYED_AMOUNT>20.50</PAYED_AMOUNT>
<PAYED_COMMISSION>1.0</PAYED_COMMISSION>
<PAYED_DEBT>0</PAYED_DEBT>
<AUTH_CODE>360157</AUTH_CODE>
<PAYER>
<CONTRACT_NUMBER>08967568</CONTRACT_NUMBER>
<ATTRIBUTE1>12082011</ATTRIBUTE1>
</PAYER>
</BILL>
</BILLS>
</PAY_ORDER>
</PAY_ORDERS>
8.3 Confirmation of payment information receipt – RESULT message
<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
<ERROR_CODE>Error code</ERROR_CODE>
<REASON>Error description</REASON>
</RESULT>
<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
<ERROR_CODE>0</ERROR_CODE>
<REASON>OK</REASON>
</RESULT>
8.4 Example of statement with authorization results in XML format
<?xml version='1.0' encoding='windows-1251' standalone='yes'?>
<portmoneresult>
<request>
<shopordernumber>305966</shopordernumber>
<shop_id>7364</shop_id>
<paymenttype>1</paymenttype>
<startdate>18/03/2010</startdate>
<enddate>18/03/2010</enddate>
<success>1</success>
</request>
<orders>
<order>
<shopordernumber>305966</shopordernumber>
<pay_date>18/03/2010</pay_date>
<description>50908: payment cards coverage</description>
<bill_amount>108.98</bill_amount>
<error_code>000</error_code>
<error_message></error_message>
<status>PAYED</status>
<pay_order_number></pay_order_number>
<pay_order_date></pay_order_date>
</order>
</orders>
</portmoneresult>
8.7 Request for getting a link to the receipt
{
"method": "getReceipt",
"params": {
"data": {
"login": "wdishop",
"password": "wdi451",
"shopOrderNumber": "SD12342"
}
},
"id": "1"
}
8.7 Example of successful response
{
"result": {
"linkPdf": "https://portmone2.com/r3/services/receipts/get-receipts/shop-bill-id/3534eff61c20da00195e14a557af25fa9cfb08110cb138958850437dfdff387dcb5ab971e4d45a9430381ee29796e8f6406ec548ad3a67d6ba31071f999a3264"
},
"id": "1"
}
To Section 9 "Refund"
<form action="https://www.portmone.com.ua/gateway/" method="post">
<input type="hidden" name="method" value="return" />
<input type="hidden" name="login" value="shp_login" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="shop_bill_id" value="87834981" />
<input type="hidden" name="return_amount" value="99.00" />
<input type="hidden" name="encoding" value="utf-8" />
<input type="hidden" name="lang" value="uk" />
</form>
9.1.1 POST refund response (successful)
<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
<request>
<method>return</method>
<login>shp_login</login>
<password>******</password>
<shop_bill_id>87834981</shop_bill_id>
<return_amount>99.00</return_amount>
<encoding>utf-8</encoding>
<lang>uk</lang>
</request>
<order>
<shop_bill_id>87834981</shop_bill_id>
<shop_order_number><![CDATA[1234]]></shop_order_number>
<description><![CDATA[Payment of order №1234]]></description>
<bill_date>15.11.2013</bill_date>
<pay_date>15.11.2013 22:21:51</pay_date>
<bill_amount>-99.00</bill_amount>
<auth_code>123456</auth_code>
<status>RETURN</status>
<error_code>0</error_code>
<error_message><![CDATA[]]></error_message>
</order>
</portmoneresult>
9.1.1 POST refund response (failure)
<order>
<error_code>5</error_code>
<error_message><![CDATA[Bill return error [SHOP_BILL_ID = 87834981]ORA-20001:
Determining payment terminal details error.[pay_terminal_id=]]]> </error_message>
</order>
{
"method": "return",
"params": {
"data": {
"login": "SHP_333",
"password": "22222222",
"payeeId": "3048",
"shopbillId": 594890029,
"returnAmount": "1",
"message": "test return by shopbillId"
}
},
"id": 1
}
[
{
"description": "",
"status": "RETURN",
"bank_id": "1000",
"terminal_id": "68611",
"merchant_id": "AVAL_TEST",
"rrn": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"commission": 0,
"shopBillId": "1035983328",
"shopOrderNumber": "P1029355342",
"billAmount": "-.5",
"errorCode": "0",
"errorMessage": "",
"authCode": "TESTPM",
"cardMask": "444433******1111",
"token": "",
"gateType": ""
}
]
9.2 Запит відміни оплати у форматі JSON
{
"method": "reject",
"params": {
"data": {
"login": "SHP_333",
"password": "22222222",
"payeeId": "3048",
"shopbillId": 594890029,
"returnAmount": "1",
"message": "test return by shopbillId"
}
},
"id": 1
}
[
{
"description": "",
"status": "RETURN",
"bank_id": "1000",
"terminal_id": "68611",
"merchant_id": "AVAL_TEST",
"rrn": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"commission": 0,
"shopBillId": "1035983328",
"shopOrderNumber": "P1029355342",
"billAmount": "-.5",
"errorCode": "0",
"errorMessage": "",
"authCode": "TESTPM",
"cardMask": "444433******1111",
"token": "",
"gateType": ""
}
]
To Section 12 "Invoicing customers by e-mail or SMS (е-invoicing)"
12.1 Form to send invoices by e-mail
<form
action="https://www.portmone.com.ua/r3/services/invoice/email/"
method="post"
target="_blank"
>
<input type="hidden" name="login" value="shp_login" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="payeeId" value="1185" />
<input type="hidden" name="shopOrderNumber" value="12345" />
<input type="hidden" name="namePayer" value="Ivanov Ivan" />
<input type="hidden" name="comment" value="Hello man!!!" />
<input type="hidden" name="amount" value="150" />
<input type="hidden" name="emailRecipient" value="[email protected]" />
<input type="hidden" name="lang" value="uk" />
<input type="hidden" name="cc_email" value="" />
<input type="hidden" name="preauth_flag" value="N" />
<input type="hidden" name="bill_currency" value="UAH" />
<input type="hidden" name="expDate" value="20190122140200" />
</form>
12.2 Form to send invoices via SMS
<form
action="https://www.portmone.com.ua/r3/services/invoice/sms/"
method="post"
target="_blank"
>
<input type="hidden" name="login" value="shp_login" />
<input type="hidden" name="password" value="******" />
<input type="hidden" name="payeeId" value="1185" />
<input type="hidden" name="shopOrderNumber" value="12345" />
<input type="hidden" name="namePayer" value="Ivanov Ivan" />
<input type="hidden" name="comment" value="Hello man!!!" />
<input type="hidden" name="amount" value="150" />
<input type="hidden" name="phoneRecipient" value="+380XXXXXXXXX" />
<input type="hidden" name="lang" value="uk" />
<input type="hidden" name="preauth_flag" value="N" />
<input type="hidden" name="bill_currency" value="UAH" />
<input type="hidden" name="expDate" value="20190122140200" />
</form>
{
"method": "invoices",
"id": "1",
"params": {
"authData": {
"login": "wdishop",
"password": "********",
"payeeId": "1185"
},
"data": {
"0": [
"Petrov Ivan",
"[email protected]",
"123",
"тест 1",
"1",
"UAH",
"N",
"uk",
"20190208132000"
],
"1": [
"Tamara Nykolaevna",
"[email protected]",
"124",
"тест 2",
"1.02",
"UAH",
"Y",
"en",
"20190208132000"
],
"2": [
"Aleksey Petrovych",
"[email protected]",
"125",
"тест 3",
"1.03",
"EUR",
"Y",
"en",
"20190208132000"
],
"3": [
"Ivan Fedorovych",
"+380930000000",
"126",
"тест 4",
"1.04",
"UAH",
"Y",
"",
"20190208132000"
],
"4": [
"Nikolay Vasylevych",
"+380930000000",
"127",
"тест 5",
"1.05",
"",
"N",
"uk",
"20190208132000"
],
"5": [
"Poddubnaia Aleksandra Serheevna",
"+380930000000",
"128",
"тест 6",
"1.06",
"",
"N",
"",
"20190208132000"
],
"6": [
"Vaska",
"[email protected]",
"129",
"тест 7",
"10.07",
"",
"N",
"",
"20190208132000"
]
}
}
}
12.3 Mass invoicing response (successful)
{
"result": {
"0": {
"shopBillId": "448808680",
"payeeId": "1185",
"shopBillNumber": "123",
"description": "test 1",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "1",
"error": "",
"errorCode": "0"
},
"1": {
"shopBillId": "448808686",
"payeeId": "1185",
"shopBillNumber": "124",
"description": "test 2",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "1.02",
"error": "",
"errorCode": "0"
},
"2": {
"shopBillId": "448808698",
"payeeId": "1185",
"shopBillNumber": "125",
"description": "test 3",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": ".44",
"error": "",
"errorCode": "0"
},
"3": {
"shopBillId": "448808699",
"payeeId": "1185",
"shopBillNumber": "126",
"description": "test 4",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "1.04",
"error": "",
"errorCode": "0"
},
"4": {
"shopBillId": "448808701",
"payeeId": "1185",
"shopBillNumber": "127",
"description": "test 5",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "1.05",
"error": "",
"errorCode": "0"
},
"5": {
"shopBillId": "448808703",
"payeeId": "1185",
"shopBillNumber": "128",
"description": "test 6",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "1.06",
"error": "",
"errorCode": "0"
},
"6": {
"shopBillId": "448808704",
"payeeId": "1185",
"shopBillNumber": "129",
"description": "test 7",
"linkInvoice": "",
"billCurrency": "UAH",
"billAmount": "10.07",
"error": "",
"errorCode": "0"
}
},
"id": "1"
}
12.4 Request for getting a payment link
{
"method": "getLinkInvoice",
"params": {
"data": {
"login": "wdishop",
"password": "wdi451",
"payeeId": "1185",
"amount": "15",
"shopOrderNumber": "123ppps31",
"emailRecipient": "[email protected]",
"comment": "test",
"expDate": "20210217175959",
"billCurrency": "USD",
"preauthFlag": "N",
"attribute1": "1",
"attribute2": "2",
"attribute3": "3",
"attribute4": "4",
"attribute5": "5"
}
},
"id": "1"
}
12.4 Getting a payment link response (successful)
{
"result": {
"linkInvoice": "https://www.portmone.com.ua/r3/uk/i/nzgi2W8pvK"
},
"id": "1"
}
12.5 Request for getting a payment link
{
"method": "createLinkPayment",
"paymentTypes": {
"clicktopay": "Y",
"createtokenonly": "N",
"token": "N",
"privat": "N",
"gpay": "Y",
"card": "Y"
},
"priorityPaymentTypes": {
"token": "6",
"gpay": "2",
"clicktopay": "4",
"privat": "5",
"card": "1"
},
"payee": {
"payeeId": "1185",
"login": "",
"dt": "",
"signature": "",
"shopSiteId": ""
},
"order": {
"description": "",
"shopOrderNumber": "578970",
"billAmount": "44",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"successUrl": "",
"failureUrl": "",
"preauthFlag": "N",
"billCurrency": "UAH",
"encoding": ""
},
"token": {
"tokenFlag": "N",
"returnToken": "Y",
"token": "",
"cardMask": "",
"otherPaymentMethods": ""
},
"payer": {
"lang": "uk",
"emailAddress": "",
"showEmail": "N"
}
}
12.5 Getting a payment link response (successful)
{
"linkPayment": "https://prt.mn/KYbE_AKxyR",
"error": "",
"errorCode": "0"
}
12.6 Request for getting a payment link
{
"method": "closeInvoice",
"params": {
"data": {
"login": "wdishop",
"password": "wdi451",
"payeeId": "1185",
"shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8"
}
}
}
12.6 Getting a payment link response (successful)
{
"description": "",
"status": "REJECTED",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"commission": 0,
"shopBillId": "1715616657",
"shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8",
"billAmount": "1459",
"errorCode": "",
"errorMessage": "Order payment time has expired or invoice was closed. ",
"authCode": "",
"cardMask": "",
"token": "",
"gateType": ""
}
To Section 13 "Transfer of funds from account to card (token)"
13.1 Request to transfer funds from account to card
{
"paymentType": "a2c",
"description": "5168742215175179",
"attribute1": "",
"attribute2": "552aa24c46c807a05bb0fc32477c19f0",
"attribute3": "3",
"attribute4": "4",
"billAmount": "1.33",
"payeeId": "17553",
"shopOrderNumber": "SHP-27810-20190913045941",
"cvvVerifyFlag": "N",
"token": "",
"billCurrency": "UAH",
"shopSiteId": "",
"cardData": "",
"dt": "20190913165941",
"signature": "7B82D64E6CC226E3A5036F6020E77BD71F517C5D49F5FF80EA24289FEDBC56AE",
"mode": "1101"
}
13.1 Transfer funds from account to card. Response (successful)
{
"status": "PAYED",
"errorCode": "0",
"error": "",
"shopBillId": "544917852",
"billAmount": "1.33",
"billNumber": "SHP-21251-20190913032725",
"attribute1": "58661656",
"attribute2": "552aa24c46c807a05bb0fc32477c19f0",
"attribute3": "838622",
"attribute4": "925615124384",
"authCode": "000000",
"payeeExportFlag": "Y",
"receiptLink": "https://portmone2.com/r3/services/receipts/get-receipts/shop-bill-id/35354f5f1297395f0d47613cb8098865636cfcd1584bd40241d634ae36efde97184b631cc0a1e8ed1c3546365bd4ce3860ac7b5b0ec0748c5236b25af3b926a624",
"billCurrency": null,
"transactionId": "ZEM_1647320190913032726"
}
13.2 Request to transfer of funds from account to card token
{
"description": "test",
"paymentType": "a2t_1",
"attribute1": "",
"attribute2": "\"client_id\":\"Іванов Іван\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
"attribute3": "3",
"attribute4": "4",
"billAmount": "1",
"payeeId": "18875",
"shopOrderNumber": "SHP-1445284353-20201020025708",
"cvvVerifyFlag": "Y",
"billCurrency": "UAH",
"mode": "1101",
"cardData": "",
"dt": "20201020145708",
"signature": "193955BF02ED0B08D42F8819D4127EB48056B3109AB68DE074A4568BD55AAECB",
"token": "18373333393634343931096442C3FD3DA5C78E03FF93B95339EDA2AA690C6E1FD63C113A431349F33C152E44EA98082AEEF72122638264BF65F9A38"
}
13.2 Transfer of funds from account to card token. Response (successful)
{
"status": "PAYED",
"errorCode": "0",
"error": "",
"shopBillId": "866480371",
"billAmount": "1",
"shopOrderNumber": "464354715",
"attribute1": "70456009",
"attribute2": "\"client_id\":\"Ivanov Ivan\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
"attribute3": null,
"attribute4": "4",
"authCode": "000000",
"payeeExportFlag": "N",
"receiptLink": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3535cc3cd0f108cbcbce4967d6501411807b39b0e068fb26a93147adfcc15cf7d5c78d9ab343063e01b82dc7ecb14809772100682ef57b2782095b38c27a03e0ab",
"billCurrency": "UAH",
"transactionId": null
}