# E Commerce платформа AlliancePay v2.59.0 E-Commerce платформа AlliancePay #### {% embed url="" %} #### Оперативний канал інформування партнерів щодо проблем з проходженням транзакцій по різних емітентах: {% embed url="" %} # Аутентифікація Початок роботи ### Для початку роботи з платформою AlliancePay необхідно: 1\. Звернутись до АТ “БАНК АЛЬЯНС” для отримання інформації щодо умов послуги інтернет-еквайринг. 2\. Відкрити рахунок в АТ “БАНК АЛЬЯНС”. 3\. Підписати договір про підключення до послуги інтернет-еквайрингу. 4\. Здійснити підключення до тестового стенду та провести тестові операції. 5\. Здійснити підключення до продуктового середовища. 6\. Почати користуватись послугою інтернет-еквайрингу. ### Процес створення нового сеансу безпеки користувача Процес створення нового сеансу безпеки користувача включає в себе ряд послідовних дій, таких як: * Генеруємо клієнтські ключі “Процес генерації комунікаційних JWK ключів клієнта” * Отримуємо зашифровані авторизаційні дані зашифрувавши тіло запиту “Процес створення JWE зашифрованих даних” та відправити “Запит створення технічної сесії” * Розшифровуємо отримані дані Уточнення: URL криптування і розкриптування : {{url}}cipher/decrypt\_by\_jwk?message= {{url}}cipher/encrypt\_by\_jwk?message= **! тільки для допомоги під час тестів! Їх заборонено виконувати з прод ключами.** ### **Для шифрування та розшифрування використовується :** * Алгоритм шифрування ключів (alg) - ECDH-ES+A256KW * Шифрування тіла запиту по алгоритму (enc) - A256GCM #### **Приклад по encrypt/decrypt** ```python def encrypt_data(self, msg: str, use_server_public_key: bool = False) -> str: """Get compact JWE token with encrypted data""" if not use_server_public_key: with open(self.public_key, 'rb') as public_key_file: public_key_raw = json.loads(public_key_file.read().decode()) public_key = jwk.JWK() key_raw = self.server_public_key if use_server_public_key else public_key_raw public_key.import_key(**key_raw) protected_header = {'alg': 'ECDH-ES+A256KW', 'enc': 'A256GCM'} jwetoken = jwe.JWE(msg.encode('utf-8'), recipient=public_key, protected=protected_header) return jwetoken.serialize(compact=True) def decrypt_data(self, msg: str) -> str: """Get decrypted data (from JWE)""" with open(self.private_key, 'rb') as private_key_file: private_key_raw = json.loads(private_key_file.read().decode()) private_key = jwk.JWK() private_key.import_key(**private_key_raw) jwetoken = jwe.JWE() jwetoken.deserialize(msg, key=private_key) return jwetoken.payload.decode() ``` ### Процес генерації комунікаційних JWK ключів клієнта Генерація публічного та приватного ключа (JSON Web Key) здійснюється з наступними параметрами: ● "[kty](https://datatracker.ietf.org/doc/html/rfc7518#section-6.1)": "EC" - тип ключа ● "[crv](https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.1)": "P-384" - еліптична крива ключа ● "[use](https://datatracker.ietf.org/doc/html/rfc7517#section-4.2)": "enc" – параметр, що використовується для криптування ключем ● "[alg](https://datatracker.ietf.org/doc/html/rfc7518#section-4.1)": ECDH-ES+A256KW - алгоритм для якого використовується ключ Приклад генерації ключа для ознайомлення наведено на сайті[ https://mkjwk.org/](https://mkjwk.org/) . Процес створення[ JWE](https://datatracker.ietf.org/doc/html/rfc7516) зашифрованих даних Об'єкт є зашифрованими даними. Для створення необхідно вказати наступні параметри: ● Кодування даних, що шифруються UTF-8 ● Алгоритм шифрування ECDH-ES+A256KW ● Метод шифрування A256GCM ● Та використовувати відповідний алгоритму публічний ключ. **Приклад тіла перед шифруванням:** ```json { "deviceType": "ECOM_MERCHANT_SERVICE_DEVICE", "clientPublicKey": { "kty": "EC", "crv": "P-384", "x": "Q0aVpIzurAJeLgcwr9SwrjBaxt6vWU9Xt9Om5WseRVHOK0KHt1fS-TmM4nNwocyl", "y": "nugxKjzsgyCBY8h095r3dex5LL0MduzU8ovLPYnl3jlExzpSG4sFTsBbUWJo8GLP" } } ``` **Приклад JWE після шифрування:** ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiSVprUG1oVm5fQUd2RkJXS2dIYmtfOFlLX2Q1aXZabHJJU19DaUxublhlVUkyX1NtSC0wWkJDOWkySDg1c3ladCIsInkiOiJ6SUFkSS1wNXZrdjVuVjNpSVNqMlFiSW85NnU0eXBhZVg0WHBJSUhiYlp4LWhkc3hwLUVCbDIwRDlNOTVHTWtQIiwiY3J2IjoiUC0zODQifX0.jfDIZ64JlVbdOgXkh0bqX6uA8H6Pkkg6s861OKn_vBtIQYk4BRxPjA.9ns8h0iFDcmG_hib.USraeD8abgHZwD_kas3L1rO1U0n_YhLx_LJpxKICAoVqVQ.myDB-We0sg1l5nzfi7b2sg ``` #### Процес розшифрування JWE даних Приклад JWE токену ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiSVprUG1oVm5fQUd2RkJXS2dIYmtfOFlLX2Q1aXZabHJJU19DaUxublhlVUkyX1NtSC0wWkJDOWkySDg1c3ladCIsInkiOiJ6SUFkSS1wNXZrdjVuVjNpSVNqMlFiSW85NnU0eXBhZVg0WHBJSUhiYlp4LWhkc3hwLUVCbDIwRDlNOTVHTWtQIiwiY3J2IjoiUC0zODQifX0.jfDIZ64JlVbdOgXkh0bqX6uA8H6Pkkg6s861OKn_vBtIQYk4BRxPjA.9ns8h0iFDcmG_hib.USraeD8abgHZwD_kas3L1rO1U0n_YhLx_LJpxKICAoVqVQ.myDB-We0sg1l5nzfi7b2sg ``` **Приклад даних після розшифрування JWE токену** ```json { "authToken": "c8e28b98-e3bd-42f3-8cba-7b3c3dd5c9da", "deviceId": "8485ff92-8ac3-4af1-aaa7-e72edfed2516", "serverPublicKey": { "kty": "EC", "crv": "P-384", "x": "glGAHNVNkXbygpcRnhoEGSUEQM-s8RrcaxY7HSJ4Cs0QIreWxYEJI2iz0W4ZtH8a", "y": "AQ_vq8Ks_dTB-HiQrPi_fpE-nlQXbHoEeInURhZFVFc1bpi7NqynflKnyBWLy590" } } ``` #### Запит створення технічної сесії Приклад тіла запиту ```json curl --location 'https://api-ecom-prod.bankalliance.ua/api-gateway/authorize_virtual_device' \ --header 'x-api_version: 1' \ --header 'Content-Type: application/json' \ --data ' { "serviceCode": "137d9304-0368-11ed-b939-0242ac120002" }' ``` **Приклад відповіді** ```json { "jwe": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiZ3F2M0xDYnpDcEZoaWhEQlRZX1JxSFN6cUZsLWJYYVZjUHhJU2w4UmNPbHdjNU5UNnpvd3Y1WWhTQW5sekxPMCIsInkiOiJENWpYX2t4UGZVYlJySmVTZGNQbnhzN0dNMlZuZTdvSHA5N3g2SVNPdWNJdU81SVY2R2pFa3NRSlBicGQ2bWVfIiwiY3J2IjoiUC0zODQifX0.nbpNZhLmDpzMdhntvVOrpdLOLu6Ryhhb-S08LgdN8iJscD4j3mqX_w.8WWRrwzW93i0oGui.jjm3mvrLxDvJTy6-lKzXHTzMliD7x3cV3ZhgAcmgWL8uyHj3Cpb5LtcdUM6KxzBsAj0CWmdjj_VCzbloEHJVQCoDPpCqIe8ScIh5irXB3hG8onyK0tKXOibf7gRoEIWES_OuT3yAfXfNn0DuEK6PhKH1sihLMDWD_ns7CATBy6atZQkk00SkswDLgDVucCakC5RmyrDDFHsaEcKAIh6eehlhHotR6x82v9qplYObKMIqneEmYRUrildPyi43_RXmkSZUFt2Bx5Q7SEINQsFw6qRPzAkhpPH2d5JWefDr3elamiJeibMJQDcKcfUDnDCviX-e2Wf3sTnacufV8O5s1hDpfJYZAxZonGK8g3CvcWk34EsnPD0pm8DOoTtSeIP9cgS4w05s53LxbFPH9xXYtxkfrSBVtnbiHcZ37GVWOdEqVeqgmDKizu6WxQnW9oJdNEsG6a5FavarFURvS5Xgz46cluYj3ppZSqIQiRSRhNDH0AD9fFPeskvsGjZ5O8efA3eRyT5gNKCO05I9ZtnC.w3pu8oSnWaBkbBjQyQN9hQ" } ``` #### **Запит розшифрування технічної сесії** Приклад тіла запиту ```json curl --location 'https://api-ecom-release.develop.bankalliance.ua/cipher/decrypt_by_jwk?message={{responseJwe}}' \ --header 'Content-Type: application/json' \ --data ' { "kty": "EC", "d": "xVoCzl9Vvlk_bP_O1OLmlTSN9P07fq_7bEBnpQhoqo29PV2TR7smqu5nAz0wZhZ_", "use": "enc", "crv": "P-384", "x": "tfOqYVvawSq5HDGvWd_zm-ha8tDuZci5THnAokWJpdZSUk40VpAtofDY_Q8fUG9O", "y": "LMHt1lT4ZdK3puWwrdrAUZBLazDbwwoZveFnlcYlL7PO62dDdHdo_KhYeUoPOHgk", "alg": "ECDH-ES+A256KW" }' ``` Приклад відповіді ```json { "refreshToken": "5aba78ac-8850-4619-8232-f62089cbcbb3", "authToken": "14a74387-9f20-4e73-a314-0d2ca80222b6", "deviceId": "1d9742cf-d392-4c2b-9982-4dc6ec2224b2", "serverPublic": { "kty": "EC", "crv": "P-384", "x": "BSWUuzrcIWk3GFUqD2ClMxVwycEWXoMnqJsDwOJNidTtfJJ0dn8h9m3Q8fRoxBaA", "y": "PnFAa3LNxJgiUYZXUx7-kr049B0IxOUXP2l8_Z7mEgUv9-xhVWuf0sJhiOn69VPe" }, "tokenExpirationDateTime": "2023-03-18 12:34:52.0998 +0000" } ``` *Refresh сесіі не передбаченний, для генераціі нового serverPublic необхідно виконати Запит створення технічної сесії повторно* # Криптування даних #### Запит криптування номеру картки Приклад тіла запиту ```json curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/encrypt_by_jwk?message={{cardNumber}}' \ --header 'Content-Type: application/json' \ --data-raw ' { "kty": "EC", "use": "enc", "crv": "P-384", "x": "lxF9kVkpdTRqd256CO0Q3fOEgAPcek-U_Q72UoySdXXZWr9Tf8bSMhc8gwVbgtDC", "y": "3aQaGq0Va9OsGhPr63jZ2KEcfO1jqibz6bKFeJr6K6h4dHFGj298hv7sb6bYaUyD", "alg": "ECDH-ES+A256KW" }' ``` Приклад відповіді ``` eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiUTZpa29VREhpSEZBTXctRG1qUWdmLXVVS2ktWXpyc21qYXRPakI2a3RmZDJjbE1ndUk5TGRreHprMEtnNmNwaCIsInkiOiJNMjF6V1BEeVVOZDA2a216dU82WTNybXFMNUZXM0xyblNZOVBnTXVnRklrU1Q5ZGM3Qno1R0xscDN4U1lIdXlvIiwiY3J2IjoiUC0zODQifX0.Kgb_4R6L2SAL077b34Ulop5tU8ICVeRhQxTlpDosg-UbfsHWx1IIbA.gIkAptJJlhH6Gf-W.-A98wK-imBnwvdAmRpy2wgofZtZ6tRsp3W4Zna-Ye1kBcjFh-93iMz73LfRjvxsKQYzSEbcYXTbd.YHunREy1MjVTRpnTRSsnGw ``` #### Запит криптування cvv та expDate Приклад тіла запиту 
curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/encrypt_by_jwk?message={{dateCvv}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "kty": "EC",
    "use": "enc",
    "crv": "P-384",
    "x": "lxF9kVkpdTRqd256CO0Q3fOEgAPcek-U_Q72UoySdXXZWr9Tf8bSMhc8gwVbgtDC",
    "y": "3aQaGq0Va9OsGhPr63jZ2KEcfO1jqibz6bKFeJr6K6h4dHFGj298hv7sb6bYaUyD",
    "alg": "ECDH-ES+A256KW"
}'
Приклад відповіді ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiY3hEcmZmZjBuRWtVU0JyX0JUN2h3SWt5V1hOV3JjNnhtaVdLV3VHZ3hNaGJoR3kza21DQVRoRjRXb1FKTEstZiIsInkiOiI4dHlqUGJtc3lxdlhDZDJQMC1FZjdEcm8zRVhxczlIWXRieWQzQzFzZS00bDJ3YkJ1djZBT2dyZHhpaUNGS0pKIiwiY3J2IjoiUC0zODQifX0.qWawnXb-PgoDgG0hbeVt9bDs1pmg4isWPfjf_7wiUfXTKsPvVrLTaw.upp1rnEiiahsghoI.lQ1Kv2sYaQ.gxOr0AdNyOctlBqZqIuUQQ ``` #### Запит криптування тіла запиту Purchase Приклад тіла запиту ```json curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/encrypt_by_jwk?message=%7B%0D%0A++++++++%22merchantId%22%3A+%22137d9304-0368-11ed-b939-0242ac120002%22%2C%0D%0A++++++++%22merchantRequestId%22%3A+%22{{requestUUIDT}}%22%2C%0D%0A++++++++%22encryptedCardNumber%22%3A+%22{{encryptedPanT}}%22%2C%0D%0A++++++++%22coinAmount%22%3A+%221000%22%2C%0D%0A++++++++%22comment%22%3A+%22comment%22%2C%0D%0A++++++++%22purpose%22%3A+%22purpose%22%2C%0D%0A++++++++%22desiredThreeDSMode%22%3A+%22MUST_NOT%22%2C%0D%0A++++++++%22date%22%3A+%22{{currentdateT}}.00%2B03%3A00%22%0D%0A++++++++%7D' ``` Приклад відповіді ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiUTQ0TUJpOHJvQ2RyNjlHdm9DNUFoQkRaLXdrZGtiZ3hSSW44SlFjMlNwa3B6QmRaY0VJYklaM1dXNkstcDlsSCIsInkiOiJ6RXlwYWU0ZXVUSUlrQ0tkVC14ZTdUQ2haaGdLX2xLTmRqN29hUmdOd0J0bnMxUjVvU2ZiR2RPNktRdVpRYzgxIiwiY3J2IjoiUC0zODQifX0.GadCMT_Gc9K1cN-VMnV1HCddxmYS9Roj7gYIOdHkyCScryGOieZOZQ.VjJtho7IEYdFHLYm.FE-TwGErA2xQgoWUVDecvHAKVI2RbZ8glI_xRTe_RgjvLg4QT_4z7p-fMvSe3ERV6Hv2HHwew1uYCXPWa1vfsZLonxro9ccMZiXxHlDmhVQBojUJPGg5Sk6wYI4WIjgEvlgkQJ3JKnH2aNIqx-C-uDuKYmpF0oR1f8oxJiFlTBUZFxHsu00wlxtPNRFQWXgDFAZaMk0fTK2R_R8TpsKXBDT-ygrh8IrXkzdxMVRZFKnY24THnT9vrECdsd4XlMfazBwMaVRu8egEjU72-iYF5b8HN4TQdGZePWXolGpcYJ3pCmzW9BC5gD5wG3z2RYKBWiMlBjldJ5BT_ATjbkzrvMjslJxPJwTS8Z7dMPP_ibS055B-KL05kEIYIATbZBKITZGamzjoWOkfFLJsO2nsHxIggBOePNrJlhDt2rPUj4-wFCceCJhn65ZHDBhOhVQIoIAIpZzqAztYXBrfZRlcPbsDNX_sNQBUYeRHFRY9r77pSXnGnwkF0zxkD5-vSIKtDJAMCkFuu4DtXQIG-oW1ko6KolmAQm7HrlB_Hz_ysB54c59xT8zDCYeF11sc48erLHTKoKv315vjx4txf1JFjePSBmh624sDMZXg1wbiLHahSSl9igbP0_KGvtm5zA_B599_IsFHdjAgSZhUChsYFafEf9DewDo8zGEfPWtHZl76hMGbaFpZwXYeyC_vaqaCuSaBpzVVv8oYZqlK5BaZMRqrcvWaBTyHoSDcxzywjPE01aXrxzFn3WtauiILM76MREorUHrEmtGL6hW7ijmKn-MwxhmuVCvnC9p1nEq_4LQhNu3lGyLw3YGfl1ovfhOZOzNeclypKoJyfElbmuYSVrEpe1DV0JdejGiidTTvrolk9xp45kl4o-54BocPcqFiTsyDuGNZR1_RICfhoWEXyibiE6EHdJOFg2nAmj0zoa-FDA905hD-Cr1Vyn4c_YuqwgbRDILFMUng6sadmz_uJ2WNZyqhiPTxaHR7gT_DsRoOCL7FbaEbNexobnSQLRSPd3Ye0c3uzqxOOFTiG-pmFuZlzbOPP5N86RVIHwjN_8L1XczJfbHQAjd60InwP1EmY3FhVDTT8m3I1Pm8BZM7Qnn2nVA3eO1kuy2iVjqLDtEWQtvfUrlivx7-xtOUY3oGi0YvzgPuROSfwCf-znWtZpItkTDJYuq3_jQhxN4_ncGSNYjcP5Jn8kJEIIUhHXcJbpkgMaQkb4iVDN-evOWaek1Rs2cghLWGrfrxuHwsGsM4J7YN-oEye2dp4PfVwP72AsHmB0IVMmZYGg2BN3_CeIpMtGJax6CPUtfiFjOUpk1Wcksciiq7CQySJSlTLrbDOYzP3s-UeD9h7P_toPTpqnhQOdcRNqYwUnSixK7RblwDQU20qo_1EuvoO5W-nANvHuZOS9qDD6RuVbaV0F6GZGTAiwJfc9XWXP1bAv0KZUkM4Bt2RnKnfO4Bum-mVgUEO49z.iLpH0bfL0nGaiBCLUtNjvw ``` #### Запит криптування тіла запиту А2С Приклад тіла запиту ```json curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/encrypt_by_jwk?message=%7B%0A%22encryptedCardNumber%22%3A%22{{encryptedPanT}}%22%2C%0A%22merchantId%22%3A%22137d9304-0368-11ed-b939-0242ac120002%22%2C%0A%22merchantRequestId%22%3A%22{{requestUUIDT}}%22%2C%0A%22purpose%22%3A%22%D0%B7%D0%B0%20%D1%82%D0%BE%D0%B2%D0%B0%D1%80%22%2C%0A%22coinAmount%22%3A%20120%2C%0A%22comment%22%3A%20%22test%22%2C%0A%22recipientCountry%22%3A%20%22840%22%2C%0A%22recipientCity%22%3A%20%22Kyiv%22%2C%0A%22recipientStreet%22%3A%20%22T.%20Shevchenka%2C%2011%22%2C%0A%22recipientFirstName%22%3A%20%22TestFirstname%22%2C%0A%22recipientLastName%22%3A%20%22TestLastName%22%2C%0A%22date%22%3A%20%22{{currentdateT}}.00%2B03%3A00%22%0A%7D' \ ``` Приклад відповіді ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiT3BPU3BzbmdhUFNZa3pyaFdOQ0hOdmVkcFpZa055aTFpV3FuODFJNnVtaWh3V3BRdWd3TExyNGNJbXdicm0zbiIsInkiOiJGQlJvVTNfOERsRmtCdEZuTzRwOEJFdFI3N3YxcWtIb3BNZmpTbjNxTmVvazVUSDN5RHN1V0dQTW9JR0JQOTZKIiwiY3J2IjoiUC0zODQifX0.cI9Lt-3nxTMgYYQzMRW3uTJ1ht2EKNNhWZQ0kL76Y8KGAs8YVnVJFw.V93PFOyteOScc-h9.Mf9xemx756NyTyTu9Qis9gNd7zshewoO2fBZDV9VWLYMhIR3VAQY1YaNAkR81XFcIV1dq4MGM61rQxdv9YvKz-RuwN0OsNfcUa8hYbtwwtmmLqg4gWVZFskF9jM1aQzhSFNsRM5eZgu3Qo7zk2mvWn5flX6BLKywQYstx-nYGi_9NRIwYVNKalAGUaOClneMxUepgJ_fYGmHfw2U4GDo09qWVsNfWLwRkT8jVXvKRfY755DQJgIDQm2HxhszdwG4YQjpA7SdYATNx1IFUwFQwIbeGntpZOPHRJCQ5zd2k_5bBGkEw1mvXBHtd8pEcbaPXxN4Bsx2vjSOBbItBmfbweLgtfcCwwZYxpi-dIMN-Yn1Gvh_ba7H0_WokObbo_MiwqJ-UBAYqPsJoH-7VetcqY9W-NGPYXIrHcVG5dEC7vx0_9HtVD1T8zZtCbA9MNMLQbzCa6YXqWFO5NzS8qTCCgV4KZ7NrQwfsStDpcXi3fsgGnV8EPRDyFg-KYed5pV8zL80Fsp4YDCo9FVFmm88mcGq1k1Dr6AKredjkSV0xutgrQdyELCWnjQ7hKlOu3RpTBtdBONnjhVWd8KtJo8AGQrZPBvLWJEcph5bJ7_bKJPJw8DIPoGbXWbb21Oo0iNwl1k1B2q3lvrdnJbi3PD1n09uii87oMetzJlwwOCNXb6xZdpSk0tNr_klcKrFuHvZPl9gMGEgodp1rYwt012ePNPEWM9YcavwsMxUxZL1m_y20fAjvYAVgBXeShT-kPLCvZhj75x4varjiEziQkuOv2MRmL1c4RRU9i3gX26ZrhSccxxJTgH0mUmdxN-sHLB1ee3smFQuCmF0hymPwlmG2EpmWDoIg8xMNQsmZ3ViTEBBA24CptVAudHN4P-RVoCkyOuRigamOuVYPMjR2Mm_E0RY7oDF-4815zd1AloieLMdpFSUNL-wRmxOWyozFeZcUsnP0oLlxanV8SrhZVGCjMVvQlhhxHrtB0vYQf00qQmCaQO7eE39dauutBvgZLj1BrwUfLAfRTHBBidDDPCmRUNO7tEk86rgkQ.v4DT6Pf_UrCIEql2MI0iPw ``` #### Запит криптування тіла запиту Refund Приклад тіла запиту ```json curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/encrypt_by_jwk?message=%7B%0A%22merchantId%22%3A%22137d9304-0368-11ed-b939-0242ac120002%22%2C%0A%22merchantRequestId%22%3A%22{{requestUUIDT}}%22%2C%0A%22coinAmount%22%3A%20400%2C%0A%22operationId%22%3A%20%2216819994379960P3JOgL9oph%22%2C%0A%22date%22%3A%22{{currentdateT}}.00%2B03%3A00%22%0A%7D' ``` Приклад відповіді ```json eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiTW5Edlg5WVBmdGg0OU9BRWlwWnQtZ1VPTkJ4ajNIM2NpQ3J3M0JVamFndXB4VUFZYmVnZll0SG9PVXNMWXVNbiIsInkiOiJOVnl0ZS1tUEZ1MXZSUnhiT2sxcWdLaHV4aThXdlZxYVo1c2JqeUc0VXN3S1EweGRfMXhRSmF0cmpfYWt2LVdyIiwiY3J2IjoiUC0zODQifX0.C6xXq_hTVMDJ6OBmLDJW0fytlv7DHLYhjmECFF8Ms22Lvo6Gmrhi9w.bHiTlA147DpUuMPT.AznDDpYaUKOQvPRT3UKYlcxByZtv1qm_TbK86Tn9pqlQz9rfucjDmBD31NuK4ZTyI_d9Vbv8vcK2JU96bg1_J5wbmgZqN_4hvyZvQ39QaL_xVUkt3EesYBH_0VyhWBm--ojnHxJgvWkF8X4xFAYp9sU7jVdsQUNRKZajLzgAR65uSTveEsZ69aifDze0C_GxDwNaRhuv6_twoQGoVLTf3IpVndAqFWhMoAqY-VNWuW9upqRWd5MVX0Lr7ngUKYWTMD0C4b2BJWsH8xoVZyuA_6ggRwqhhx5Jz0010pBMM29TNToCLA.n04GZIciLzo_BBnXKKO0Rg ``` #### Запит декриптування тіла відповіді Приклад тіла запиту ```json curl --location --request POST 'https://api-ecom-release.develop.bankalliance.ua/cipher/decrypt_by_jwk?message={{responseJwe}}' ``` Приклад відповіді ```json { "operationId":"7efc160e-f9d9-49dd-bc1d-38c064193c5a", "status":"SUCCESS", "rrn":"1037470888" } ``` # Авторизація #### Авторизація запитів Для авторизації запиту необхідно до запиту додати заголовки: > x-api\_version:V1 > > x-device\_id:{{deviceId}} > > x-refresh\_token:{{refreshToken}} #### Відновлення авторизації При виконанні запитів, у разі отримання у відповіді http status 401, необхідно відновити авторизаційні дані Запит оновлення сесії та виконати невдалий запит ще раз #### Таймаут Інформація щодо таймаутів буде додана у наступній версії документу. #### Робота з платежами Платіж - тип операцій, що використовується для оплати на сайтах товарів/сервісів/послуг за допомогою платіжної картки. По операціям Платежу передбачено верифікацію картотримача за допомогою технології 3D Secure, якщо карта залучена до даної програми. #### Дані для проведення тестування serviceCode для авторизації девайсу - UUID, приклад a51e68aa-c6fa-11ed-afa1-0242ac120005. В продуктивному середовищі генерується Банком окремо для кожного мерчанта Ключ для авторизації: ```json { "kty": "EC", "d": "QVwaujXBuM1mdyNSadU5qSjRk5xggY-aX7yzes_qyNQC9nTVO1SmNBHd_fBzZILd", "use": "enc", "crv": "P-384", "x": "lxF9kVkpdTRqd256CO0Q3fOEAPcek-U_Q72UoySdXXZWr9Tf8bSMhc8gwVbgtDC", "y": "3aQaGq0Va9OshPr63jZ2KEcfO1jqibz6bKFeJr6K6h4dHFGj298hv7sb6bYaUyD", "alg": "ECDH-ES+A256KW" } ``` Payment ключ ```json { "kty": "EC", "use": "enc", "crv": "P-384", "x": "lxF9kVkpdTRqd256CO0Q3fOEgAPcek-U_Q72UoySdXXZWr9Tf8bSMhc8gwVbgtDC", "y": "3aQaGq0Va9OsGhPr3jZ2KEcfO1jqibz6bKFeJr6K6h4dHFGj298hv7sb6bYaUyD", "alg": "ECDH-ES+A25KW" } ``` URL - #### Headers для запитів
| Параметр | Опис | Приклад | | ---------------- | ------------------------------------------------- | ------------------------------------ | | x-api\_version | Версія api | v1 | | x-device\_id | Генерується при запиті authorize\_virtual\_device | f7b244ae-57e7-4fe2-89d7-7d6a02a17048 | | x-refresh\_token | Генерується при запиті authorize\_virtual\_device | 9a64d090-732c-4e28-9c57-609083b8bd56 | # Авторизація 2.0 Авторизація запитів за допомогою JWS (JSON Web Signature) # Порядок переходу на JWS Authorization 2.0 Для безшовного переходу з поточного формату авторизації на JWS Authorization 2.0 рекомендуємо виконувати інтеграцію поетапно. {% stepper %} {% step %} ### Крок 1. Ознайомитися з форматом JWS Authorization 2.0 У новому форматі авторизації запити до Ecom передаються у вигляді JWS: ``` HEADER.PAYLOAD.SIGNATURE ``` де: * `HEADER` — містить службову інформацію, необхідну для перевірки запиту; * `PAYLOAD` — містить параметри API-запиту; * `SIGNATURE` — цифровий підпис запиту, сформований приватним ключем мерчанта. Перед початком інтеграції рекомендуємо ознайомитися з принципом формування та підписання JWS: [Робота з підписанням](https://docs.merchant.alb.ua/avtorizaciya-2.0/robota-z-pidpisannyam) ### Крок 2. Згенерувати ключі для підписання JWS {% endstep %} {% step %} Для роботи з JWS необхідно згенерувати пару криптографічних ключів: * `Private Key` — використовується мерчантом для підписання JWS-запитів; * `Public Key` — використовується Банком для перевірки підпису запитів мерчанта. `Private Key` повинен зберігатися виключно на стороні мерчанта та не передаватися Банку або третім особам. Генерацію ключів необхідно виконувати відповідно до параметрів та алгоритмів, зазначених у документації : [Генерація ключів](https://docs.merchant.alb.ua/avtorizaciya-2.0/generaciya-klyuchiv?select=%D0%B7%D0%B0%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-payload,%D1%80%D0%BE%D0%B7%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-payload,%D0%B7%D0%B0%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-header,%D1%80%D0%BE%D0%B7%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-header) {% endstep %} {% step %} ### Крок 3. Передати Public Key Банку Для підключення JWS Authorization 2.0 до існуючого `merchantId` необхідно передати Банку згенерований `Public Key`. Публічний ключ необхідно направити на: `aromashkan@alliancedigital.tech` Після реєстрації ключа на стороні Банку мерчанту буде надано ідентифікатор ключа — `kid`. Отриманий `kid` необхідно використовувати при формуванні `HEADER` JWS-запитів. Наприклад: ``` { "alg": "ES256", "kid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "ts": "1769174930000", "targetUrl": "/ecom/jws/payments/create/purchase_v3" } ``` {% endstep %} {% step %} ### Крок 4. Реалізувати формування та підписання JWS Для кожного API-запиту необхідно: 1. Сформувати `HEADER`. 2. Сформувати `PAYLOAD` відповідно до документації конкретного ендпоінта. 3. Закодувати необхідні частини JWS. 4. Сформувати `SIGNATURE` за допомогою `Private Key` мерчанта. 5. Передати сформований JWS на відповідний JWS-ендпоінт Ecom. При формуванні `HEADER` необхідно враховувати: * `alg` — алгоритм підписання; * `kid` — ідентифікатор зареєстрованого публічного ключа мерчанта; * `ts` — час формування JWS; * `targetUrl` — URL API-методу, для якого формується JWS. Детальніше: {% endstep %} {% step %} ### Крок 5. Реалізувати шифрування карткових даних Якщо мерчант використовує API-методи, в яких передаються карткові дані, необхідно додатково реалізувати їх шифрування. Шифрування карткових даних та підписання JWS є окремими механізмами. Детальніше: {% endstep %} {% step %} ### Крок 6. Реалізувати перевірку JWS-відповідей Банку Відповіді Ecom повертаються мерчанту у форматі JWS та містять цифровий підпис Банку. {% hint style="info" %} Перевірка відповіді, не є обов'язковим {% endhint %} На стороні мерчанта необхідно реалізувати перевірку цього підпису. Загальний алгоритм: 1. Отримати JWS-відповідь. 2. Декодувати `HEADER`. 3. Отримати значення `kid`. 4. За `kid` визначити публічний ключ Банку. 5. Перевірити `SIGNATURE`. 6. Після успішної перевірки обробити дані з `PAYLOAD`. Якщо необхідний публічний ключ Банку ще не був отриманий, його можна отримати через: ``` /ecom/keys/public_key/get_v1 ``` Детальніше про перевірку підпису: {% endstep %} {% step %} ### Крок 7. Провести тестування інтеграції Перед переходом на JWS Authorization 2.0 у production необхідно провести тестування інтеграції. Для цьго рекомендуємо ознайомитись з покроковим описом робот з JWS на прикладі операції [Purchase](https://docs.merchant.alb.ua/avtorizaciya-2.0/opis-roboti-z-jws?select=%D0%B7%D0%B0%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-payload,%D1%80%D0%BE%D0%B7%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-payload,%D0%B7%D0%B0%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-header,%D1%80%D0%BE%D0%B7%D0%BA%D0%BE%D0%B4%D0%BE%D0%B2%D0%B0%D0%BD%D0%B0-%D1%87%D0%B0%D1%81%D1%82%D0%B8%D0%BD%D0%B0-header) Після успішного проходження тестування можна погоджувати переключення інтеграції на JWS Authorization 2.0. {% endstep %} {% endstepper %} # Опис роботи з JWS ## Приклад роботи з JWS для Purchase платежу ```mermaid sequenceDiagram autonumber participant M as Merchant participant E as Ecom Note over M: Підготовка Purchase M->>M: Шифрування карткових даних M->>M: Формування Header для Create Purchase M->>M: Формування Payload M->>M: Підписання JWS приватним ключем M->>E: JWS
POST /ecom/jws/payments/create/purchase_v3 E->>E: Пошук public key мерчанта за kid E->>E: Перевірка JWS Signature E->>E: Обробка Create Purchase E->>E: Формування та підписання JWS Response E-->>M: JWS Response M->>M: Декодування Header M->>M: Отримання kid Банку opt Публічний ключ ще не отримано M->>E: Запит public key за kid E-->>M: Public Key Банку end M->>M: Перевірка Signature відповіді alt Signature валідний M->>M: Обробка Payload else Signature невалідний M->>M: Відхилення відповіді end Note over M: Execute Purchase M->>M: Формування Header для Execute Purchase M->>M: Формування Payload M->>M: Підписання нового JWS M->>E: JWS
POST /ecom/jws/payments/execute/purchase_v1 E->>E: Перевірка JWS Signature E->>E: Виконання Purchase E->>E: Формування JWS Response E-->>M: JWS Response M->>M: Отримання kid з Header M->>M: Перевірка Signature alt Signature валідний M->>M: Декодування та обробка Payload M->>M: Обробка результату Purchase else Signature невалідний M->>M: Відхилення відповіді end ``` #### Опис : 1. Мерчант шифрує карткові дані. 2. Формує `payload` для Create Purchase. 3. Формує `header` з `alg`, `kid`, `ts` та `targetUrl`. 4. Підписує JWS своїм приватним ключем. 5. Відправляє JWS на `/ecom/jws/payments/create/purchase_v3`. 6. Отримує JWS-відповідь Банку. 7. Отримує `kid` з `header` відповіді. 8. За необхідності отримує відповідний public key Банку та верифікує підпис відповіді. 9. Отримує дані для наступного кроку з `payload`. 10. Формує новий JWS для Execute Purchase. 11. Відправляє його на `/ecom/jws/payments/execute/purchase_v1`. 12. Отримує фінальну JWS-відповідь. 13. Перевіряє її цифровий підпис. 14. Обробляє результат виконання Purchase. # Генерація ключів ## Процес отримання ключів: 1. Потібно перейти на [сторінку генерації ключів](https://merchant.alb.ua/jwt) 2. Згенерувати пару ключів 3. Зберегти на свої стороні частину `private_key` 4. Надіслати співробітнику банку частину `public_key` 5. Після виконання реєстрації співробітником банку, буде надіслано всі необхідні дані для роботи з підписанням > Буде надано такі параметри: > > * `merchantId` - внутрішній ідентифікатор термінала (використовується в запитах) > * `kid` - ідентифікатор ключів > * `payment_public_key` - публічний платіжний ключ (використовується для шифрування карткових даних). Ознайомитись можна за посиланням : ### Вимоги до ключів для підписання Для підписання та перевірки запитів використовується асиметрична криптографія. Мерчант повинен згенерувати пару ключів (приватний та публічний) відповідно до однієї з підтримуваних комбінацій алгоритмів. #### Підтримувані алгоритми | Тип ключа | Підтримувані алгоритми | | ------------------- | ---------------------- | | RSA | RS256, RS384, RS512 | | Elliptic Curve (EC) | ES256, ES384, ES512 | #### Вимоги до ключів **RSA** * Тип ключа (`kty`): `RSA` * Призначення (`use`): `sig` (підпис) * Алгоритм (`alg`): `RS256`, `RS384` або `RS512` **Elliptic Curve (EC)** | Алгоритм | Крива (`crv`) | | -------- | ------------- | | ES256 | P-256 | | ES384 | P-384 | | ES512 | P-521 | * Тип ключа (`kty`): `EC` * Призначення (`use`): `sig` (підпис) * Алгоритм (`alg`): один із підтримуваних ES256 / ES384 / ES512 #### Формат ключів Публічний та приватний ключі повинні бути представлені у форматі **X.509 PEM**. **Приклад вигляду ключів :** {% tabs %} {% tab title="Private\_key" %} ``` -----BEGIN PRIVATE KEY----- MEECAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQcEJzAlAgEBBCDCOWlpGDoMfQ25x4Ku K9J96WuwVn3Ri/UTYEMIV/KPXA== -----END PRIVATE KEY----- ``` {% endtab %} {% tab title="Public\_key" %} ``` -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEHZ+3wM4Hmyq6f1H7RJjU4SSrqjt3 8f2VX9aS8ikCxXHID92roxYMsDBzAcVRPwNPiexCu5eS/UzyJsP8e9eydA== -----END PUBLIC KEY----- ``` {% endtab %} {% endtabs %} # Робота з підписанням ## Структура JWS Типовий JWS складається з трьох частин, розділених крапками (`.`): ``` {Base64Url(header)}.{Base64Url(payload)}.{Base64Url(signature)} ``` Де: * **header** — описує загальні мета данні 
{
    "alg": "ES256",  // Алгоритм підписання 
    "kid": "uuid",  // Ідентифікатор публічного ключа (надається від співробітника банку)
    "ts" : "1769174930000", // Дата та час у форматі timestamp в мілісекундах
    "targetUrl" : "/ecom/jws/payments/create/purchase_v3" // URL на який надсилається запит
}
* **payload** — дані, які потрібно передати (необхідні данні для коженого запиту, дивитись у документації [Платіжні методи H2H](https://docs.merchant.alb.ua/avtorizaciya-2.0/platizhni-metodi-h2h)). * **signature** — цифровий підпис, створений за допомогою приватного ключа відправника. Приклад JWS: ``` eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9. eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ. MEYCIQDmG... ``` **Як виконується підписання** 1. Формується **header** (мета дані) **payload** (дані запиту). 2. Обидві частини кодуються у формат **Base64Url**. 3. Об’єднуються в одне повідомлення: ``` signingInput = base64Url(header) + "." + base64Url(payload) ``` 4. Це повідомлення підписується приватним ключем (детальніше як отирмати ключ - [Генерація ключів](/avtorizaciya-2.0/generaciya-klyuchiv)) за вказаним алгоритмом . 5. Результат (signature) додається як третя частина JWS. Приклад генерації JWS можна переглянути на сайті **Приклад коду для генерації підпису:** {% tabs %} {% tab title="JavaScript" %} ```javascript import { CompactSign, importPKCS8 } from 'jose'; // === Дані === const privateKeyPem = ` -----BEGIN EC PRIVATE KEY----- MHcCAQEEIBOS+Xg3qgYSe5T4H2AoB0zWrhb0jNmcdW6o2bTXXWlQoAoGCCqGSM49 AwEHoUQDQgAEMO4qQsgPskZ4E1X6nHZU9yHnJrZ97K3QAjQ1oG1zgrht3mA4+lf5 aMqTIk1glXZpMT4pAzTURmmP2+prvQul3g== -----END EC PRIVATE KEY----- `; const header = { alg: "ES256", kid: "9a3f6e6d-4f56-4b8b-99d3-24db19f54d8a", ts: Math.floor(Date.now() / 1000), targetUrl: "/ecom/jws/payments/create/purchase_v3" }; // payload — це тіло запиту const payload = { merchantId: "12345", amount: "1000.00", currency: "UAH", orderId: "ORD-2025-001" }; // === Генерація JWS === const privateKey = await importPKCS8(privateKeyPem, 'ES256'); const encoder = new TextEncoder(); const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url'); const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url'); const signingInput = `${encodedHeader}.${encodedPayload}`; const sign = new CompactSign(encoder.encode(JSON.stringify(payload))) .setProtectedHeader(header); const jws = await sign.sign(privateKey); console.log("JWS:", jws); ``` {% endtab %} {% tab title="Python" %} ```python from jwcrypto import jwk, jws import json, time, base64 # === Приватний ключ === private_key_pem = """-----BEGIN EC PRIVATE KEY----- MHcCAQEEIBOS+Xg3qgYSe5T4H2AoB0zWrhb0jNmcdW6o2bTXXWlQoAoGCCqGSM49 AwEHoUQDQgAEMO4qQsgPskZ4E1X6nHZU9yHnJrZ97K3QAjQ1oG1zgrht3mA4+lf5 aMqTIk1glXZpMT4pAzTURmmP2+prvQul3g== -----END EC PRIVATE KEY-----""" key = jwk.JWK.from_pem(private_key_pem.encode()) header = { "alg": "ES256", "kid": "9a3f6e6d-4f56-4b8b-99d3-24db19f54d8a", "ts": int(time.time()), "targetUrl": "/ecom/jws/payments/create/purchase_v3" } payload = { "merchantId": "12345", "amount": "1000.00", "currency": "UAH", "orderId": "ORD-2025-001" } protected = base64.urlsafe_b64encode(json.dumps(header).encode()).decode().rstrip("=") body = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=") signing_input = f"{protected}.{body}" signature = jws.JWS(json.dumps(payload)) signature.add_signature(key, protected=json.dumps(header), alg="ES256") print("JWS:", signature.serialize(compact=True)) ``` {% endtab %} {% tab title="Java" %} ```java import com.nimbusds.jose.*; import com.nimbusds.jose.crypto.*; import com.nimbusds.jose.util.Base64URL; import java.security.*; import java.security.spec.*; import java.util.*; public class GenerateJWS { public static void main(String[] args) throws Exception { // Завантажуємо приватний ключ (EC P-256) String privateKeyPEM = """ -----BEGIN EC PRIVATE KEY----- MHcCAQEEIBOS+Xg3qgYSe5T4H2AoB0zWrhb0jNmcdW6o2bTXXWlQoAoGCCqGSM49 AwEHoUQDQgAEMO4qQsgPskZ4E1X6nHZU9yHnJrZ97K3QAjQ1oG1zgrht3mA4+lf5 aMqTIk1glXZpMT4pAzTURmmP2+prvQul3g== -----END EC PRIVATE KEY----- """; // (Простий приклад: створити EC ключову пару) KeyPairGenerator keyGen = KeyPairGenerator.getInstance("EC"); keyGen.initialize(Curve.P_256.toECParameterSpec()); KeyPair pair = keyGen.generateKeyPair(); Map payload = new HashMap<>(); payload.put("merchantId", "12345"); payload.put("amount", "1000.00"); payload.put("currency", "UAH"); payload.put("orderId", "ORD-2025-001"); JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.ES256) .customParam("kid", "9a3f6e6d-4f56-4b8b-99d3-24db19f54d8a") .customParam("ts", System.currentTimeMillis() / 1000) .customParam("targetUrl", "/ecom/jws/payments/create/purchase_v3") .build(); Payload jwsPayload = new Payload(new com.nimbusds.jose.util.JSONObjectUtils().toJSONString(payload)); JWSObject jwsObject = new JWSObject(header, jwsPayload); jwsObject.sign(new ECDSASigner((ECPrivateKey) pair.getPrivate())); System.out.println("JWS: " + jwsObject.serialize()); } } ``` {% endtab %} {% tab title="PHP" %} ```php 'ES256', 'kid' => '9a3f6e6d-4f56-4b8b-99d3-24db19f54d8a', 'ts' => time(), 'targetUrl' => '/ecom/jws/payments/create/purchase_v3' ]; $payload = [ 'merchantId' => '12345', 'amount' => '1000.00', 'currency' => 'UAH', 'orderId' => 'ORD-2025-001' ]; $jwsBuilder = new JWSBuilder(null, [new ES256()]); $jws = $jwsBuilder ->create() ->withPayload(JsonConverter::encode($payload)) ->addSignature($jwk, $header) ->build(); $serializer = new \Jose\Component\Signature\Serializer\CompactSerializer(); echo "JWS: " . $serializer->serialize($jws, 0); ``` {% endtab %} {% endtabs %} ## Вимоги до JWS ### **1. Загальні вимоги до JWS :** * Усі запити до API повинні бути підписані за допомогою **JWS (JSON Web Signature)**. * Підпис формується відповідно до алгоритму, що відповідає типу ключа, переданого у параметрі `kid`. * При валідації JWS система перевіряє правильність **header**, **payload** та **signature**. У разі порушення будь-якої з вимог запит відхиляється з помилкою. ### 2. Вимоги до частини header JWS : ПІдтримувальні параметри header :
ПолеОписТипОбов'язковеПриклад
algАлгоритм підпису, що відповідає типу ключаstringтак
ES256
kidІдентифікатор публічного ключаstringтак
28da60c2-d60f-404e-b4da-6b089fb29555
tsЧас генерації JWS по UTC(Kyiv)number (Unix timestamp, milliseconds)так
1769174930000
targetUrlURL, для якого формується запитstring (URL)так
/ecom/jws/payments/create/purchase_v3
#### 2.1. **Перевірка терміну дії токена (`ts`)** * Поле `ts` повинно містити timestamp (в мілісекундах). * JWS вважається дійсним протягом **60 секунд** з моменту формування. {% hint style="danger" %} #### Умови помилки: * Якщо `ts` > (поточний час + 60 секунд) або `ts` < (поточний час − 60 секунд). * Якщо значення `ts` не відповідає формату `1769174930000` * Якщо значення не відповідає UTC по Київу {% endhint %} #### 2.2. **Перевірка `targetUrl`** Система перевіряє, що значення: * відповідає формату URL, * є дозволеним маршрутом API, * відповідає фактичному endpoint, куди надсилається запит.\ Приклад : \ Запит надійщо в на- `{url}/ecom/jws/payments/create/purchase_v3`\ Фактичний - `/ecom/jws/payments/create/purchase_v3` {% hint style="danger" %} #### **Умови помилки:** * Якщо `targetUrl` невалідний, має неправильний формат або не співпадає з фактичним шляхом запиту. * Якщо запит надійшов на `/ecom/jws/payments/account_to_card_v3` , а значення `targetURL` вказаний `/ecom/jws/payments/create/purchase_v3` . {% endhint %} #### 2.3. **Перевірка алгоритму підпису (`alg`)** Значення `alg` повинно відповідати алгоритму пари ключів, що використовується для підпису `ES256`. {% hint style="danger" %} #### Умова помилки: * Якщо в `alg` передано значення, що не відповідає алгоритму згенерованого ключа. {% endhint %} #### 2.4. **Перевірка існування ключа (`kid`)** * `kid` повинен відповідати одному з активних ключів мерчанта. {% hint style="danger" %} #### Умова помилки: Якщо ключ із зазначеним `kid` не існує. {% endhint %} ### 3. **Вимоги до JWS Payload** Payload JWS повинен містити **тіло запиту (request body)** у JSON, яке повністю відповідає вимогам конкретного endpoint’у. Приклад: якщо запит виконується до `/ecom/jws/payments/create/purchase_v3`, то саме тіло цього запиту ([Запит проведення PURCHASE Крок 1](https://docs.merchant.alb.ua/avtorizaciya-2.0/platizhni-metodi-h2h/purchase/zapit-provedennya-purchase-krok-1)) включається у payload JWS. #### 3.1. **Валідація структури тіла запиту** Payload повинен: * містити всі обов'язкові параметри, визначені для відповідного endpoint’у, * відповідати JSON схемі, * проходити внутрішню бізнес-валідацію. {% hint style="danger" %} #### Умова помилки: Якщо тіло запиту не відповідає вимогам (відсутні поля, неправильні типи). {% endhint %} #### 3.2. **Перевірка мерчанта (`merchantId`)** Усі операції повинні виконуватися від імені існуючого мерчанта. {% hint style="danger" %} #### Умова помилки: Якщо в payload передано `merchantId`, який: * не існує * деактивований * не прив’язаний до ключа `kid` {% endhint %} # Шифрування карткових даних В розділі описано, яким чином відбувається шифрувння карткових даних, для забеспечення конфіденційності чутливих даних. ## Робота зі стандартом шифрування JWE Для забезпечення конфіденційності передачі даних, використовується **JWE (JSON Web Encryption)** — стандарт, який визначає формат зашифрованих JSON повідомлень. Для шифрування номеру картки (PAN) використовується публічний платіжний ключ `payment_public_key` , що надається під час генерації ключів (дивитись документацію "[Генерація ключів](https://docs.merchant.alb.ua/avtorizaciya-2.0/generaciya-klyuchiv#proces-otrimannya-klyuchiv)") Ключ відповідає формату JWK : ```json "paymentPublicKey": { "kty": "EC", "x": "Hp833OY6a0VbFD1j8xFyXWcAA-HOlyr7B_-B05esZUy32RA41s0oGAMTal23AX9d", "y": "WGHeR9PhKRymoA-ggsR3VkQTgdfzt7PWa8P2qNpu0cV83lmLxE57b8rR7ajBurvj", "crv": "P-384" } ``` > **Публічний платіжний ключ (`payment_public_key`)** відповідає параметрам : > > ● "[kty](https://datatracker.ietf.org/doc/html/rfc7518#section-6.1)": "EC" - тип ключа > > ● "[crv](https://datatracker.ietf.org/doc/html/rfc7518#section-6.2.1.1)": "P-384" - еліптична крива ключа > > ● "[use](https://datatracker.ietf.org/doc/html/rfc7517#section-4.2)": "enc" – параметр, що використовується для криптування ключем > > ● "[alg](https://datatracker.ietf.org/doc/html/rfc7518#section-4.1)": ECDH-ES+A256KW - алгоритм для якого використовується ключ ### Приклад ендпоінта, для шифрування : {% hint style="warning" %} **Запит викоритсосується тільки для тестування.**\ **Запит заборонено виконувати з реальними ключами.** \ **Запит шифрування потрібно реалізовувати на свої стороні.** {% endhint %} ## Шифрування повідомлення за допомогою JWK > Шифрує передане повідомлення (наприклад, номер картки або термін дії картки та CVV) за допомогою публічного ключа JWK (EC).
```json {"openapi":"3.0.3","info":{"title":"Encrypt Card Data API","version":"1.0.0"},"servers":[{"url":"https://api-ecom-release.develop.bankalliance.ua"}],"paths":{"/cipher/encrypt_by_jwk":{"post":{"summary":"Шифрування повідомлення за допомогою JWK","description":"Шифрує передане повідомлення (наприклад, номер картки або термін дії картки та CVV) за допомогою публічного ключа JWK (EC).\n","parameters":[{"name":"message","in":"query","description":"Повідомлення для шифрування (наприклад, номер картки або термін дії картки та CVV)","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kty","crv","x","y"],"properties":{"kty":{"type":"string","enum":["EC"],"description":"Тип ключа (EC)"},"crv":{"type":"string","description":"Тип кривої"},"x":{"type":"string","description":"X-координата публічного ключа (base64url)"},"y":{"type":"string","description":"Y-координата публічного ключа (base64url)"}}}}}},"responses":{"200":{"description":"Успішне шифрування. Повертає зашифроване повідомлення (наприклад, JWE токен).","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Некоректний запит (наприклад, відсутні параметри)"},"500":{"description":"Внутрішня помилка сервера"}},"tags":["Encryption"]}}}} ``` # Обробка синхронних/асинхронних відповідей Всі відповіді асинхронні та синхронні будуть підписані. ## Структура відповіді Усі відповіді сервісу передаються **у форматі JWS (JSON Web Signature)** Це гарантує: * **цілісність** даних — повідомлення не було змінено під час передачі; * **автентичність** джерела — запит дійсно надійшов від авторизованого сервісу. Повідомлення JWS має вигляд: ``` .. ``` ### **Кодування Header і Payload** Обидві частини (`header`, `payload`) **не шифруються**, а лише **кодуються у формат Base64Url**.\ Тобто, їх можна декодувати для перегляду змісту, але змінювати — ні (це зламає підпис). > **Параметр `Signature`** забезпечує гарантію, що навіть якщо хтось змінить одне поле у `payload`, підпис стане невалідним. #### **Приклад вигляду закодованих даних:** {% tabs %} {% tab title="Закодована частина header" %} ``` eyJhbGciOiJFUzI1NiIsImtpZCI6IjYwMjE3ZDU2LTJkMzYtNDhlMy1hYmU4LTVjMDBiNDJjYTg4NSJ9 ``` {% endtab %} {% tab title="Розкодована частина header" %} ```json { "alg": "ES256", "kid": "60217d56-2d36-48e3-abe8-5c00b42ca885" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Закодована частина payload" %} ``` eyJ0eXBlIjoiQUNDT1VOVF8yX0NBUkQiLCJycm4iOiI1MzE3MTU5MzczMDUiLCJwdXJwb3NlIjoi0LfQsCDRgtC-0LLQsNGAIiwiY29pbkFtb3VudCI6MTAsIm1lcmNoYW50SWQiOiIxMzdkOTMwNC0wMzY4LTExZWQtYjkzOS0wMjQyYWMxMjAwMDIiLCJvcGVyYXRpb25JZCI6IjE3NjMwNDY5NjQyODl5R2pEZDJ1RVBrWSIsImVjb21PcGVyYXRpb25JZCI6ImQ1Y2RlYzg0LWNkYzUtNDVjMi1hZmEyLWQ4MWJmZDc5ZmU2MSIsInN0YXR1cyI6IlNVQ0NFU1MiLCJ0cmFuc2FjdGlvblR5cGUiOjQ2LCJtZXJjaGFudFJlcXVlc3RJZCI6IjA0MDIyNjVkLWMwYzYtNDNlYi05NDhlLTAyMzEwYzMzMWEzMyIsInRyYW5zYWN0aW9uQ3VycmVuY3kiOiI5ODAiLCJtZXJjaGFudENvbW1pc3Npb24iOjAsImNyZWF0aW9uRGF0ZVRpbWUiOiIyMDI1LjExLjEzIDE3OjE2OjA0LjIyNyIsIm1vZGlmaWNhdGlvbkRhdGVUaW1lIjoiMjAyNS4xMS4xMyAxNzoxNjowNC4yMjciLCJ0cmFuc2FjdGlvblJlc3BvbnNlSW5mbyI6eyJhY3Rpb25Db2RlIjoiMCIsInJlc3BvbnNlQ29kZSI6IjAwIiwiZGVzY3JpcHRpb24iOiLQntC_0LXRgNCw0YbRltGPINGD0YHQv9GW0YjQvdCwIn0sInByb2R1Y3RUeXBlIjoiQTJDIiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvNDExNjM0ZjQtNmMxNy00ODYyLTg4NTYtZDA2NGY3ZjIxMzVhIiwicGF5bWVudFNlcnZpY2VUeXBlIjoiQ0FSRCIsIm5vdGlmaWNhdGlvbkVuY3J5cHRpb24iOmZhbHNlLCJub3RpZmljYXRpb25TaWduYXR1cmUiOnRydWUsInByb2Nlc3NpbmdUZXJtaW5hbElkIjoiQUUwMDEwMDQiLCJwcm9jZXNzaW5nTWVyY2hhbnRJZCI6IkFFMDAxMDA0IiwiY3JlYXRvclN5c3RlbSI6IkgySCIsImJhbGFuY2VBbW91bnRBZnRlciI6OTkwMTAxOTY5NDQ5MTMsInNlbmRlckN1c3RvbWVySWQiOiIwMDAwMDAiLCJzZW5kZXJGaXJzdE5hbWUiOiJzZW5kZXJGaXJzdE5zZW5kZXJGaXJzdE5hbWVzZW4iLCJzZW5kZXJMYXN0TmFtZSI6InNlbmRlckxhc3ROYW1lc2VuZGVyTGFzdE5hbWVzZSIsInNlbmRlck1pZGRsZU5hbWUiOiJzZW5kZXJNaWRkbGVOYW1lc2VuZGVyTWlkZGxlTmEiLCJzZW5kZXJDb3VudHJ5IjoiODA0Iiwic2VuZGVyUmVnaW9uIjoic2VuZGVyX3JlZ2lvbiIsInNlbmRlckNpdHkiOiJzZW5kZXJfY2l0eSIsInNlbmRlclN0cmVldCI6InNlbmRlcl9zdHJlZXQiLCJzZW5kZXJBZGRpdGlvbmFsQWRkcmVzcyI6Ik4gNiIsInNlbmRlckl0biI6IjEyMzQ1Iiwic2VuZGVyUGFzc3BvcnQiOiIxMjM0NSIsInNlbmRlcklwIjoiMTY1LjIyMi44Ny4yMjQiLCJzZW5kZXJQaG9uZSI6IjM4MDk2NzU0MjM0NCIsInNlbmRlckJpcnRoZGF5IjoiMTIxMjIwMDAiLCJzZW5kZXJHZW5kZXIiOiJNYWxlIiwic2VuZGVyWmlwQ29kZSI6IjEyMzQ1IiwicmVjaXBpZW50Q3VzdG9tZXJJZCI6IjEyMzQ1NjciLCJyZWNpcGllbnRGaXJzdE5hbWUiOiJyZWNpcGllbnRGaXJzdE5yZWNpcGllbnRGaXJzdE4iLCJyZWNpcGllbnRMYXN0TmFtZSI6InJlY2lwaWVudExhc3N0TnJlY2lwaWVudExhc3N0TiIsInJlY2lwaWVudE1pZGRsZU5hbWUiOiJyZWNpcGllbnRNaWRkbGVOYW1lcmVjaXBpZW50TWkiLCJyZWNpcGllbnRFbWFpbCI6InLRhNGEQGdtYWlsLmNvbSIsInJlY2lwaWVudENvdW50cnkiOiI4MDQiLCJyZWNpcGllbnRSZWdpb24iOiJyZXNfcmVnIiwicmVjaXBpZW50Q2l0eSI6InJlc19kbmlwcm8iLCJyZWNpcGllbnRTdHJlZXQiOiJyZXNfc3RyZWV0IiwicmVjaXBpZW50QWRkaXRpb25hbEFkZHJlc3MiOiJyZXNfYWRkcmVzIiwicmVjaXBpZW50SXRuIjoiMTIzNDU2Nzg5MCIsInJlY2lwaWVudFBhc3Nwb3J0IjoicmVzX3Bhc3BvcnQiLCJyZWNpcGllbnRJcCI6IjE2NS4yMjIuODcuMjI0IiwicmVjaXBpZW50UGhvbmUiOiIzODA5Njc1NDIzNDQiLCJyZWNpcGllbnRCaXJ0aGRheSI6IjEyMTIyMDAwIiwicmVjaXBpZW50R2VuZGVyIjoiRmVtYWxlIiwicmVjaXBpZW50WmlwQ29kZSI6Ijc3Nzc3In0 ``` {% endtab %} {% tab title="Розкодована частина payload" %} {% code expandable="true" %} ```json { "type": "ACCOUNT_2_CARD", "rrn": "531715937305", "purpose": "за товар", "coinAmount": 10, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1763046964289yGjDd2uEPkY", "ecomOperationId": "d5cdec84-cdc5-45c2-afa2-d81bfd79fe61", "status": "SUCCESS", "transactionType": 46, "merchantRequestId": "0402265d-c0c6-43eb-948e-02310c331a33", "transactionCurrency": "980", "merchantCommission": 0, "creationDateTime": "2025.11.13 17:16:04.227", "modificationDateTime": "2025.11.13 17:16:04.227", "transactionResponseInfo": { "actionCode": "0", "responseCode": "00", "description": "Операція успішна" }, "productType": "A2C", "notificationUrl": "https://webhook.site/411634f4-6c17-4862-8856-d064f7f2135a", "paymentServiceType": "CARD", "notificationEncryption": false, "notificationSignature": true, "processingTerminalId": "AE001004", "processingMerchantId": "AE001004", "creatorSystem": "H2H", "balanceAmountAfter": 99010196944913, "senderCustomerId": "000000", "senderFirstName": "senderFirstNsenderFirstNamesen", "senderLastName": "senderLastNamesenderLastNamese", "senderMiddleName": "senderMiddleNamesenderMiddleNa", "senderCountry": "804", "senderRegion": "sender_region", "senderCity": "sender_city", "senderStreet": "sender_street", "senderAdditionalAddress": "N 6", "senderItn": "12345", "senderPassport": "12345", "senderIp": "165.222.87.224", "senderPhone": "380967542344", "senderBirthday": "12122000", "senderGender": "Male", "senderZipCode": "12345", "recipientCustomerId": "1234567", "recipientFirstName": "recipientFirstNrecipientFirstN", "recipientLastName": "recipientLasstNrecipientLasstN", "recipientMiddleName": "recipientMiddleNamerecipientMi", "recipientEmail": "rфф@gmail.com", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "1234567890", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12122000", "recipientGender": "Female", "recipientZipCode": "77777" } ``` {% endcode %} {% endtab %} {% endtabs %} ## **Перевірка підпису** Параметр `kid` (Key ID) у JWS Header визначає, **який саме публічний ключ** слід використовувати для перевірки підпису. У разі, якщо ключова пара оновлюється, сервер формує відповіді з новим `kid`.\ Клієнт має: 1. Отримати новий `kid` з header JWS; 2. Виконати запит на [`/ecom/keys/public_key/get_v1`](https://docs.merchant.alb.ua/avtorizaciya-2.0/obrobka-sinkhronnikh-asinkhronnikh-vidpovidei#post-ecom-keys-public_key-get_v1) для отримання відповідного публічного ключа; 3. Використати цей ключ для перевірки підпису наступних повідомлень. Для перевірки підпису, потрібно розкодувати частину `header` де буде знаходитись параметр `kid` . {% hint style="info" %} При роботі з Recurring Payment для отримання ключа потрібно використовувати ендпоінт `{{url}}/keys/get_public_key_v1` {% endhint %} ## Отримати публічний ключ за kid > Повертає публічний ключ (JWK) для вказаного kid.
```json {"openapi":"3.0.3","info":{"title":"Get Public Key API","version":"1.0.0"},"servers":[{"url":"https://{{url}}"}],"paths":{"/ecom/keys/public_key/get_v1":{"post":{"summary":"Отримати публічний ключ за kid","description":"Повертає публічний ключ (JWK) для вказаного kid.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kid"],"properties":{"kid":{"type":"string","description":"Ідентифікатор ключа (Key ID)"}}}}}},"responses":{"200":{"description":"Успішно. Повертає публічний ключ у форматі JWK.","content":{"application/json":{"schema":{"type":"object","properties":{"kty":{"type":"string","description":"Тип ключа (наприклад, EC)"},"use":{"type":"string","description":"Призначення ключа (наприклад, sig)"},"crv":{"type":"string","description":"Крива (наприклад, P-256)"},"kid":{"type":"string","description":"Ідентифікатор ключа"},"x":{"type":"string","description":"X-координата публічного ключа (base64url)"},"y":{"type":"string","description":"Y-координата публічного ключа (base64url)"},"alg":{"type":"string","description":"Алгоритм (наприклад, ES256)"}}}}}},"400":{"description":"Некоректний запит (наприклад, відсутній kid)"},"404":{"description":"Ключ не знайдено"},"500":{"description":"Внутрішня помилка сервера"}},"tags":["Keys"]}}}} ``` # Платіжні методи H2H # PURCHASE # Запит проведення PURCHASE Крок 1 {{url}}/ecom/jws/payments/create/purchase\_v3 ### **Вхідні параметри** ч**астини payload JWS :**
ПараметрОпиcФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
coinAmountсума платежу в копійках stringТак2000
txnType

