# Card Verification Request Step 1

#### Input parameters of the JWS payload part:

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data format</th><th>Required</th><th>Example</th></tr></thead><tbody><tr><td>merchantRequestId</td><td>unique identifier generated by the merchant system, used to be able to find out the status of the operation if the request ended with an unknown error or disconnection</td><td>string(36)</td><td>Yes</td><td>137d9304-0368-11ed-b939-0242ac120002</td></tr><tr><td>merchantId</td><td>Merchant Id generated in Ekom</td><td>string(36)</td><td>Yes</td><td>137d9304-0368-11ed-b939-0242ac120002</td></tr><tr><td>encryptedCardNumber</td><td>card number encrypted in JWE using public payment key</td><td>string</td><td>Yes</td><td>5573670000000304 (decrypted form)</td></tr><tr><td>desiredThreeDSMode</td><td>a flag that indicates whether the merchant wants to use 3DS in the purchase or not.</td><td>string (50)</td><td>Yes</td><td><p>Default SHOULD</p><p>Possible values:</p><ul><li>MUST - the merchant requires payment with 3DS</li><li>MUST_NOT - forced operation without 3DS</li><li>SHOULD - if the card supports 3DS, then we perform a check</li></ul></td></tr><tr><td>notificationUrl</td><td>url to which the notification will be sent CallBack</td><td>string (1000)</td><td>No</td><td>https://merchant.notification_url</td></tr><tr><td>notificationEncryption</td><td>CallBack data encryption flag</td><td>string</td><td>No</td><td><p>true/false</p><p>If the parameter is not passed or is passed false, the data in CallBack will be unencrypted</p></td></tr><tr><td>date</td><td>date and time of payment</td><td>string</td><td>Yes</td><td>{{currentdateT}}.00+00:00</td></tr><tr><td>comment</td><td>additional description of the transaction filled in by the merchant's client</td><td>string (1000)</td><td>No</td><td>///5555.25412</td></tr><tr><td>purpose</td><td>payment purpose filled in by the merchant</td><td>string (255)</td><td>No</td><td>For product</td></tr><tr><td>merchantComment</td><td>additional information\merchant comment on the order</td><td><p>string(255)</p><p>a-zA-Z0-9 ,.;:@#$%'-=+1,256$</p></td><td>No</td><td>merchant Comment id 1258728c1</td></tr><tr><td>resultRedirectUrl</td><td>Url to redirect the customer after passing 3DS authentication</td><td>string (1000)</td><td>No</td><td><a href="https://support.google.com/"><img src="https://support.google.com/favicon.ico" alt="">Google Help</a></td></tr><tr><td>customerData</td><td>object with customer data</td><td>object</td><td>Yes</td><td></td></tr><tr><td>senderCustomerId</td><td>Sender customer ID</td><td>string (255)</td><td>Yes</td><td>1258728c1</td></tr><tr><td>senderFirstName</td><td>sender name</td><td><p>string (30)</p><ul><li>value cannot contain only numbers</li><li>cannot contain periods or other special characters</li><li>cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”</li><li>only alphanumeric values ​​are allowed</li><li>can accept spaces and hyphens, but cannot be exclusively with “ “ or “-“</li><li>a hyphen or space can be inside, but cannot be at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - '<br>which is in:<br>utf 16 - u0027<br>utf32 - 00000027</li></ul></td><td>No</td><td>Ivanenko</td></tr><tr><td>senderLastName</td><td>sender's last name</td><td><p>string (30)</p><ul><li>the value cannot contain only numbers</li><li>cannot contain periods and other special characters</li><li>only alphanumeric values ​​are allowed</li><li>can accept space and hyphen, but cannot consist exclusively of “ “ or “-“</li><li>a hyphen or space can be inside, but cannot be at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - '<br>which is in:<br>utf 16 - u0027<br>utf32 - 00000027</li></ul></td><td>No</td><td>Ivan</td></tr><tr><td>senderMiddleName</td><td>sender's middle name</td><td><p>string (30)</p><ul><li>value cannot contain only numbers</li><li>cannot contain periods or other special characters</li><li>only alphanumeric values ​​are allowed</li><li>can accept spaces and hyphens, but cannot consist exclusively of “ “ or “-“</li><li>a hyphen or space can be inside, but cannot be at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - '<br>which is in:<br>utf 16 - u0027<br>utf32 - 00000027</li></ul></td><td>No</td><td>Ivanovich</td></tr><tr><td>senderEmail</td><td>sender's email</td><td>string (256)</td><td>No</td><td><a href="mailto:mail@gmail.com">mail@gmail.com</a></td></tr><tr><td>senderCountry</td><td>sender's country</td><td>string (3) ISO 3166, 804 (Ukraine)</td><td>No</td><td>804</td></tr><tr><td>senderRegion</td><td>region sender</td><td>string (255)</td><td>No</td><td>Kyiv</td></tr><tr><td>senderСity</td><td>sender city</td><td>string (25)</td><td>No</td><td>Kyiv</td></tr><tr><td>senderStreet</td><td>sender street</td><td>string (35)</td><td>No</td><td>Sichovyh striltsiv</td></tr><tr><td>senderAdditionalAddress</td><td>additional sender address data (floor, house number, apartment)</td><td>string (255)</td><td>No</td><td>23</td></tr><tr><td>senderItn</td><td>sender's IP address</td><td>string (20)</td><td>No</td><td>123456789</td></tr><tr><td>senderPassport</td><td>sender's passport</td><td>string (255)</td><td>No</td><td>AN123456</td></tr><tr><td>senderIp</td><td>sender's IP address</td><td>string (50)</td><td>No</td><td>123.12.12.12</td></tr><tr><td>senderPhone</td><td>sender phone number</td><td>string (20)</td><td>No</td><td>380630000000</td></tr><tr><td>senderBirthday</td><td>sender's birthday</td><td>string (50)</td><td>No</td><td>12/31/2000</td></tr><tr><td>senderGender</td><td>sender's gender</td><td>string (50)</td><td>No</td><td>Male/Female</td></tr><tr><td>senderZipCode</td><td>Sender Zip Code</td><td>string (50)</td><td>No</td><td>49000</td></tr></tbody></table>

