> For the complete documentation index, see [llms.txt](https://docs.merchant.alb.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.merchant.alb.ua/avtorizaciya-2.0/obrobka-sinkhronnikh-asinkhronnikh-vidpovidei.md). # Обробка синхронних/асинхронних відповідей ## Структура відповіді Усі відповіді сервісу передаються **у форматі 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` . ## Отримати публічний ключ за 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"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.merchant.alb.ua/avtorizaciya-2.0/obrobka-sinkhronnikh-asinkhronnikh-vidpovidei.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.