під тип транзакціі

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

enumНіМожливі значення: NONCVV/noncvv
typeTokenвизначає тип токена при його створенніstringНі

можливі значення:

  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
customerDataоб'єкт з customer даними objectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправника string (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeІндекс відправникаstring (50)Ні 49000
### **Вихідні параметри** ч**астини payload JWS :** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```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" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```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 } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```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 } ```
# Запит проведення PURCHASE Крок 2 {{url}}/ecom/jws/payments/execute/purchase\_v1 ### **Вхідні параметри** ч**астини payload JWS :**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак1697008393082nW0c1jr6KVv
encryptedCardData

термін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvv

  • Якщо в параметр TxnType передається "NONCVV\noncvv" тоді у параметрі ecnryptedCardData потрібно передати лише YYMM без CVV
  • У іншому випадку якщо в TxnType нічого не педеається, тоді у параметрі encryptedCardData піотрбно обов'язкового передавати у форматі YYMMCVV
stringТак2503111 (розшифрований вигляд, у форматі YYMMCVV)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### **Вихідні параметри** ч**астини payload JWS :** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | creationDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "operationId": "{{operationIdT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "PURCHASE", "rrn": "410114186775", "purpose": "purpose", "comment": "comment", "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "17127594157429eggOuxH5yl", "ecomOperationId": "63feb70f-8eb0-43cc-96c3-2e2eea9cec1e", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 35, "merchantRequestId": "1d4787d6-75cb-4c75-8466-59cc698e7bbf", "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", "paymentServiceType": "CARD", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "txnType": "NONCVV", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```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": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712822536063CdDIRi8hhjq", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
# A2C {{url}}/ecom/jws/payments/account\_to\_card\_v3 Максимальна сума запиту операції А2С становить 29999.00 грн. Перевищення граничної суми супроводжуєтсья помилкою: ```json ERROR: @Payment coin amount exceeds the limit ``` ### **Вхідні параметри** ч**астини payload JWS :**
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер картки отримувача зашифрованый в JWE за допомогою платіжного ключаstringТак5473670000000304 (розшифрованний вид)
coinAmountсума платежу в копійкахintТак2000
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
notificationUrlurl, на який буде відправлено CallBackstringНіhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