#### Output parameters of the JWS payload part:

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data Format</th><th>Example</th></tr></thead><tbody><tr><td>type</td><td>transaction type</td><td>string</td><td>Purchase</td></tr><tr><td>rrn</td><td>transaction RRN number in MPS</td><td>string</td><td>2554256963</td></tr><tr><td>purpose</td><td>payment purpose</td><td>string</td><td>For goods</td></tr><tr><td>comment</td><td>comment</td><td>string</td><td>test</td></tr><tr><td>coinAmount</td><td>payment amount</td><td>int</td><td>2000</td></tr><tr><td>merchantId</td><td>merchant ID</td><td>string</td><td>137d9304-0368-11ed-b939-0242ac120002</td></tr><tr><td>operationId</td><td>transaction ID</td><td>string</td><td>1712844596346b9F-WwrWZpq</td></tr><tr><td>ecomOperationId</td><td>transaction ID in the Ecom system</td><td>string</td><td>8c3303e9-7396-43b8-af4e-31d9facdde9b</td></tr><tr><td>merchantName</td><td>merchant name</td><td>string</td><td>KB test terminal</td></tr><tr><td>approvalCode</td><td>authorization code</td><td>string</td><td>39203</td></tr><tr><td>status</td><td>transaction status</td><td>string</td><td>SUCCESS FAIL PENDING REQUIRED_3DS DESIRED_THREEDS_MODE_ERROR</td></tr><tr><td>transactionType</td><td>transaction type in numeric value</td><td>string</td><td>35</td></tr><tr><td>merchantRequestId</td><td>merchant request ID</td><td>string</td><td>72837906-f526-4aef-8d11-58d80b44cb75</td></tr><tr><td>transactionCurrency</td><td>payment currency</td><td>string</td><td>980</td></tr><tr><td>merchantCommission</td><td>commission amount</td><td>string</td><td>2</td></tr><tr><td>createDateTime</td><td>payment creation date</td><td>string</td><td>2024.09.19 15:29:25.675</td></tr><tr><td>modificationDateTime</td><td>payment modification date</td><td>string</td><td>2024.09.19 15:29:25.675</td></tr><tr><td>actionCode</td><td>response code</td><td>string</td><td>0</td></tr><tr><td>responseCode</td><td>response details</td><td>string</td><td>0</td></tr><tr><td>description</td><td>response description</td><td>string</td><td>approved</td></tr><tr><td>bankCode</td><td>issuer bank name</td><td>string</td><td>BANK_ALLIANCE</td></tr><tr><td>paymentSystem</td><td>issuer payment system name</td><td>string</td><td>MasterCard</td></tr><tr><td>productType</td><td>terminal product type</td><td>string</td><td>PURCHASE</td></tr><tr><td>notificationUrl</td><td>URL to which the CallBack was sent</td><td>string</td><td><a href="https://merchant.notification_url/">https://merchant.notification_url/</a></td></tr><tr><td>paymentServiceType</td><td>payment type</td><td>string</td><td>CARD/APPLE_PAY/GOOGLE_PAY</td></tr><tr><td>notificationEncryption</td><td>indicator of CallBack data encryption</td><td>string</td><td>true/false If the parameter is not provided or set to false, the CallBack data will not be encrypted</td></tr><tr><td>cardNumberMask</td><td>masked card number</td><td>string</td><td>5573********0304</td></tr><tr><td>desiredThreeDSMode</td><td>indicator specifying whether the merchant wants to use 3DS in the purchase</td><td>string</td><td>MUST/SHOULD/MUST_NOT</td></tr><tr><td>threeDSMode</td><td>parameter indicating whether 3DS was used in the purchase</td><td>string</td><td>MUST - payment with 3DS MUST_NOT - payment without 3DS</td></tr><tr><td>statusThreeDs</td><td>3DS processing status</td><td>string</td><td>Y - successful 3DS N - unsuccessful 3DS</td></tr><tr><td>threeDSServerTransId</td><td>transaction ID in the 3DS system</td><td>string</td><td>8a811df4-91e0-436b-a9ac-9b0772c96f28</td></tr><tr><td>acsTransId</td><td>transaction ID in the ACS system</td><td>string</td><td>3e17fabb-71e6-498e-8794-ef8c95c5ba6f</td></tr><tr><td>dsTransId</td><td>transaction ID generated by the Directory Server</td><td>string</td><td>12ebc556-82d3-4e35-9fb8-77ac18b050ea</td></tr><tr><td>eci</td><td>Electronic Commerce Indicator Code indicating the security level of the transaction</td><td>string</td><td>02</td></tr><tr><td>processingMerchantId</td><td>merchant ID in the processing center</td><td>string</td><td>AE100000</td></tr><tr><td>processingTerminalId</td><td>terminal ID in the processing center</td><td>string</td><td>AE100000</td></tr><tr><td>redirect3dsUrl</td><td>URL for redirecting the client to the issuer's page for 3DS authentication</td><td>string</td><td><a href="https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA">https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA</a></td></tr><tr><td>txnType</td><td>transaction subtype</td><td>enum</td><td>Possible values: NONCVV/noncvv - when this value is received, CVV input and verification do not occur</td></tr><tr><td>senderCustomerId</td><td>sender's customer ID</td><td>string</td><td>1258728c1</td></tr><tr><td>senderFirstName</td><td>sender's first name</td><td>string</td><td>Ivanenko</td></tr><tr><td>senderLastName</td><td>sender's last name</td><td>string</td><td>Ivan</td></tr><tr><td>senderMiddleName</td><td>sender's middle name</td><td>string</td><td>Ivanovich</td></tr><tr><td>senderEmail</td><td>sender's email</td><td>string</td><td><a href="mailto:mail@gmail.com">mail@gmail.com</a></td></tr><tr><td>senderCountry</td><td>sender's country</td><td>string</td><td>Ukraine</td></tr><tr><td>senderRegion</td><td>sender's region</td><td>string</td><td>Kyivska</td></tr><tr><td>senderCity</td><td>sender's city</td><td>string</td><td>Kyiv</td></tr><tr><td>senderStreet</td><td>sender's street</td><td>string</td><td>Sichovykh Striltsiv</td></tr><tr><td>senderAdditionalAddress</td><td>additional sender address details (floor, house number, apartment)</td><td>string</td><td>23</td></tr><tr><td>senderItn</td><td>sender's tax identification number</td><td>string</td><td>123456789</td></tr><tr><td>senderPassport</td><td>sender's passport</td><td>string</td><td>AN123456</td></tr><tr><td>senderIp</td><td>sender's IP address</td><td>string</td><td>123.12.12.12</td></tr><tr><td>senderPhone</td><td>sender's phone number</td><td>string</td><td>380630000000</td></tr><tr><td>senderBirthday</td><td>sender's date of birth</td><td>string</td><td>31.12.2000</td></tr><tr><td>senderGender</td><td>sender's gender</td><td>string</td><td>M</td></tr><tr><td>senderZipCode</td><td>sender's postal code</td><td>string</td><td>12000</td></tr><tr><td>senderBankCode</td><td>sender's issuer bank name</td><td>string</td><td>BANK_ALLIANCE</td></tr><tr><td>senderPaymentSystem</td><td>sender's issuer payment system name</td><td>string</td><td>MasterCard</td></tr><tr><td>senderCardNumberMask</td><td>sender's masked card number</td><td>string</td><td>5573********0304</td></tr></tbody></table>

