Pre-authorization Request (Preauth) — Step 1
{{url}}/ecom/execute_request/payments/v1/create/preauth
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 ,.;:@#)
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).
Іванович
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
{
"merchantRequestId": "e2980c5e-cddc-4ccf-be36-47ef8c73da84",
"merchantId": "137d9304-0368-11ed-b939-0242ac120002",
"encryptedCardNumber": "5573670000000304",
"coinAmount": "100",
"txnType": "NONCVV",
"desiredThreeDSMode": "SHOULD",
"notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d",
"notificationEncryption": true,
"date": "2024.09.19T15:29:25.00+00:00",
"purpose": "LLopo",
"preAuthExpDate": "2025-10-07T14:27:00.00+00:00",
"customerData": {
"senderCustomerId": "1258728c1"
// ... other sender fields ...
}
}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"
// ... remaining fields are null or omitted ...
}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
{
"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"
// ... all sender and other fields ...
}Last updated