# Processing Synchronous and Asynchronous Responses ## Response Structure All service responses are transmitted in JWS (JSON Web Signature) format. This guarantees: * Data integrity — the message has not been altered during transmission. * Source authenticity — the request genuinely originated from an authorized service. The JWS message looks like this: ``` .. ``` #### Header and Payload Encoding Both parts (`header`, `payload`) are not encrypted, but only encoded in Base64Url format. This means they can be decoded to view the content, but they cannot be altered (this would break the signature). The `Signature` parameter guarantees that even if someone changes a single field in the `payload`, the signature will become invalid. **Example of Encoded Data:** {% tabs %} {% tab title="Encoded header part" %} `eyJhbGciOiJFUzI1NiIsImtpZCI6IjYwMjE3ZDU2LTJkMzYtNDhlMy1hYmU4LTVjMDBiNDJjYTg4NSJ9` {% endtab %} {% tab title="Decoded header part" %} ``` { "alg": "ES256", "kid": "60217d56-2d36-48e3-abe8-5c00b42ca885" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Encoded payload part" %} ``` eyJ0eXBlIjoiQUNDT1VOVF8yX0NBUkQiLCJycm4iOiI1MzE3MTU5MzczMDUiLCJwdXJwb3NlIjoi0LfQsCDRgtC-0LLQsNGAIiwiY29pbkFtb3VudCI6MTAsIm1lcmNoYW50SWQiOiIxMzdkOTMwNC0wMzY4LTExZWQtYjkzOS0wMjQyYWMxMjAwMDIiLCJvcGVyYXRpb25JZCI6IjE3NjMwNDY5NjQyODl5R2pEZDJ1RVBrWSIsImVjb21PcGVyYXRpb25JZCI6ImQ1Y2RlYzg0LWNkYzUtNDVjMi1hZmEyLWQ4MWJmZDc5ZmU2MSIsInN0YXR1cyI6IlNVQ0NFU1MiLCJ0cmFuc2FjdGlvblR5cGUiOjQ2LCJtZXJjaGFudFJlcXVlc3RJZCI6IjA0MDIyNjVkLWMwYzYtNDNlYi05NDhlLTAyMzEwYzMzMWEzMyIsInRyYW5zYWN0aW9uQ3VycmVuY3kiOiI5ODAiLCJtZXJjaGFudENvbW1pc3Npb24iOjAsImNyZWF0aW9uRGF0ZVRpbWUiOiIyMDI1LjExLjEzIDE3OjE2OjA0LjIyNyIsIm1vZGlmaWNhdGlvbkRhdGVUaW1lIjoiMjAyNS4xMS4xMyAxNzoxNjowNC4yMjciLCJ0cmFuc2FjdGlvblJlc3BvbnNlSW5mbyI6eyJhY3Rpb25Db2RlIjoiMCIsInJlc3BvbnNlQ29kZSI6IjAwIiwiZGVzY3JpcHRpb24iOiLQntC_0LXRgNCw0YbRltGPINGD0YHQv9GW0YjQvdCwIn0sInByb2R1Y3RUeXBlIjoiQTJDIiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvNDExNjM0ZjQtNmMxNy00ODYyLTg4NTYtZDA2NGY3ZjIxMzVhIiwicGF5bWVudFNlcnZpY2VUeXBlIjoiQ0FSRCIsIm5vdGlmaWNhdGlvbkVuY3J5cHRpb24iOmZhbHNlLCJub3RpZmljYXRpb25TaWduYXR1cmUiOnRydWUsInByb2Nlc3NpbmdUZXJtaW5hbElkIjoiQUUwMDEwMDQiLCJwcm9jZXNzaW5nTWVyY2hhbnRJZCI6IkFFMDAxMDA0IiwiY3JlYXRvclN5c3RlbSI6IkgySCIsImJhbGFuY2VBbW91bnRBZnRlciI6OTkwMTAxOTY5NDQ5MTMsInNlbmRlckN1c3RvbWVySWQiOiIwMDAwMDAiLCJzZW5kZXJGaXJzdE5hbWUiOiJzZW5kZXJGaXJzdE5zZW5kZXJGaXJzdE5hbWVzZW4iLCJzZW5kZXJMYXN0TmFtZSI6InNlbmRlckxhc3ROYW1lc2VuZGVyTGFzdE5hbWVzZSIsInNlbmRlck1pZGRsZU5hbWUiOiJzZW5kZXJNaWRkbGVOYW1lc2VuZGVyTWlkZGxlTmEiLCJzZW5kZXJDb3VudHJ5IjoiODA0Iiwic2VuZGVyUmVnaW9uIjoic2VuZGVyX3JlZ2lvbiIsInNlbmRlckNpdHkiOiJzZW5kZXJfY2l0eSIsInNlbmRlclN0cmVldCI6InNlbmRlcl9zdHJlZXQiLCJzZW5kZXJBZGRpdGlvbmFsQWRkcmVzcyI6Ik4gNiIsInNlbmRlckl0biI6IjEyMzQ1Iiwic2VuZGVyUGFzc3BvcnQiOiIxMjM0NSIsInNlbmRlcklwIjoiMTY1LjIyMi44Ny4yMjQiLCJzZW5kZXJQaG9uZSI6IjM4MDk2NzU0MjM0NCIsInNlbmRlckJpcnRoZGF5IjoiMTIxMjIwMDAiLCJzZW5kZXJHZW5kZXIiOiJNYWxlIiwic2VuZGVyWmlwQ29kZSI6IjEyMzQ1IiwicmVjaXBpZW50Q3VzdG9tZXJJZCI6IjEyMzQ1NjciLCJyZWNpcGllbnRGaXJzdE5hbWUiOiJyZWNpcGllbnRGaXJzdE5yZWNpcGllbnRGaXJzdE4iLCJyZWNpcGllbnRMYXN0TmFtZSI6InJlY2lwaWVudExhc3N0TnJlY2lwaWVudExhc3N0TiIsInJlY2lwaWVudE1pZGRsZU5hbWUiOiJyZWNpcGllbnRNaWRkbGVOYW1lcmVjaXBpZW50TWkiLCJyZWNpcGllbnRFbWFpbCI6InLRhNGEQGdtYWlsLmNvbSIsInJlY2lwaWVudENvdW50cnkiOiI4MDQiLCJyZWNpcGllbnRSZWdpb24iOiJyZXNfcmVnIiwicmVjaXBpZW50Q2l0eSI6InJlc19kbmlwcm8iLCJyZWNpcGllbnRTdHJlZXQiOiJyZXNfc3RyZWV0IiwicmVjaXBpZW50QWRkaXRpb25hbEFkZHJlc3MiOiJyZXNfYWRkcmVzIiwicmVjaXBpZW50SXRuIjoiMTIzNDU2Nzg5MCIsInJlY2lwaWVudFBhc3Nwb3J0IjoicmVzX3Bhc3BvcnQiLCJyZWNpcGllbnRJcCI6IjE2NS4yMjIuODcuMjI0IiwicmVjaXBpZW50UGhvbmUiOiIzODA5Njc1NDIzNDQiLCJyZWNpcGllbnRCaXJ0aGRheSI6IjEyMTIyMDAwIiwicmVjaXBpZW50R2VuZGVyIjoiRmVtYWxlIiwicmVjaXBpZW50WmlwQ29kZSI6Ijc3Nzc3In0... ``` {% endtab %} {% tab title="Decoded payload part" %} {% 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 %} #### Signature Verification The `kid` (Key ID) parameter in the JWS Header determines which public key should be used to verify the signature. In case the key pair is updated, the server generates responses with the new `kid`. The client must: 1. Retrieve the new `kid` from the JWS header. 2. Make a request to `/ecom/keys/public_key/get_v1` to obtain the corresponding public key. 3. Use this key to verify the signature of subsequent messages. To verify the signature, you need to decode the header part where the kid parameter will be located. ## Get Public Key by kid > Returns the public key (JWK) for the specified 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":"Get Public Key by kid","description":"Returns the public key (JWK) for the specified kid.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kid"],"properties":{"kid":{"type":"string","description":"Key Identifier (Key ID)"}}}}}},"responses":{"200":{"description":"Success. Returns the public key in JWK format.","content":{"application/json":{"schema":{"type":"object","properties":{"kty":{"type":"string","description":"Key Type (e.g., EC)"},"use":{"type":"string","description":"Key purpose (e.g., sig)"},"crv":{"type":"string","description":"Curve (e.g., P-256)"},"kid":{"type":"string","description":"Key Identifier"},"x":{"type":"string","description":"X-coordinate of the public key (base64url)"},"y":{"type":"string","description":"Y-coordinate of the public key (base64url)"},"alg":{"type":"string","description":"Algorithm (e.g., ES256)"}}}}}},"400":{"description":"Bad Request (e.g., missing kid)"},"404":{"description":"Key not found"},"500":{"description":"Internal Server Error"}},"tags":["Keys"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.merchant.alb.ua/en/authorization-2.0/processing-synchronous-and-asynchronous-responses.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.