# 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>