# Payment Processing Request - Step 1

## Input parameters:

<table data-header-hidden><thead><tr><th></th><th></th><th width="162"></th><th width="107"></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>The paymentData object to be encrypted with the payment key</td><td></td><td></td><td></td><td></td></tr><tr><td>paymentMethod</td><td>Payment credential type. CARD is currently only supported</td><td>string</td><td>Yes</td><td>CARD</td></tr><tr><td>authMethod</td><td>Method of card transaction authentication.<br>PAN_ONLY - PAN card<br>CRYPTOGRAM_3DS - encrypted PAN</td><td>string</td><td>Yes</td><td>CRYPTOGRAM_3DS</td></tr><tr><td>pan</td><td>Number of the debited personal account. This line contains only numbers.</td><td>string</td><td>Yes</td><td>1,11122E+15</td></tr><tr><td>expirationMonth</td><td>The card's expiration month, where 1 means January, 2 means February, and so on.</td><td>number</td><td>Yes</td><td>10</td></tr><tr><td>expirationYear</td><td>The four-digit card expiration year, such as 2020.</td><td>number</td><td>Yes</td><td>2025</td></tr><tr><td>cryptogram</td><td>3-D Secure cryptogram.</td><td>string</td><td>No</td><td>AVn0rK8BiDxN2D/w2j8LMAABAAA=</td></tr><tr><td>eciIndicator</td><td>This line is not always present. It is only returned for transactions with authenticated device tokens on Android</td><td>string(1)</td><td>No</td><td>4</td></tr><tr><td>messageId</td><td>A unique identifier that identifies the message in case it needs to be recalled or found later.</td><td>string</td><td>No</td><td>some-message-id</td></tr><tr><td>messageExpiration</td><td>Дата й час закінчення терміну дії повідомлення в мілісекундах UTC з епохи. Інтегратори повинні відхиляти будь-які повідомлення, термін дії яких минув.</td><td>string</td><td>No</td><td>1,75931E+12</td></tr><tr><td>Additional data for payment</td><td></td><td></td><td></td><td></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>transactionAmount</td><td>Payment amount in pennies</td><td>string</td><td>Yes</td><td>2000</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>Default: SHOULD MUST - Payment must be processed with 3DS. MUST_NOT - Payment must be processed without 3DS. SHOULD - If the card supports 3DS, verification is performed.</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>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 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) a-zA-Z0-9 ,.;:@#$%'-=+1,256$</td><td>No</td><td>merchant Comment id 1258728c1</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></p><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>Ivanenko</td></tr><tr><td>senderLastName</td><td>Sender's last name. </td><td><p></p><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>Ivan</td></tr><tr><td>senderMiddleName</td><td>Sender's middle name. </td><td><p></p><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) (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>1,20E+08</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>3,80E+11</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:

| Parameter                  | Description                                                                                | Data Format | Example                                                                                                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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                                                                                                                    |
| 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      | 19.09.2024 15:29                                                                                                                                                                                         |
| modificationDateTime       | Transaction modification date.                                                             | string      | 19.09.2024 15:29                                                                                                                                                                                         |
| actionCode                 | Response code                                                                              | string      | 0                                                                                                                                                                                                        |
| 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/​](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      | 2                                                                                                                                                                                                        |
| 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​](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                                                                                                                                                                                                  |
| recipientRegion            | Recipient's region                                                                         | string      | Kyivska                                                                                                                                                                                                  |
| recipientСity              | Recipient's city                                                                           | string      | Kyiv                                                                                                                                                                                                     |
| recipientStreet            | Recipient's street                                                                         | string      | Sichovykh Striltsiv                                                                                                                                                                                      |
| recipientAdditionalAddress | Recipient's additional address data (floor, house number, apartment).                      | string      | 23                                                                                                                                                                                                       |
| recipientItn               | Recipient's tax ID.                                                                        | string      | 123456789                                                                                                                                                                                                |
| recipientPassport          | Recipient's passport                                                                       | string      | AN123456                                                                                                                                                                                                 |
| recipientIp                | Recipient's IP address.                                                                    | string      | 123.12.12.12                                                                                                                                                                                             |
| recipientPhone             | Recipient's phone number                                                                   | string      | 3,81E+11                                                                                                                                                                                                 |
| recipientBirthday          | Recipient's date of birth.                                                                 | string      | 31.12.2000                                                                                                                                                                                               |
| recipientGender            | Recipient's gender                                                                         | string      | Male/Female                                                                                                                                                                                              |
| recipientZipCode           | Recipient's zip code                                                                       | string      | 49000                                                                                                                                                                                                    |
| senderBankCode             | Sender's issuing bank                                                                      | string      | BANK\_ALLIANCE                                                                                                                                                                                           |
| senderPaymentSystem        | Sender's issuer                                                                            | string      | MasterCard                                                                                                                                                                                               |
| senderCardNumberMask       | Masked card number of the sender                                                           | string      | 5573\*\*\*\*\*\*\*\*0304                                                                                                                                                                                 |

## An example of a request body

```json
{
	"paymentData": "{{encryptedPaymentData}}",
	"merchantRequestId": "{{requestUUIDT}}",
	"desiredThreeDSMode": "MUST",
	"notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
	"resultRedirectUrl": "",
	"purpose": "purpose",
	"comment": "comment",
	"merchantId": "137d9304-0368-11ed-b939-0242ac120002",
	"currencyCode": "980",
	"transactionAmount": "100",
	"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": "410211187850",
    "purpose": "purpose",
    "comment": "comment",
    "coinAmount": null,
    "merchantId": "137d9304-0368-11ed-b939-0242ac120002",
    "operationId": "1712836451574mxQBagrb76l",
    "ecomOperationId": "7fb11c16-918d-4bfb-83aa-00e7a8576f9c",
    "merchantName": null,
    "approvalCode": null,
    "status": "SUCCESS",
    "transactionType": 35,
    "merchantRequestId": "9a89759c-f500-461f-a0c7-69a5b678b89d",
    "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": "Операція успішна"
    },
    "bankCode": null,
    "paymentSystem": null,
    "productType": "PURCHASE",
    "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
    "paymentServiceType": "GOOGLE_PAY",
    "notificationEncryption": false,
    "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": "purpose",
    "comment": "comment",
    "coinAmount": null,
    "merchantId": "137d9304-0368-11ed-b939-0242ac120002",
    "operationId": "17128429092802o9koN8eABn",
    "ecomOperationId": "99261a33-cfae-4dfa-9396-812817b5dffb",
    "merchantName": null,
    "approvalCode": null,
    "status": "REQUIRED_3DS",
    "transactionType": 35,
    "merchantRequestId": "8bf3bc51-53e8-4d12-9e86-c13dd6af3b9e",
    "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/cbf8c83a-ee1e-47c6-899c-eca5731ff084",
    "paymentServiceType": "GOOGLE_PAY",
    "notificationEncryption": false,
    "cardNumberMask": null,
    "desiredThreeDSMode": "MUST",
    "threeDSMode": "MUST",
    "statusThreeDs": null,
    "threeDSServerTransId": "5d175446-df26-4ad0-a60c-cd8f95570c0c",
    "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
}
```