POS API - bezpečnost
TLS
Veškerá komunikace se službou je povinně zabezpečena použitím Transport Layer Security se serverovým certifikátem.
Server požaduje použití TLS verze 1.2 nebo vyšší.
Server požaduje použití ciphersuites aktuálně (Q1/2025) považovaných za silné. To jsou:
Ve verzi 1.2:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
Ve verzi 1.3:
TLS_AES_256_GCM_SHA384TLS_CHACHA20_POLY1305_SHA256TLS_AES_128_GCM_SHA256
Které ciphersuites jsou považované za silné se průběžně mění. Počítejte s tím, že tento výčet není pevný a server jej může změnit.
Autentizace zpráv
Komunikace mezi pokladním systémem a cloudovou službou MúzaPay je chráněna kódem message authentication code (MAC), který je vypočtený z přenášených dat a přidaný jako další parametr přenášené zprávy. Příjemce zprávy musí zkontrolovat, zda přijatá data odpovídají MAC. Pokud kontrola MAC selže, nesmí zprávě důvěřovat, protože může být podvržená.
Jako klient služby MúzaPay implementujte výpočet MAC z požadavků algoritmem HMAC-SHA-256 - SHA256 hash-based message authentication code.
Pro výpočet potřebujete tajný klíč (tajemství), který s vámi nasdílí Benefit Management v rámci registrace vaší POS integrace. Tajný klíč je specifický pro vaši provozovnu.
Parametry z požadavku vkládejte do vstupního řetězce clearTextString k výpočtu MAC vždy v níže uvedeném pořadí. Jednotlivá pole z požadavku oddělte oddělovačem “|" (svislou čarou). Pokud některé nepovinné pole není přítomno, do řetezce nevkládejte ani jeho oddělovač.
Operace |
| Seznam a pořadí polí ke vložení do řetězce k podepsání clearTextString - tučně jsou povinná |
|---|---|---|
createPayment | požadavek | amount, cashierId, country, language, merchantData, orderDescription, orderReferenceCode, payerCode, posId, productCode, requestTimestamp*, storeId, x-correlation-id |
odpověď | amount, beneficiaryId, currency, orderReferenceCode, payerId, paymentId, paymentTimestamp, posId, storeId, x-correlation-id | |
getPayment | požadavek | paymentId, requestTimestamp, storeId |
odpověď | beneficiaryId, currency, language, orderDescription, orderReferenceCode, payerId, paymentId, paymentState, paymentTimestamp, posId, remainingAmount, responseCode, responseMessage, responseTimestamp, storeId, x-correlation-id | |
getPaymentStream | požadavek | paymentId, requestTimestamp, storeId |
paymentUpdatedEvent | eventTimestamp, orderReferenceCode, payerId, paymentId, paymentState, paymentTimestamp, posId, remainingAmount, responseCode, responseMessage, storeId, x-correlation-id | |
cancelPayment | požadavek | paymentId, requestTimestamp, storeId |
odpověď | responseTimestamp, x-correlation-id |
* hodnotu requestTimestamp do MAC použijte vždy stejnou jako tu, kterou posíláte v HTTP požadavku. V této operaci tedy - narozdíl od ostatních - bude hodnota date-time v plném formátu, se třemi pozicemi milisekund a se zónou.
Příklad sestavení řetězce clearTextString pro výpočet MAC u operace getPayment
Do clearTextString bude vždy vloženo paymentId, requestTmestamp a storeId. Pokud je hodnota paymentId např. “EC42E6695FFADAE5D0017952F0CF7A6”, requestTimestamp “20231111232301“ a storeId “AD202A31B11FF123C2301EFF90212233AC“.
potom clearTextString=EC42E6695FFADAE5D0017952F0CF7A69|20231111232301|AD202A31B11FF123C2301EFF90212233AC.
Příklad výpočtu HMAC v jazyku Java:
/*
rawSecretKey is example secret key
macStringUrlEncoded is a value to put into mac request parameter
*/
byte[] rawSecretKey = hexStringToByteArray("0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF");
String clearTextString = "Example cleartext string content";
javax.crypto.SecretKey secretKey = new javax.crypto.spec.SecretKeySpec(rawSecretKey, "HmacSHA256");
javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA256");
mac.init(secretKey);
byte[] code = mac.doFinal(clearTextString.getBytes());
String macString = java.util.Base64.getEncoder().encodeToString(code);
String macStringUrlEncoded = java.net.URLEncoder.encode(macString, java.nio.charset.StandardCharsets.UTF_8.name());Příklady jsou poskytované tak jak jsou, bez záruky jejich použitelnosti ve vaší konkrétní POS!
Kontrola odpovědí
Obdobným způsobem implementujte kontrolu odpovědí přijatých ze služby.
Příklad kontroly HMAC v jazyku Java:
/*
rawSecretKey2 is example secret key
macString1 is a value from mac field received from a service
code1 is HMAC received from a service
code2 is HMAC calculated by you
*/
byte[] rawSecretKey2 = hexStringToByteArray("0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF");
String clearTextString1 = "Example cleartext string content";
String macString1 = "0qLxqzNGsNzQIshX1HgEpjFyvoRRtcz+lh+Ukq37t74=";
byte [] code1 = java.util.Base64.getDecoder().decode(macString1);
javax.crypto.SecretKey secretKey2 = new javax.crypto.spec.SecretKeySpec(rawSecretKey2, "HmacSHA256");
javax.crypto.Mac mac2 = javax.crypto.Mac.getInstance("HmacSHA256");
mac2.init(secretKey2);
byte[] code2 = mac2.doFinal(clearTextString1.getBytes());
boolean isMacValid = Arrays.equals(code1, code2);Příklady jsou poskytované tak jak jsou, bez záruky jejich použitelnosti ve vaší konkrétní POS!
Příklady v dalších jazycích jsou k dispozici v https://github.com/danharper/hmac-examples.
Kontrola aktuálnosti odpovědí
Pokud je kontrola dat úspěšná, zkontrolujte ještě, zda časové informace obsažené v odpovědi(události) odpovídají reálnému času.
Služba posílá časové informace vždy v časové zóně UTC.
Ochrana přístupových dat
Pro bezpečnost placení s použitím POS API je kritické, abyste ochránili vaše tajné klíče sloužící pro výpočet a kontrolu HMAC.
Nastavte proto vaše procesy tak, aby nedošlo k jejich vyzrazení. Pokud k němu přesto dojde, informujte neprodleně Benefit Management.
Informace k PCI DSS
Integrační služba pro POS žádným způsobem nepracuje s daty bankovních (ani jiných) platebních karet a nepodléhá tedy PCI standardům.
Platba metodou MúzaPay v POS obchodníků je postavena na principu scanování dočasného čarového kódu obchodníkem. Platby jsou autorizované ověřením identity plátce v mobilní aplikaci MúzaPay, buď s pomocí biometrie nebo PINu. Jde o funkční obdobu 3D Secure v2 klíčů v současných internetových bankovnictvích.