> For the complete documentation index, see [llms.txt](https://docs.merchant.alb.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.merchant.alb.ua/en/payment-methods-h2h/preauthorization-and-completion/pre-authorization-request-preauth-step-1.md).
# 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
```