commentДодаткова інформація про платіжstringНі///5555.25412
purposeПризначення платежуstringНіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
senderAccountРахунок відправникаstringНі2900000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Ні1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Так1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувача

У разі, якщо фізична особа офіційно відмовилась від отримання ІПН, необхідно передавати альтернативний параметр — recipientPassport з коректними паспортними даними отримувача.		string (20)Так, якщо не вказан recipientPassport123456789
recipientPassportпаспорт отримувачаstring (255)Так, якщо не вказан recipientItnАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
### **Вхихідні параметри** ч**астини payload JWS :** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | -------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | ACCOUNT\_2\_CARD | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 46 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | A2C | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
ExpandJWS Payload — тіло запиту перед підписанням ```json { "encryptedCardNumber":"{{encryptedPanT}}", "merchantId":"137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId":"{{requestUUIDT}}", "purpose":"за товар", "coinAmount": 120, "notificationUrl":"https://api-ecom-prod.bankalliance.ua/mock", "ecomComment": "string", "senderAccount": "UA12305299260022119999", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" }, "date": "{{currentdateT}}.00+00:00" } ```
ExpandJWS Payload — тіло відповіді перед підписанням ```json { "type": "ACCOUNT_2_CARD", "rrn": "410208187340", "purpose": "за товар", "comment": null, "coinAmount": 120, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712822901491QtPAxAWOrrg", "ecomOperationId": "ff1ae4eb-d66d-467e-896d-01ed579bd040", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 46, "merchantRequestId": "cf17607f-c1f8-4e8e-abb2-5fd1b3dd17ec", "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": "A2C", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "CARD", "notificationEncryption": false, "senderAccount": "UA12305299260022119999", "recipientCardNumberMask": null, "senderCustomerId": null, "senderFirstName": "Petro", "senderLastName": "Petrenko", "senderMiddleName": null, "senderEmail": null, "senderCountry": "803", "senderRegion": null, "senderCity": "Kyiv", "senderStreet": "L.Ukrainki01", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "recipientCustomerId": null, "recipientFirstName": "TestFirstname", "recipientLastName": "TestLastName", "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": "803", "recipientRegion": null, "recipientCity": "Kyiv", "recipientStreet": "T. Shevchenka, 11", "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "recipientBankCode": null, "recipientPaymentSystem": null } ```
# C2A ``` ``` # Запит проведення C2A Крок 1 {{url}}/ecom/jws/payments/create/card\_to\_account\_v3 ### **Вхідні параметри** ч**астини payload JWS :**
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberНомер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
coinAmountСума платежу в копійкахstringТак2000
txnType

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

stringНі

Можливі значення:

NONCVV/noncvv

typeTokenвизначає тип токена при його створенніstringНі

можливі значення:

  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)Ніhttps://support.google.com/
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

merchantCommissionСума комісіїintНі0
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі29000000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
### **Вихідні параметри** ч**астини payload JWS :** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
ExpandJWS Payload — тіло запиту перед підписанням ```json { "merchantId":"467c8a10-c705-11ed-afa1-0242ac120002", "merchantRequestId": "{{requestUUIDT}}", "encryptedCardNumber": "{{encryptedPanT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "coinAmount": "1000", "comment": "comment", "purpose": "purpose", "merchantCommission": "0", "desiredThreeDSMode": "MUST" "notificationUrl": "", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" } "date": "{{currentdateT}}.00+00:00" } ```
**Приклад тіла запиту** # Запит проведення C2A Крок 2 {{url}}/ecom/jws/payments/execute/card\_to\_account\_v1 ### **Вхідні параметри** ч**астини payload JWS :**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
encryptedCardData

термін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvv

  • Якщо в параметр TxnType передається "NONCVV\noncvv" тоді у параметрі ecnryptedCardData потрібно передати лише YYMM без CVV
  • У іншому випадку якщо в TxnType нічого не педеається, тоді у параметрі encryptedCardData піотрбно обов'язкового передавати у форматі YYMMCVV
stringТак2503111 (розшифрований вигляд)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### **Вихідні параметри** ч**астини payload JWS :** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | ### Приклади :
ExpandJWS Payload — тіло запиту перед підписанням ```json { "operationId": "{{operationIdT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ```
ExpandJWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": "410208187342", "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823122106xnUK8T9Z9d8", "ecomOperationId": "a4842af1-ab80-4685-9cef-0d97aedbb99f", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "0d7a190d-9cfc-4b01-9615-e207ebe8b23b", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
ExpandJWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823334404zicRAYWIAm1", "ecomOperationId": "412ac336-aac5-43b5-8d35-b57ffa9d53ff", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "60cb4f84-add5-48c6-984f-7b20a6b50c75", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "db259063-61ba-4681-a7e9-65fbbebead2d", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712823334404zicRAYWIAm1", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
# ApplePay decrypted #### # PURCHASE # Запит проведення платежу Крок 1 {{url}}/ecom/jws/payments/apple\_pay/purchase\_v3 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
Об’єкт paymentData, який необхідно закриптувати платіжним ключем
applicationPrimaryAccountNumberномер рахунку картки, з якої фінансується ця транзакціяstringТак4420642424203999
applicationExpirationDateТермін дії картки у форматі YYMMDDstringТак261001
currencyCodeЦифровий код валюти ISO 4217stringТак980
transactionAmountсума платежу в копійкахstringТак2000
cardholderNameІм'я власника карткиstringНіІванченко Петро
deviceManufacturerIdentifierHex-encoded device manufacturer identifierstringТак1
paymentDataType stringТак3DSecure
paymentData
onlinePaymentCryptogramКриптограма платежу у форматі Base64stringТакAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorECI indicatorstring(1)Ні7
Додаткові дані для проведення платежу
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | ### Приклади : **Приклад об’єкту paymentData** ```json { "applicationPrimaryAccountNumber":"{{applePayCardNumber}}", "applicationExpirationDate":"{{applePayDate}}", "currencyCode":"980", "transactionAmount":"100", "cardholderName":"{{cardholderName}}", "deviceManufacturerIdentifier":"1255548888hfhhbbk", "paymentDataType":"3DSecure", "paymentData":{ "onlinePaymentCryptogram":"AVn0rK8BiDxN2D/w2j8LMAABAAA=", "eciIndicator":"7"} } ```
JWS Payload — тіло запиту перед підписанням ```json { "paymentData": "{{encryptedPaymentData}}", "merchantRequestId": "{{requestUUIDT}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "", "resultRedirectUrl": "", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "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" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "PURCHASE", "rrn": null, "purpose": "назначение", "comment": "тестовыйкомент", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": null, "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 35, "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": null, "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 } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "PURCHASE", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712824711120IbbgGHLPNCm", "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 35, "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8", "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 } ```
# Запит проведення платежу Крок 2 (3DS) {{url}}/ecom/jws/payments/apple\_pay\_3ds/purchase\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "operationId": "", "browserInfo": { "browserAcceptHeader":"", "browserUserAgent": "", "browserLanguage": "", "browserColorDepth": "", "browserScreenHeight": "", "browserScreenWidth": "", "browserTZ": "" }, "date": "{{currentdateT}}.00+00:00" } ```
\\
JWS Payload — тіло відповіді перед підписанням без 3дс
JWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "PURCHASE", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712824711120IbbgGHLPNCm", "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 35, "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712824711120IbbgGHLPNCm", "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 } ```
# C2A # Запит проведення C2A Крок 1 {{url}}/ecom/jws/payments/apple\_pay/card\_to\_account\_v3 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
Об’єкт paymentData, який необхідно закриптувати платіжним ключем
applicationPrimaryAccountNumberномер рахунку картки, з якої фінансується ця транзакціяstringТак4420642424203999
applicationExpirationDateТермін дії картки у форматі YYMMDDstringТак261001
currencyCodeЦифровий код валюти ISO 4217stringТак980
transactionAmountсума платежу в копійкахstringТак2000
cardholderNameІм'я власника карткиstringНіІванченко Петро
deviceManufacturerIdentifierHex-encoded device manufacturer identifierstringТак1
paymentDataType stringТак3DSecure
paymentData
onlinePaymentCryptogramКриптограма платежу у форматі Base64stringТакAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorECI indicatorstring(1)Ні7
Додаткові дані для проведення платежу
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі2900000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (50)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingMerchantId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади : **Приклад об’єкту paymentData** ```json { "applicationPrimaryAccountNumber":"{{applePayCardNumber}}", "applicationExpirationDate":"{{applePayDate}}", "currencyCode":"980", "transactionAmount":"100", "cardholderName":"{{cardholderName}}", "deviceManufacturerIdentifier":"1255548888hfhhbbk", "paymentDataType":"3DSecure", "paymentData":{ "onlinePaymentCryptogram":"AVn0rK8BiDxN2D/w2j8LMAABAAA=", "eciIndicator":"7"} } ```
JWS Payload — тіло запиту перед підписанням ```json { "paymentData": "{{encryptedPaymentData}}", "merchantRequestId": "{{requestUUIDT}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "resultRedirectUrl": "", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": "410209187456", "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826505345NY4bmiIDrE5", "ecomOperationId": "21931655-17db-44e3-bd2f-212cbf5069c9", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "586fc1f5-f647-4800-94e1-a9e65a68d424", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826655741bHtPOJY9BvI", "ecomOperationId": "92f0ccdd-48fb-43d8-9ee4-f4bd2e295f86", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "45f336e8-f58d-43d5-9cdd-c3a06ba794c5", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "a011f12f-ddfa-4629-b786-4aa427f7210f", "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
# Запит проведення c2a Крок 2 (3DS) {{url}}/ecom/jws/payments/apple\_pay\_3ds/card\_to\_account\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "operationId": "", "browserInfo": { "browserAcceptHeader":"", "browserUserAgent": "", "browserLanguage": "", "browserColorDepth": "", "browserScreenHeight": "", "browserScreenWidth": "", "browserTZ": "" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826797010P-juYeIJRx3", "ecomOperationId": "cbf7e357-d216-46ca-a885-71d917b0e405", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "004dbc84-f3c1-4cc7-b7fb-50a3b0b6fa7e", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "e13f7b12-fcc9-4028-9307-0749d7076bdd", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712826797010P-juYeIJRx3", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
# ApplePay encrypted
1. Клієнт натискає кнопку «Сплатити замовлення» на сайті/в застосунку. 2. WebPage запускає скрипт Запит підтримки Apple Pay, щоб перевірити, чи підтримується Apple Pay на цій сторінці. 3. Якщо пристрій клієнта не підтримує оплату через аРay, клієнт не зможе скористатися цим способом оплати, і запит буде відхилено. 4. Якщо підтримується, webPage надсилає опціональний Запит отримання даних мерчанта в Apple Pay. Можливо зробити hard-coded даних Apple Pay на стороні мерчанта 5. WebPage запускає скрипт на валідацію мерчанта через Apple Pay для підтвердження даних. 6. Apple Pay повертає callback з параметром validationUrl. 7. Клієнт натискає кнопку Сплатити з Apple Pay, підтверджуючи вибір цього способу оплати. 8. Встановлюється сесія з Apple Pay, і пристрій клієнта готовий до взаємодії з Apple Pay. 9. У відповідь на встановлення сесії Apple передає токенізовані дані карт клієнта. 10. Клієнту відображається список карток на пристрої, які можна використовувати для оплати. 11. Клієнт обирає картку, яку хоче використати для оплати. 12. Скрипт на пристрої клієнта взаємодіє з сервером Apple для отримання зашифрованого paymentToken 13. Викликається автентифікація клієнта через біометрію або пароль. 14. Apple формує paymentToken, який передається на webPage для подальшої обробки. 15. WebPage надсилає Запит проведення платежу, використовуючи отриманий токен. 16. Якщо необхідна перевірка через 3D Secure (3DS), починається цей процес. Якщо 3DS не потрібен, транзакція продовжується. 17. Гілка без 3DS: * Виконується авторизація платежу. * Формується відповідь на запит проведення платежу. 18. Гілка з 3DS: * Виконується додаткова перевірка через 3DS. * Після завершення перевірки надається відповідь на запит проведення платежу з параметром redirect3dsUrl. * webPage перенаправляє клієнта на сторінку redirect3dsUrl для підтвердження 3DS. * Клієнт підтверджує транзакцію через 3DS. * Транзакція авторизується. 19. Надсилається callback мерчанту, на вказаний notificationUrl, з даними про проведену транзакцію. 20. Клієнту відображається сторінка результату, яка інформує про завершення оплати.
# Запит підтримки aPay на сторінці Необхідно виконати скрипт для перевірки підтримки оплати за допомогою Арау на сторінці ```javascript if (!window.ApplePaySession || !window.ApplePaySession?.canMakePayments?.()) { return
Apple Pay is not supported on this device
; } ``` # Запит отримання данних мерчанта aPау {{url}}/ecom/jws/payments/merchant/get\_v1 Запит для отримання мерчантом даних та налаштувань аРау мерчанта Опціональний запит. Можливий hard-coded данних аРау на стороні мерчанта ### Вхідні параметри частини payload JWS : | Параметр | Опиc | Формат даних | Приклад | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ | | merchantCapabilities | визначає, які можливості підтримує мерчант для обробки платежів через Apple Pay | object | supports3DS, supportsCredit, supportsDebit | | supportedNetworks | визначає список платіжних мереж (типів карток), які підтримуються мерчантом для обробки платежів через Apple Pay. | object | visa, masterCard | | countryCode | дволітерний код країни (згідно зі стандартом ISO 3166-1 alpha-2), де буде здійснено транзакцію через Apple Pay. | string | UA | | currencyCode | визначає валюту, в якій буде здійснено платіж через Apple Pay. Трилітерний код валюти згідно зі стандартом ISO 4217. | string | UAH | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { } ```
JWS Payload — тіло відповіді перед підписанням ```json { "merchantCapabilities": [ "SUPPORTS_3DS" ], "supportedNetworks": [ "VISA" ], "countryCode": [ "UA" ], "currencyCode": "UAH" } ```
# Запит валідації мерчанта Запит через сервер проксі до сервера apple pay для отримання валідації мерчанта `fetchAppleSessionAPI` та `purchaseApplePayAPI` - функції які викликають API, використовуйте свої функції для роботи з апі, або `fetch` Нижче описано приклад обробника події кліку на кнопку оплати через ApplePay: ```javascript const onApplePayButtonClicked = async () => { // Додаткова перевірка на те чи підтримує браузер епл пей if (!window.ApplePaySession) { return; } // Обʼєкт для створення сесії const request = { countryCode: 'UA', currencyCode: 'UAH', merchantCapabilities: ['supports3DS'], supportedNetworks: ['visa', 'masterCard'], total: { label: 'PoC Merchant Apple Pay', // назва мерчанта type: 'final', amount: amount.toString(), // сума транзакції }, }; // Створення сесії const session = new window.ApplePaySession(3, request); session.onvalidatemerchant = async (event: any) => { try { // Виклик запиту для створення сесії https://docs.merchant.alb.ua/platizhni-metodi-h2h/applepay-encrypted/zapit-vstanovlennya-sesiyi-v-apau const response = await fetchAppleSessionAPI(event.validationURL, applePayMercantId, { deviceId, refreshToken }); session.completeMerchantValidation(response.applePaySessionData); } catch (error) { // обробка помилки запиту для створення сесії } }; session.onshippingmethodselected = () => { const newTotal = { label: 'PoC Merchant Apple Pay', // назва мерчанта type: 'final', amount: amount.toString(), // сума транзакції }; session.completeShippingMethodSelection(window.ApplePaySession.STATUS_SUCCESS, {}, newTotal); }; // подія коли користувач успішно вибрав картку для оплати session.onpaymentauthorized = async (event: any) => { const result = { status: window.ApplePaySession.STATUS_SUCCESS, }; session.completePayment(result); try { // виклик запиту проведення платежу https://docs.merchant.alb.ua/platizhni-metodi-h2h/applepay-encrypted/zapit-provedennya-platezhu const response = await purchaseApplePayAPI( { paymentToken: event.payment.token, // інші дані які потрібні для виклику } { deviceId, refreshToken, serverPublicKey } ); } catch (error) { // обробка помилки запиту для проведення платежу } }; session.begin(); }; ``` # Запит встановлення сесії в aPау Запит за допомогою якого встановлюється сесія в aPау. У відповідь повертаються токенізовані картки клієнта {{url}}/ecom/jws/payments/apple\_pay/get\_session\_v1 ### Вхідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Обов'язковіть | Приклад | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- | ---------------------------------------------------------------------------- | | validationUrl | URL-адреса, на яку Apple надсилає запит для валідації сесії платежу | string(1000) | Так | [apple-pay-gateway.apple.com](http://apple-pay-gateway.apple.com/) | | merchantId | apple merchant identifier. параметр отримуєте від банка | string(255) | Так | YN\_O1aEEFqF6Jal4B5qHy7b7 | | domain | доменне ім'я (URL), яке використовується для авторизації | string(255) | Так | [checkout.develop.bankalliance.ua](http://checkout.develop.bankalliance.ua/) | | merchantRequestId |

унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектом

| string(50) | Так | merchantRequestId\_cfc297a1e1e91 | ### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------- | | applePaySessionData | | object | | | epochTimestamp | час початку дії сесії (у мілісекундах) | string | 2024-09-30T15:06:05.274+03:00 | | expiresAt | час закінчення дії сесії (у мілісекундах) | string | 2024-09-30T16:06:05.274+03:00 | | merchantSessionIdentifier | ідентифікатор сесії мерчанта | string | SSHB8FD6B91EB2B4C909990AE16F652A8BB\_BB8E.. | | nonce | унікальний токен, який використовується для безпеки | string | 0162edba | | merchantIdentifier | ідентифікатор зареєстрованого мерчанта | string | C20AFFF8FC4092AB90F781FFA08E5C49.. | | domainName | доменне ім'я, де була ініційована сесія | string | checkout.develop.bankalliance.ua | | displayName | ім'я мерчанта, яке буде відображене | string | merchant.aliiancebank.ua | | signature | підпис, який використовується для підтвердження дійсності сесії | string | 308006092a864886f70d010702a080308002010.. | | merchantRequestId |

унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектом

| string | merchantRequestId\_cfc297a1e1e91 | | applePaySessionId | ідентифікатор сесії Apple Pay | string | f40b099c-38f3-46f9-a989-52818018f557 | ### Приклади:
JWS Payload — тіло запиту перед підписанням ```json { "merchantId": "YN_O1aEEFqF6Jal475qHy7b7", "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "merchantRequestId": "merchantRequestId_cfc297a1e1e91", "domain": "checkout.develop.bankalliance.ua" } ```
JWS Payload — тіло відповіді перед підписанням ```json { "applePaySessionData": { "epochTimestamp": "2024-09-30T15:06:05.274+03:00", "expiresAt": "2024-09-30T16:06:05.274+03:00", "merchantSessionIdentifier": "SSHB8FD6B91EB2B4C52A8BB_BB8E62003687F8FCC159B2B83AAFC02DB625F1F1E3997CCC2FE2CFD11F636558", "nonce": "016edba", "merchantIdentifier": "C20AFFF8FC4092AB90F781FFA08E5C49434674F64EB2A187A7FE3094EB1C8EF5", "domainName": "checkout.develop.bankalliance.ua", "displayName": "merchant.aliiancebank.ua", "signature": "308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a003020102020816634c8b0e305717300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3234303432393137343732375a170d3239303432383137343732365a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020349003046022100c6f023cb2614bb303888a162983e1a93f1056f50fa78cdb9ba4ca241cc14e25e022100be3cd0dfd16247f6494475380e9d44c228a10890a3a1dc724b8b4cb8889818bc308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018730820183020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020816634c8b0e305717300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3234303933303132303630355a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d010904312204204d17711f18e7059ad3384feba35ac718f0f948cdcce8c32126d4508ef685bf55300a06082a8648ce3d04030204463044022027a6f4b471800884326cb9c69705f3d05ba840086c7ef87b7b11014252e2acd30220539dca31d5847a8db531a210cc49f833a04ce7fd39fa64eb1d5d607384183078000000000000" }, "merchantRequestId": "merchantRequestId_cfc297a1e1e91", "applePaySessionId": "f45b099c-38f3-46f9-a989-52818018f557" } ```
# Запит проведення платежу {{url}}/ecom/jws/payments/apple\_pay/token/purchase\_v1 ### Вхідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Обов'язковість | Приклад | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Об’єкт **paymentToken** | | object | Так | | | Об'єкт **paymentData** | | object | Так | | | data |

зашифрований блок даних, який містить деталі платіжної картки, інформацію про транзакцію, суму, валюту тощо

| string | Так | CLtkH05O6bkhXkEdN/0LGtJQGeNT+9PMDp... | | transactionIdentifier | унікальний ідентифікатор транзакції, який генерується Apple Pay для кожного платежу | string | Так | 2d4921ff56bf979b76c53b3... | | signature | підпис, який підтверджує, що дані в полі `data` не були змінені після шифрування | string | Так | MIAGCSqGSIb3DQEHAqCAMIACA... | | version |

версія формату paymentData, яка вказує на специфікацію Apple Pay для зашифрованих даних.

| string | Так | EC\_v1 | | Об'єкт **header** | | object | Так | | | publicKeyHash | хеш відкритого ключа мерчанта, який підтверджує, що дані були зашифровані для конкретного мерчанта | string | Так | 1LSYfOslX5QlRIUAidZju... | | applicationData | додаткові дані, які мерчант хоче передати разом із запитом на оплату | string | Ні | | | wrappedKey | зашифрований симетричний ключ, який використовується для додаткового захисту платіжних даних | string | Ні | MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8... | | ephemeralPublicKey | тимчасовий відкритий ключ, який використовується для шифрування даних | string | Так | MFkwEwYHKoZIzj0CAQYIKoZI.. | | transactionId | унікальний ідентифікатор транзакції | string | Так | 2d4921ff56bf979b76c53b3a.. | | Об'єкт **paymentMethod** | | object | Так | | | displayName | ім'я мерчанта, яке відображається користувачу під час проведення платежу | string | Так | Merchant 5538 | | network | платіжна мережа, яка використовується для транзакції | string | Так | visa, masterCard | | type | тип транзакції, який визначає, як проводиться платіж | string | Так | debit, credit | | Додаткові дані для проведення платежу | | object | | | | merchantRequestId | унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектом | string(36) | Так | 137d9304-0368-11ed-b939-0242ac120002 | | merchantId | Id мерчанту згенерований в Єкомі | string(36) | Так | 137d9304-0368-11ed-b939-0242ac120002 | | desiredThreeDSMode | Ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string (50) | Так | За замовчуванням SHOULD | | resultRedirectUrl | Url для редиректа клієнта після проходження 3DS аутентифікації | string (1000) | Ні | [![](https://docs.merchant.alb.ua/~gitbook/image?url=https%3A%2F%2Fsupport.google.com%2Ffavicon.ico\&width=300\&dpr=4\&quality=100\&sign=ae88f641\&sv=1)Google Help](https://support.google.com/) | | notificationUrl | url, на який буде відправлено CallBack | string (1000) | Ні | [https://merchant.notification\_url](https://merchant.notification_url/) | | notificationEncryption | ознака криптування данних CallBack | string | Ні |

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | date | дата та час платежу | string | Так | {{currentdateT}}.00+00:00 | | comment | додаткова опис операції яку заповнює клієнт мерчанта | string (1000) | Ні | ///5555.25412 | | purpose | призначення платежу яке заповнює мерчант | string (255) | Ні | За товар | | merchantComment | додаткова інформація\коментар мерчанта по замовленню |

