# PURCHASE Request - Step 1

## **Input Parameters:**

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th width="61"></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Description</td><td>Data Format</td><td>Required</td><td>Example</td></tr><tr><td>merchantRequestId</td><td>A unique identifier generated by the merchant's system, used to retrieve the operation status in case of 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 Ecom.</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 format using the public payment key.</td><td>string</td><td>Yes</td><td>5573670000000304 (decrypted view)</td></tr><tr><td>coinAmount</td><td>Payment amount.</td><td>string</td><td>Yes</td><td>2000</td></tr><tr><td>txnType</td><td>Transaction subtype. If specified, CVV input and verification are skipped. If not specified, CVV input and verification are required.</td><td>enum</td><td>No</td><td>Possible values: NONCVV/noncvv</td></tr><tr><td><p></p><p>typeToken</p></td><td>determines the type of token when it is created</td><td>string</td><td>NO</td><td>possible values: TOKEN_PER_CUSTOMER - the token is created for a specific customer</td></tr><tr><td>desiredThreeDSMode</td><td>Indicates whether the merchant prefers to use 3DS in the purchase.</td><td>string(50)</td><td>Yes</td><td><p>Default: SHOULD</p><p></p><ul><li>MUST - Payment must be processed with 3DS.</li><li>MUST_NOT - Payment must be processed without 3DS.</li><li>SHOULD - If the card supports 3DS, verification is performed.</li></ul></td></tr><tr><td>notificationUrl</td><td>The URL to which the CallBack will be sent.</td><td>string(1000)</td><td>No</td><td>https://merchant.notification_url</td></tr><tr><td>notificationEncryption</td><td>Indicates whether CallBack data is encrypted.</td><td>string</td><td>No</td><td>true/false<br><br>If not provided or set to false, CallBack data will be unencrypted.</td></tr><tr><td>date</td><td>Date and time of the payment.</td><td>string</td><td>Yes</td><td>{{currentdateT}}.00+00:00</td></tr><tr><td>comment</td><td>Additional transaction description provided by the merchant's customer.</td><td>string(1000)</td><td>No</td><td>///5555.25412</td></tr><tr><td>purpose</td><td>Payment purpose provided by the merchant.</td><td>string(255)</td><td>No</td><td>For goods</td></tr><tr><td>merchantComment</td><td>Additional information or comments from the merchant regarding the order.</td><td>string(255)</td><td>No</td><td>merchant Comment id 1258728c1</td></tr><tr><td>resultRedirectUrl</td><td>URL for redirecting the customer after 3DS authentication.</td><td>string(1000)</td><td>No</td><td>Google Help</td></tr><tr><td>customerData</td><td>Object containing customer details.</td><td>object</td><td>Yes</td><td>-</td></tr><tr><td>senderCustomerId</td><td>Sender's customer ID.</td><td>string(255)</td><td>Yes</td><td>1258728c1</td></tr><tr><td>senderFirstName</td><td>Sender's first name.</td><td><p>string(30)<br></p><ul><li>the 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 a space and a hyphen, but can NOT consist exclusively of “ ” or “-“</li><li>a hyphen or space can be inside, but not at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 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 or other special characters</li><li>only alphanumeric values ​​are allowed</li><li>can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“</li><li>a hyphen or space can be inside, but not at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027</li></ul><p><br></p></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>the 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 a space and a hyphen, but can NOT consist exclusively of “ ” or “-“</li><li>a hyphen or space can be inside, but not at the beginning or end</li><li>For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 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>mail@gmail.com</td></tr><tr><td>senderCountry</td><td>Sender's country code.</td><td>string(3)<br>(ISO 3166, e.g., 804 for Ukraine)</td><td>No</td><td>804</td></tr><tr><td>senderRegion</td><td>Sender's region.</td><td>string(255)</td><td>No</td><td>Kyivska</td></tr><tr><td>senderCity</td><td>Sender's city.</td><td>string(25)</td><td>No</td><td>Kyiv</td></tr><tr><td>senderStreet</td><td>Sender's street.</td><td>string(35)</td><td>No</td><td>Sichovykh Striltsiv</td></tr><tr><td>senderAdditionalAddress</td><td>Additional sender address details (floor, house number, apartment).</td><td>string(255)</td><td>No</td><td>23</td></tr><tr><td>senderItn</td><td>Sender's tax identification number.</td><td>string(20)</td><td>No</td><td>123456789</td></tr><tr><td>senderPassport</td><td>Sender's passport number.</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's phone number.</td><td>string(20)</td><td>No</td><td>380630000000</td></tr><tr><td>senderBirthday</td><td>Sender's date of birth.</td><td>string(50)</td><td>No</td><td>31.12.2000</td></tr><tr><td>senderGender</td><td>Sender's gender. </td><td>string(50)</td><td>No</td><td>Male</td></tr><tr><td>senderZipCode</td><td>Sender's postal code.</td><td>string(50)</td><td>No</td><td>49000</td></tr></tbody></table>

