# Creating an 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:

| | 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](https://docs.merchant.alb.ua/en/dictionary/prioritybankcode-directory) 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)

| No | "Іваненко" (Ivanenko) | | senderLastName | Sender's last name. |

string(30)

| No | "Іван" (Ivan) | | senderMiddleName | Sender's middle name. |

string(30)

| No | "Іванович" (Ivanovych) | | senderEmail | Sender's email. | string (256) | No | `mail@gmail.com` | | 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 | \ | 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: . | string | `https://bank.gov.ua/qr/QkNECjAwMwoxCklDVAoK0JrQvtCy0LDQu9GM0YHRjNC60LjQuSDQktC70LDQtNC40YHQu9Cw0LIg0KLQtdGB0YIKVUExMjMyMjAwMTAwMDAwMjYyMDYzNjM1MDU1MTMKVUFIMTAuMDAKMzQ2NzgwODE1MApNUDJCL09USFIKMTc2Mjk1MDQ0ODg2MEZFUmtMbDc2bENwCjEzN2Q5MzA0LTAzNjgtMTE9ZWI5MzkKUGF5bWVudCBmb3IgT3JkZXIg4oSWMTIzNDU2CkZGRkYKMjUxMTEyMTQ0MjI4CjI1MTExMjE0MjcyOAoK` | ### Example Request Body: `hppPayType = PURCHASE` ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "hppPayType": "PURCHASE", "directType": "REDIRECT", "failUrl": "https://example.com/fail", "successUrl": "https://example.com/success", "merchantRequestId": "137d93491081eb", "merchantComment": "12", "statusPageType": "STATUS_PAGE", "expirationTimeMinutes": 1440, "paymentMethods": [ "CARD", "APPLE_PAY", "GOOGLE_PAY" ], "customerData": { "senderCustomerId": "Id", "senderEmail": "aaaa@gmail.com", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStret", "senderCity": "senderCity", "senderIp": "255.255.244.255", "senderBirthday": "22081989", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "senderPassport", "senderItn": "5555557777", "senderPhone": "380957388888" }, "coinAmount": 1000, "purpose": "Payment for Order №123456", "language": "uk", "notificationUrl": "https://example.com/notify" } ``` ### Example Response Body: `hppPayType = PURCHASE` ```json { "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "statusUrl": "https://defe-status-page.develop.bankalliance.ua/?hpp_id=1762952514564YK07ZIElutD", "hppOrderId": "1762952514564YK07ZIElutD", "ecomOrderId": "b57fdfad-a7ba-4f4a-bd5f-07c07e2f2813", "redirectUrl": "https://defe-pgi-ecom.develop.bankalliance.ua/?hpp_id=1762952514564YK07ZIElutD", "hppPayType": "PURCHASE", "merchantRequestId": "137d93491081eb", "orderStatus": "PENDING", "paymentMethods": [ "CARD", "APPLE_PAY", "GOOGLE_PAY" ], "createDate": "2025-11-12 15:01:54.50+02:00", "expiredOrderDate": "2025-11-13 15:01:54.56+02:00", "nbuQrCode": null } ``` ### Example Request Body: `hppPayType = A2A` and `priorityBankCode = null` ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "hppPayType": "A2A", "directType": "BANK_LINK", "failUrl": "https://example.com/fail", "successUrl": "https://example.com/success", "merchantRequestId": "137d93491081eb939", "merchantComment": "137d9304-0368-11=eb939", "statusPageType": "STATUS_PAGE", "expirationTimeMinutes": 1440, "priorityBankCode": null, "paymentMethods": [ "CARD" ], "customerData": { "senderCustomerId": "Id", "senderEmail": "aaaa@gmail.com", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStret", "senderCity": "senderCity", "senderIp": "255.255.244.255", "senderBirthday": "22081989", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "senderPassport", "senderItn": "5555557777", "senderPhone": "380957388888" }, "coinAmount": 1000, "purpose": "Payment for Order №123456", "language": "uk", "notificationUrl": "https://example.com/notify", "generateQrNbu": "true" } ``` ### Example Response Body: `hppPayType = A2A` and `priorityBankCode = null` ```json { "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "statusUrl": null, "hppOrderId": "1762952144215CrdMyJEw_AI", "ecomOrderId": "80820e24-af95-4a7e-991b-f83efe851e86", "redirectUrl": "https://defe-ecom-deep-link.develop.bankalliance.ua/?redirectUrl=https%3A%2F%2Fbankalliance.go.link%2Fecomc2a%3Forder_id%3D1762952144215CrdMyJEw_AI%26adj_t%3D1rknh2ig%26adj_deep_link%3Dbankalliance%253A%252F%252Fecomc2a%253Forder_id%253D1762952144215CrdMyJEw_AI", "hppPayType": "A2A", "merchantRequestId": "137d93491081eb939", "orderStatus": "PENDING", "paymentMethods": [ "CARD" ], "createDate": "2025-11-12 14:55:44.18+02:00", "expiredOrderDate": "2025-11-13 14:55:44.21+02:00", "nbuQrCode": "https://bank.gov.ua/qr/QkNECjAwMwoxCklDVAoK0JrQvtCy0LDQu9GM0YHRjNC60LjQuSDQktC70LDQtNC40YHQu9Cw0LIg0KLQtdGB0YIKVUExMjMyMjAwMTAwMDAwMjYyMDYzNjM1MDU1MTMKVUFIMTAuMDAKMzQ2NzgwODE1MApNUDJCL09USFIKMTc2Mjk1MjE0NDIxNUNyZE15SkV3X0FJCjEzN2Q5MzA0LTAzNjgtMTE9ZWI5MzkKUGF5bWVudCBmb3IgT3JkZXIg4oSWMTIzNDU2CkZGRkYKMjUxMTEzMTQ1NTQ0CjI1MTExMjE0NTU0NAoK" } ``` ### Example Request Body: `hppPayType = A2A` and `priorityBankCode = PRIVAT_BANK` ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "hppPayType": "A2A", "directType": "BANK_LINK", "failUrl": "https://example.com/fail", "successUrl": "https://example.com/success", "merchantRequestId": "137d93491081eb93", "merchantComment": "137d9304-0368-11=eb939", "statusPageType": "STATUS_PAGE", "expirationTimeMinutes": 1440, "priorityBankCode": "PRIVAT_BANK", "paymentMethods": [ "CARD" ], "customerData": { "senderCustomerId": "Id", "senderEmail": "aaaa@gmail.com", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStret", "senderCity": "senderCity", "senderIp": "255.255.244.255", "senderBirthday": "22081989", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "senderPassport", "senderItn": "5555557777", "senderPhone": "380957388888" }, "coinAmount": 1000, "purpose": "Payment for Order №123456", "language": "uk", "notificationUrl": "https://example.com/notify", "generateQrNbu": "true" } ``` ### Example Response Body: `hppPayType = A2A` and `priorityBankCode = PRIVAT_BANK` ```json { "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "statusUrl": null, "hppOrderId": "1762952263495CsBJT9xC-s4", "ecomOrderId": "cce880f8-18e5-4cbc-8d88-0a85903d80e9", "redirectUrl": "https://www.privat24.ua/rd/send_qr/nbu/QkNECjAwMwoxCklDVAoK0JrQvtCy0LDQu9GM0YHRjNC60LjQuSDQktC70LDQtNC40YHQu9Cw0LIg0KLQtdGB0YIKVUExMjMyMjAwMTAwMDAwMjYyMDYzNjM1MDU1MTMKVUFIMTAuMDAKMzQ2NzgwODE1MApNUDJCL09USFIKMTc2Mjk1MjI2MzQ5NUNzQkpUOXhDLXM0CjEzN2Q5MzA0LTAzNjgtMTE9ZWI5MzkKUGF5bWVudCBmb3IgT3JkZXIg4oSWMTIzNDU2CkZGRkYKMjUxMTEzMTQ1NzQzCjI1MTExMjE0NTc0MwoK", "hppPayType": "A2A", "merchantRequestId": "137d93491081eb93", "orderStatus": "PENDING", "paymentMethods": [ "CARD" ], "createDate": "2025-11-12 14:57:43.46+02:00", "expiredOrderDate": "2025-11-13 14:57:43.49+02:00", "nbuQrCode": "https://bank.gov.ua/qr/QkNECjAwMwoxCklDVAoK0JrQvtCy0LDQu9GM0YHRjNC60LjQuSDQktC70LDQtNC40YHQu9Cw0LIg0KLQtdGB0YIKVUExMjMyMjAwMTAwMDAwMjYyMDYzNjM1MDU1MTMKVUFIMTAuMDAKMzQ2NzgwODE1MApNUDJCL09USFIKMTc2Mjk1MjI2MzQ5NUNzQkpUOXhDLXM0CjEzN2Q5MzA0LTAzNjgtMTE9ZWI5MzkKUGF5bWVudCBmb3IgT3JkZXIg4oSWMTIzNDU2CkZGRkYKMjUxMTEzMTQ1NzQzCjI1MTExMjE0NTc0MwoK" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.merchant.alb.ua/en/payment-methods-hpp/purchase/creating-an-order.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.