#### Examples

<details>

<summary>JWS Payload - the request body before signing up</summary>

```
{
    "merchantId": "137d9304-0368-11ed-b939-0242ac1200",
    "merchantRequestId": "8c1f4b28-5b96-4b0e-bdc6-1d1cc2f2c42a",
    "encryptedCardNumber": "",
    "merchantComment": "",
    "comment": "",
    "purpose": "",
    "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru",
    "desiredThreeDSMode": "MUST",
    "notificationUrl": "https://webhook.site/739593ac-8e50-48fd-a6c4-0422f9487a6e",
    "notificationEncryption": false,
    "date": "2025-04-03 14:55:14.00+00:00",
    "customerData": {
        "senderCustomerId": "senderCustomerId",
        "senderLastName": "senderLastName",
        "senderEmail": "aaaa@gmail.com",
        "senderFirstName": "senderFirstName",
        "senderMiddleName": "senderMiddleName",
        "senderRegion": "senderRegion",
        "senderCountry": "804",
        "senderAdditionalAddress": "senderAdditionalAddress",
        "senderStreet": "senderStreet",
        "senderCity": "senderCity",
        "senderIp": "55.555.44",
        "senderBirthday": "senderBirthday",
        "senderGender": "senderGender",
        "senderZipCode": "senderZipCode",
        "senderPassport": "senderPassport",
        "senderItn": "senderItn",
        "senderPhone": "senderPhone"
    }
}
```