## **Output Parameters:**<br>

| type                    | Transaction type.                                                                          | string | Purchase                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| rrn                     | RRN transaction number in MPS.                                                             | string | 2554256963                                                                                                      |
| purpose                 | Payment purpose.                                                                           | string | For goods                                                                                                       |
| comment                 | Comment.                                                                                   | string | test                                                                                                            |
| coinAmount              | Payment amount.                                                                            | int    | 2000                                                                                                            |
| merchantId              | Merchant ID.                                                                               | string | 137d9304-0368-11ed-b939-0242ac120002                                                                            |
| operationId             | Transaction ID.                                                                            | string | 1712844596346b9F-WwrWZpq                                                                                        |
| ecomOperationId         | Transaction ID in the Ecom system.                                                         | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b                                                                            |
| merchantName            | Merchant name.                                                                             | string | KB test terminal                                                                                                |
| approvalCode            | Authorization code.                                                                        | string | 39203                                                                                                           |
| status                  | Transaction status.                                                                        | string | Possible values: SUCCESS, FAIL, PENDING, REQUIRED\_3DS, DESIRED\_THREEDS\_MODE\_ERROR                           |
| transactionCurrency     | Payment currency.                                                                          | string | 980                                                                                                             |
| transactionType         | Transaction type in numerical form.                                                        | string | 35                                                                                                              |
| merchantRequestId       | Merchant request ID                                                                        | string | 72837906-f526-4aef-8d11-58d80b44cb75                                                                            |
| transactionCurrency     | payment currency                                                                           | string | 980                                                                                                             |
| merchantCommission      | commission amount                                                                          | string | 2                                                                                                               |
| createDateTime          | Transaction creation date.                                                                 | string | 2024.09.19 15:29:25.675                                                                                         |
| modificationDateTime    | Transaction modification date.                                                             | string | 2024.09.19 15:29:25.675                                                                                         |
| responseCode            | Response details.                                                                          | string | 0                                                                                                               |
| description             | Response description.                                                                      | string | approved                                                                                                        |
| bankCode                | Issuer bank name.                                                                          | string | BANK\_ALLIANCE                                                                                                  |
| paymentSystem           | Issuer MPS name.                                                                           | string | MasterCard                                                                                                      |
| productType             | Terminal product type.                                                                     | string | PURCHASE                                                                                                        |
| notificationUrl         | URL to which the CallBack is sent                                                          | string | <https://merchant.notification_url/>                                                                            |
| paymentServiceType      | Payment type                                                                               | string | CARD/APPLE\_PAY/GOOGLE\_PAY                                                                                     |
| notificationEncryption  | Callback data encryption feature                                                           | string | true/false If the parameter is not passed or false is passed, then the data in the CallBack will be unencrypted |
| cardNumberMask          | Masked card number                                                                         | string | 5573\*\*\*\*\*\*\*\*0304                                                                                        |
| desiredThreeDSMode      | A feature that indicates whether the merchant wants to use the 3DS in the purchase or not. | string | MUST/SHOULD/MUST\_NOT                                                                                           |
| threeDSMode             | A parameter that indicates whether a 3DS is used in the purchase or not                    | string | MUST- pay with 3DS MUST\_NOT- pay without 3DS                                                                   |
| statusThreeDs           | 3DS holding status                                                                         | string | Y - successful 3ds N - unsuccessful 3ds                                                                         |
| threeDSServerTransId    | Id of the transaction in the 3ds system                                                    | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28                                                                            |
| acsTransId              | Id of the transaction in the ACS system                                                    | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f                                                                            |
| dsTransId               | Transaction ID generated by Directory Server                                               | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea                                                                            |
| eci                     | Electronic Commerce Indicator A code that indicates the security level of a transaction    | string | 02                                                                                                              |
| processingMerchantId    | Id of the merchant in PC                                                                   | string | AE100000                                                                                                        |
| processingTerminalId    | Id of the terminal in the PS                                                               | string | AE100000                                                                                                        |
| redirect3dsUrl          | URL to redirect the client to the issuer's page for the 3DS pass                           | string | <https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA>             |
| txnType                 | Under the type of transaction                                                              | enum   | Possible values: NONCVV/noncvv- upon receipt of a given value of cvv input and its verification does not occur  |
| senderCustomerId        | Id of the sender's client                                                                  | string | 1258728c1                                                                                                       |
| senderFirstName         | Sender's first name                                                                        | string | Ivanenko                                                                                                        |
| senderLastName          | Sender's last name                                                                         | string | Ivan                                                                                                            |
| senderMiddleName        | Sender's middle name                                                                       | string | Ivanovich                                                                                                       |
| senderEmail             | Sender's mail                                                                              | string | <mail@gmail.com>                                                                                                |
| senderCountry           | Sender's country                                                                           | string | Ukraine                                                                                                         |
| senderRegion            | Sender's area                                                                              | string | Kyivska                                                                                                         |
| senderCity              | Sender's city                                                                              | string | Kyiv                                                                                                            |
| senderStreet            | Sender's street                                                                            | string | Sichovykh strilʹtsiv                                                                                            |
| senderAdditionalAddress | Additional data of the sender's address (floor, house number, apartment)                   | string | 23                                                                                                              |
| senderItn               | Sender's tax identification number.                                                        | string | 123456789                                                                                                       |
| senderPassport          | Sender's passport number.                                                                  | string | АН123456                                                                                                        |
| senderIp                | Sender's IP address.                                                                       | string | 123.12.12.12                                                                                                    |
| senderPhone             | Sender's phone number.                                                                     | string | 380630000000                                                                                                    |
| senderBirthday          | Sender's date of birth.                                                                    | string | 31.12.2000                                                                                                      |
| senderGender            | Sender's gender.                                                                           | string | M                                                                                                               |
| senderZipCode           | Sender's postal code.                                                                      | string | 12000                                                                                                           |
| senderBankCode          | The name of the sender's issuing bank                                                      | string | BANK\_ALLIANCE                                                                                                  |
| senderPaymentSystem     | The name of the sender's issuer                                                            | string | MasterCard                                                                                                      |
| senderCardNumberMask    | masked card number of the sender                                                           | string | 5573\*\*\*\*\*\*\*\*0304                                                                                        |

## **Request Body Example**

```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",
    "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

```json
{
    "type": "PURCHASE",
    "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": 35,
    "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",
    "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,
    "senderGender": null,
    "senderZipCode": null,
    "senderBankCode": null,
    "senderPaymentSystem": null,
    "senderCardNumberMask": null
}
```

## **Example of response body from 3DS**

```json
{
    "type": "PURCHASE",
    "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": 35,
    "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",
    "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,
    "senderZipCode": null,
    "senderBankCode": null,
    "senderPaymentSystem": null,
    "senderCardNumberMask": 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/purchase/purchase-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.