tring(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

| Ні | merchant Comment id 1258728c1 | | customerData | об'єкт з customer даними | object | Так | | | senderCustomerId | Id клієнта відправника | string (255) | Так | 1258728c1 | | senderFirstName | ім'я відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іваненко | | senderLastName | прізвище відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іван | | senderMiddleName | по-батькові відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іванович | | senderEmail | пошта відправника | string (256) | Ні | | | senderСountry | країна відправника | string (3) ISO 3166, 804 (Ukraine) | Ні | 804 | | senderRegion | область відправника | string (255) | Ні | Київська | | senderСity | місто відправника | string (25) | Ні | Київ | | senderStreet | вулиця відправника | string (35) | Ні | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string (255) | Ні | 23 | | senderItn | іпн відправника | string (20) | Ні | 123456789 | | senderPassport | паспорт відправника | string (255) | Ні | АН123456 | | senderIp | space.vars.senderIP\_description | string (50) | Ні | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string (20) | Ні | 380630000000 | | senderBirthday | день народження відправника | string (50) | Ні | 31.12.2000 | | senderGender | Гендер відправника | string (50) | Ні | Male/Female | | senderZipCode | індекс відправника | string (50) | Ні | 49000 | ### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json "paymentToken": { "paymentData": { "data": "CLtkH05O6bkhXkEdN/0LGtJQGeNT+9PMDpC0oITlXse1wZby4EtRwNhWz5Cp12ZjKGvsVX0aHeNsyULl8ca3fbVdaYA6b6MGQ7oPBVVyecRo0dl3p8Xhm5oHx9NcI+KTgx2oAZAGxylAAVADKFhYY0xo81yPm8KIhnv8rsKmCyL3d/Vhmlznfr7HgkmmXVhF/YoMp1FDdO6SWQkQBbM8Bu30DQBxPKJAHWGhWTBx8ufWKx+P7ErP2dROhQbFKZEtAvpNOS1o4CV5l4lLfNjiRb+QO85aPbbp80ohD6D9xjCP30lpP8JnWsJIBB3p158SId4Fz95152cvpirqZkOinCfHMLPM371Ent9e50UjQj20d4HVkV6XfwZpRUj8/UYFcemqG+w/VNp7WUFePA==", "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCBZjTIsOMFcXMAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yNDA0MjkxNzQ3MjdaFw0yOTA0MjgxNzQ3MjZaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAxvAjyyYUuzA4iKFimD4ak/EFb1D6eM25ukyiQcwU4l4CIQC+PNDf0WJH9klEdTgOnUTCKKEIkKOh3HJLi0y4iJgYvDCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIIFmNMiw4wVxcwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI0MDkyNTE0NTIxMFowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIBpIgKQboEHgDkNYiHuoxqtps5oRjZAr/0YLZmSz2pq6MAoGCCqGSM49BAMCBEgwRgIhAIkjGYfkIWMHGQ4y3xMqF3qvRKc2KwWaqBuTaf8iSlmvAiEAje5izLs9ItZTUCob80n+W3/oOQD0MmdrbIU75mztQ6YAAAAAAAA=", "header": { "publicKeyHash": "1LSYfOslX5QlRIUAidZjuXuz3w3KHgpnF7RZXPOPAbc=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAECWpX1FFd7LTXechNBSUtq9OVotLI1zCSgdr5fUWYVt4hJpl1qFSIPPOpbtOhhugrF+ZmZVvbmUe9gNscRUHOtw==", "transactionId": "2d4921ff56bf979b76c53b3a6f79125883546ace6548889a0468209741cc0f33" }, "version": "EC_v1" }, "paymentMethod": { "displayName": "MasterCard 5538", "network": "MasterCard", "type": "debit" }, "transactionIdentifier": "2d4921ff56bf979b76c53b3a6f79125883546ace6548889a0468209741cc0f33" }, "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://www.google.com.ua/?hl=ru", "resultRedirectUrl": "https://www.google.com.ua/?hl=ru", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "d7e27615-4357-4647-a9b8-3488d48be594", "date": "2024-09-25 18:54:37.00+03:00", "customerData": { "senderCustomerId": "1231234124142", "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" } } } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "PURCHASE", "rrn": null, "purpose": "назначение", "comment": "комент", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": null, "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 35, "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": null, "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 } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "PURCHASE", "rrn": null, "purpose": "назначение", "comment": "комент", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": null, "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 35, "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": null, "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 } ```

# GooglePay™ decrypted GooglePay™ API ## Для мерчанта: #### 1.Налаштовувати GooglePay™ до веб-сайту, по інструкціям, розміщених за посиланнями: Документація: [https://developers.google.com/pay/api/web
](https://developers.google.com/pay/api/web)Вимоги з брендування: #### 2.При оплаті клієнтом послуги, розшифрувати об'єкт [CARD](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#card) за допомогою [PublicKey](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#step-two) та [PrivateKey](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#step-three) Приклад картки: ```json { "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "PAN_ONLY", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2025 }, "gatewayMerchantId": "some-merchant-id", "messageId": "some-message-id", "messageExpiration": "1759309000000" } Приклад криптованого PAN: { "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "CRYPTOGRAM_3DS", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2025, "cryptogram": "AAAAAA...", "eciIndicator": "5" }, "messageId": "some-message-id", "messageExpiration": "1759309000000" } ``` #### 3.Об’єкт paymentData який описаний в пункті 2, необхідно закриптувати платіжним ключем # PURCHASE # Запит проведення purchase Крок 1 {{url}}/ecom/jws/payments/google\_pay/purchase\_v3 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
Об'єкт PaymentData (шифрування зі сторони мерчанта )
paymentMethodТип платіжних облікових даних. Наразі CARD підтримується лишеstringТакCARD
authMethod

Спосіб аутентифікації карткової операції.

PAN_ONLY - PAN картки

CRYPTOGRAM_3DS - криптованний PAN

stringТакCRYPTOGRAM_3DS
panНомер особового рахунку, що стягується. Цей рядок містить лише цифри.stringТак1111222233334444
expirationMonthМісяць закінчення терміну дії картки, де 1 означає січень, 2 означає лютий і так далі.numberТак10
expirationYearЧотиризначний рік закінчення терміну дії картки, наприклад 2020.numberТак2025
cryptogramКриптограма 3-D Secure.stringНіAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorЦей рядок не завжди присутній. Він повертається лише для транзакцій із автентифікованими маркерами пристроїв на Androidstring(1)Ні4
messageIdУнікальний ідентифікатор, який ідентифікує повідомлення на випадок, якщо його потрібно буде відкликати або знайти пізніше.stringНіsome-message-id
messageExpirationДата й час закінчення терміну дії повідомлення в мілісекундах UTC з епохи. Інтегратори повинні відхиляти будь-які повідомлення, термін дії яких минув.stringНі1759309000000
Додаткові стандартні об'єкти для проведення Purchase
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
transactionAmountСума платежу в копійкахstringТак2000
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+03:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі в системі ACS | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```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" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```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 } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```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 } ```
# Запит проведення purchase Крок 2 (3DS) {{url}}/ecom/jws/payments/google\_pay\_3ds/purchase\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузераobjectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запитуstringТак, якщо операція потребує 3DStext/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DSMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DSen-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS1280
browserTZTimezone браузераstringТак, якщо операція потребує 3DS-180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням 
{
    "operationId": "1702047427621BHu5X99yDbA",
    "browserInfo": {
        "browserAcceptHeader"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36",
        "browserLanguage": "en-US,en",
        "browserColorDepth": "24",
        "browserScreenHeight": "800",
        "browserScreenWidth": "1280",
        "browserTZ": "-180"
    },
    "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
    "date": "{{currentdateT}}.00+00:00"
}
JWS Payload — тіло відповіді перед підписанням ```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": "PENDING", "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 } ```
# C2A # Запит проведення C2A Крок 1 {{url}}/ecom/jws/payments/google\_pay/card\_to\_account\_v3 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
Об'єкт PaymentData (шифрування зі сторони мерчанта)
paymentMethodТип платіжних облікових даних. Наразі CARD підтримується лишеstringТакCARD
authMethod

Спосіб аутентифікації карткової операції.

PAN_ONLY - PAN картки

CRYPTOGRAM_3DS - криптованний PAN

stringТакCRYPTOGRAM_3DS
panНомер особового рахунку, що стягується. Цей рядок містить лише цифри.stringТак1111222233334444
expirationMonthМісяць закінчення терміну дії картки, де 1 означає січень, 2 означає лютий і так далі.numberТак10
expirationYearЧотиризначний рік закінчення терміну дії картки, наприклад 2020.numberТак2025
cryptogramКриптограма токена.stringНіAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicator

Цей рядок не завжди присутній. Він повертається лише для транзакцій із автентифікованими маркерами пристроїв на Android (CRYPTOGRAM_3DS).

Це значення має передаватися в процесі обробки платежу.

string (1)Ні4
messageIdУнікальний ідентифікатор, який ідентифікує повідомлення на випадок, якщо його потрібно буде відкликати або знайти пізніше.stringНіsome-message-id
messageExpirationДата й час закінчення терміну дії повідомлення в мілісекундах UTC з епохи. Інтегратори повинні відхиляти будь-які повідомлення, термін дії яких минув.stringНі1759309000000
Додаткові стандартні об'єкти для проведення Purchase
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
transactionAmountСума платежу в копійкахstringТак2000
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+02:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі2900000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | [creqForm](https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA) | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "paymentData": "{{encryptedPaymentData}}", "merchantRequestId": "{{requestUUIDT}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "resultRedirectUrl": "", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "currencyCode": "980", "transactionAmount": "100", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": "410213187859", "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "17128431233853bBBN9JV2NG", "ecomOperationId": "60ae2b45-995a-42c4-bdf5-76e3e8c2a85b", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "42840103-507e-4541-857d-d66f3ae52332", "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": "C2A", "notificationUrl": "https://webhook.site/55533b14-b72b-4d6b-b9bc-1906103240ba", "paymentServiceType": "GOOGLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": 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, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712843252781OgXAcDp-0Gn", "ecomOperationId": "ec2ce45b-9a97-4507-980a-f8249e9ef84f", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "a8fec362-b5ed-42c7-b2fd-c89e9d0ec508", "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": "C2A", "notificationUrl": "https://webhook.site/cbf8c83a-ee1e-47c6-899c-eca5731ff084/mock", "paymentServiceType": "GOOGLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "b6c35fdb-28c1-454d-a2f3-51098c26bda4", "redirect3dsUrl": null, "recipientAccount": 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, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
# Запит проведення c2a Крок 2 (3DS) {{url}}/ecom/jws/payments/google\_pay\_3ds/card\_to\_account\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузераobjectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запитуstringТак, якщо операція потребує 3DStext/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DSMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DSen-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS1280
browserTZTimezone браузераstringТак, якщо операція потребує 3DS-180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "operationId": "1705414311419tEIgRRDZSLm", "browserInfo": { "browserAcceptHeader":", "browserUserAgent": "", "browserLanguage": "", "browserColorDepth": "", "browserScreenHeight": "", "browserScreenWidth": "", "browserTZ": "" }, "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712843252781OgXAcDp-0Gn", "ecomOperationId": "ec2ce45b-9a97-4507-980a-f8249e9ef84f", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "a8fec362-b5ed-42c7-b2fd-c89e9d0ec508", "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": "C2A", "notificationUrl": "https://webhook.site/cbf8c83a-ee1e-47c6-899c-eca5731ff084/mock", "paymentServiceType": "GOOGLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "b6c35fdb-28c1-454d-a2f3-51098c26bda4", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712843252781OgXAcDp-0Gn", "recipientAccount": 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, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ```
# GooglePay™ encrypted
# Докуменація GooglePay™ ## Етап 1. **Ознайомлення** Перед початком роботи з Google Pay™ API варто детально ознайомитися з офіційною документацією. Вона містить вимоги до використання сервісу, керівництва з інтеграції та контрольний список для перевірки коректності підключення. 1. [Для розробників мобільних додатків](https://developers.google.com/pay/api/android/overview): містить інформацію про правила використання Google Pay™ API, бренду Google Pay™, [посібник користувача ](https://developers.google.com/pay/api/android/guides/brand-guidelines?hl=ru)та [контрольний список інтеграції](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist?hl=ru). 2. [Для розробників вебсайтів](https://developers.google.com/pay/api/web/overview?authuser=0): включає правила застосування Google Pay™ API та його брендовані елементи, [посібник користувача](https://developers.google.com/pay/api/web/guides/brand-guidelines?hl=ru) та [контрольний список інтеграції](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist?hl=ru). [Для коректної інтеграції Google Pay™ API та отримання PaymentData ](https://developers.google.com/pay/api/web/guides/tutorial?authuser=0\&hl=ru)у ваш сайт або додаток необхідно: * Використовувати вебсторінку з HTTPS-протоколом і дійсним TLS-сертифікатом. * Налаштувати параметри: * allowPaymentMethods : CARD * tokenizationSpecification = { "type": "PAYMENT\_GATEWAY" } * allowedCardNetworks = \['MASTERCARD', 'VISA'] * allowedCardAuthMethods = \['PAN\_ONLY', 'CRYPTOGRAM\_3DS'] * gateway = timeproject * gatewayMerchantId — унікальний ідентифікатор магазину, що видається при підключенні до платіжного шлюзу AllianceBank. 3DS-верифікація для PAN\_ONLY виконується за замовчуванням. ## Етап 2. **Інтеграція вашого сайту або додатка з** Google Pay™ API **з платіжним шлюзом Alliance Bank** Якщо інтеграція виконана коректно, на сторінці вашого сайту або у додатку відобразиться кнопка оплати. При натисканні користувач побачить спливаюче вікно з вибором картки, прив'язаної до облікового запису Google™. **Приклад параметрів, які повертає Google Pay™ API описані в запиті:** [**Запит проведення платежу** ](https://app.gitbook.com/o/zBSkiJ3Oy2kvtv30JbMh/s/djW26z83WQoOq0ZjunWw/~/changes/129/platizhni-metodi-h2h/googlepay-encrypted/zapit-provedennya-platezhu) ## Етап 3. Активація способу оплати Google Pay™ для магазину та користувача * Якщо ваш інтернет-магазин вже інтегрований з Alliance Bank, зверніться до менеджера або напишіть запит на email: `ecom.support@bankalliance.ua` * Якщо інтеграція з Alliance Bank ще не виконана, також зверніться за вказаною електронною адресою `ecom.support@bankalliance.ua` ## Етап 4. Обробка даних із параметру **"token"** Є два способи обробки отриманого `token`: 1. **Розшифровка на стороні магазину** — дані розшифровуються перед передачею в Alliance Bank. 2. **Розшифровка на стороні Alliance Bank** — дані у незмінному вигляді передаються до Alliance Bank. Для розшифровки [paymentData](https://developers.google.com/pay/api/web/guides/tutorial) Google™ рекомендує використовувати бібліотеку [**Tink**](https://github.com/google/tink). [Опис використання бібілотеки Tink](https://developers.google.com/pay/api/processors/guides/implementation/using-tink) ## Етап 5. Перевірте відповідність інтеграціі по чек листу * Ознайомтесь з [контрольним списком](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) та переконайтесь що всі етапи інтеграції сторінки оплати виконані. * Ознайомтесь з [контрольним списком](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) і переконайтесь, що інтеграція Android-додатку відповідає вимогам. ## Етап 6. Запит доступу до робочої версії від спеціалістів Google**™** * Подайте запит на доступ [для сайту](https://developers.google.com/pay/api/web/guides/test-and-deploy/request-prod-access?hl=ru). * Подайте запит на доступ [для Android-додатку](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access?hl=ru). *** *** # Запит підтримки GooglePay™ на сторінці Для того, щоб підключити Google Pay™ на сторінку потрібно: 1. Підключити скрипт на сторінку: ```javascript ``` 2. Вставити наступний скріпт на сторінку (функція onGooglePayLoaded має запуститись після завантаження pay.js): ```javascript const baseRequest = { apiVersion: 2, apiVersionMinor: 0, }; const allowedCardNetworks = ["MASTERCARD", "VISA"]; const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"]; const tokenizationSpecification = { type: "PAYMENT_GATEWAY", parameters: { gateway: "timeproject", // TODO: вказуємо потрібний gateway gatewayMerchantId: "123123123123324", // TODO: вказуємо потрібний merchantId }, }; const baseCardPaymentMethod = { type: "CARD", parameters: { allowedAuthMethods: allowedCardAuthMethods, allowedCardNetworks: allowedCardNetworks, }, }; const baseCardPaymentMethod = { type: "CARD", parameters: { allowedAuthMethods: allowedCardAuthMethods, allowedCardNetworks: allowedCardNetworks, assuranceDetailsRequired: true }, }; const cardPaymentMethod = Object.assign({}, baseCardPaymentMethod, { tokenizationSpecification: tokenizationSpecification, }); let paymentsClient = null; function getGoogleIsReadyToPayRequest() { return Object.assign({}, baseRequest, { allowedPaymentMethods: [baseCardPaymentMethod], }); } function getGooglePaymentDataRequest() { const paymentDataRequest = Object.assign({}, baseRequest); paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod]; paymentDataRequest.transactionInfo = getGoogleTransactionInfo(); paymentDataRequest.merchantInfo = { merchantId: "12345678901234567890", // TODO: вказуємо потрібний merchantId merchantName: "Example Merchant", // TODO: вказуємо потрібний merchantName }; return paymentDataRequest; } function getGooglePaymentsClient() { if (!paymentsClient) { paymentsClient = new google.payments.api.PaymentsClient({ environment: "TEST", }); } return paymentsClient; } function onGooglePayLoaded() { const paymentsClient = getGooglePaymentsClient(); paymentsClient .isReadyToPay(getGoogleIsReadyToPayRequest()) .then(function (response) { if (response.result) { addGooglePayButton(); } }) .catch(function (err) { console.error(err); }); } function addGooglePayButton() { const paymentsClient = getGooglePaymentsClient(); const button = paymentsClient.createButton({ onClick: onGooglePaymentButtonClicked, allowedPaymentMethods: [baseCardPaymentMethod], }); document.getElementById("container").appendChild(button); } function getGoogleTransactionInfo() { return { countryCode: "UA", currencyCode: "UAH", totalPriceStatus: "FINAL", totalPrice: "1.00", // TODO: вказуємо потрібну ціну }; } function prefetchGooglePaymentData() { const paymentDataRequest = getGooglePaymentDataRequest(); paymentDataRequest.transactionInfo = { totalPriceStatus: "NOT_CURRENTLY_KNOWN", currencyCode: "UAH", }; const paymentsClient = getGooglePaymentsClient(); paymentsClient.prefetchPaymentData(paymentDataRequest); } function onGooglePaymentButtonClicked() { const paymentDataRequest = getGooglePaymentDataRequest(); paymentDataRequest.transactionInfo = getGoogleTransactionInfo(); const paymentsClient = getGooglePaymentsClient(); paymentsClient .loadPaymentData(paymentDataRequest) .then(function (paymentData) { processPayment(paymentData); }) .catch(function (err) { console.error(err); }); } function processPayment(paymentData) { // Далі записано приклад запиту до серверу, у запит потрібно підставити свої значення // Відправляємо запит на сервер, попередньо зашифрувавши його, у прикладі цього не вказано та виконувати запит під авторизацією // Обробка запиту не описана, через те, що на кожному проекті своя обвʼязка для виклику запитів // Звертати увагу прохання лише на структуру fetch('/ecom/execute_request/payments/v1/google_pay/token/purchase', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ "googlePayPaymentData": { ...paymentData, merchantInfo: { merchantId: '123123123123324', // TODO: вказуємо потрібний gatewayMerchantId gateway: 'timeproject' // TODO: вказуємо потрібний gateway }, }, environment: 'TEST', // або PRODUCTION coinAmount: 100, // ціна у копійках desiredThreeDSMode: 'MUST_NOT', notificationUrl: 'https://www.google.com.ua/?hl=ru', resultRedirectUrl: 'https://www.google.com.ua/?hl=ru', purpose: 'purpose', comment: 'comment', merchantId: '137d6304-0668-11ed-b939-0242ac120002', // // TODO: вказуємо потрібний merchantId merchantRequestId: uuid(), // унікальний uuid date: getCurrentDate(), // поточна дата у форматі customerData: { senderCustomerId: '34234234', senderCountry: '804', }, browserInfo: { browserAcceptHeader: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7', browserUserAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36', browserLanguage: 'ru-RU', browserColorDepth: '24', browserScreenHeight: '864', browserScreenWidth: '1536', browserTZ: '-180', }, }) }) } ``` 3. Вказати у allowedCardNetworks типи карток які підтримуються для платежу 4. У змінну tokenizationSpecification вставити відповідні gateway та gatewayMerchantId. 5. Для getGooglePaymentsClient використовувати **PRODUCTION** замість **TEST** для роботи з реальними даними 6. У функції getGooglePaymentDataRequest вказати merchantId та merchantName для paymentDataRequest.merchantInfo 7. У функції processPayment відправити токенізовані дані для обробки на сервер # Запит отримання даних мерчанта GooglePay™ {{url}}/ecom/jws/payments/google\_pay/merchant/get\_v1 Запит для отримання мерчантом даних та налаштувань GooglePay™ мерчанта Опціональний запит. Можливий hard-coded данних GooglePay™ на стороні мерчанта ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
idІдентифікатор продавця в системі gPaystring "1234567890"
gPayMerchantNameНазва торговцяstringExample Merchant
gatewayIdsId gatewaylist
countryCodeЗначення кодів країнstringUA
allowedAuthMethods

Поля, які підтримуються для автентифікації карткової транзакції.

  • PAN_ONLY: цей метод автентифікації пов’язано з платіжними картками, які зберігаються в обліковому записі Google користувача. Дані про повернений платіж містять номер особового рахунку (PAN) із зазначенням місяця закінчення терміну дії та року закінчення терміну дії.
  • CRYPTOGRAM_3DS: цей метод автентифікації пов’язаний із картками, що зберігаються як маркери пристрою Android. Повернені платіжні дані містять криптограму 3-D Secure (3DS), згенеровану на пристрої.

string["PAN_ONLY", "CRYPTOGRAM_3DS"]
allowedCardNetworks

Одна або кілька карткових мереж, які ви підтримуєте, а також підтримується Google Pay API.

  • MASTERCARD
  • VISA
string["MASTERCARD", "VISA"]
enabledОзнака активний чи не активний статс мерчанта stringtrue/false
### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { } ```
JWS Payload — тіло відповіді перед підписанням ```json { "id": "paujUKks5E7jFHdsGLgShAIZ", "gPayMerchantName": "gPayMerchantName00", "gatewayIds": [ "9ACW_gv4dRs6yLIzdW_WZUNw" ], "allowedCardNetworks": [ "MASTERCARD", "VISA" ], "allowedAuthMethods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ], "enabled": true, "countryCode": "UA" } ```
# Запит проведення платежу {{url}}/ecom/jws/payments/google\_pay/token/purchase\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
googlePayPaymentData Основний об'єкт із даними платежу Google PayJSON-об'єкт Так{ ... }
apiVersionВерсія Google Pay APIintТак2
apiVersionMinorМінорна версія APIintТак0
paymentMethodDataІнформація про платіжний методJSON-об'єктТак{ ... }
descriptionОпис платіжного методуstringТак"Mastercard •••• 9079"
infoДодаткові деталі про картуJSON-об'єктТак{ ... }
assuranceDetailsДані про верифікацію картиJSON-об'єктТак{ ... }
accountVerifiedЧи верифіковано акаунтbooleanТакtrue
cardHolderAuthenticatedЧи аутентифіковано власника карткиbooleanТакfalse
cardDetailsОстанні чотири цифри карткиstringТак"9079"
cardNetworkПлатіжна система карткиstringТак"MASTERCARD"
tokenizationDataДані про токенізаціюJSON-об'єктТак{ ... }
tokenТокен платежу string Так "{...}"
typeТип токенізації (наприклад, платіжний шлюз)stringТак"PAYMENT_GATEWAY"
merchantInfoІнформація про продавцяJSON-об'єктТак{ ... }
merchantIdІдентифікатор продавцяstringТак"1234567890"
gatewayНазва платіжного шлюзуstringТак"timeproject"
environmentСередовище для тестування або продакшнstringТак"TEST"
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
transactionAmountСума платежу в копійкахstringТак2000
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+03:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі в системі ACS | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "googlePayPaymentData": { "apiVersion": 2, "apiVersionMinor": 0, "paymentMethodData": { "description": "Mastercard •••• 9079", "info": { "assuranceDetails": { "accountVerified": true, "cardHolderAuthenticated": false }, "cardDetails": "9079", "cardNetwork": "MASTERCARD" }, "tokenizationData": { "token": "{\"signature\":\"MEUCIQDaNH5qORDmyWCADBPPQdx0WLGzqP4l9gznr1P0C92JQIgcCC5sGVaHKcopWwx9qMQ+nJswxyk5LugcQng8cUQKPs\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/uMFvqw3uWfiJfev8mveNhiQcRSVSzqynD1jo/WAKA1iXtyyoty/uzQBbRhFmnwRxRWJvSJiVe8Q3aMEePajgA\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1732261522591\\\"}\",\"signatures\":[\"MEUCIEr2AORUfr3tThPtgNAmtXX3kMXlxqQE5HfzFf/qCt5FAiEArM2taQdIa+t2ug2GxaXo7so9CcVSAXe5vfo/AATvHuU\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"jOTMB2WrbkP7mV2PzNrz8TDM0vgoyfLfL5MoqkfyzNP1bSr5agnuxaTOH6zdUVNcqM1tI45H8/vZvMA7Atqk05iUteWMbMS8jcHdwbOXqXdHAmK2keUBJ1+WltKDfdcldTqRCVUbkb2zEOPS9O7x97EKshGcdOFMgy3rWkSDHOGYI2iU4fcu780LkZ2S9qOiQxugF77HyWF+R6eY6YONMftw1dbyLlifz1NQkRqiVuWZfY1haBFS54P23PTPg/z8LEndY/34DoHSPbErxtaweu5mzZmFhCvaNSurjdUQSG9ZnrRFS4sBsMDkdnKgtuDl/Dp8DWoKDGQ5N1KQHK6I429r5HQzGvZI/mpLGXjLS/IqKPYail0xFbQt/sKKJWslMuzgtPLdwOGJOaC3EiS9ASy7Xwjfsy8kmZiCMH0J6XFbDQPW1nYupMkCNmQbmV0xUhkPX1meGmJ/gGYw+r/c6NtQfBoU+pfaQUOuMPU5swdlArtCdfKve0NkPTgvXErz6sLwB/WTv1iWknescQC2skne7d3KUE5dQsUIKWDtlbStAZwHfRC9SrhqA9OF8Q\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BCWiEFk24pBKXyporPbi4AAqbKJNa9kV1XDAwJHxCkyDFwZaGKzdpgFfuOVXgZTOREohQXSowPvp+7Cf9Zq9xTI\\\\u003d\\\",\\\"tag\\\":\\\"7aO3dd8BrbM0xYGd8rlAdOEeUiT+vXYxCXedIM9nw/w\\\\u003d\\\"}\"}", "type": "PAYMENT_GATEWAY" }, "type": "CARD" }, "merchantInfo": { "merchantId": "1234567890", "gateway": "timeproject" } }, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "environment": "TEST", "resultRedirectUrl": "137d9304-0368-11ed-b939-0242ac120002", "notificationEncryption": false, "notificationUrl": "https://eocfzhqbfuebmke.m.pipedream.net", "merchantRequestId": "1df6672b-d198-469d-88ce-6dab74d7feb2", "coinAmount": 1000, "customerData": { "senderCustomerId": "34234234", "senderCountry": "234" }, "comment": "comment", "purpose": "purpose", "desiredThreeDSMode": "MUST_NOT", "date": "2024-11-15 14:13:50.00+03:00", "merchantComment": "resultRedirectUrl", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtmlxml,application/xml;q=0.9,image/avif,imagewebp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,like,Gecko)Chrome/87.0.4280.66Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" } } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```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 } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ```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 } ```
\ ​ # Preauthorization and completion # Запит проведення Preauth Крок 1 {{url}}/ecom/jws/payments/preauth/create\_v1 #### **Вхідні параметри:**
ПараметрОпиcФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак, якщо paymentMethodType = CARD5573670000000304 (розшифрований вигляд)
typeTokenознака створення токену та його тип для paymentMethodType = CARDstringНі, по замовчуванню NO_TOKEN
  • NO_TOKEN,
  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
tokenтокен карткиstringТак, якщо paymentMethodType = TOKENTRXjqdJDr-4nA0jkSGfDFoe2
cvvзашифрованний cvvstringТак, якщо paymentMethodType = TOKEN{{cvv}}
paymentTokenоплата по закриптованному токену aPayobjectТак, якщо paymentMethodType = APPLE_PAY_ENCRYPTED{{paymentToken}}
paymentDataEncryptedоплата по розкриптованному токену aPay або gPayobjectТак, якщо paymentMethodType = APPLE_PAY_DECRYPTED або GOOGLE_PAY_DECRYPTED{{paymentDataEncrypted}}
googlePayPaymentDataоплата по закриптованному токену gPayobjectТак, якщо paymentMethodType = GOOGLE_PAY_ENCRYPTED{{googlePayPaymentData}}
environmentсередовищеstringТак, GOOGLE_PAY_ENCRYPTEDTEST/PRODUCTION
coinAmountсума платежу в копійках string

Ні, якщо paymentMethodType =

APPLE_PAY_ENCRYPTED

APPLE_PAY_DECRYPTED

2000
paymentMethodTypeознака, що визначає тип платіжного методу, через який здійснюється Preauth.enumТак, якщо параметр не вказано то по замовчванні CARD

  1. CARD - по номеру карти з послідуючою генерацією токену в нашій системі
  2. TOKEN - по токену згенерованному в нашій системі
  3. APPLE_PAY_ENCRYPTED
  4. APPLE_PAY_DECRYPTED
  5. GOOGLE_PAY_ENCRYPTED
  6. GOOGLE_PAY_DECRYPTED
txnType

під тип транзакціі

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

enumНіМожливі значення: NONCVV/noncvv
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

preAuthExpDate

Дата та час закінчення дії преавторизації.

Цей параметр визначає момент, до якого преавторизована сума залишається заблокованою на картці клієнта. Після настання вказаної дати система автоматично виконає реверс по операції, якщо вона не була завершена раніше.

  • Значення має бути не менше ніж на 2 години пізніше від дати створення операції
  • Значення має бути не більше ніж на 28 днів пізніше від дати, переданої в запиті

string

Так{{currentdateT}}.00+00:00
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
customerDataоб'єкт з customer даними objectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника string (30)

Ні

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
Іваненко
senderLastNameпрізвище відправникаstring (30)

Ні

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
Іван
senderMiddleNameпо-батькові відправникаstring (30)