</details>

<details>

<summary>JWS Payload - the response body before subscriptions without 3ds</summary>

```
{
    "type": "VERIFICATION",
    "purpose": "",
    "comment": "",
    "coinAmount": 0,
    "merchantId": "137d9304-0368-11ed-b939-0242ac1200",
    "operationId": "17436921182614gyGFwqQKlb",
    "ecomOperationId": "71baa5d2-d685-4f1e-9b44-3b1e747855dc",
    "status": "PENDING",
    "transactionType": 215,
    "merchantRequestId": "8c1f4b28-5b96-4b0e-bdc6-1d1cc2f2c42a",
    "transactionCurrency": "980",
    "creationDateTime": "2025.04.03 17:55:18.214",
    "modificationDateTime": "2025.04.03 17:55:18.214",
    "transactionResponseInfo": {},
    "productType": "PURCHASE",
    "notificationUrl": "https://webhook.site/739593ac-8e50-48fd-a6c4-0422f9487a6e",
    "paymentServiceType": "CARD",
    "notificationEncryption": false,
    "processingTerminalId": "AE001001",
    "processingMerchantId": "AE001001",
    "creatorSystem": "H2H",
    "desiredThreeDSMode": "MUST",
    "threeDSMode": "MUST",
    "threeDSServerTransId": "6c187d07-e46e-4683-930c-8e8312433130",
    "senderCustomerId": "1234",
    "senderFirstName": "senderFirstName",
    "senderLastName": "senderLastName",
    "senderMiddleName": "senderMiddleName",
    "senderEmail": "aaaa@gmail.com",
    "senderCountry": "804",
    "senderRegion": "senderRegion",
    "senderCity": "senderCity",
    "senderStreet": "senderStreet",
    "senderAdditionalAddress": "senderAdditionalAddress",
    "senderItn": "5555555",
    "senderPassport": "passport",
    "senderIp": "55.555.44",
    "senderPhone": "5555",
    "senderBirthday": "20000110",
    "senderGender": "Female",
    "senderZipCode": "12345"
}
```

