# Pre-authorization Request (Preauth) — Step 1
#### Input Parameters
| **Parameter Name** | **Type / Format** | **Required** | **Description / Constraints** | **Example** |
| ----------------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| merchantRequestId | `string(36)` | Yes | A unique identifier generated by the merchant's system, used to check operation status if the request ends with an unknown error or disconnection. | `137d9304-0368-11ed-b939-0242ac120002` |
| merchantId | `string(36)` | Yes | Merchant ID generated within the Ecom system. | `137d9304-0368-11ed-b939-0242ac120002` |
| encryptedCardNumber | `string` | Yes | Card number encrypted in JWE using the public payment key. | `5573670000000304` (Decrypted view) |
| coinAmount | `string` | Yes | Payment amount in cents/kopecks. | `2000` |
| txnType | `enum` | No | Sub-type of the transaction.
Possible Values: NONCVV/noncvv
If specified: CVV entry and check are NOT performed.
If NOT specified: CVV entry and check ARE performed.
| `NONCVV` |
| desiredThreeDSMode | `string(50)` | Yes | An indicator of whether the merchant wishes to use 3DS for the purchase. Default: SHOULD
Possible Values:
- MUST: Merchant requires payment with 3DS.
- MUST\_NOT: Force operation without 3DS.
- SHOULD: If the card supports 3DS, the check is performed.
| `SHOULD` |
| notificationUrl | `string(1000)` | No | The URL to which the CallBack will be sent. | `https://merchant.notification_url` |
| notificationEncryption | `string` | No | Indicator for CallBack data encryption.
Possible Values: true/false. If omitted or false, data in CallBack will not be encrypted.
| `true` |
| date | `string` | Yes | Date and time of the payment. | `{{currentdateT}}.00+00:00` |
| comment | `string(1000)` | No | Additional operation description filled in by the merchant's customer. | `///5555.25412` |
| purpose | `string(255)` | No | Payment purpose filled in by the merchant. | `За товар` (For goods) |
| resultRedirectUrl | `string(1000)` | No | URL for customer redirection after successful 3DS authentication. | |
| customerData | `object` | Yes | Object containing customer data (contains all fields below starting with `senderCustomerId`). | |
| merchantComment | `string(255)` | No | Additional information/comment from the merchant regarding the order. (Allowed chars: a-zA-Z0-9 ,.;:@#$$ $%'-=+1,256$ $$) | `merchant Comment id 1258728c1` |
| preAuthExpDate | `string` | Yes | Date and time when the pre-authorization action expires. This parameter determines the moment until which the pre-authorized amount remains blocked on the customer's card. After this date, the system will automatically reverse the operation if it has not been completed earlier.
Constraints:
- Value must be at least 2 hours later than the operation creation date.
- Value must be no more than 28 days later than the date passed in the request.
| `{{currentdateT}}.00+00:00` |
| senderCustomerId | `string(255)` | Yes | Sender's Customer ID. | `1258728c1` |
| senderFirstName | `string(30)` | No | Sender's first name. (Constraints: Cannot contain only digits; cannot contain dots or special symbols; must be alphanumeric; may contain space/hyphen internally, but not at the start/end; use UTF-8 apostrophe `'` (u0027)). | `Іваненко` |
| senderLastName | `string(30)` | No | Sender's last name. (Same constraints as above, plus cannot be "NULL", "3D SECURE", etc.) | `Іван` |
| senderMiddleName | `string(30)` | No | Sender's middle name. (Same constraints as above). | `Іванович` |
| senderEmail | `string(256)` | No | Sender's email. | `mail@gmail.com` |
| senderСountry | `string(3)` | No | Sender's country (ISO 3166, 804 for Ukraine). | `804` |
| senderRegion | `string(255)` | No | Sender's region/oblast. | `Київська` |
| senderСity | `string(25)` | No | Sender's city. | `Київ` |
| senderStreet | `string(35)` | No | Sender's street. | `Січових стрільців` |
| senderAdditionalAddress | `string(255)` | No | Sender's additional address data (floor, house number, apartment). | `23` |
| senderItn | `string(20)` | No | Sender's Tax ID (ІПН). | `123456789` |
| senderPassport | `string(255)` | No | Sender's Passport ID. | `АН123456` |
| senderIp | `string(50)` | No | Sender's IPv4 address. | `123.12.12.12` |
| senderPhone | `string(20)` | No | Sender's phone number. | `380630000000` |
| senderBirthday | `string(50)` | No | Sender's date of birth. | `31.12.2000` |
| senderGender | `string(50)` | No | Sender's gender. (Male/Female) | `Male` |
| senderZipCode | `string(50)` | No | Sender's zip code. | `49000` |
#### Output Parameters
| **Parameter Name** | **Type** | **Description / Possible Values** | **Example** |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| type | `string` | Transaction type. | `PREAUTH` |
| rrn | `string` | RRN (Retrieval Reference Number) of the transaction in the payment system. | `2554256963` |
| purpose | `string` | Payment purpose. | `За товар` |
| comment | `string` | Comment. | `тест` |
| coinAmount | `int` | Payment amount in cents/kopecks. | `2000` |
| merchantId | `string` | Merchant ID. | `137d9304-0368-11ed-b939-0242ac120002` |
| operationId | `string` | Transaction ID. | `1712844596346b9F-WwrWZpq` |
| ecomOperationId | `string` | Transaction ID in the Ecom system. | `8c3303e9-7396-43b8-af4e-31d9facdde9b` |
| merchantName | `string` | Merchant name. | `KB test terminal` |
| approvalCode | `string` | Authorization code. | `39203` |
| status | `string` | Transaction status.
Possible Values: SUCCESS, FAIL, PENDING, REQUIRED\_3DS, DESIRED\_THREEDS\_MODE\_ERROR
| `SUCCESS` |
| transactionType | `string` | Transaction type in numerical value. | `195` |
| merchantRequestId | `string` | Merchant's request ID. | `72837906-f526-4aef-8d11-58d80b44cb75` |
| transactionCurrency | `string` | Payment currency (ISO code). | `980` |
| merchantCommission | `string` | Commission amount. | `2` |
| createDateTime | `string` | Date and time of payment creation. | `2024.09.19 15:29:25.675` |
| modificationDateTime | `string` | Date and time of payment modification. | `2024.09.19 15:29:25.675` |
| actionCode | `string` | Response code. | `0` |
| responseCode | `string` | Response details. | `0` |
| description | `string` | Response description. | `approved` |
| bankCode | `string` | Issuing bank name. | `BANK_ALLIANCE` |
| paymentSystem | `string` | Issuing payment system name. | `MasterCard` |
| productType | `string` | Terminal product type. | `PURCHASE` |
| notificationUrl | `string` | URL to which the CallBack was sent. | `https://merchant.notification_url/` |
| paymentServiceType | `string` | Payment type. (CARD/APPLE\_PAY/GOOGLE\_PAY) | `CARD` |
| notificationEncryption | `string` | CallBack data encryption indicator. | `true/false` |
| cardNumberMask | `string` | Masked card number. | `5573********0304` |
| desiredThreeDSMode | `string` | 3DS mode requested by the merchant. | `MUST/SHOULD/MUST_NOT` |
| threeDSMode | `string` | Indicator showing if 3DS was used in the purchase. (MUST/MUST\_NOT) | `MUST` |
| statusThreeDs | `string` | 3DS execution status. (Y - successful 3DS, N - unsuccessful 3DS) | `Y` |
| threeDSServerTransId | `string` | Transaction ID in the 3DS system. | `8a811df4-91e0-436b-a9ac-9b0772c96f28` |
| redirect3dsUrl | `string` | URL for customer redirection to the issuer's page for 3DS authentication. | `https://api-ecom-release...` |
| txnType | `enum` | Sub-type of the transaction. (NONCVV/noncvv - CVV check was NOT performed). | `NONCVV` |
| preAuthExpDate | `string` | Date and time when the pre-authorization action expires. | `2025.10.07 14:27:00.000` |
| *Sender & 3DS details* | *string* | *All sender details and 3DS IDs (`acsTransId`, `dsTransId`, `eci`, etc.) are also returned.* | |
#### Request and Response Examples
**Example Request Body**
```json
{
"merchantId": "467c8a10-c705-11ed-afa1-0242ac120002",
"merchantRequestId": "{{requestUUIDT}}",
"encryptedCardNumber": "{{encryptedPanT}}",
"coinAmount": "100",
"comment": "comment",
"notificationUrl": "",
"purpose": "purpose",
"resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru",
"desiredThreeDSMode": "MUST",
"preAuthExpDate": "2025-10-07 14:27:00.00+03:00",
"customerData": {
"senderFirstName": "John",
"senderLastName": "Doe",
"senderMiddleName": "Fall",
"senderEmail": "test@gmail.com",
"senderCountry": "sender_country",
"senderRegion": "sender_region",
"senderCity": "sender_city",
"senderStreet": "sender_street",
"senderAdditionalAddress": "N 6",
"senderItn": "12345",
"senderPassport": "12345",
"senderIp": "165.222.87.224",
"senderPhone": "380967542344",
"senderBirthday": "12/12/2000",
"senderGender": "Male",
"senderZipCode": "12345"
}
"date": "{{currentdateT}}.00+00:00"
}
```
**Example Response Body (Without 3DS)**
This response indicates that 3DS was not required or skipped (e.g., if `desiredThreeDSMode` was `MUST_NOT`, or card was non-3DS capable).
```json
{
"type": "PREAUTH",
"rrn": null,
"purpose": "LLopo",
"comment": "RRRR",
"coinAmount": 100,
"merchantId": "137d9304-0368-11ed-b939-0242ac120002",
"operationId": "1712822786872mHQm6XSmmKt",
"ecomOperationId": "2bbd1b87-9a07-41cc-9789-48d8895b3cf1",
"merchantName": null,
"approvalCode": null,
"status": "PENDING",
"transactionType": 195,
"merchantRequestId": "e2980c5e-cddc-4ccf-be36-47ef8c73da84",
"transactionCurrency": "980",
"merchantCommission": null,
"createDateTime": "2024.09.19 15:29:25.675",
"modificationDateTime": "2024.09.19 15:29:25.675",
"transactionResponseInfo": {
"actionCode": null,
"responseCode": null,
"description": null
},
"bankCode": null,
"paymentSystem": null,
"productType": "PURCHASE",
"preAuthExpDate": "2025-10-07 14:27:00.00+03:00",
"notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d",
"paymentServiceType": "CARD",
"notificationEncryption": true,
"cardNumberMask": null,
"desiredThreeDSMode": "MUST_NOT",
"threeDSMode": "MUST_NOT",
"statusThreeDs": null,
"threeDSServerTransId": null,
"redirect3dsUrl": null,
"txnType": "null",
"senderCustomerId": null,
"senderFirstName": null,
"senderLastName": null,
"senderMiddleName": null,
"senderEmail": null,
"senderCountry": null,
"senderRegion": null,
"senderCity": null,
"senderStreet": null,
"senderAdditionalAddress": null,
"senderItn": null,
"senderPassport": null,
"senderIp": null,
"senderPhone": null,
"senderBirthday": null,
```
**Example Response Body (With 3DS Required)**
This response requires the merchant to redirect the customer to the URL provided in `redirect3dsUrl` to complete authentication.
```json
{
"type": "PREAUTH",
"rrn": null,
"purpose": "LLopo",
"comment": "RRRR",
"coinAmount": 100,
"merchantId": "137d9304-0368-11ed-b939-0242ac120002",
"operationId": "1712822536063CdDIRi8hhjq",
"ecomOperationId": "82da90c3-50b8-4d5b-b357-2cbe55167200",
"merchantName": null,
"approvalCode": null,
"status": "REQUIRED_3DS",
"transactionType": 195,
"merchantRequestId": "8aa31389-fe6f-4b40-bb5e-4ecedfefb847",
"transactionCurrency": "980",
"merchantCommission": null,
"createDateTime": "2024.09.19 15:29:25.675",
"modificationDateTime": "2024.09.19 15:29:25.675",
"transactionResponseInfo": {
"actionCode": null,
"responseCode": null,
"description": null
},
"bankCode": null,
"paymentSystem": null,
"productType": "PURCHASE",
"preAuthExpDate": "2025-10-07 14:27:00.00+03:00",
"notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d",
"paymentServiceType": "CARD",
"notificationEncryption": true,
"cardNumberMask": null,
"desiredThreeDSMode": "MUST",
"threeDSMode": "MUST",
"statusThreeDs": null,
"threeDSServerTransId": "0ce5cc44-2698-4a2c-969a-3155bad68b6e",
"redirect3dsUrl": null,
"txnType": "null",
"senderCustomerId": null,
"senderFirstName": null,
"senderLastName": null,
"senderMiddleName": null,
"senderEmail": null,
"senderCountry": null,
"senderRegion": null,
"senderCity": null,
"senderStreet": null,
"senderAdditionalAddress": null,
"senderItn": null,
"senderPassport": null,
"senderIp": null,
"senderPhone": null,
"senderBirthday": null,
"senderGender": null
```
---
# 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-h2h/preauthorization-and-completion/pre-authorization-request-preauth-step-1.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.