Ні

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
Іванович
senderEmailпошта відправника string (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeІндекс відправникаstring (50)Ні 49000
#### **Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | PREAUTH | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 195 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | preAuthExpDate | Дата та час закінчення дії преавторизації. | string | 2025.10.07 14:27:00.000 | #### Приклад тіла запиту paymentMethodType = CARD ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "encryptedCardNumber": "{{encryptedPanT}}", "coinAmount": 1000, "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://webhook.site/5ec0db94-bce6-41a2-9216-08de60ab7822", "notificationEncryption": true, "date": "{{currentdateT}}.00+02:00", "preAuthExpDate": "2026-07-17 19:19:26.00+02:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "1234", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` #### Приклад тіла запиту paymentMethodType = TOKEN ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "coinAmount": 100, "paymentMethodType":"TOKEN", "token":"TRXjqdJDr-4nA0jkSGfDFoe2", "cvv":"{{cvv}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://webhook.site/ff6d19be-b232-4dc8-928e-326db6bff10b", "date": "{{currentdateT}}.00+03:00", "preAuthExpDate": "2026-07-15 12:35:26.00+00:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "tesChokan102726t", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` #### Приклад тіла запиту paymentMethodType = APPLE\_PAY\_ENCRYPTED ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "coinAmount": 100, "paymentMethodType":"APPLE_PAY_ENCRYPTED", "paymentToken": { "transactionIdentifier": "aebd938f2f9b060f59a640bc1919942d65adb05e3713af2102313465a2d68b17", "paymentData": { "data": "MDvMS5yxQwWCY2ZBQc1HTAUwXLcbaKIu+l8WYNs5K+avUHFjL7K1m3AXexbczirtsPuQJzUp6GEW7YM72LHIQzZElyCjEmbn08kJdju9htcC/q5bTeqsThOZNvVukbYsFIe1nVm+00kuWA4wxD+eHWqm2OIFovTbN4tRbPq3BBnwPOsc383Wo47mJOr4q3qFQGbPnoZWfHN9dMlTVWA6XP4MNzd46VPuPyGt6uOHcS4XDXWG4ma14y81FvCHWetszIfYnkFCdwN6MPIBff83alMbK4kX9+Kcb0+gev1aVuI+v4uwU39rQmuARnmL9SnCWRQcY2Aap7B2dfgXr4cNqvqmhzwm4v+I4udipM5THWk9jKCW1YWemLCcjY5YI35u6hkT1HGufrM+MBZNYQ==", "signature": "MIAGCSqGS1b3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCBZjTIsOMFcXMAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yNDA0MjkxNzQ3MjdaFw0yOTA0MjgxNzQ3MjZaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAxvAjyyYUuzA4iKFimD4ak/EFb1D6eM25ukyiQcwU4l4CIQC+PNDf0WJH9klEdTgOnUTCKKEIkKOh3HJLi0y4iJgYvDCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIIFmNMiw4wVxcwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI2MDUxODE1NTQxN1owKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIN3AKwGMNES793ABEU2UTIjMySmYEHvfdAwzO9ewg3rgMAoGCCqGSM49BAMCBEgwRgIhAPbQWQrGicaVoyLlWDFOzrXdAs7frxT1PhMIe1h00PVjAiEA5W0EeNVihjRVRl1JgDVTOq8vL95tTVmAz5dQxzNOoBUAAAAAAAA=", "header": { "publicKeyHash": "3RA+IEMm3t+ZfpjWNxfVXsjRVamcUTGwXdp181xWCYk=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+s48S0xnNbMihR97GBCn3gTJAPpB7h4h3Hw6Ga1uZ9W9phPhQbBc/OAvgF7uCh6Tqpr91adOKIDWtRZzDQFerw==", "transactionId": "aebd928f2f8b060f59a640bc1919942d65adb05e3713af2102313465a2d68b17" }, "version": "EC_v1" }, "paymentMethod": { "type": "credit", "displayName": "MasterCard 6702", "network": "MasterCard" } }, "desiredThreeDSMode": "MUST", "notificationUrl": "https://webhook.site/ff6d19be-b232-4dc8-928e-326db6bff10b", "date": "{{currentdateT}}.00+03:00", "preAuthExpDate": "2026-07-15 12:35:26.00+00:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "tesChokan102726t", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` #### Приклад тіла запиту paymentMethodType = APPLE\_PAY\_DECRYPTED ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "coinAmount": 100, "paymentMethodType":"APPLE_PAY_DECRYPTED", "paymentDataEncrypted":"{{encryptedPaymentData}}", "desiredThreeDSMode": "MUST", "notificationUrl": "https://webhook.site/ff6d19be-b232-4dc8-928e-326db6bff10b", "date": "{{currentdateT}}.00+03:00", "preAuthExpDate": "2026-07-15 12:35:26.00+00:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "tesChokan102726t", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` #### Приклад тіла запиту paymentMethodType = GOOGLE\_PAY\_ENCRYPTED ```json { "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "coinAmount": 100, "paymentMethodType": "GOOGLE_PAY_ENCRYPTED", "environment": "TEST", "googlePayPaymentData": { "apiVersion": 2, "apiVersionMinor": 0, "paymentMethodData": { "description": "Test Card: Visa •••• 1111", "info": { "assuranceDetails": { "accountVerified": true, "cardHolderAuthenticated": false }, "cardDetails": "1111", "cardFundingSource": "CREDIT", "cardNetwork": "VISA" }, "tokenizationData": { "token": "{\"signature\":\"MEYCIQC+gX+WIL6SvlTP2x7OX70/cCLGjKu1nbve+oxKJiFvZwIhAOFjPso1c03Br6vbSoL0MDGLLpS18yTNpfrP0DpnkkL4\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIuJ+WGM0VMSE7B3Tgdc3dTZnGCQR3fu0sp5G6yDfHnk73s7nkhBtRVnXV65dgqk3yCBAF3rpqC6dOwL1mhdNTg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1784600346590\\\"}\",\"signatures\":[\"MEQCIHMxGwiIbncetYMrRyFMBFsu7zoNGHHzmyFqQGhjqkzlAiBfFmJf1hMfRJFrCG9SMXfIke1u2lKK2drUsU2HSU+WTA\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"O/fT6x63R2cZyjC0Sf+UP7XkOx7+N3aO0t6GY/4FaO7Q1medKWbS99whcrfoWEHTLRXF3JDmqb6Ubq/WebY2LisgyPxp80cQ/tw72fq4GNsiLMUFul9WsjPfvamUlQiFPV7/1yz5a8XpcZw3+MhDZG73yDKTEeRsNiyPPMj7ur2JT/K/zvy0JP7drExZ3x7a5+LLGJMfp9G79LBb/GZw1P//SF7oIT/7XOq7OYJoCfSSX6FQhkzuGzr6o+NR7ZeEm69bBZgSSfeh1yj950hi28TI0XgXPc6STdNjsWs1+DI7pjXwYOfguUfOd364YHBjCbQyVKiCxnhJ12oTqTqgtlTIhSA+pPhzmQ3d6eaTeZ5oTKe1KpoYBd/QcPjFu5lsTeAcQBUJDURIqEef3wIIVInOgI9yeRWJuvj4FGQmH9aG0PxbErRyij5Ym2DaCnziAZGzF6ip3AcA34xR6YykAwtUYa2yTi55WrNT3yl2xz0t4OGmT4XD6b50jrqzf7IrUrHA13nMZ522oytiwiiKWDvBW7poQaWESN0Ysnozr+AD1O3XWlVMNvJ79dDnp5a3jDVx5+xuNLQ2pYm26WYU4HcDZ3dCxfQXe4cmc3DBkzdFU8laUCNIp1rZeA\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BFEDoOFurjvz2/nDIg/gnXG1fM4Mr6Dc3aUw67KnMesdf0vRxy6rblHDHtYHwqk+UizLcrMIqrCiyd+zfsxh8Wk\\\\u003d\\\",\\\"tag\\\":\\\"jC5aXNoqqtvvUVhctqc3Qo5Uq/XK9rIHDIZv2LxfEss\\\\u003d\\\"}\"}", "type": "PAYMENT_GATEWAY" }, "type": "CARD" }, "merchantInfo": { "merchantId": "Iltxpa99j20LCOZ2oU_Hw6SJ", "gateway": "timeproject" } }, "desiredThreeDSMode": "MUST", "notificationUrl": "https://webhook.site/ff6d19be-b232-4dc8-928e-326db6bff10b", "date": "{{currentdateT}}.00+03:00", "preAuthExpDate": "2026-07-15 12:35:26.00+00:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "tesChokan102726t", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` #### Приклад тіла запиту paymentMethodType = GOOGLE\_PAY\_DECRYPTED ```json {{ "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "{{$guid}}", "coinAmount": 100, "paymentMethodType": "GOOGLE_PAY_DECRYPTED", "environment": "TEST", "paymentDataEncrypted":"{{encryptedPaymentData}}", "desiredThreeDSMode": "MUST", "notificationUrl": "https://webhook.site/ff6d19be-b232-4dc8-928e-326db6bff10b", "date": "{{currentdateT}}.00+03:00", "preAuthExpDate": "2026-07-15 12:35:26.00+00:00", "merchantComment": "mezzzmezzzme", "comment": "AAAAfasfsfsfAAAAf", "purpose": "AAAAfasfsfsfAAAAfasAA", "resultRedirectUrl": "https://support.google.com/websearch/answer/463?hl=ru", "customerData": { "senderCustomerId": "tesChokan102726t", "senderLastName": "senderLastName", "senderEmail": "aaaa@gmail.com", "senderFirstName": "senderFirstName", "senderMiddleName": "senderMiddleName", "senderRegion": "senderRegion", "senderCountry": "804", "senderAdditionalAddress": "senderAdditionalAddress", "senderStreet": "senderStreet", "senderCity": "senderCity", "senderIp": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "senderBirthday": "20000110", "senderGender": "Female", "senderZipCode": "12345", "senderPassport": "passport", "senderItn": "5555555", "senderPhone": "5555" } } ``` **Приклад тіла відповіді без 3DS** ```json { "type": "PREAUTH", "rrn": null, "purpose": "LLopo", "comment": "RRRR", "coinAmount": 100, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712822786872mHQm6XSmmKt", "ecomOperationId": "2bbd1b87-9a07-41cc-9789-48d8895b3cf1", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 195, "merchantRequestId": "e2980c5e-cddc-4ccf-be36-47ef8c73da84", "transactionCurrency": "980", "merchantCommission": null, "createDateTime": "2024.09.19 15:29:25.675", "modificationDateTime": "2024.09.19 15:29:25.675", "transactionResponseInfo": { "actionCode": null, "responseCode": null, "description": null }, "bankCode": null, "paymentSystem": null, "productType": "PURCHASE", "preAuthExpDate": "2025-10-07 14:27:00.00+03:00", "notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d", "paymentServiceType": "CARD", "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 } ``` **Приклад тіла відповіді з 3DS** ```json { "type": "PREAUTH", "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": 195, "merchantRequestId": "8aa31389-fe6f-4b40-bb5e-4ecedfefb847", "transactionCurrency": "980", "merchantCommission": null, "createDateTime": "2024.09.19 15:29:25.675", "modificationDateTime": "2024.09.19 15:29:25.675", "transactionResponseInfo": { "actionCode": null, "responseCode": null, "description": null }, "bankCode": null, "paymentSystem": null, "productType": "PURCHASE", "preAuthExpDate": "2025-10-07 14:27:00.00+03:00", "notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d", "paymentServiceType": "CARD", "notificationEncryption": true, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0ce5cc44-2698-4a2c-969a-3155bad68b6e", "redirect3dsUrl": null, "txnType": "null", "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 } ``` # Запит проведення Preauth Крок 2 {{url}}/ecom/jws/payments/preauth/execute\_v1 #### **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак1697008393082nW0c1jr6KVv
encryptedCardData

термін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvv

  • Якщо в параметр TxnType передається "NONCVV\noncvv" тоді у параметрі ecnryptedCardData потрібно передати лише YYMM без CVV
  • У іншому випадку якщо в TxnType нічого не педеається, тоді у параметрі encryptedCardData піотрбно обов'язкового передавати у форматі YYMMCVV
stringТак, якщо paymentMethodType = CARD2503111 (розшифрований вигляд, у форматі YYMMCVV)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
#### **Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | PREAUTH | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 195 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | creationDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | preAuthExpDate | Дата та час закінчення дії преавторизації. | string | 2025.10.07 14:27:00.000 | #### Приклад тіла запиту ```json { "operationId": "{{operationIdT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ``` #### Приклад тіла відповіді без 3DS ```json { "type": "PREAUTH", "rrn": "410114186775", "purpose": "purpose", "comment": "comment", "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "17127594157429eggOuxH5yl", "ecomOperationId": "63feb70f-8eb0-43cc-96c3-2e2eea9cec1e", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 195, "merchantRequestId": "1d4787d6-75cb-4c75-8466-59cc698e7bbf", "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", "preAuthExpDate": "2025-10-07 14:27:00.00+03:00", "paymentServiceType": "CARD", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "txnType": "NONCVV", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` #### Приклад тіла відповіді з 3DS ```json { "type": "PREAUTH", "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": 195, "merchantRequestId": "8aa31389-fe6f-4b40-bb5e-4ecedfefb847", "transactionCurrency": "980", "merchantCommission": null, "createDateTime": "2024.09.19 15:29:25.675", "modificationDateTime": "2024.09.19 15:29:25.675", "transactionResponseInfo": { "actionCode": null, "responseCode": null, "description": null }, "bankCode": null, "paymentSystem": null, "productType": "PURCHASE", "preAuthExpDate": "2025-10-07 14:27:00.00+03:00", "notificationUrl": "https://webhook.site/6e35c4af-9af9-4212-9aa4-6a79ed6d7a0d", "paymentServiceType": "CARD", "notificationEncryption": true, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0ce5cc44-2698-4a2c-969a-3155bad68b6e", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712822536063CdDIRi8hhjq", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` # Запит проведення Completion {{url}}/ecom/jws/payments/preauth/completion\_v1 #### **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring (36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
originalOperationIdідентифікатор операції преавторизаціі.stringТак17853174998663DNdLakuczP
coinAmountсума повернення в копійкахstringТак2500
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
#### **Вихідні параметри** | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ | | type | тип транзакції | string | COMPLETION | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING

| | transactionType | тип транзакції у цифровому значенні | string | 196 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | preauthOperationId | id преавторизаціі | string | 1712843529623cHAHkmt-G5u | | preauthCoinAmount | Сума преавторизаціі | int | 100 | | preauthEcomOperationId | id в системі Еком під яким створено операцію преавторизацію | string | c25ee1cb-a052-439b-b075-bcb632615b11 | | rrnPreauth | rrn номер преавторизаціі в МПС | string | 123456789 | #### Приклад тіла запиту ```json { "merchantRequestId":"137d9304-0368-11ed-b939-0242ac120002", "originalOperationId":"17594943825392XRyx8EeK6e", "merchantId":"137d9304-0368-11ed-b939-0242ac120002", "coinAmount":"2500", "notificationUrl": "", "date": "2022-11-11 11:58:41.56+00:00" } ``` #### Приклад тіла відповіді ```json { "type":"COMPLETION", "rrn":"527612892256", "purpose":"AAAAfasfsfsfAAAAfasAA", "comment":"AAAAfasfsfsfAAAAf", "coinAmount":100, "merchantId":"137d9304-0368-11ed-b939-0242ac120002", "operationId":"17594944974293A5xR2LzpAQ", "ecomOperationId":"9ee1923c-11ce-4ac2-9917-899d499ff3d8", "status":"SUCCESS", "transactionType":196, "merchantRequestId":"e582be0c-aa5c-4991-95a3-ff3d5f53a1c6", "transactionCurrency":"980", "creationDateTime":"2025.10.03 15:28:17.399", "modificationDateTime":"2025.10.03 15:28:17.399", "transactionResponseInfo":{ "actionCode":"0", "responseCode":"00", "description":"Операція успішна" }, "productType":"PURCHASE", "notificationUrl":"https://webhook.site/95b1ded7-b86f-46cb-a771-c70f1f913d57", "paymentServiceType":"CARD", "notificationEncryption":false, "processingTerminalId":"AE001001", "processingMerchantId":"AE001001", "creatorSystem":"H2H", "rrnPreauth":"527612892256", "preauthOperationId":"17594943825392XRyx8EeK6e", "preauthCoinAmount":100, "preauthEcomOperationId":"f1a166ce-a19e-46e2-bd7c-2dc90acd1041" } ``` # REFUND {{url}}/ecom/jws/payments/refund\_v1 Поверненіня застосовується у разі необхідності повернути кошти клієнту по успішно здійсненій операції платежу. В результаті даної операції кошти будуть повернені на ту карту, з якої проводився розрахунок по оригінальній операції. ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring (36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
operationIdідентифікатор платіжної операції згенерований КБ по якій проводиться поверненняstringТак137d9304-0368-11ed-b939-0242ac120002
coinAmountсума повернення в копійкахstringТак2500
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

НІmerchant Comment id 1258728c1
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | | type | тип транзакції | string | REFUND | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string |

76 - повернення по операції Purchase
213 - повернення по операції Preauth
214 - повернення по операції Complition

| | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | originalOperationId | id під яким створено оригінальну операцію | string | 1712843529623cHAHkmt-G5u | | originalCoinAmount | Сума оригінального платежу | int | 100 | | originalEcomOperationId | id в системі Еком під яким створено оригінальну операцію | string | c25ee1cb-a052-439b-b075-bcb632615b11 | | rrnOriginal | rrn номер оригінальної транзакції в МПС | string | 123456789 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ```json { "merchantRequestId":"137d9304-0368-11ed-b939-0242ac120002", "operationId":"137d9304-0368-11ed-b939-0242ac120002", "merchantId":"137d9304-0368-11ed-b939-0242ac120002", "coinAmount":"2500", "notificationUrl": "", "date": "2022-11-11 11:58:41.56+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ```json { "type": "REFUND", "rrn": "410213187861", "purpose": null, "comment": null, "coinAmount": 100, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712843529623cHAHkmt-G5u", "ecomOperationId": "3af2de3a-035d-44c4-9f63-d3c899687d34", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 76, "merchantRequestId": "21f8ab16-3d4e-4ece-a3f5-ecb406c394ff", "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": null, "notificationEncryption": false, "rrnOriginal": "410213187861", "originalOperationId": "1712843529623cHAHkmt-G5u", "originalCoinAmount": 100, "cardNumberMask": null, "originalEcomOperationId": "c25ee1cb-a052-439b-b075-bcb632615b11" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс
# TOKEN Проведення платежу за допомогою токену картки Токен картки — це спеціальний цифровий ідентифікатор, який замінює реальні дані картки для безпечних платежів. Використовуючи токен, ви можете оплачувати покупки, не передаючи фактичний номер картки. ### Як отримати токен картки? Є два способи створення токену: 1. **Під час платежу** – при використанні запиту [Purchase](/platizhni-metodi-h2h/purchase/zapit-provedennya-purchase-krok-1) або [C2A](/platizhni-metodi-h2h/c2a/zapit-provedennya-c2a-krok-1), якщо додатково передати параметр typeToken = TOKEN\_PER\_CUSTOMER. 2. **Окремим запитом** – за допомогою спеціального запиту **"**[**Створення токену**](/platizhni-metodi-h2h/token/zapit-stvorennya-tokenu)**"**. ### Як оплатити за допомогою токену? Після створення токену можна провести платіж через спеціальний ендпоінт 1. **"**[**Проведення платежу по токену**](/platizhni-metodi-h2h/token/purchase/zapit-provedennya-platezhu-po-tokenu-krok-1)**"** для типу платежу Purchase. 2. **"**[**Проведення платежу по токену**](/platizhni-metodi-h2h/token/c2a/zapit-provedennya-platezhu-po-tokenu-krok-1)**"** для типу платежу C2A. Просто передайте токен замість даних картки, і платіж буде оброблений безпечно та швидко. Це дозволяє уникнути збереження конфіденційних даних картки та підвищує рівень безпеки ваших транзакцій. ### **Додаткові запити пов’язані з токенами:** 🔹 [**Отримання токену за customerId**](/platizhni-metodi-h2h/token/zapit-otrimannya-tokenu-po-customerid)\ Якщо потрібно знайти токен, прив’язаний до конкретного клієнта, використовується запит **"Отримання токену по customerId"**. 🔹 [**Отримання даних про токен**](/platizhni-metodi-h2h/token/zapit-otrimannya-danikh-tokenu)\ Щоб отримати детальну інформацію про токен (наприклад, термін дії, статус або прив’язану картку), використовується запит **"Отримання даних про токен"**. 🔹 [**Зміна статус токену**](/platizhni-metodi-h2h/token/zapit-zmini-statusa-tokenu)\ Щоб змінити статус токену, використовується ендпоінт **"Зміни статуса токену"** Ці запити дозволяють зручно керувати токенами та забезпечують безпечний і швидкий процес оплати. # PURCHASE # Запит проведення платежу по токену Крок 1 {{url}}/ecom/jws/payments/token\_purchase\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОпиcФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчантаstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
tokenтокен карткиstringТакK24YmzXWbw6aCWQn3sdpk7E9
cvvcvv картки зашифрованний в JWEstringТак263 (розшифрований вигляд)
coinAmountсума платежу в копійкахstringТак2000
txnType

під тип транзакціі

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

enumНіМожливі значення: NONCVV/noncvv
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
customerDataоб'єкт з customer даними objectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправника string (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeІндекс відправникаstring (50)Ні 49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | K24YmzXWbw6aCWQn3sdpk7E9 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "merchantId": "467c8a10-c705-11ed-afa1-0242ac120002", "merchantRequestId": "{{requestUUIDT}}", "token": "K24YmzXWbw6aCWQn3sdpk7E9", "cvv": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiZ2lYMHdQZmVvendRVHRsNHYxLWVMd09NR3JxbEphTzU3clREeGxlMHYxSFY0N3AycGJEOENha2RnLWpLUVlyNCIsInkiOiIxX3ZUZnd4X2d0WDRTYU1DbDdTdWNiS3pXYW8zRFlIM2Z0aVRKZnFJZ3Qwdk5KZ1JTanUzODhyTTJaQlNvQ1RwIiwiY3J2IjoiUC0zODQifX0", "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" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ``` { "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, "externalCardToken":"K24YmzXWbw6aCWQn3sdpk7E9" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ``` { "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, "externalCardToken":"K24YmzXWbw6aCWQn3sdpk7E9" } ```
# Запит проведення платежу по токену 3DS Крок 2 {{url}}/ecom/jws/payments/purchase/token\_3ds\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак1697008393082nW0c1jr6KVv
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | creationDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "operationId": "{{operationIdT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "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": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712822536063CdDIRi8hhjq", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
# C2A ``` ``` # Запит проведення платежу по токену Крок 1 {{url}}/ecom/jws/payments/token\_card\_2\_terminal\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчантаstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
tokenтокен картки stringТакK24YmzXWbw6aCWQn3sdpk7E9
cvvcvv картки зашифрованний в JWEstringТак345 (розшифрованний вигляд)
typeTokenвизначає тип токена при його створенніstringНі

можливі значення:

  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
txnType

під тип транзакціі

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

enumНіМожливі значення: NONCVV/noncvv
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)Ніhttps://support.google.com/
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

merchantCommissionСума комісіїintНі0
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі29000000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | K24YmzXWbw6aCWQn3sdpk7E9 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "merchantId":"467c8a10-c705-11ed-afa1-0242ac120002", "merchantRequestId": "{{requestUUIDT}}", "cvv": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiZlJYSlpPOVYxSlFaTlJjNUZUdENnWWVQSGhRVGs0MEt1N0ZnQ3QxblpGYnRkSHlWVXp0Tkl0Rzh3TVdTZzNBbiIsInkiOiJZekxRZlYwM3dmRVlyTlN4M2dZUjQ3cXlnak9pNGxMNWxLV01qWktzS3ZCYXpWbmUySDBUVTBQUEd2azhvaWlBIiwiY3J2IjoiUC0zODQifX0", "token": "K24YmzXWbw6aCWQn3sdpk7E9", "coinAmount": "1000", "comment": "comment", "purpose": "purpose", "merchantCommission": "0", "desiredThreeDSMode": "MUST" "notificationUrl": "", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" } "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ``` { "type": "CARD_2_ACCOUNT", "rrn": "410208187342", "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823122106xnUK8T9Z9d8", "ecomOperationId": "a4842af1-ab80-4685-9cef-0d97aedbb99f", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "0d7a190d-9cfc-4b01-9615-e207ebe8b23b", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ``` { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823334404zicRAYWIAm1", "ecomOperationId": "412ac336-aac5-43b5-8d35-b57ffa9d53ff", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "60cb4f84-add5-48c6-984f-7b20a6b50c75", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "db259063-61ba-4681-a7e9-65fbbebead2d", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712823334404zicRAYWIAm1", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
# Запит проведення платежу по токену 3DS Крок 2 {{url}}/ecom/jws/payments/card\_2\_terminal/token\_3ds\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | ### **Приклади :**
JWS Payload — тіло запиту перед підписанням ​ ``` { "operationId": "{{operationIdT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823334404zicRAYWIAm1", "ecomOperationId": "412ac336-aac5-43b5-8d35-b57ffa9d53ff", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "60cb4f84-add5-48c6-984f-7b20a6b50c75", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "db259063-61ba-4681-a7e9-65fbbebead2d", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712823334404zicRAYWIAm1", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ```
# Запит створення токену {{url}}/ecom/jws/token/create\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчантаstring (36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
customerIdId клієнтаstring(255)Так12345
encryptedCardNumberНомер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
encryptedExpDateтермін дії карти зашифрованний в JWE. stringТак2503 (розшифрований вигляд)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------- | -------------------------------- | ------------ | ------------------------------------ | | customerId | Id клієнта | string(255) | 14534543 | | token | Id токену | string | *TlcMw5uKf9Gp6nM\_7cHGAf* | | maskedPan | маска картки | string | 528529••••••0255 | | merchantId | Id мерчанту згенерований в Єкомі | string(36) | 137d9304-0368-11ed-b939-0242ac168002 | | status | статус токену | string | ACTIVE | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "merchantId": "137d9304-0368-11ed-b939-0242ac168002", "customerId": "14534543", "encryptedCardNumber": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoidE1sRVIyWGNHWGpxUTg2dEpRTEgyeHRyQ2NvVzdLUXJnVVZRNVJtQmNSaEZycmhnZnlxVW5sLTF2WVh0cjZIeiIsInkiOiJ3T0xyV3R5RzBqYlA4OWlUaVl1UkF2Si1valNoZE0yVWUycnVlYkhqUmlIMEt5clJELVBfdGFZV0ZxX3dGemRvIiwiY3J2IjoiUC0zODQifX0.ZAIlVIU6nh2Nt5yAx1QVolk82fEb-Gyw8X6DZxmhCbq-E1Kvz83jYQ.HGw9tqjLb8HtdmeF.nCXcOe4S9KcX-k4MKHNpXw.bDUYIFzik3HfHBrYYz-Wdw", "encryptedExpDate": "eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoibHZxMTdaWnBVWTNsX1JlcFpFU0lRUnlOeWlpS09xU0tfRUF5aHdvNGk4c0QwaVF4ZnE3ZTQxM1VjRFJMbjJQZyIsInkiOiIwVXJkcjJialhOTS16SUxiOTg1bGNZYjJrcUJReGNBMkZSNzdhWXhVVU1qUHFNR0Z6SlBxUDhpT2hGaU9pZHNiIiwiY3J2IjoiUC0zODQifX0.L35f-ycKXciH_WM2Zh-iOzMqsjL9pTz6OBPu8BVkqj9kp8Ck-faNjg.Q5CGl2neg0laf4TP.TZ_giQ.w7e9zx6LTbA_e607veBRHA", "date": "2025-02-20 16:42:05.00+00:00", "merchantRequestId": "8d1b3cbb-3d31-4067-81bd-57edbe050011" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "customerId": "14534543", "token": "_TlcMw5uKf9Gp6nM_7cHGAf_", "maskedPan": "528529••••••0255", "merchantId": "137d9304-0368-11ed-b939-0242ac168002", "status": "ACTIVE" } ```
# Запит отримання токену по customerId {{url}}/ecom/jws/token/list/by-customer-id\_v1 ### Вхідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Обовʼязковість | Приклад | | ---------- | ---------- | ------------ | -------------- | ------- | | customerId | Id клієнта | string(255) | Так | 12345 | ### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------- | ------------- | ------------ | ------------------------------------ | | customerId | Id клієнта | string(255) | 12345 | | token | Id токену | string | SRrSBe5DOb7lrZ\_FS46fihty | | maskedPan | маска картки | string | 516874\*\*\*\*\*\*7753 | | merchantId | Id мерчанта | string | 137d9304-0368-11ed-b939-0242ac120002 | | status | статус токену | string | ACTIVE | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "customerId": "senderCustomerId" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "result": [ { "token": "-s9UCfCNN0YMk4ZOyZX8pWAt", "status": "ACTIVE", "maskedPan": "523244••••••0177", "customerId": "senderCustomerId", "merchantId": "137d9304-0368-11ed-b939-0242ac120002" } ] } ```
# Запит отримання даних токену {{url}}/ecom/jws/token/get\_v1 ### Вхідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Обовʼязковість | Приклад | | -------- | --------- | ------------ | -------------- | ------------------------- | | token | Id токену | string | Так | SRrSBe5DOb7lrZ\_FS46fihty | ### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ---------- | ------------- | ------------ | ------------------------------------ | | customerId | Id клієнта | string(255) | 12345 | | token | Id токену | string | SRrSBe5DOb7lrZ\_FS46fihty | | maskedPan | маска картки | string | 516874\*\*\*\*\*\*7753 | | merchantId | Id мерчанта | string | 137d9304-0368-11ed-b939-0242ac120002 | | status | статус токену | string | ACTIVE | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "token": "SRrSBe5DOb7lrZ_FS46fihty" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "result": [ { "token": "-s9UCfCNN0YMk4ZOyZX8pWAt", "status": "ACTIVE", "maskedPan": "523244••••••0177", "customerId": "senderCustomerId", "merchantId": "137d9304-0368-11ed-b939-0242ac120002" } ] } ```
# Запит зміни статуса токену {{url}}/ecom/jws/token/state/update\_v1 Зміна статусу можлива відповідно до наступних правил: 1. **ACTIVE → SUSPENDED** – Активний статус може бути змінений на призупинений (наприклад, у разі тимчасового блокування). 2. **SUSPENDED → ACTIVE** – Призупинений статус може бути відновлений до активного (наприклад, після розблокування). 3. **ACTIVE → DELETED** – Активний статус може бути змінений на видалений (наприклад, при остаточному видаленні). 4. **SUSPENDED → DELETED** – Призупинений статус може бути змінений на видалений (наприклад, якщо користувач не відновив активність). Перехід між статусами **DELETED → будь-який інший** неможливий. ### Вхідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Обовʼязковість | Приклад | | -------- | ------------- | ------------ | -------------- | ------------------------- | | token | Id токену | string | Так | SRrSBe5DOb7lrZ\_FS46fihty | | state | статус токена | string | Так | SUSPENDED | ### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ------------ | --------------------------- | ------------ | ------------------------- | | tokenUpdated | ознака зміни статусу токену | boolean | true/false | | customerId | Id клієнта | string(255) | 12345 | | token | Id токену | string | SRrSBe5DOb7lrZ\_FS46fihty | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "token": "-s9UCfCNN0YMk4ZOyZX8pWAt", "state": "SUSPENDED" } ```
JWS Payload — тіло відповіді перед підписанням ``` { "tokenUpdated": true, "customerId": "senderCustomerId", "token": "-s9UCfCNN0YMk4ZOyZX8pWAt" } ```
# Статуси токена * ACTIVE - активний * SUSPENDED - деактивованний * OBSOLETE - деактивованний системою * DELETED - видаленний # Account Verification # Запит верифікації картки Крок 1 {{url}}/ecom/jws/payments/create/verification\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОпиcФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
notificationUrlurl, на який буде відправлено CallBackstring (1000)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
customerDataоб'єкт з customer даними objectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправника string (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeІндекс відправникаstring (50)Ні 49000
### Вихідні параметри частини payload JWS : | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | ### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "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" } } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ``` { "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" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ``` { "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" } ```
# Запит верифікації картки Крок 2 {{url}}/ecom/jws/payments/execute/verification\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак1697008393082nW0c1jr6KVv
encryptedCardDataтермін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvvstringТак2503111 (розшифрований вигляд, у форматі YYMMCVV)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
### Вихідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
typeтип транзакціїstringPurchase
rrnrrn номер транзакції в МПСstring2554256963
purposeпризначення платежуstringЗа товар
commentкоментарstringтест
coinAmountсума платежуint2000
merchantIdId мерчантуstring137d9304-0368-11ed-b939-0242ac120002
operationIdId транзакцііstring1712844596346b9F-WwrWZpq
ecomOperationIdId транзакціі в системі Ecomstring8c3303e9-7396-43b8-af4e-31d9facdde9b
merchantNameнайменування торговцяstringKB test terminal
approvalCodeкод авторизацііstring39203
statusстатус транзакцііstringSUСCESS
FAIL
PENDING
REQUIRED_3DS
DESIRED_THREEDS_MODE_ERROR
transactionTypeтип транзакції у цифровому значенніstring35
merchantRequestIdId запиту мерчантаstring72837906-f526-4aef-8d11-58d80b44cb75
transactionCurrencyвалюта платежуstring980
merchantCommissionсума комісіїstring2
creationDateTimeдата створення платежуstring2024.09.19 15:29:25.675
modificationDateTimeдата модифікаціі платежуstring2024.09.19 15:29:25.675
actionCodeкод відповідіstring0
responseCodeдеталі відповідіstring0
descriptionопис відповідіstringapproved
bankCodeназва банку емітентаstringBANK_ALLIANCE
paymentSystemназва мпс емітентаstringMasterCard
productTypeтип продукту терміналаstringPURCHASE
notificationUrlurl, на який відправлено CallBackstringhttps://merchant.notification_url/
paymentServiceTypeтип оплатиstringCARD/APPLE_PAY/GOOGLE_PAY
notificationEncryptionознака криптування данних CallBackstringtrue/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані
cardNumberMaskмаскований номер картиstring5573********0304
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.stringMUST/SHOULD/MUST_NOT
threeDSModeпараметр який вказує, використовувася 3DS у покупці чи ніstringMUST- проводимо оплату з 3DS
MUST_NOT- проводимо оплату без 3DS
statusThreeDsстатус проведення 3DSstringY - успіший 3ds
N - не успішний 3ds
threeDSServerTransIdId транзакціі в системі 3dsstringb6c35fdb-28c1-454d-a2f3-51098c26bda4
acsTransIdId транзакціі в системі ACSstring3e17fabb-71e6-498e-8794-ef8c95c5ba6f
dsTransIdId транзакціі згенерований Directory Serverstring12ebc556-82d3-4e35-9fb8-77ac18b050ea
eciElectronic Commerce Indicator Код, який вказує рівень безпеки транзакціїstring02
processingMerchantIdId мерчанту в ПЦstringAE100000
processingTerminalIdId терміналу в ПЦstringAE100000
redirect3dsUrlurl для редиректа клієнта на сторінку емітента для проходження 3DSstringhttps://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA
txnTypeпід тип транзакцііenumМожливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається
senderCustomerIdId клієнта відправникаstring1258728c1
senderFirstNameім'я відправника stringІваненко
senderLastNameпрізвище відправникаstringІван
senderMiddleNameпо-батькові відправникаstringІванович
senderEmailпошта відправникаstringmail@gmail.com
senderCountryкраїна відправникаstringУкраїна
senderRegionобласть відправникаstringКиївська
senderCityмісто відправникаstringКиїв
senderStreetвулиця відправникаstringСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string23
senderItnіпн відправникаstring123456789
senderPassportпаспорт відправникаstringАН123456
senderIpspace.vars.senderIP_descriptionstringspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring380630000000
senderBirthdayдень народження відправникаstring31.12.2000
senderGenderгендер відправникаstringM
senderZipCodeіндекс відправникаstring12000
senderBankCodeназва банку емітента відправникаstringBANK_ALLIANCE
senderPaymentSystemназва мпс емітента відправникаstringMasterCard
senderCardNumberMaskмаскований номер карти відправникаstring5573********0304
externalCardTokenid токенуstringtmkEYenZSa8FV03aawVXxbep
### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "operationId": "{{operationId}}", "encryptedCardData": "{{encryptedCardData}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ```
JWS Payload — тіло відповіді перед підписанням без 3дс ``` { "type": "VERIFICATION", "rrn": "509310723011", "purpose": "", "comment": "", "coinAmount": 0, "merchantId": "137d9304-0368-11ed-b939-0242ac120", "operationId": "17436771609101HDujgZphks", "ecomOperationId": "1c97b778-d8d0-4680-89eb-8015842b45a3", "status": "SUCCESS", "transactionType": 215, "merchantRequestId": "03185335-3a9f-4aad-a3b9-c8b1e6d4051b", "transactionCurrency": "980", "creationDateTime": "2025.04.03 13:46:00.846", "modificationDateTime": "2025.04.03 13:46:01.465", "transactionResponseInfo": { "actionCode": "0", "responseCode": "00", "description": "Операція успішна" }, "productType": "PURCHASE", "notificationUrl": "test", "paymentServiceType": "CARD", "notificationEncryption": false, "processingTerminalId": "AE001001", "processingMerchantId": "AE001001", "creatorSystem": "H2H", "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "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" } ```
JWS Payload — тіло відповіді перед підписанням з 3дс ``` { "type": "VERIFICATION", "purpose": "", "comment": "", "coinAmount": 0, "merchantId": "137d9304-0368-11ed-b939-0242ac1200", "operationId": "1743677843021zx9DLwCfxz-", "ecomOperationId": "d8abe162-99a1-4cb9-8611-8b610cda510b", "status": "REQUIRED_3DS", "transactionType": 215, "merchantRequestId": "f821a5fa-cbfb-4ace-9c2f-83abc799d3a9", "transactionCurrency": "980", "creationDateTime": "2025.04.03 13:57:22.957", "modificationDateTime": "2025.04.03 13:57:23.752", "transactionResponseInfo": {}, "productType": "PURCHASE", "notificationUrl": "test", "paymentServiceType": "CARD", "notificationEncryption": false, "processingTerminalId": "AE001001", "processingMerchantId": "AE001001", "creatorSystem": "H2H", "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "threeDSServerTransId": "1a85c9f3-c19c-448a-a4bb-04f265b62a28", "redirect3dsUrl": "https://api-ecom-preprod.develop.bankalliance.ua/threeDS/getRedirectHtml/1743677843021zx9DLwCfxz-", "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" } ```
# Отримання даних # по OPERATION\_ID {{url}}/ecom/jws/payments/operations\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
idId транзакцііstringТак1712844596346b9F-WwrWZpq
### Вихідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
typeтип транзакціїstringPurchase, CARD_2_ACCOUNT, ACCOUNT_2_CARD,REFUND
rrnrrn номер транзакції в МПСstring2554256963
purposeпризначення платежуstringЗа товар
commentкоментарstringтест
Coin amountсума платежу в копійкахint2000
merchantIdId мерчантуstring137d9304-0368-11ed-b939-0242ac120002
operationIdId транзакцііstring1712844596346b9F-WwrWZpq
ecomOperationIdId транзакціі в системі Ecomstring8c3303e9-7396-43b8-af4e-31d9facdde9b
merchantNameнайменування торговцяstringKB test terminal
approvalCodeкод авторизацііstring39203
statusстатус транзакцііstringSUСCESS
FAIL
PENDING
REQUIRED_3DS
DESIRED_THREEDS_MODE_ERROR
transactionTypeтип транзакції у цифровому значенніstring35
merchantRequestIdId запиту мерчантаstring72837906-f526-4aef-8d11-58d80b44cb75
transactionCurrencyвалюта платежуstring980
merchantCommissionсума комісіїstring2
createDateTimeдата створення платежуstring2024.09.19 15:29:25.675
modificationDateTimeдата модифікаціі платежуstring2024.09.19 15:29:25.675
actionCodeкод відповідіstring0
responseCodeдеталі відповідіstring0
descriptionопис відповідіstringapproved
bankCodeназва банку емітентаstringBANK_ALLIANCE
paymentSystemназва мпс емітентаstringMasterCard
productTypeтип продукту терміналаstringPURCHASE
notificationUrlurl, на який відправлено CallBackstringhttps://merchant.notification_url/
paymentServiceTypeтип оплатиstringCARD/APPLE_PAY/GOOGLE_PAY
notificationEncryptionознака криптування данних CallBackstringtrue/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані
cardNumberMaskмаскований номер картиstring5573********0304
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.stringMUST/SHOULD/MUST_NOT
threeDSModeпараметр який вказує, використовувася 3DS у покупці чи ніstringMUST- проводимо оплату з 3DS
MUST_NOT- проводимо оплату без 3DS
statusThreeDsстатус проведення 3DSstringY - успіший 3ds
N - не успішний 3ds
threeDSServerTransIdId транзакціі в системі 3dsstringb6c35fdb-28c1-454d-a2f3-51098c26bda4
acsTransIdId транзакціі в системі ACSstring3e17fabb-71e6-498e-8794-ef8c95c5ba6f
dsTransIdId транзакціі згенерований Directory Serverstring12ebc556-82d3-4e35-9fb8-77ac18b050ea
eciElectronic Commerce Indicator Код, який вказує рівень безпеки транзакціїstring02
processingMerchantIdId мерчанту в ПЦstringAE100000
processingTerminalIdId терміналу в ПЦstringAE100000
redirect3dsUrlurl для редиректа клієнта на сторінку емітента для проходження 3DSstringhttps://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA
txnTypeпід тип транзакцііenumМожливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається
senderCustomerIdId клієнта відправникаstring1258728c1
senderFirstNameім'я відправника stringІваненко
senderLastNameпрізвище відправникаstringІван
senderMiddleNameпо-батькові відправникаstringІванович
senderEmailпошта відправникаstringmail@gmail.com
senderCountryкраїна відправникаstringУкраїна
senderRegionобласть відправникаstringКиївська
senderCityмісто відправникаstringКиїв
senderStreetвулиця відправникаstringСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string23
senderItnіпн відправникаstring123456789
senderPassportпаспорт відправникаstringАН123456
senderIpspace.vars.senderIP_descriptionstringspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring380630000000
senderBirthdayдень народження відправникаstring31.12.2000
senderGenderгендер відправникаstringM
senderZipCodeіндекс відправникаstring12000
senderBankCodeназва банку емітента відправникаstringBANK_ALLIANCE
senderPaymentSystemназва мпс емітента відправникаstringMasterCard
senderCardNumberMaskмаскований номер карти відправникаstring5573********0304
recipientCustomerIdId клієнта відправникаstring1258728c1
recipientFirstNameім'я отримувача stringІваненко
recipientLastNameпрізвище отримувачаstringІван
recipientMiddleNameпо-батькові отримувачаstringІванович
recipientEmailпошта отримувачаstringmail@gmail.com
recipientCountryкраїна отримувачаstringУкраїна
recipientRegionобласть отримувачаstringКиївська
recipientCityмісто отримувачаstringКиїв
recipientStreetвулиця отримувачаstringСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string23
recipientItnіпн отримувачаstring123456789
recipientPassportпаспорт отримувачаstringАН123456
recipientIpspace.vars.recipientIP_desctiptionstringspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring380630000000
recipientBirthdayдень народження отримувачаstring31.12.2000
recipientGenderгендер отримувачаstringM
recipientZipCodeіндекс отримувачаstring12000
recipientBankCodeназва банку емітента отримувачаstringBANK_ALLIANCE
recipientPaymentSystemназва мпс емітента отримувачаstringMasterCard
recipientCardNumberMaskмаскований номер карти отримувачаstring5573********0304
originalOperationIdid під яким створено оригінальну операціюstring1712843529623cHAHkmt-G5u
originalCoinAmountСума оригінального платежуint100
originalEcomOperationIdid в системі Еком під яким створено оригінальну операціюstringc25ee1cb-a052-439b-b075-bcb632615b11
rrnOriginalrrn номер оригінальної транзакції в МПСstring123456789
### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { "id": "16849296265235MUp5dm2pxD" } ```
JWS Payload — тіло відповіді перед підписанням дял A2C ``` { "type": "ACCOUNT_2_CARD", "rrn": "314412161279", "purpose": "test", "comment": "за товар", "merchantId": "467c8a10-c705-11ed-afa1-0242ac120002", "operationId": "16849296265235MUp5dm2pxD", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 46, "merchantRequestId": "65d5dd3e-a07e-424f-adde-b608205a82ee", "transactionCurrency": "980", "createDateTime": "2024.09.19 15:29:25.675", "modificationDateTime": "2024.09.19 15:29:25.675", "transactionResponseInfo":{ "actionCode":"0", "responseCode":"00", "description":"approved" }, "senderCity": "Kyiv", "senderStreet": "L.Ukrainki01", "senderCountry": "840", "senderAccount": "UA12305299260022119999", "senderLastName": "Petrenko", "senderFirstName": "Petro", "recipientCity": "Kyiv", "recipientStreet": "T. Shevchenka, 11", "recipientCountry": "840", "recipientLastName": "TestLastName", "recipientFirstName": "TestFirstname", "recipientCardNumberMask": "537541******7190", "coinAmount": 120, "merchantCommission": null } ```
JWS Payload — тіло відповіді перед підписанням для Refund ``` { "type": "REFUND", "rrn": null, "purpose": null, "comment": null, "coinAmount": 100, "merchantId": "467c8a10-c705-11ed-afa1-0242ac120002", "operationId": "1698132724973lPTqsaiELlg", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 76, "merchantRequestId": "269498bf-c581-48f5-8294-b3b504cb0642", "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 }, "rrnOriginal": null, "originalOperationId": "1698060925854-0zLY-_uCnL", "originalCoinAmount": 0, "cardNumberMask": "516874••••••4924" } ```
# по merchantRequestId {{url}}/ecom/jws/payments/operation/by\_merchant\_request\_id\_v1 ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdId запиту stringТак72837906-f526-4aef-8d11-58d80b44cb75
### Вихідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
typeтип транзакціїstringPurchase, CARD_2_ACCOUNT, ACCOUNT_2_CARD,REFUND
rrnrrn номер транзакції в МПСstring2554256963
purposeпризначення платежуstringЗа товар
commentкоментарstringтест
coinAmountсума платежу в копійкахint2000
merchantIdId мерчантуstring137d9304-0368-11ed-b939-0242ac120002
operationIdId транзакцііstring1712844596346b9F-WwrWZpq
ecomOperationIdId транзакціі в системі Ecomstring8c3303e9-7396-43b8-af4e-31d9facdde9b
merchantNameнайменування торговцяstringKB test terminal
approvalCodeкод авторизацііstring39203
statusстатус транзакцііstringSUСCESS
FAIL
PENDING
REQUIRED_3DS
DESIRED_THREEDS_MODE_ERROR
transactionTypeтип транзакції у цифровому значенніstring35
merchantRequestIdId запиту мерчантаstring72837906-f526-4aef-8d11-58d80b44cb75
transactionCurrencyвалюта платежуstring980
merchantCommissionсума комісіїstring2
createDateTimeдата створення платежуstring2024.09.19 15:29:25.675
modificationDateTimeдата модифікаціі платежуstring2024.09.19 15:29:25.675
actionCodeкод відповідіstring0
responseCodeдеталі відповідіstring0
descriptionопис відповідіstringapproved
bankCodeназва банку емітентаstringBANK_ALLIANCE
paymentSystemназва мпс емітентаstringMasterCard
productTypeтип продукту терміналаstringPURCHASE
notificationUrlurl, на який відправлено CallBackstringhttps://merchant.notification_url/
paymentServiceTypeтип оплатиstringCARD/APPLE_PAY/GOOGLE_PAY
notificationEncryptionознака криптування данних CallBackstringtrue/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані
cardNumberMaskмаскований номер картиstring5573********0304
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.stringMUST/SHOULD/MUST_NOT
threeDSModeпараметр який вказує, використовувася 3DS у покупці чи ніstringMUST- проводимо оплату з 3DS
MUST_NOT- проводимо оплату без 3DS
statusThreeDsстатус проведення 3DSstringY - успіший 3ds
N - не успішний 3ds
threeDSServerTransIdId транзакціі в системі 3dsstringb6c35fdb-28c1-454d-a2f3-51098c26bda4
acsTransIdId транзакціі в системі ACSstring3e17fabb-71e6-498e-8794-ef8c95c5ba6f
dsTransIdId транзакціі згенерований Directory Serverstring12ebc556-82d3-4e35-9fb8-77ac18b050ea
eciElectronic Commerce Indicator Код, який вказує рівень безпеки транзакціїstring02
processingMerchantIdId мерчанту в ПЦstringAE100000
processingTerminalIdId терміналу в ПЦstringAE100000
redirect3dsUrlurl для редиректа клієнта на сторінку емітента для проходження 3DSstringhttps://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA
txnTypeпід тип транзакцііenumМожливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається
senderCustomerIdId клієнта відправникаstring1258728c1
senderFirstNameім'я відправника stringІваненко
senderLastNameпрізвище відправникаstringІван
senderMiddleNameпо-батькові відправникаstringІванович
senderEmailпошта відправникаstringmail@gmail.com
senderCountryкраїна відправникаstringУкраїна
senderRegionобласть відправникаstringКиївська
senderCityмісто відправникаstringКиїв
senderStreetвулиця відправникаstringСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string23
senderItnіпн відправникаstring123456789
senderPassportпаспорт відправникаstringАН123456
senderIpspace.vars.senderIP_descriptionstringspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring380630000000
senderBirthdayдень народження відправникаstring31.12.2000
senderGenderгендер відправникаstringM
senderZipCodeіндекс відправникаstring12000
senderBankCodeназва банку емітента відправникаstringBANK_ALLIANCE
senderPaymentSystemназва мпс емітента відправникаstringMasterCard
senderCardNumberMaskмаскований номер карти відправникаstring5573********0304
recipientCustomerIdId клієнта відправникаstring1258728c1
recipientFirstNameім'я отримувача stringІваненко
recipientLastNameпрізвище отримувачаstringІван
recipientMiddleNameпо-батькові отримувачаstringІванович
recipientEmailпошта отримувачаstringmail@gmail.com
recipientCountryкраїна отримувачаstringУкраїна
recipientRegionобласть отримувачаstringКиївська
recipientCityмісто отримувачаstringКиїв
recipientStreetвулиця отримувачаstringСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string23
recipientItnіпн отримувачаstring123456789
recipientPassportпаспорт отримувачаstringАН123456
recipientIpspace.vars.recipientIP_desctiptionstringspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring380630000000
recipientBirthdayдень народження отримувачаstring31.12.2000
recipientGenderгендер отримувачаstringM
recipientZipCodeіндекс отримувачаstring12000
recipientBankCodeназва банку емітента отримувачаstringBANK_ALLIANCE
recipientPaymentSystemназва мпс емітента отримувачаstringMasterCard
recipientCardNumberMaskмаскований номер карти отримувачаstring5573********0304
originalOperationIdid під яким створено оригінальну операціюstring1712843529623cHAHkmt-G5u
originalCoinAmountСума оригінального платежуint100
originalEcomOperationIdid в системі Еком під яким створено оригінальну операціюstringc25ee1cb-a052-439b-b075-bcb632615b11
rrnOriginalrrn номер оригінальної транзакції в МПСstring123456789
# Отримання балансу POST {{url}}/ecom/jws/balance/get\_v1 ### Вихідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
merchantIdId мерчантаstring235d9304-0368-11ed-b939-0242ac120002
balanceAmountСума на балансіstring47
balanceLimitСума овердрафт ліміту для мерчантаstring0
totalAmountЗагальна сумаstring47
### Приклади :
JWS Payload — тіло запиту перед підписанням ``` { } ```
JWS Payload — тіло відповіді перед підписанням ``` { "merchantId": "235d9304-0368-11ed-b939-0242ac120002", "balanceAmount": 47, "balanceLimit": 0, "totalAmount": 47 } ```
# Callback Для відправки Callback буде виконаний POST запит на `notificationUrl` який був вказаний в запиті на проведення платежу. Кожен Callback буде підписаний та надсилатись у форматі JWS. Відправлення Callback відбувається одразу після фіналізації платіжної операції. * Якщо статус отримання Callback не 200 ОК, відбувається перевідправка Callback через 5 сек, потім через 30 сек, потім через 5 хв, потім через 30 хв, через 1 годину * Якщо статус отримання Callback не 200 ОК для 1-го разу, а для 2-го разу 200 ОК, то перевідправка Callback більше не виконується ### Вхідні параметри частини payload JWS :
ПараметрОписФормат данихПриклад
typeтип транзакціїstringPurchase, CARD_2_ACCOUNT, ACCOUNT_2_CARD,REFUND
rrnrrn номер транзакції в МПСstring2554256963
purposeпризначення платежуstringЗа товар
commentкоментарstringтест
coinAmountсума платежу в копійкахint2000
merchantIdId мерчантуstring137d9304-0368-11ed-b939-0242ac120002
operationIdId транзакцііstring1712844596346b9F-WwrWZpq
ecomOperationIdId транзакціі в системі Ecomstring8c3303e9-7396-43b8-af4e-31d9facdde9b
merchantNameнайменування торговцяstringKB test terminal
approvalCodeкод авторизацііstring39203
statusстатус транзакцііstringSUСCESS
FAIL
PENDING
REQUIRED_3DS
DESIRED_THREEDS_MODE_ERROR
transactionTypeтип транзакції у цифровому значенніstring35
merchantRequestIdId запиту мерчантаstring72837906-f526-4aef-8d11-58d80b44cb75
transactionCurrencyвалюта платежуstring980
merchantCommissionсума комісіїint2
creationDateTimeдата створення платежуstring2024.09.19 15:29:25.675
modificationDateTimeдата модифікаціі платежуstring2024.09.19 15:29:25.675
transactionResponseInfoобʼєкт з даними object
transactionResponseInfo.actionCodeкод відповідіstring0
transactionResponseInfo.responseCodeдеталі відповідіstring0
transactionResponseInfo.descriptionопис відповідіstringapproved
bankCodeназва банку емітентаstringBANK_ALLIANCE
paymentSystemназва мпс емітентаstringMasterCard
productTypeтип продукту терміналаstringPURCHASE
notificationUrlurl, на який відправлено CallBackstringhttps://merchant.notification_url/
paymentServiceTypeтип оплатиstringCARD/APPLE_PAY/GOOGLE_PAY
notificationEncryptionознака криптування данних CallBackstringtrue/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані
cardNumberMaskмаскований номер картиstring5573********0304
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.stringMUST/SHOULD/MUST_NOT
threeDSModeпараметр який вказує, використовувася 3DS у покупці чи ніstringMUST- проводимо оплату з 3DS
MUST_NOT- проводимо оплату без 3DS
statusThreeDsстатус проведення 3DSstringY - успіший 3ds
N - не успішний 3ds
threeDSServerTransIdId транзакціі в системі 3dsstringb6c35fdb-28c1-454d-a2f3-51098c26bda4
acsTransIdId транзакціі в системі ACSstring3e17fabb-71e6-498e-8794-ef8c95c5ba6f
dsTransIdId транзакціі згенерований Directory Serverstring12ebc556-82d3-4e35-9fb8-77ac18b050ea
eciElectronic Commerce Indicator Код, який вказує рівень безпеки транзакціїstring02
hppOrderIdId hpp ордеру, в якому було свторено платіжstring1812844596346b9F-WwrWZpq
processingMerchantIdId мерчанту в ПЦstringAE100000
processingTerminalIdId терміналу в ПЦstringAE100000
creatorSystemсистема в якійстворено платіжstringH2H, HPP
redirect3dsUrlurl для редиректа клієнта на сторінку емітента для проходження 3DSstringhttps://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA
txnTypeпід тип транзакцііenumМожливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається
balanceAmountAfterзначення балансу після списанняstring23400
senderCustomerIdId клієнта відправникаstring1258728c1
senderFirstNameпрізвище відправникаstringІваненко
senderLastNameім'я відправникаstringІван
senderMiddleNameпо-батькові відправникаstringІванович
senderEmailпошта відправникаstringmail@gmail.com
senderCountryкраїна відправникаstringУкраїна
senderRegionобласть відправникаstringКиївська
senderCityмісто відправникаstringКиїв
senderStreetвулиця відправникаstringСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string23
senderItnіпн відправникаstring123456789
senderPassportпаспорт відправникаstringАН123456
senderIpspace.vars.senderIP_descriptionstringspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring380630000000
senderBirthdayдень народження відправникаstring31.12.2000
senderGenderгендер відправникаstringM
senderZipCodeіндекс відправникаstring12000
senderBankCodeназва банку емітента відправникаstringBANK_ALLIANCE
senderPaymentSystemназва мпс емітента відправникаstringMasterCard
senderCardNumberMaskмаскований номер карти відправникаstring5573********0304
senderAccountрахунок відправникаstring2600000000
recipientCustomerIdId клієнта відправникаstring1258728c1
recipientFirstNameпрізвище отримувачаstringІваненко
recipientLastNameім'я отримувачаstringІван
recipientMiddleNameпо-батькові отримувачаstringІванович
recipientEmailпошта отримувачаstringmail@gmail.com
recipientCountryкраїна отримувачаstringУкраїна
recipientRegionобласть отримувачаstringКиївська
recipientCityмісто отримувачаstringКиїв
recipientStreetвулиця отримувачаstringСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string23
recipientItnіпн отримувачаstring123456789
recipientPassportпаспорт отримувачаstringАН123456
recipientIpspace.vars.recipientIP_desctiptionstringspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring380630000000
recipientBirthdayдень народження отримувачаstring31.12.2000
recipientGenderгендер отримувачаstringM
recipientZipCodeіндекс отримувачаstring12000
recipientBankCodeназва банку емітента отримувачаstringBANK_ALLIANCE
recipientPaymentSystemназва мпс емітента отримувачаstringMasterCard
recipientCardNumberMaskмаскований номер карти отримувачаstring5573********0304
originalOperationIdid під яким створено оригінальну операціюstring1712843529623cHAHkmt-G5u
originalCoinAmountСума оригінального платежуint100
originalEcomOperationIdid в системі Еком під яким створено оригінальну операціюstringc25ee1cb-a052-439b-b075-bcb632615b11
rrnOriginalrrn номер оригінальної транзакції в МПСstring123456789
externalCardTokenid токену string1234567YTDHJI
#### Приклад тіла запиту ACCOUNT\_2\_CARD ```json { "type":"ACCOUNT_2_CARD", "rrn":" ", "purpose":"", "comment":" ", "coinAmount":3000, "merchantId":" ", "operationId":" ", "ecomOperationId":" ", "merchantName":" ", "approvalCode":" ", "status":"SUCCESS", "transactionType":46, "merchantRequestId":" ", "transactionCurrency":"980", "merchantCommission":450, "creationDateTime":"2025.07.21 13:19:15.620", "modificationDateTime":"2025.07.21 13:19:16.424", "processingDateTime":"2025.07.21 13:19:14.000", "transactionResponseInfo":{ "actionCode":"0", "responseCode":"00", "description":"approved" }, "bankCode":" ", "paymentSystem":" ", "productType":" ", "notificationUrl":"", "paymentServiceType":"CARD", "notificationEncryption":false, "processingTerminalId":" ", "processingMerchantId":" ", "creatorSystem":"H2H", "balanceAmountAfter":48924, "senderAccount":"2600000000000", "recipientCardNumberMask":" ", "cardNumberMask":" ", "senderCustomerId":" ", "recipientCustomerId":" ", "recipientFirstName":" ", "recipientLastName":" ", "recipientItn":" ", "recipientBankCode":" ", "recipientPaymentSystem":" " } ``` Приклад тіла запиту PURCHASE ```json { "type":"PURCHASE", "rrn":" ", "purpose":"", "coinAmount":100, "merchantId":" ", "operationId":" ", "ecomOperationId":" ", "merchantName":" ", "approvalCode":" ", "status":"SUCCESS", "transactionType":35, "transactionCurrency":"980", "creationDateTime":"2025.07.21 10:39:35.501", "modificationDateTime":"2025.07.21 11:04:39.194", "processingDateTime":"2025.07.21 10:39:42.000", "transactionResponseInfo":{ "actionCode":"0", "responseCode":"00", "description":"approved" }, "bankCode":" ", "paymentSystem":" ", "paymentServiceType":"CARD", "notificationEncryption":false, "hppOrderId":" ", "processingTerminalId":" ", "processingMerchantId":" ", "creatorSystem":"", "cardNumberMask":"", "desiredThreeDSMode":"SHOULD", "threeDSMode":"MUST", "acsTransId":" ", "dsTransId":" ", "eci":"", "statusThreeDs":"", "threeDSServerTransId":"", "senderCustomerId":" ", "senderFirstName":"", "senderLastName":"", "senderMiddleName":"", "senderEmail":"", "senderCountry":"", "senderRegion":"", "senderCity":"", "senderStreet":"", "senderAdditionalAddress":"", "senderItn":" ", "senderPassport":"", "senderIp":" ", "senderPhone":" ", "senderBirthday":" ", "senderGender":" ", "senderZipCode":" ", "senderBankCode":" ", "senderPaymentSystem":" ", "senderCardNumberMask":" ", "externalCardToken":" " } ``` Приклад тіла запиту REFUND ```json { "type":"REFUND", "rrn":" ", "coinAmount":10000, "merchantId":" ", "operationId":" ", "ecomOperationId":" ", "merchantName":" ", "approvalCode":" ", "status":"SUCCESS", "transactionType":76, "merchantRequestId":" ", "transactionCurrency":"980", "creationDateTime":"2025.07.21 13:19:31.745", "modificationDateTime":"2025.07.21 13:19:32.794", "processingDateTime":"2025.07.21 13:19:31.000", "transactionResponseInfo":{ "actionCode":"0", "responseCode":"00" }, "bankCode":" ", "paymentSystem":" ", "productType":"PURCHASE", "notificationUrl":" ", "notificationEncryption":false, "processingTerminalId":" ", "processingMerchantId":" ", "creatorSystem":"", "rrnOriginal":" ", "originalOperationId":" ", "cardNumberMask":" ", "originalEcomOperationId":" " } ``` Приклад відповіді ```http HTTP 200 OK ``` # Використання авторизаціїного токену Після розшифрування JWE відповіді (Детальніше: [Приклад розшифрування](https://docs.merchant.alb.ua/autentifikaciya#proces-rozshifruvannya-jwe-danikh)) на запит авторизації `"/api-gateway/authorize_virtual_device"`, отримуємо сесійний токен, а також його термін життя у параметрах: * "tokenExpirationDateTime": "2025-02-27 12:12:34.0430 +0000" // UTC+00:00 * "tokenExpiration": "2025-02-27 14:12:34.430+02:00" // UTC+02:00 Kyiv Загальний термін дії авторизації 24 години з моменту виконання запиту на аторизацію `"/api-gateway/authorize_virtual_device"` Рекомендовано виконувати авторизацію раз у 8 або 12 або 24 години, для зменьшення помилок під час експлатації авторизаційного токену. > Примітка! Не потрібно для кожного запиту виконувати нову авторизацію **Можливі проблеми:** 1. Просроченний авторизаційний токен через неактивність * При відсутності активності `serviceCode` більше ніж 200 днів, доступ до API автоматично закривається. * При спробі виконати запит на авторизацію `"/api-gateway/authorize_virtual_device"` виникає помилка : `"b_auth_token_expired"`. * У випадку необхідності вирішення проблеми, потрібно звернутись до служби підтримку. * **Після виправлення проблеми**, у відповіді на авторизацію надійдуть нові параметри, які потрібно оновити, перед подальшим використання API запитів. 2. Простроченний поточний токен * У випадку виникнення помилки `"b_expired_token"`. * Потрібно виконати запит на авторизацію `"/api-gateway/authorize_virtual_device"`. 3. Просроченний поточний сеанс * Виникнення помилки `"b_session_doesnt_exists"` з текстом "Сеансу не існує". * Помилка з'являється, коли використовується данні попереднього сеансу. * Для вирішення проблеми, потрібно виконати запит на авторизацію `"/api-gateway/authorize_virtual_device"` , та використовувати нові дані сеансу. # Опис роботи з ключами ## # Приклад PURCHASE колекції 1\. Authorize by virtual device — `{{url}}/api-gateway/authorize_virtual_device`\ Для запиту потрібен serviceCode, котрий ми передаємо Вам перед інтеграцією на проді. \ У відповідь повернеться зашифрований серверний ключ - serverPublicKey у форматі jwe, котрий буде потрібен для виконання кроку 2. 2\. Decrypt auth response — `{{url}}/cipher/decrypt_by_jwk?message={{responseJwe}}`\ Запит декриптує відповідь банку на своїй стороні за допомогою приватного ключа - userPrivateKey (котрий Мерчант генерує за інструкцією [Процес генерації комунікаційних JWK ключів клієнта](https://docs.merchant.alb.ua/autentifikaciya#proces-generaciyi-komunikaciinikh-jwk-klyuchiv-kliyenta) ) , щоб отримати серверний ключ - serverPublicKey у відкритому вигляді, котрий буде потрібен для виконання кроків 5 та 8. \ На Продакшн середовищі, Мерчант самостійно повинен виконувати декриптування на своїй стороні. 3\. Encrypt card number — `{{url}}/cipher/encrypt_by_jwk?message={{card_number}}`\ За допомогою платіжного ключа - paymentPublicKey, котрий Банк надає Мерчанту, відбувається криптування номеру картки клієнта.\ Для тестування можна скористатися допоміжним методом "/ecom/help/encrypt\_by\_jwk". \ На Продакшн середовищі, Мерчант самостійно повинен виконувати криптування на своїй стороні. 4\. Ecnrypt Date and Security cvv — `{{url}}/cipher/encrypt_by_jwk?message={{year_month_day}}`\ За допомогою платіжного ключа - paymentPublicKey, котрий Банк надає Мерчанту, виконується криптування терміну дії та cvvа. Передається у форматі: рік, місяць, cvva - "2603123"\ Для тестування можна скористатися допоміжним методом "/ecom/help/encrypt\_ru\_jwk". \ На Продакшн середовищі, Мерчант самостійно повинен виконувати криптування на своїй стороні. 5\. Encrypt create purchase request body — `{{url}}/cipher/encrypt_by_jwk?message={{body_request}}`\ {{body\_request}} - повинно відповідати обов'язковим вхідним параметрам [Запит проведення PURCHASE Крок 1](https://docs.merchant.alb.ua/platizhni-metodi-h2h/purchase/zapit-provedennya-purchase-krok-1) За допомогою розкриптованого серверного ключа - serverPublicKey, котрий отримано на кроках 1 і 2, виконується криптування тіла запиту для створення платежу на стороні Мерчанта. \ У відповідь отримуємо зашифроване тіло запиту - {{encryptJweT}}\ Для тестів допускається використання допоміжного методу "/ecom/help/encrypt\_ru\_jwk" 6\. Create Purchase — `{{url}}/ecom/execute_request/payments/v3/create/purchase`\ Запит відправляє зашифроване тіло запиту - {{encryptJweT}}, згенероване на кроці 5. \ У відповіді отримуємо зашифровану відповідь - {{responseJwe}}, котра буде потрібна для виконання кроку 7. 7\. Decrypt craet purchase response — `{{url}}/cipher/decrypt_by_jwk?message={{responseJwe}}`\ Запит декриптує відповідь від банку за допомогою приватного ключа - userPrivateKey, (котрий Мерчант генерує за інструкцією [Процес генерації комунікаційних JWK ключів клієнта](https://docs.merchant.alb.ua/autentifikaciya#proces-generaciyi-komunikaciinikh-jwk-klyuchiv-kliyenta)).\ У відповідь отримуємо розшифровану тіло відповіді на запит у кроці 6. 8\. Encrypt execute purchase request body — `{{url}}/cipher/encrypt_by_jwk?message={{body_request}}`\ {{body\_request}} - повинно відповідати обов'язковим вхідним параметрам [PURCHASE крок 2 ](https://docs.merchant.alb.ua/platizhni-metodi-h2h/purchase/zapit-provedennya-purchase-krok-2)\ За допомогою розкриптованого серверного ключа - serverPublicKey, котрий отримано на кроках 1 і 2, виконується криптування тіла запиту на проведення платежу. \ У відповідь отримуємо зашифроване тіло запиту - {{encryptJweT}}\ Для тестів допускається використання допоміжного методу "/ecom/help/encrypt\_by\_jwk" 9\. Execute Purchase — `{{url}}/ecom/execute_request/payments/v1/execute/purchase`\ Запит відправляє зашифроване тіло запиту - {{encryptJweT}}, згенероване на кроці 8. \ У відповіді отримуємо зашифровану відповідь - {{responseJwe}}, котра буде потрібна для виконання кроку 10. 10\. Decrypt execute purchase response — `{{url}}/cipher/decrypt_by_jwk?message={{responseJwe}}`\ Запит декриптує відповідь від банку за допомогою приватного ключа - userPrivateKey, (котрий Мерчант генерує за інструкцією [Процес генерації комунікаційних JWK ключів клієнта](https://docs.merchant.alb.ua/autentifikaciya#proces-generaciyi-komunikaciinikh-jwk-klyuchiv-kliyenta)).\ У відповідь отримуємо розшифровану тіло відповіді на запит у кроці 9. \ Для тестів дозволено використання допоміжного методу "/ecom/help/encrypt\_by\_jwk" # Приклад А2С колекції 1\. Authorize by virtual device —`{{url}}/api-gateway/authorize_virtual_device` \ Для запиту потрібен serviceCode, котрий ми передаємо Вам перед інтеграцією на проді.\ У відповідь повернеться зашифрований серверний ключ - serverPublicKey у форматі jwe, котрий буде потрібен для виконання кроку 2. \ На тесті, він вже присутній в даних колекції. 2\. Decrypt auth response — `{{url}}/cipher/decrypt_by_jwk?message={{responseJwe}}`\ Запит декриптує відповідь банку на своїй стороні за допомогою приватного ключа - userPrivateKey (котрий Мерчант генерує за інтрукцією [Процес генерації комунікаційних JWK ключів клієнта](https://docs.merchant.alb.ua/autentifikaciya#proces-generaciyi-komunikaciinikh-jwk-klyuchiv-kliyenta) ) , щоб отримати серверний ключ - serverPublicKey у відкритому вигляді, котрий буде потрібен для виконання крок 4.\ На Продакшн середовищі, Мерчант самостійно повинен виконувати декриптування на своїй стороні. 3\. A2C card number encrypt — `{{url}}/cipher/encrypt_by_jwk?message={{card_number}}`\ За допомогою платіжного ключа - paymentPublicKey, котрий Банк надає Мерчанту, відбувається криптування номеру картки клієнта.\ Для тестування можна скористатися допоміжним методом "/ecom/help/encrypt\_by\_jwk". \ На Продакшн середовищі, Мерчант самостійно повинен виконувати криптування на своїй стороні. 4\. A2C encrypt body — `{{url}}/cipher/encrypt_by_jwk?message={{body_request}}`\ {{body\_request}} - повинно відповідати обов'язковим вхідним параметрам [A2C](https://docs.merchant.alb.ua/platizhni-metodi-h2h/a2c)\ За допомогою серверного ключа - serverPublicKey, котрий отриманий на кроках 1 і 2, відбувається криптування тіла запиту на проведення платежу на стороні Мерчанта.\ У відповіді отримуємо зашифроване тіло запиту - {{encryptJweT}}, котре буде потрібне для виконання кроку 5.\ Для тестів допускається використання допоміжного методу "/ecom/help/encrypt\_ru\_jwk" 5\. A2C v3 — `{{url}}/ecom/execute_request/payments/v3/account_to_card`\ Запит відправляє зашифроване тіло - {{encryptJweT}}, згенероване на кроці 4. \ У відповіді отримуємо зашифровану відповідь - {{responseJwe}}, котра буде потрібна для виконання кроку 6. 6\. A2C v3 decrypt result — `{{url}}/cipher/decrypt_by_jwk?message={{responseJwe}}`\ Запит декриптує відповідь від банку за допомогою приватного ключа - userPrivateKey, (котрий Мерчант генерує за інструкцією [Процес генерації комунікаційних JWK ключів клієнта](https://docs.merchant.alb.ua/autentifikaciya#proces-generaciyi-komunikaciinikh-jwk-klyuchiv-kliyenta)).\ У відповідь отримуємо розшифровану тіло відповіді на запит у кроці 5. # Рекомендації щодо роботи з параметрами запитів **Важливо:**\ Якщо параметр **не є обов'язковим**, рекомендується **не передавати його** у запиті взагалі. У разі передачі необов'язкового параметра система автоматично застосовує до нього валідацію, зокрема: * Перевірку на відсутність значення (`null`); * Відповідність специфікації (формат, тип даних, діапазон значень тощо). **Наслідки:**\ Якщо клієнт передає необов'язковий параметр зі значенням `null` або у невірному форматі, система поверне помилку валідації, що може призвести до відмови обробки запиту. **Рекомендації для клієнтів:** 1. Уважно перевіряйте передавані параметри, звертаючи увагу на: * Обов'язковість параметра (позначено у документації як ***обов'язкові*** або ***не обов'язкові***); * Очікуваний тип даних та формат (наприклад, `string`, `ISO 8601 timestamp`). 2. Для необов'язкових параметрів: * Пропускайте параметр у запиті, якщо він не використовується; * Уникайте передачі явних `null` або порожніх значень. # Платіжні методи H2H # PURCHASE # Запит проведення PURCHASE Крок 1 {{url}}/ecom/execute\_request/payments/v3/create/purchase **Вхідні параметри:**
ПараметрОпиcФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
coinAmountсума платежу в копійках stringТак2000
txnType

