Creating an order
{{url}}/ecom/execute_request/hpp/v1/create-order
Input parameters:
Parameter
Description
Data Format
Mandatory
Example
merchantRequestId
A unique identifier generated by the merchant's system, used to check the operation status if the request resulted in an unknown error or disconnection.
string(36)
Yes
137d9304-0368-11ed-b939-0242ac120002
merchantId
Merchant ID generated in Ecom.
string(36)
Yes
137d9304-0368-11ed-b939-0242ac120002
hppPayType
Payment type.
string
Yes
Available values: PURCHASE, A2A
directType
Method for redirecting the client to the payment page.
enum
No
REDIRECT - (default) redirects to the HPP page. BANK_LINK - redirects to the mobile application.
expirationTimeMinutes
Link validity period (value is passed in minutes).
int (4)
No
1440
coinAmount
Order amount in cents (kopecks).
long
Yes
2000
paymentMethods
Payment methods.
enum
Yes
Available values: CARD, APPLE_PAY, GOOGLE_PAY
language
Language of the payment widget. ISO 639-1 2 digits.
string (50)
No
Available values: uk (default), en, es, de, pl, fr, tr, it, nl, pt
notificationUrl
URL to which the Callback will be sent.
string (1000)
No
https://merchant.notification_url
notificationEncryption
Flag for encrypting Callback data.
string
No
If the parameter is not passed or passed as false, the data in the Callback will not be encrypted.
successUrl
URL for redirecting to the merchant's website upon successful status.
string (1000)
Yes
https://example.com/success
failUrl
URL for redirecting to the merchant's website upon unsuccessful status.
string (1000)
Yes
https://example.com/fail
statusPageType
Type of status page.
enum
Yes
Available values:
STATUS_TIMER_PAGE - default page, if the merchant has not selected the desired type, the redirect timer automatically 1 minute displays the status page with automatic redirection of the user to the merchant's site (redirect URL)
STATUS_REDIRECT_MERCHANT_PAGE - immediate redirect to the merchant's URL
STATUS_PAGE - redirect, to our status page (download receipt ...)
purpose
Payment purpose filled in by the merchant.
string (255)
No
"За товар" (For goods)
merchantComment
Additional information/comment from the merchant regarding the order.
string(255) a-zA-Z0-9 ,.;:@#$%'-=+1,256$ (min 14, max 255 chars for hppPayType = A2A)
Yes, if hppPayType = A2A
merchant Comment id 1258728c1
priorityBankCode
ID of the priority application. For NBU QR generation.
string
No
PRIVAT_BANK (See Available values for all options)
paymentCategoryGoal
Goal category. For NBU QR generation.
string
No
MP2B/OTHR
generateQrNbu
Flag for NBU QR generation.
boolean
No
true or false, default = false
customerData
Object with customer data.
object
Yes
senderCustomerId
Sender's client ID.
string (255)
Yes
1258728c1
senderFirstName
Sender's first name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
"Іваненко" (Ivanenko)
senderLastName
Sender's last name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
"Іван" (Ivan)
senderMiddleName
Sender's middle name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
"Іванович" (Ivanovych)
senderCountry
Sender's country.
string (3) ISO 3166, 804 (Ukraine)
No
804
senderRegion
Sender's region (oblast).
string (255)
No
"Київська" (Kyivska)
senderCity
Sender's city.
string (25)
No
"Київ" (Kyiv)
senderStreet
Sender's street.
string (35)
No
"Січових стрільців" (Sichovykh Striltsiv)
senderAdditionalAddress
Additional sender address data (floor, house number, apartment).
string (255)
No
23
senderItn
Sender's tax ID (ITN).
string (20)
No
123456789
senderPassport
Sender's passport details.
string (255)
No
АН123456
senderIp
Sender's IPv4 address.
string (50)
No
123.12.12.12
senderPhone
Sender's phone number.
string (20)
No
380630000000
senderBirthday
Sender's date of birth.
string (50)
No
31.12.2000
senderGender
Sender's Gender.
string (50)
No
Male/Female
senderZipCode
Sender's Zip Code.
string (50)
No
49000
Output parameters:
Parameter
Description
Data Format
Example
hppOrderId
Order ID.
string
1764688635274xVtoUo7bDcn
merchantRequestId
Unique merchant ID.
string
64d9304-0368-11ed-b939-0242ac1221458
hppPayType
Payment type.
string
PURCHASE, A2A
paymentMethods
Payment methods.
enum
CARD
orderStatus
Order status.
string
SUCCESS, FAIL, PENDING, REQUIRED_3DS, CANCELED, PARTIAL_REFUND
coinAmount
Order amount in cents (kopecks).
long
2000
merchantId
Merchant ID generated in Ecom.
string
37d9304-0368-11ed-b939-0242ac120002
expiredOrderDate
Date and time the order is valid until.
string
2024-09-05 18:35:18.210+03:00
redirectUrl
<ul><li>Link for redirecting the client to the HPP page.</li><li>Link for redirecting the client to the mobile application.</li></ul>
string
HPP Example: {{url}}/?hpp_id=1728551936236-DAfCP7wrKT A2A Example: {{url}}/?redirectUrl=https%3A%2F%2Fbankalliance.go.link%2Fecomc2a%3Forder_id%3D1762950448860FERkLl76lCp%26adj_t%3D1rknh2ig%26adj_deep_link%3Dbankalliance%253A%252F%252Fecomc2a%253Forder_id%253D1762950448860FERkLl76lCp
createDate
Date and time the order was created.
string
2024-09-05 18:35:18.210+03:00
statusUrl
URL for redirecting to the status page.
string
{{url}}/?hpp_id=1728551936236-DAfCP7wrKT
nbuQrCode
Redirect URL for displaying the NBU QR. Default: https://bank.gov.ua/qr/.
string
https://bank.gov.ua/qr/QkNECjAwMwoxCklDVAoK0JrQvtCy0LDQu9GM0YHRjNC60LjQuSDQktC70LDQtNC40YHQu9Cw0LIg0KLQtdGB0YIKVUExMjMyMjAwMTAwMDAwMjYyMDYzNjM1MDU1MTMKVUFIMTAuMDAKMzQ2NzgwODE1MApNUDJCL09USFIKMTc2Mjk1MDQ0ODg2MEZFUmtMbDc2bENwCjEzN2Q5MzA0LTAzNjgtMTE9ZWI5MzkKUGF5bWVudCBmb3IgT3JkZXIg4oSWMTIzNDU2CkZGRkYKMjUxMTEyMTQ0MjI4CjI1MTExMjE0MjcyOAoK
Example Request Body: hppPayType = PURCHASE
hppPayType = PURCHASEExample Response Body: hppPayType = PURCHASE
hppPayType = PURCHASEExample Request Body: hppPayType = A2A and priorityBankCode = null
hppPayType = A2A and priorityBankCode = nullExample Response Body: hppPayType = A2A and priorityBankCode = null
hppPayType = A2A and priorityBankCode = nullExample Request Body: hppPayType = A2A and priorityBankCode = PRIVAT_BANK
hppPayType = A2A and priorityBankCode = PRIVAT_BANKExample Response Body: hppPayType = A2A and priorityBankCode = PRIVAT_BANK
hppPayType = A2A and priorityBankCode = PRIVAT_BANKLast updated