</details>

<details>

<summary>JWS Payload - the response body before subscriptions with 3ds</summary>

```
{
    "type": "VERIFICATION",
    "purpose": "",
    "comment": "",
    "coinAmount": 0,
    "merchantId": "137d9304-0368-11ed-b939-0242ac1200",
    "operationId": "17436921182614gyGFwqQKlb",
    "ecomOperationId": "71baa5d2-d685-4f1e-9b44-3b1e747855dc",
    "status": "REQUIRED_3DS",
    "transactionType": 215,
    "merchantRequestId": "8c1f4b28-5b96-4b0e-bdc6-1d1cc2f2c42a",
    "transactionCurrency": "980",
    "creationDateTime": "2025.04.03 17:55:18.214",
    "modificationDateTime": "2025.04.03 17:55:18.214",
    "transactionResponseInfo": {},
    "productType": "PURCHASE",
    "notificationUrl": "https://webhook.site/739593ac-8e50-48fd-a6c4-0422f9487a6e",
    "paymentServiceType": "CARD",
    "notificationEncryption": false,
    "processingTerminalId": "AE001001",
    "processingMerchantId": "AE001001",
    "creatorSystem": "H2H",
    "desiredThreeDSMode": "MUST",
    "threeDSMode": "MUST",
    "threeDSServerTransId": "6c187d07-e46e-4683-930c-8e8312433130",
    "senderCustomerId": "1234",
    "senderFirstName": "senderFirstName",
    "senderLastName": "senderLastName",
    "senderMiddleName": "senderMiddleName",
    "senderEmail": "aaaa@gmail.com",
    "senderCountry": "804",
    "senderRegion": "senderRegion",
    "senderCity": "senderCity",
    "senderStreet": "senderStreet",
    "senderAdditionalAddress": "senderAdditionalAddress",
    "senderItn": "5555555",
    "senderPassport": "passport",
    "senderIp": "55.555.44",
    "senderPhone": "5555",
    "senderBirthday": "20000110",
    "senderGender": "Female",
    "senderZipCode": "12345"
}
```

</details>


---

# 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/authorization-2.0/payment-methods-h2h/account-verification/card-verification-request-step-1.md?ask=<question>
```

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.