під тип транзакціі

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

enumНіМожливі значення: NONCVV/noncvv
typeTokenвизначає тип токена при його створенніstringНі

можливі значення:

  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
desiredThreeDSModeознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
customerDataоб'єкт з customer даними objectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • не може містити “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправника string (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpIPv4 або IPv6 адреса відправникаstring (50)Ні123.12.12.12 або 2001:0db8:85a3:0000:0000:8a2e:0370:7334
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeІндекс відправникаstring (50)Ні 49000
**Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | 8a811df4-91e0-436b-a9ac-9b0772c96f28 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | IPv4 або IPv6 адреса відправника | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | **Приклад тіла запиту** ```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" } ``` **Приклад тіла відповіді без 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 } ``` **Приклад тіла відповіді з 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 } ``` # Запит проведення PURCHASE Крок 2 {{url}}/ecom/execute\_request/payments/v1/execute/purchase #### **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак1697008393082nW0c1jr6KVv
encryptedCardData

термін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvv

  • Якщо в параметр TxnType передається "NONCVV\noncvv" тоді у параметрі ecnryptedCardData потрібно передати лише YYMM без CVV
  • У іншому випадку якщо в TxnType нічого не педеається, тоді у параметрі encryptedCardData піотрбно обов'язкового передавати у форматі YYMMCVV
stringТак2503111 (розшифрований вигляд, у форматі YYMMCVV)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
#### **Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | creationDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | IPv4 або IPv6 адреса відправника | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | #### Приклад тіла запиту ```json { "operationId": "{{operationIdT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ``` #### Приклад тіла відповіді без 3DS ```json { "type": "PURCHASE", "rrn": "410114186775", "purpose": "purpose", "comment": "comment", "coinAmount": 1000, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "17127594157429eggOuxH5yl", "ecomOperationId": "63feb70f-8eb0-43cc-96c3-2e2eea9cec1e", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 35, "merchantRequestId": "1d4787d6-75cb-4c75-8466-59cc698e7bbf", "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", "paymentServiceType": "CARD", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "txnType": "NONCVV", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` #### Приклад тіла відповіді з 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": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712822536063CdDIRi8hhjq", "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, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` # A2C {{url}}/ecom/execute\_request/payments/v4/account\_to\_card Максимальна сума запиту операції А2С становить 29999.00 грн. Перевищення граничної суми супроводжуєтсья помилкою: ```json ERROR: @Payment coin amount exceeds the limit ``` **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberномер картки отримувача зашифрованый в JWE за допомогою платіжного ключаstringТак5473670000000304 (розшифрованний вид)
coinAmountсума платежу в копійкахintТак2000
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

commentДодаткова інформація про платіжstringНі///5555.25412
purposeПризначення платежуstringНіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
senderAccountРахунок відправникаstringНі2900000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Ні1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpIPv4 або IPv6 адреса відправникаstring (50)Ні123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Так1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувача

У разі, якщо фізична особа офіційно відмовилась від отримання ІПН, необхідно передавати альтернативний параметр — recipientPassport з коректними паспортними даними отримувача.		numeric(10)

Тільки 10 цифр		Так, якщо не вказан recipientPassport123456789
recipientPassportпаспорт отримувачаstring (255)Так, якщо не вказан recipientItnАН123456
recipientIpIPv4 або IPv6 адреса отримувачаstring (50)Ні123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
**Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | -------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | ACCOUNT\_2\_CARD | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 46 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | A2C | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | IPv4 або IPv6 адреса відправника | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | IPv4 або IPv6 адреса отримувача | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | **Приклад тіла запиту** ```json { "encryptedCardNumber":"{{encryptedPanT}}", "merchantId":"137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId":"{{requestUUIDT}}", "purpose":"за товар", "coinAmount": 120, "notificationUrl":"https://api-ecom-prod.bankalliance.ua/mock", "ecomComment": "string", "senderAccount": "UA12305299260022119999", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" }, "date": "{{currentdateT}}.00+00:00" } ``` **Приклад тіла відповіді** ```json { "type": "ACCOUNT_2_CARD", "rrn": "410208187340", "purpose": "за товар", "comment": null, "coinAmount": 120, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712822901491QtPAxAWOrrg", "ecomOperationId": "ff1ae4eb-d66d-467e-896d-01ed579bd040", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 46, "merchantRequestId": "cf17607f-c1f8-4e8e-abb2-5fd1b3dd17ec", "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": "A2C", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "CARD", "notificationEncryption": false, "senderAccount": "UA12305299260022119999", "recipientCardNumberMask": null, "senderCustomerId": null, "senderFirstName": "Petro", "senderLastName": "Petrenko", "senderMiddleName": null, "senderEmail": null, "senderCountry": "803", "senderRegion": null, "senderCity": "Kyiv", "senderStreet": "L.Ukrainki01", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "recipientCustomerId": null, "recipientFirstName": "TestFirstname", "recipientLastName": "TestLastName", "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": "803", "recipientRegion": null, "recipientCity": "Kyiv", "recipientStreet": "T. Shevchenka, 11", "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "recipientBankCode": null, "recipientPaymentSystem": null } ``` # C2A ``` ``` # Запит проведення C2A Крок 1 {{url}}/ecom/execute\_request/payments/v3/create/card\_to\_account **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumberНомер карти зашифрований в JWE за допомогою публічного платіжного ключаstringТак5573670000000304 (розшифрований вигляд)
coinAmountСума платежу в копійкахstringТак2000
txnType

Параметр вказан - введення cvv та його перевірка не відбувається

Параметр НЕ вказан - введення cvv та його перевірка відбувається

stringНі

Можливі значення:

NONCVV/noncvv

typeTokenвизначає тип токена при його створенніstringНі

можливі значення:

  • TOKEN_PER_CUSTOMER - токен створюється для конкретного клієнта (customer)
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)Ніhttps://support.google.com/
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

merchantCommissionСума комісіїintТак0
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі29000000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpIPv4 або IPv6 адреса відправникаstring (50)Ні123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpIPv4 або IPv6 адреса отримувачаstring (50)Ні123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334
recipientPhoneномер телефону отримувачаstring (20)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
**Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | IPv4 або IPv6 адреса відправника | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | IPv4 або IPv6 адреса отримувача | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | **Приклад тіла запиту** ```json { "merchantId":"467c8a10-c705-11ed-afa1-0242ac120002", "merchantRequestId": "{{requestUUIDT}}", "encryptedCardNumber": "{{encryptedPanT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "coinAmount": "1000", "comment": "comment", "purpose": "purpose", "merchantCommission": "0", "desiredThreeDSMode": "MUST" "notificationUrl": "", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" } "date": "{{currentdateT}}.00+00:00" } ``` # Запит проведення C2A Крок 2 {{url}}/ecom/execute\_request/payments/v1/execute/card\_to\_account #### **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
encryptedCardData

термін дії карти та cvv2 зашифровані в JWE. Перші 4 символи ExpDate, наступні 3 символи cvv

  • Якщо в параметр TxnType передається "NONCVV\noncvv" тоді у параметрі ecnryptedCardData потрібно передати лише YYMM без CVV
  • У іншому випадку якщо в TxnType нічого не педеається, тоді у параметрі encryptedCardData піотрбно обов'язкового передавати у форматі YYMMCVV
stringТак2503111 (розшифрований вигляд)
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
#### **Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | IPv4 або IPv6 адреса відправника | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | IPv4 або IPv6 адреса отримувача | string |

123.12.12.12
або
2001:0db8:85a3:0000:0000:8a2e:0370:7334

| | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | | externalCardToken | id токену | string | tmkEYenZSa8FV03aawVXxbep | **Приклад тіла запиту** ```json { "operationId": "{{operationIdT}}", "encryptedCardData": "{{encryptedDateAndSecurityT}}", "browserInfo": { "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36", "browserLanguage": "en-US,en", "browserColorDepth": "24", "browserScreenHeight": "800", "browserScreenWidth": "1280", "browserTZ": "-180" }, "date": "{{currentdateT}}.00+00:00" } ``` #### Приклад тіла відповіді без 3DS ```json { "type": "CARD_2_ACCOUNT", "rrn": "410208187342", "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823122106xnUK8T9Z9d8", "ecomOperationId": "a4842af1-ab80-4685-9cef-0d97aedbb99f", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "0d7a190d-9cfc-4b01-9615-e207ebe8b23b", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` **Приклад тіла відповіді з 3DS** ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": 1010, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712823334404zicRAYWIAm1", "ecomOperationId": "412ac336-aac5-43b5-8d35-b57ffa9d53ff", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "60cb4f84-add5-48c6-984f-7b20a6b50c75", "transactionCurrency": "980", "merchantCommission": 67, "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": "C2A", "paymentServiceType": "CARD", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "db259063-61ba-4681-a7e9-65fbbebead2d", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712823334404zicRAYWIAm1", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null, "externalCardToken": "tmkEYenZSa8FV03aawVXxbep" } ``` # ApplePay decrypted #### # PURCHASE # Запит проведення платежу Крок 1 {{url}}/ecom/execute\_request/payments/v3/apple\_pay/purchase **Вхідні JSON параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
Об’єкт paymentData, який необхідно закриптувати платіжним ключем
applicationPrimaryAccountNumberномер рахунку картки, з якої фінансується ця транзакціяstringТак4420642424203999
applicationExpirationDateТермін дії картки у форматі YYMMDDstringТак261001
currencyCodeЦифровий код валюти ISO 4217stringТак980
transactionAmountсума платежу в копійкахstringТак2000
cardholderNameІм'я власника карткиstringНіІванченко Петро
deviceManufacturerIdentifierHex-encoded device manufacturer identifierstringТак1
paymentDataType stringТак3DSecure
paymentData
onlinePaymentCryptogramКриптограма платежу у форматі Base64stringТакAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorECI indicatorstring(1)Ні7
Додаткові дані для проведення платежу
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
**Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | **Приклад об’єкту paymentData** ```json { "applicationPrimaryAccountNumber":"{{applePayCardNumber}}", "applicationExpirationDate":"{{applePayDate}}", "currencyCode":"980", "transactionAmount":"100", "cardholderName":"{{cardholderName}}", "deviceManufacturerIdentifier":"1255548888hfhhbbk", "paymentDataType":"3DSecure", "paymentData":{ "onlinePaymentCryptogram":"AVn0rK8BiDxN2D/w2j8LMAABAAA=", "eciIndicator":"7"} } ``` **Приклад тіла запиту** ```json { "paymentData": "{{encryptedPaymentData}}", "merchantRequestId": "{{requestUUIDT}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "", "resultRedirectUrl": "", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "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" } ``` **Приклад тіла відповіді без 3DS** ```json { "type": "PURCHASE", "rrn": null, "purpose": "назначение", "comment": "тестовыйкомент", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": null, "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 35, "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": null, "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 } ``` **Приклад тіла відповіді з 3DS** ```json { "type": "PURCHASE", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712824711120IbbgGHLPNCm", "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 35, "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8", "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 } ```
# Запит проведення платежу Крок 2 (3DS) {{url}}/ecom/execute\_request/payments/v1/apple\_pay\_3ds/purchase #### **Вхідні JSON параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
#### **Вихідні JSON параметри:** | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | #### **Приклад тіла запиту** ```json { "operationId": "", "browserInfo": { "browserAcceptHeader":", "browserUserAgent": "", "browserLanguage": "", "browserColorDepth": "", "browserScreenHeight": "", "browserScreenWidth": "", "browserTZ": "" }, "date": "{{currentdateT}}.00+00:00" } ``` #### **Приклад тіла відповіді з 3DS** ```json { "type": "PURCHASE", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712824711120IbbgGHLPNCm", "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 35, "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712824711120IbbgGHLPNCm", "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 } ``` # C2A # Запит проведення C2A Крок 1 {{url}}/ecom/execute\_request/payments/v3/apple\_pay/card\_to\_account **Вхідні JSON параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
Об’єкт paymentData, який необхідно закриптувати платіжним ключем
applicationPrimaryAccountNumberномер рахунку картки, з якої фінансується ця транзакціяstringТак4420642424203999
applicationExpirationDateТермін дії картки у форматі YYMMDDstringТак261001
currencyCodeЦифровий код валюти ISO 4217stringТак980
transactionAmountсума платежу в копійкахstringТак2000
cardholderNameІм'я власника карткиstringНіІванченко Петро
deviceManufacturerIdentifierHex-encoded device manufacturer identifierstringТак1
paymentDataType stringТак3DSecure
paymentData
onlinePaymentCryptogramКриптограма платежу у форматі Base64stringТакAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorECI indicatorstring(1)Ні7
Додаткові дані для проведення платежу
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)Так

За замовчуванням SHOULD

Можливі значення:

  • MUST - мерчант вимагає проведення платежу з 3DS
  • MUST_NOT - примусова операція без 3DS
  • SHOULD - якщо картка підтримує 3DS, то робимо перевірку
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+00:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
recipientAccountРахунок отримувачаstringНі2900000000000
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
ТакІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50) Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
recipientCustomerIdId клієнта отримувачаstring (255)Ні1258728c1
recipientFirstNameім'я отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
recipientLastNameпрізвище отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
recipientMiddleNameпо-батькові отримувача

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
recipientEmailпошта отримувачаstring (256)Ніmail@gmail.com
recipientСountryкраїна отримувачаstring (3) ISO 3166, 804 (Ukraine)Ні804
recipientRegionобласть отримувачаstring (255)НіКиївська
recipientСityмісто отримувачаstring (25)НіКиїв
recipientStreetвулиця отримувачаstring (35)НіСічових стрільців
recipientAdditionalAddressдодаткові дані адреси отримувача (поверх, номер дому, квартира)string (255)Ні23
recipientItnіпн отримувачаstring (20)Ні123456789
recipientPassportпаспорт отримувачаstring (255)НіАН123456
recipientIpspace.vars.recipientIP_desctiptionstring (50)Ніspace.vars.recipientIP_example
recipientPhoneномер телефону отримувачаstring (50)Ні380630000000
recipientBirthdayдень народження отримувачаstring (50)Ні31.12.2000
recipientGenderГендер отримувачаstring (50)НіMale/Female
recipientZipCodeіндекс отримувачаstring (50)Ні49000
**Вихідні параметри** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingMerchantId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | space.vars.recipientIP\_desctiption | string | space.vars.recipientIP\_example | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | **Приклад об’єкту paymentData** ```json { "applicationPrimaryAccountNumber":"{{applePayCardNumber}}", "applicationExpirationDate":"{{applePayDate}}", "currencyCode":"980", "transactionAmount":"100", "cardholderName":"{{cardholderName}}", "deviceManufacturerIdentifier":"1255548888hfhhbbk", "paymentDataType":"3DSecure", "paymentData":{ "onlinePaymentCryptogram":"AVn0rK8BiDxN2D/w2j8LMAABAAA=", "eciIndicator":"7"} } ``` **Приклад тіла запиту** ```json { "paymentData": "{{encryptedPaymentData}}", "merchantRequestId": "{{requestUUIDT}}", "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "resultRedirectUrl": "", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "customerData": { "senderCustomerId": "1234567", "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", "recipientCustomerId": "1234567", "recipientFirstName": "Yura", "recipientLastName": "Bura", "recipientMiddleName": "TestMiddle", "recipientEmail": "res@gmail", "recipientCountry": "804", "recipientRegion": "res_reg", "recipientCity": "res_dnipro", "recipientStreet": "res_street", "recipientAdditionalAddress": "res_addres", "recipientItn": "res_iin", "recipientPassport": "res_pasport", "recipientIp": "165.222.87.224", "recipientPhone": "380967542344", "recipientBirthday": "12/12/2000", "recipientGender": "Female", "recipientZipCode": "77777" }, "date": "{{currentdateT}}.00+00:00" } ``` **Приклад тіла відповіді без 3DS** ```json { "type": "CARD_2_ACCOUNT", "rrn": "410209187456", "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826505345NY4bmiIDrE5", "ecomOperationId": "21931655-17db-44e3-bd2f-212cbf5069c9", "merchantName": null, "approvalCode": null, "status": "SUCCESS", "transactionType": 62, "merchantRequestId": "586fc1f5-f647-4800-94e1-a9e65a68d424", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": "MUST_NOT", "statusThreeDs": null, "threeDSServerTransId": null, "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ``` **Приклад тіла відповіді з 3DS** ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826655741bHtPOJY9BvI", "ecomOperationId": "92f0ccdd-48fb-43d8-9ee4-f4bd2e295f86", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "45f336e8-f58d-43d5-9cdd-c3a06ba794c5", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "a011f12f-ddfa-4629-b786-4aa427f7210f", "redirect3dsUrl": null, "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ``` # Запит проведення c2a Крок 2 (3DS) {{url}}/ecom/execute\_request/payments/v1/apple\_pay\_3ds/card\_to\_account #### **Вхідні JSON параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузера objectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запиту stringТак, якщо операція потребує 3DS text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DS Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DS en-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS 24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS 1280
browserTZTimezone браузера stringТак, якщо операція потребує 3DS -180
#### **Вихідні параметри** | Параметр | Опис | Формат даних | Приклад | | -------------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | CARD\_2\_ACCOUNT | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 62 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | C2A | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | | recipientCustomerId | Id клієнта відправника | string | 1258728c1 | | recipientFirstName | ім'я отримувача | string | Іваненко | | recipientLastName | прізвище отримувача | string | Іван | | recipientMiddleName | по-батькові отримувача | string | Іванович | | recipientEmail | пошта отримувача | string | | | recipientCountry | країна отримувача | string | Україна | | recipientRegion | область отримувача | string | Київська | | recipientCity | місто отримувача | string | Київ | | recipientStreet | вулиця отримувача | string | Січових стрільців | | recipientAdditionalAddress | додаткові дані адреси отримувача (поверх, номер дому, квартира) | string | 23 | | recipientItn | іпн отримувача | string | 123456789 | | recipientPassport | паспорт отримувача | string | АН123456 | | recipientIp | IPv4 адреса отримувача | string | 123.12.12.12 | | recipientPhone | номер телефону отримувача | string | 380630000000 | | recipientBirthday | день народження отримувача | string | 31.12.2000 | | recipientGender | гендер отримувача | string | M | | recipientZipCode | індекс отримувача | string | 12000 | | recipientBankCode | назва банку емітента отримувача | string | BANK\_ALLIANCE | | recipientPaymentSystem | назва мпс емітента отримувача | string | MasterCard | | recipientCardNumberMask | маскований номер карти отримувача | string | 5573\*\*\*\*\*\*\*\*0304 | #### **Приклад тіла запиту** ```json { "operationId": "", "browserInfo": { "browserAcceptHeader":", "browserUserAgent": "", "browserLanguage": "", "browserColorDepth": "", "browserScreenHeight": "", "browserScreenWidth": "", "browserTZ": "" }, "date": "{{currentdateT}}.00+00:00" } ``` #### **Приклад тіла відповіді** ```json { "type": "CARD_2_ACCOUNT", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712826797010P-juYeIJRx3", "ecomOperationId": "cbf7e357-d216-46ca-a885-71d917b0e405", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 62, "merchantRequestId": "004dbc84-f3c1-4cc7-b7fb-50a3b0b6fa7e", "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": "C2A", "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "senderCardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "e13f7b12-fcc9-4028-9307-0749d7076bdd", "redirect3dsUrl": "https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1712826797010P-juYeIJRx3", "recipientAccount": null, "senderCustomerId": null, "senderFirstName": "FirstName", "senderLastName": "Name", "senderMiddleName": null, "senderEmail": null, "senderCountry": "Ukraine", "senderRegion": null, "senderCity": "City", "senderStreet": "Str.", "senderAdditionalAddress": null, "senderItn": null, "senderPassport": null, "senderIp": null, "senderPhone": null, "senderBirthday": null, "senderGender": null, "senderZipCode": null, "senderBankCode": null, "senderPaymentSystem": null, "recipientCustomerId": null, "recipientFirstName": null, "recipientLastName": null, "recipientMiddleName": null, "recipientEmail": null, "recipientCountry": null, "recipientRegion": null, "recipientCity": null, "recipientStreet": null, "recipientAdditionalAddress": null, "recipientItn": null, "recipientPassport": null, "recipientIp": null, "recipientPhone": null, "recipientBirthday": null, "recipientGender": null, "recipientZipCode": null } ``` # ApplePay encrypted
1. Клієнт натискає кнопку «Сплатити замовлення» на сайті/в застосунку. 2. WebPage запускає скрипт Запит підтримки Apple Pay, щоб перевірити, чи підтримується Apple Pay на цій сторінці. 3. Якщо пристрій клієнта не підтримує оплату через аРay, клієнт не зможе скористатися цим способом оплати, і запит буде відхилено. 4. Якщо підтримується, webPage надсилає опціональний Запит отримання даних мерчанта в Apple Pay. Можливо зробити hard-coded даних Apple Pay на стороні мерчанта 5. WebPage запускає скрипт на валідацію мерчанта через Apple Pay для підтвердження даних. 6. Apple Pay повертає callback з параметром validationUrl. 7. Клієнт натискає кнопку Сплатити з Apple Pay, підтверджуючи вибір цього способу оплати. 8. Встановлюється сесія з Apple Pay, і пристрій клієнта готовий до взаємодії з Apple Pay. 9. У відповідь на встановлення сесії Apple передає токенізовані дані карт клієнта. 10. Клієнту відображається список карток на пристрої, які можна використовувати для оплати. 11. Клієнт обирає картку, яку хоче використати для оплати. 12. Скрипт на пристрої клієнта взаємодіє з сервером Apple для отримання зашифрованого paymentToken 13. Викликається автентифікація клієнта через біометрію або пароль. 14. Apple формує paymentToken, який передається на webPage для подальшої обробки. 15. WebPage надсилає Запит проведення платежу, використовуючи отриманий токен. 16. Якщо необхідна перевірка через 3D Secure (3DS), починається цей процес. Якщо 3DS не потрібен, транзакція продовжується. 17. Гілка без 3DS: * Виконується авторизація платежу. * Формується відповідь на запит проведення платежу. 18. Гілка з 3DS: * Виконується додаткова перевірка через 3DS. * Після завершення перевірки надається відповідь на запит проведення платежу з параметром redirect3dsUrl. * webPage перенаправляє клієнта на сторінку redirect3dsUrl для підтвердження 3DS. * Клієнт підтверджує транзакцію через 3DS. * Транзакція авторизується. 19. Надсилається callback мерчанту, на вказаний notificationUrl, з даними про проведену транзакцію. 20. Клієнту відображається сторінка результату, яка інформує про завершення оплати.
# Запит підтримки aPay на сторінці Необхідно виконати скрипт для перевірки підтримки оплати за допомогою Арау на сторінці ```javascript if (!window.ApplePaySession || !window.ApplePaySession?.canMakePayments?.()) { return
Apple Pay is not supported on this device
; } ``` # Запит отримання данних мерчанта aPау {{url}}/ecom/execute\_request/payments/v1/applepay/merchant/get Запит для отримання мерчантом даних та налаштувань аРау мерчанта Опціональний запит. Можливий hard-coded данних аРау на стороні мерчанта **Вихідні параметри** | Параметр | Опиc | Формат даних | Приклад | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ | | merchantCapabilities | визначає, які можливості підтримує мерчант для обробки платежів через Apple Pay | object | supports3DS, supportsCredit, supportsDebit | | supportedNetworks | визначає список платіжних мереж (типів карток), які підтримуються мерчантом для обробки платежів через Apple Pay. | object | visa, masterCard | | countryCode | дволітерний код країни (згідно зі стандартом ISO 3166-1 alpha-2), де буде здійснено транзакцію через Apple Pay. | string | UA | | currencyCode | визначає валюту, в якій буде здійснено платіж через Apple Pay. Трилітерний код валюти згідно зі стандартом ISO 4217. | string | UAH | **Приклад тіла запиту** ```json { } ``` **Приклад тіла відповіді** ```json { "merchantCapabilities": [ "SUPPORTS_3DS" ], "supportedNetworks": [ "VISA" ], "countryCode": [ "UA" ], "currencyCode": "UAH" } ``` # Запит валідації мерчанта Запит через сервер проксі до сервера apple pay для отримання валідації мерчанта `fetchAppleSessionAPI` та `purchaseApplePayAPI` - функції які викликають API, використовуйте свої функції для роботи з апі, або `fetch` Нижче описано приклад обробника події кліку на кнопку оплати через ApplePay: ```javascript const onApplePayButtonClicked = async () => { // Додаткова перевірка на те чи підтримує браузер епл пей if (!window.ApplePaySession) { return; } // Обʼєкт для створення сесії const request = { countryCode: 'UA', currencyCode: 'UAH', merchantCapabilities: ['supports3DS'], supportedNetworks: ['visa', 'masterCard'], total: { label: 'PoC Merchant Apple Pay', // назва мерчанта type: 'final', amount: amount.toString(), // сума транзакції }, }; // Створення сесії const session = new window.ApplePaySession(3, request); session.onvalidatemerchant = async (event: any) => { try { // Виклик запиту для створення сесії https://docs.merchant.alb.ua/platizhni-metodi-h2h/applepay-encrypted/zapit-vstanovlennya-sesiyi-v-apau const response = await fetchAppleSessionAPI(event.validationURL, applePayMercantId, { deviceId, refreshToken }); session.completeMerchantValidation(response.applePaySessionData); } catch (error) { // обробка помилки запиту для створення сесії } }; session.onshippingmethodselected = () => { const newTotal = { label: 'PoC Merchant Apple Pay', // назва мерчанта type: 'final', amount: amount.toString(), // сума транзакції }; session.completeShippingMethodSelection(window.ApplePaySession.STATUS_SUCCESS, {}, newTotal); }; // подія коли користувач успішно вибрав картку для оплати session.onpaymentauthorized = async (event: any) => { const result = { status: window.ApplePaySession.STATUS_SUCCESS, }; session.completePayment(result); try { // виклик запиту проведення платежу https://docs.merchant.alb.ua/platizhni-metodi-h2h/applepay-encrypted/zapit-provedennya-platezhu const response = await purchaseApplePayAPI( { paymentToken: event.payment.token, // інші дані які потрібні для виклику } { deviceId, refreshToken, serverPublicKey } ); } catch (error) { // обробка помилки запиту для проведення платежу } }; session.begin(); }; ``` # Запит встановлення сесії в aPау Запит за допомогою якого встановлюється сесія в aPау. У відповідь повертаються токенізовані картки клієнта {{url}}/ecom/execute\_request/payments/v1/apple\_pay/get\_session **Вхідні параметри** | Параметр | Опис | Формат даних | Обов'язковіть | Приклад | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- | ---------------------------------------------------------------------------- | | validationUrl | URL-адреса, на яку Apple надсилає запит для валідації сесії платежу | string(1000) | Так | [apple-pay-gateway.apple.com](http://apple-pay-gateway.apple.com/) | | merchantId | apple merchant identifier. параметр отримуєте від банка | string(255) | Так | YN\_O1aEEFqF6Jal4B5qHy7b7 | | domain | доменне ім'я (URL), яке використовується для авторизації | string(255) | Так | [checkout.develop.bankalliance.ua](http://checkout.develop.bankalliance.ua/) | | merchantRequestId |

унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектом

| string(50) | Так | merchantRequestId\_cfc297a1e1e91 | **Вихідні параметри** | Параметр | Опис | Формат даних | Приклад | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------- | | applePaySessionData | | object | | | epochTimestamp | час початку дії сесії (у мілісекундах) | string | 2024-09-30T15:06:05.274+03:00 | | expiresAt | час закінчення дії сесії (у мілісекундах) | string | 2024-09-30T16:06:05.274+03:00 | | merchantSessionIdentifier | ідентифікатор сесії мерчанта | string | SSHB8FD6B91EB2B4C909990AE16F652A8BB\_BB8E.. | | nonce | унікальний токен, який використовується для безпеки | string | 0162edba | | merchantIdentifier | ідентифікатор зареєстрованого мерчанта | string | C20AFFF8FC4092AB90F781FFA08E5C49.. | | domainName | доменне ім'я, де була ініційована сесія | string | checkout.develop.bankalliance.ua | | displayName | ім'я мерчанта, яке буде відображене | string | merchant.aliiancebank.ua | | signature | підпис, який використовується для підтвердження дійсності сесії | string | 308006092a864886f70d010702a080308002010.. | | merchantRequestId |

унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектом

| string | merchantRequestId\_cfc297a1e1e91 | | applePaySessionId | ідентифікатор сесії Apple Pay | string | f40b099c-38f3-46f9-a989-52818018f557 | **Приклад тіда запиту** ```json { "merchantId": "YN_O1aEEFqF6Jal475qHy7b7", "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "merchantRequestId": "merchantRequestId_cfc297a1e1e91", "domain": "checkout.develop.bankalliance.ua" } ``` **Приклад тіла відповіді** ```json { "applePaySessionData": { "epochTimestamp": "2024-09-30T15:06:05.274+03:00", "expiresAt": "2024-09-30T16:06:05.274+03:00", "merchantSessionIdentifier": "SSHB8FD6B91EB2B4C52A8BB_BB8E62003687F8FCC159B2B83AAFC02DB625F1F1E3997CCC2FE2CFD11F636558", "nonce": "016edba", "merchantIdentifier": "C20AFFF8FC4092AB90F781FFA08E5C49434674F64EB2A187A7FE3094EB1C8EF5", "domainName": "checkout.develop.bankalliance.ua", "displayName": "merchant.aliiancebank.ua", "signature": "308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a003020102020816634c8b0e305717300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3234303432393137343732375a170d3239303432383137343732365a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020349003046022100c6f023cb2614bb303888a162983e1a93f1056f50fa78cdb9ba4ca241cc14e25e022100be3cd0dfd16247f6494475380e9d44c228a10890a3a1dc724b8b4cb8889818bc308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018730820183020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020816634c8b0e305717300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3234303933303132303630355a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d010904312204204d17711f18e7059ad3384feba35ac718f0f948cdcce8c32126d4508ef685bf55300a06082a8648ce3d04030204463044022027a6f4b471800884326cb9c69705f3d05ba840086c7ef87b7b11014252e2acd30220539dca31d5847a8db531a210cc49f833a04ce7fd39fa64eb1d5d607384183078000000000000" }, "merchantRequestId": "merchantRequestId_cfc297a1e1e91", "applePaySessionId": "f45b099c-38f3-46f9-a989-52818018f557" } ``` # Запит проведення платежу {{url}}/ecom/execute\_request/payments/v1/apple\_pay/token/purchase **Вхідні параметри:** | Параметр | Опис | Формат даних | Обов'язковість | Приклад | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Об’єкт **paymentToken** | | object | Так | | | Об'єкт **paymentData** | | object | Так | | | data |

зашифрований блок даних, який містить деталі платіжної картки, інформацію про транзакцію, суму, валюту тощо

| string | Так | CLtkH05O6bkhXkEdN/0LGtJQGeNT+9PMDp... | | transactionIdentifier | унікальний ідентифікатор транзакції, який генерується Apple Pay для кожного платежу | string | Так | 2d4921ff56bf979b76c53b3... | | signature | підпис, який підтверджує, що дані в полі `data` не були змінені після шифрування | string | Так | MIAGCSqGSIb3DQEHAqCAMIACA... | | version |

версія формату paymentData, яка вказує на специфікацію Apple Pay для зашифрованих даних.

| string | Так | EC\_v1 | | Об'єкт **header** | | object | Так | | | publicKeyHash | хеш відкритого ключа мерчанта, який підтверджує, що дані були зашифровані для конкретного мерчанта | string | Так | 1LSYfOslX5QlRIUAidZju... | | applicationData | додаткові дані, які мерчант хоче передати разом із запитом на оплату | string | Ні | | | wrappedKey | зашифрований симетричний ключ, який використовується для додаткового захисту платіжних даних | string | Ні | MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8... | | ephemeralPublicKey | тимчасовий відкритий ключ, який використовується для шифрування даних | string | Так | MFkwEwYHKoZIzj0CAQYIKoZI.. | | transactionId | унікальний ідентифікатор транзакції | string | Так | 2d4921ff56bf979b76c53b3a.. | | Об'єкт **paymentMethod** | | object | Так | | | displayName | ім'я мерчанта, яке відображається користувачу під час проведення платежу | string | Так | Merchant 5538 | | network | платіжна мережа, яка використовується для транзакції | string | Так | visa, masterCard | | type | тип транзакції, який визначає, як проводиться платіж | string | Так | debit, credit | | Додаткові дані для проведення платежу | | object | | | | merchantRequestId | унікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статусоперації якщо запит закінчився невідомою помилкою чи дісконектом | string(36) | Так | 137d9304-0368-11ed-b939-0242ac120002 | | merchantId | Id мерчанту згенерований в Єкомі | string(36) | Так | 137d9304-0368-11ed-b939-0242ac120002 | | desiredThreeDSMode | Ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string (50) | Так | За замовчуванням SHOULD | | resultRedirectUrl | Url для редиректа клієнта після проходження 3DS аутентифікації | string (1000) | Ні | [![](https://docs.merchant.alb.ua/~gitbook/image?url=https%3A%2F%2Fsupport.google.com%2Ffavicon.ico\&width=300\&dpr=4\&quality=100\&sign=ae88f641\&sv=1)Google Help](https://support.google.com/) | | notificationUrl | url, на який буде відправлено CallBack | string (255) | Ні | [https://merchant.notification\_url](https://merchant.notification_url/) | | notificationEncryption | ознака криптування данних CallBack | string | Ні |

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | date | дата та час платежу | string | Так | {{currentdateT}}.00+00:00 | | comment | додаткова опис операції яку заповнює клієнт мерчанта | string (1000) | Ні | ///5555.25412 | | purpose | призначення платежу яке заповнює мерчант | string (255) | Ні | За товар | | merchantComment | додаткова інформація\коментар мерчанта по замовленню |

tring(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

| Ні | merchant Comment id 1258728c1 | | customerData | об'єкт з customer даними | object | Так | | | senderCustomerId | Id клієнта відправника | string (255) | Так | 1258728c1 | | senderFirstName | ім'я відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іваненко | | senderLastName | прізвище відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іван | | senderMiddleName | по-батькові відправника |

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - ' який в: utf 16 - u0027 utf32 - 00000027
| Ні | Іванович | | senderEmail | пошта відправника | string (256) | Ні | | | senderСountry | країна відправника | string (3) ISO 3166, 804 (Ukraine) | Ні | 804 | | senderRegion | область відправника | string (255) | Ні | Київська | | senderСity | місто відправника | string (25) | Ні | Київ | | senderStreet | вулиця відправника | string (35) | Ні | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string (255) | Ні | 23 | | senderItn | іпн відправника | string (20) | Ні | 123456789 | | senderPassport | паспорт відправника | string (255) | Ні | АН123456 | | senderIp | space.vars.senderIP\_description | string (50) | Ні | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string (20) | Ні | 380630000000 | | senderBirthday | день народження відправника | string (50) | Ні | 31.12.2000 | | senderGender | Гендер відправника | string (50) | Ні | Male/Female | | senderZipCode | індекс відправника | string (50) | Ні | 49000 | **Вихідні параметри:** | Параметр | Опис | Формат даних | Приклад | | ---------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | прізвище відправника | string | Іваненко | | senderLastName | ім'я відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | **Приклад тіла запиту** ```json "paymentToken": { "paymentData": { "data": "CLtkH05O6bkhXkEdN/0LGtJQGeNT+9PMDpC0oITlXse1wZby4EtRwNhWz5Cp12ZjKGvsVX0aHeNsyULl8ca3fbVdaYA6b6MGQ7oPBVVyecRo0dl3p8Xhm5oHx9NcI+KTgx2oAZAGxylAAVADKFhYY0xo81yPm8KIhnv8rsKmCyL3d/Vhmlznfr7HgkmmXVhF/YoMp1FDdO6SWQkQBbM8Bu30DQBxPKJAHWGhWTBx8ufWKx+P7ErP2dROhQbFKZEtAvpNOS1o4CV5l4lLfNjiRb+QO85aPbbp80ohD6D9xjCP30lpP8JnWsJIBB3p158SId4Fz95152cvpirqZkOinCfHMLPM371Ent9e50UjQj20d4HVkV6XfwZpRUj8/UYFcemqG+w/VNp7WUFePA==", "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCBZjTIsOMFcXMAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yNDA0MjkxNzQ3MjdaFw0yOTA0MjgxNzQ3MjZaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAxvAjyyYUuzA4iKFimD4ak/EFb1D6eM25ukyiQcwU4l4CIQC+PNDf0WJH9klEdTgOnUTCKKEIkKOh3HJLi0y4iJgYvDCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIIFmNMiw4wVxcwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI0MDkyNTE0NTIxMFowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIBpIgKQboEHgDkNYiHuoxqtps5oRjZAr/0YLZmSz2pq6MAoGCCqGSM49BAMCBEgwRgIhAIkjGYfkIWMHGQ4y3xMqF3qvRKc2KwWaqBuTaf8iSlmvAiEAje5izLs9ItZTUCob80n+W3/oOQD0MmdrbIU75mztQ6YAAAAAAAA=", "header": { "publicKeyHash": "1LSYfOslX5QlRIUAidZjuXuz3w3KHgpnF7RZXPOPAbc=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAECWpX1FFd7LTXechNBSUtq9OVotLI1zCSgdr5fUWYVt4hJpl1qFSIPPOpbtOhhugrF+ZmZVvbmUe9gNscRUHOtw==", "transactionId": "2d4921ff56bf979b76c53b3a6f79125883546ace6548889a0468209741cc0f33" }, "version": "EC_v1" }, "paymentMethod": { "displayName": "MasterCard 5538", "network": "MasterCard", "type": "debit" }, "transactionIdentifier": "2d4921ff56bf979b76c53b3a6f79125883546ace6548889a0468209741cc0f33" }, "desiredThreeDSMode": "MUST_NOT", "notificationUrl": "https://www.google.com.ua/?hl=ru", "resultRedirectUrl": "https://www.google.com.ua/?hl=ru", "purpose": "purpose", "comment": "comment", "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "merchantRequestId": "d7e27615-4357-4647-a9b8-3488d48be594", "date": "2024-09-25 18:54:37.00+03:00", "customerData": { "senderCustomerId": "1231234124142", "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" } } } ``` **Приклад тіла відповіді без 3DS** ```json { "type": "PURCHASE", "rrn": null, "purpose": "назначение", "comment": "комент", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": null, "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9", "merchantName": null, "approvalCode": null, "status": "PENDING", "transactionType": 35, "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST_NOT", "threeDSMode": null, "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 } ``` **Приклад тіла відповіді з 3DS** ```json { "type": "PURCHASE", "rrn": null, "purpose": "purpose", "comment": "comment", "coinAmount": null, "merchantId": "137d9304-0368-11ed-b939-0242ac120002", "operationId": "1712824711120IbbgGHLPNCm", "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b", "merchantName": null, "approvalCode": null, "status": "REQUIRED_3DS", "transactionType": 35, "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686", "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://api-ecom-prod.bankalliance.ua/mock", "paymentServiceType": "APPLE_PAY", "notificationEncryption": false, "cardNumberMask": null, "desiredThreeDSMode": "MUST", "threeDSMode": "MUST", "statusThreeDs": null, "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8", "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 } ```

# GooglePay™ decrypted GooglePay™ API ## Для мерчанта: #### 1.Налаштовувати GooglePay™ до веб-сайту, по інструкціям, розміщених за посиланнями: Документація: [https://developers.google.com/pay/api/web
](https://developers.google.com/pay/api/web)Вимоги з брендування: #### 2.При оплаті клієнтом послуги, розшифрувати об'єкт [CARD](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#card) за допомогою [PublicKey](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#step-two) та [PrivateKey](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru#step-three) Приклад картки: ```json { "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "PAN_ONLY", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2025 }, "gatewayMerchantId": "some-merchant-id", "messageId": "some-message-id", "messageExpiration": "1759309000000" } Приклад криптованого PAN: { "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "CRYPTOGRAM_3DS", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2025, "cryptogram": "AAAAAA...", "eciIndicator": "5" }, "messageId": "some-message-id", "messageExpiration": "1759309000000" } ``` #### 3.Об’єкт paymentData який описаний в пункті 2, необхідно закриптувати платіжним ключем # PURCHASE # Запит проведення purchase Крок 1 {{url}}/ecom/execute\_request/payments/v3/google\_pay/purchase **Вхідні параметри:**
ПараметрОписФормат данихОбов'язковістьПриклад
Об'єкт PaymentData (шифрування зі сторони мерчанта )
paymentMethodТип платіжних облікових даних. Наразі CARD підтримується лишеstringТакCARD
authMethod

Спосіб аутентифікації карткової операції.

PAN_ONLY - PAN картки

CRYPTOGRAM_3DS - криптованний PAN

stringТакCRYPTOGRAM_3DS
panНомер особового рахунку, що стягується. Цей рядок містить лише цифри.stringТак1111222233334444
expirationMonthМісяць закінчення терміну дії картки, де 1 означає січень, 2 означає лютий і так далі.numberТак10
expirationYearЧотиризначний рік закінчення терміну дії картки, наприклад 2020.numberТак2025
cryptogramКриптограма 3-D Secure.stringНіAVn0rK8BiDxN2D/w2j8LMAABAAA=
eciIndicatorЦей рядок не завжди присутній. Він повертається лише для транзакцій із автентифікованими маркерами пристроїв на Androidstring(1)Ні4
messageIdУнікальний ідентифікатор, який ідентифікує повідомлення на випадок, якщо його потрібно буде відкликати або знайти пізніше.stringНіsome-message-id
messageExpirationДата й час закінчення терміну дії повідомлення в мілісекундах UTC з епохи. Інтегратори повинні відхиляти будь-які повідомлення, термін дії яких минув.stringНі1759309000000
Додаткові стандартні об'єкти для проведення Purchase
merchantRequestIdунікальний ідентифікатор згенерований системою мерчанта, використовується для можливості дізнатися статус операції якщо запит закінчився невідомою помилкою чи дісконектомstring(36)Так137d9304-0368-11ed-b939-0242ac120002
merchantIdId мерчанту згенерований в Єкоміstring(36)Так137d9304-0368-11ed-b939-0242ac120002
transactionAmountСума платежу в копійкахstringТак2000
desiredThreeDSModeОзнака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні.string (50)ТакЗа замовчуванням SHOULD
resultRedirectUrlUrl для редиректа клієнта після проходження 3DS аутентифікаціїstring (1000)НіGoogle Help
notificationUrlurl, на який буде відправлено CallBackstring (255)Ніhttps://merchant.notification_url
notificationEncryptionознака криптування данних CallBackstringНі

true/false

Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

dateдата та час платежуstringТак{{currentdateT}}.00+03:00
commentдодаткова опис операції яку заповнює клієнт мерчантаstring (1000)Ні///5555.25412
purposeпризначення платежу яке заповнює мерчантstring (255)НіЗа товар
merchantCommentдодаткова інформація\коментар мерчанта по замовленню

string(255)

a-zA-Z0-9 ,.;:@#$%'-=+1,256$

Ніmerchant Comment id 1258728c1
customerDataоб'єкт з customer данимиobjectТак
senderCustomerIdId клієнта відправникаstring (255)Так1258728c1
senderFirstNameім'я відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІваненко
senderLastNameпрізвище відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІван
senderMiddleNameпо-батькові відправника

string (30)

  • значення не може містити виключно цифри
  • не може містити крапки та інші спецсимволи
  • дозволено приймати тільки літерно-цифрові значення
  • може приймати пробіл та дефіс, але НЕ може складатися виключно з “ “ или “-“
  • дефіс чи пробіл може бути всередині, але не може бути на початку чи кінці
  • Для символу апострофу використовуйте єдиний доступний символ utf8 - '
    який в:
    utf 16 - u0027
    utf32 - 00000027
НіІванович
senderEmailпошта відправникаstring (256)Ніmail@gmail.com
senderСountryкраїна відправникаstring (3) ISO 3166, 804 (Ukraine)Ні804
senderRegionобласть відправникаstring (255)НіКиївська
senderСityмісто відправникаstring (25)НіКиїв
senderStreetвулиця відправникаstring (35)НіСічових стрільців
senderAdditionalAddressдодаткові дані адреси відправника (поверх, номер дому, квартира)string (255)Ні23
senderItnіпн відправникаstring (20)Ні123456789
senderPassportпаспорт відправникаstring (255)НіАН123456
senderIpspace.vars.senderIP_descriptionstring (50)Ніspace.vars.senderIP_example
senderPhoneномер телефону відправникаstring (20)Ні380630000000
senderBirthdayдень народження відправникаstring (50)Ні31.12.2000
senderGenderГендер відправникаstring (50)НіMale/Female
senderZipCodeіндекс відправникаstring (50)Ні49000
**Вихідні параметри** | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string | SUСCESS FAIL PENDING REQUIRED\_3DS DESIRED\_THREEDS\_MODE\_ERROR | | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string | true/false Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані | | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string | MUST- проводимо оплату з 3DS MUST\_NOT- проводимо оплату без 3DS | | statusThreeDs | статус проведення 3DS | string | Y - успіший 3ds N - не успішний 3ds | | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі в системі ACS | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum | Можливі значення: NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається | | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | **Приклад тіла запиту** ```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" } ``` **Приклад тіла відповіді без 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 } ``` **Приклад тіла відповіді з 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 } ``` # Запит проведення purchase Крок 2 (3DS) {{url}}/ecom/execute\_request/payments/v1/google\_pay\_3ds/purchase
ПараметрОписФормат данихОбов'язковістьПриклад
operationIdІд операції, який отримали на 1 кроціstringТак137d9304-0368-11ed-b939-0242ac120002
dateдата та час платежуstringТак{{currentdateT}}.00+00:00
browserInfoоб’єкт за даними браузераobjectТак, якщо операція потребує 3DS
browserAcceptHeaderHttp заголовок запитуstringТак, якщо операція потребує 3DStext/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
browserUserAgentпрограмний елемент браузера, що позначає систему, що користується неюstringТак, якщо операція потребує 3DSMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36
browserLanguageмова браузераstringТак, якщо операція потребує 3DSen-US,en
browserColorDepthзначення глибини кольору екрана у браузеріstringТак, якщо операція потребує 3DS24
browserScreenHeightвисота області перегляду вікна браузераstringТак, якщо операція потребує 3DS800
browserScreenWidthширота області перегляду вікна браузераstringТак, якщо операція потребує 3DS1280
browserTZTimezone браузераstringТак, якщо операція потребує 3DS-180
#### Вихідні параметри | Параметр | Опис | Формат даних | Приклад | | ----------------------- | ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | type | тип транзакції | string | Purchase | | rrn | rrn номер транзакції в МПС | string | 2554256963 | | purpose | призначення платежу | string | За товар | | comment | коментар | string | тест | | coinAmount | сума платежу в копійках | int | 2000 | | merchantId | Id мерчанту | string | 137d9304-0368-11ed-b939-0242ac120002 | | operationId | Id транзакціі | string | 1712844596346b9F-WwrWZpq | | ecomOperationId | Id транзакціі в системі Ecom | string | 8c3303e9-7396-43b8-af4e-31d9facdde9b | | merchantName | найменування торговця | string | KB test terminal | | approvalCode | код авторизаціі | string | 39203 | | status | статус транзакціі | string |

SUСCESS
FAIL
PENDING
REQUIRED\_3DS
DESIRED\_THREEDS\_MODE\_ERROR

| | transactionType | тип транзакції у цифровому значенні | string | 35 | | merchantRequestId | Id запиту мерчанта | string | 72837906-f526-4aef-8d11-58d80b44cb75 | | transactionCurrency | валюта платежу | string | 980 | | merchantCommission | сума комісії | string | 2 | | createDateTime | дата створення платежу | string | 2024.09.19 15:29:25.675 | | modificationDateTime | дата модифікаціі платежу | string | 2024.09.19 15:29:25.675 | | actionCode | код відповіді | string | 0 | | responseCode | деталі відповіді | string | 0 | | description | опис відповіді | string | approved | | bankCode | назва банку емітента | string | BANK\_ALLIANCE | | paymentSystem | назва мпс емітента | string | MasterCard | | productType | тип продукту термінала | string | PURCHASE | | notificationUrl | url, на який відправлено CallBack | string | | | paymentServiceType | тип оплати | string | CARD/APPLE\_PAY/GOOGLE\_PAY | | notificationEncryption | ознака криптування данних CallBack | string |

true/false
Якщо параметр не передано або передано false, то дані в CallBack будуть не закриптовані

| | cardNumberMask | маскований номер карти | string | 5573\*\*\*\*\*\*\*\*0304 | | desiredThreeDSMode | ознака яка вказує, чи бажає мерчант використати 3DS в покупці чи ні. | string | MUST/SHOULD/MUST\_NOT | | threeDSMode | параметр який вказує, використовувася 3DS у покупці чи ні | string |

MUST- проводимо оплату з 3DS
MUST\_NOT- проводимо оплату без 3DS

| | statusThreeDs | статус проведення 3DS | string |

Y - успіший 3ds
N - не успішний 3ds

| | threeDSServerTransId | Id транзакціі в системі 3ds | string | b6c35fdb-28c1-454d-a2f3-51098c26bda4 | | acsTransId | Id транзакціі в системі ACS | string | 3e17fabb-71e6-498e-8794-ef8c95c5ba6f | | dsTransId | Id транзакціі згенерований Directory Server | string | 12ebc556-82d3-4e35-9fb8-77ac18b050ea | | eci | Electronic Commerce Indicator Код, який вказує рівень безпеки транзакції | string | 02 | | processingMerchantId | Id мерчанту в ПЦ | string | AE100000 | | processingTerminalId | Id терміналу в ПЦ | string | AE100000 | | redirect3dsUrl | url для редиректа клієнта на сторінку емітента для проходження 3DS | string | | | txnType | під тип транзакціі | enum |

Можливі значення:
NONCVV/noncvv- при отриманні даного значення введення cvv та його перевірка не відбувається

| | senderCustomerId | Id клієнта відправника | string | 1258728c1 | | senderFirstName | ім'я відправника | string | Іваненко | | senderLastName | прізвище відправника | string | Іван | | senderMiddleName | по-батькові відправника | string | Іванович | | senderEmail | пошта відправника | string | | | senderCountry | країна відправника | string | Україна | | senderRegion | область відправника | string | Київська | | senderCity | місто відправника | string | Київ | | senderStreet | вулиця відправника | string | Січових стрільців | | senderAdditionalAddress | додаткові дані адреси відправника (поверх, номер дому, квартира) | string | 23 | | senderItn | іпн відправника | string | 123456789 | | senderPassport | паспорт відправника | string | АН123456 | | senderIp | space.vars.senderIP\_description | string | space.vars.senderIP\_example | | senderPhone | номер телефону відправника | string | 380630000000 | | senderBirthday | день народження відправника | string | 31.12.2000 | | senderGender | гендер відправника | string | M | | senderZipCode | індекс відправника | string | 12000 | | senderBankCode | назва банку емітента відправника | string | BANK\_ALLIANCE | | senderPaymentSystem | назва мпс емітента відправника | string | MasterCard | | senderCardNumberMask | маскований номер карти відправника | string | 5573\*\*\*\*\*\*\*\*0304 | #### Приклад тіла запиту 
{
    "operationId": "1702047427621BHu5X99yDbA",
    "browserInfo": {
        "browserAcceptHeader"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like,Gecko)Chrome/87.0.4280.66 Safari/537.36",
        "browserLanguage": "en-US,en",
        "browserColorDepth": "24",
        "browserScreenHeight": "800",
        "browserScreenWidth": "1280",
        "browserTZ": "-180"
    },
    "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
    "date": "{{currentdateT}}.00+00:00"
}
#### Приклад тіла відповіді ```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": "PENDING", "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 } ``` # C2A --- [Next Page](/llms-full.txt/1)