Apple Pay - csob/platebnibrana GitHub Wiki

img/shared/apple-pay/apple-pay-logo.png

Apple Pay na webu a v mobilních iOS & iPadOS aplikacích

Apple Pay je známá zejména z bezkontaktních plateb na platebních terminálech, kde lze platit telefonem, nebo hodinkami Apple Watch. Kartami, které si uživatelé zavedou do iPhonu, iPadu a Apple Watch je možné platit i online. Platební brána ČSOB je nově připravena na zpracování online plateb Apple Pay. Platba se odehrává přímo v e-shopu (na webu nebo v nativní mobilní iOS aplikaci), aniž by zákazník odcházel na platební bránu.

Karty ve virtuální peněžence

Pokud má zákazník v Apple Pay více karet, má vždy v průběhu platby možnost si vybrat kartu, kterou chce platit. Interakci mezi zákazníkem a kartami v iOS zařízení (nebo Apple Watch) nemůže ani obchodník, ani platební brána ovlivnit; jedná se o systémové služby iOS a Watch OS. Při volání Apple Pay služeb je možné omezit výběr karet, nicméně tuto funkci nedoporučujeme používat.

Integrace s Apple Pay službami je jednoduchá a bezpečná

Implementace Apple Pay tak vyžaduje integraci nejen na platební bránu, ale i přímo na Apple Pay. Při platbě si e-shop zažádá do Apple Pay o kartu, zákazník tuto žádost potvrdí (biometricky pomocí Touch ID, Face ID nebo na hodinkách) a zašifrované platební údaje jsou od Applu předány do e-shopu. Teprve v tento moment začíná na pozadí komunikace s platební bránou, která přijímá od obchodníka platební údaje (které si obchodník nemohl přečíst, protože komunikace mezi Applem až na platební bránu je šifrovaná), které platební brána ověří a použije pro autorizaci platby. Celý proces je tedy velice podobný tomu, kdy obchodník v kamenném obchodě žádá zákazníka o platbu (e-shop zakládá platbu v Apple Pay), zákazník vytahuje vybranou kartu z peněženky (zákazník se biometricky ověřuje na iPhonu, iPadu nebo Apple Watch), předává ji obchodníkovi (Apple Pay posílá obchodníkovi šifrované platební údaje) a následně se platba autorizuje.

Platby na všech Apple zařízeních

Apple Pay funguje jak v prohlížeči (pouze Safari - platformy Mac OS, iOS), tak v nativních aplikacích pro iOS. Na iOS zařízeních (jak iPhone, tak iPad) může zákazník zaplatit těmi kartami, které má v iPhonu nebo iPadu zavedené. Při platbě na počítači (v Safari) je platba potvrzována na zařízení, které je poblíž počítače. Tím může být iPhone nebo Apple Watch. Zjišťování blízkých zařízení probíhá přes continuity a upřednostňovány jsou hodinky před telefonem. MacBooky s Touch ID a M1 Macy s Touch ID v bezdrátové klávesnici se obejdou bez potvrzování plateb na telefonu a hodinkách, protože je možné přidat si karty přímo do počítače a potvrzovat platby otiskem prstu.

Zpracování Apple Pay plateb na platební bráně ČSOB

Apple Pay platba je běžnou karetní platbou ze všech hledisek s výjimkou interakce zákazníka s platbou. Autorizace platby, možnost manuálního uzavření platby, zaúčtování na nižší částku i vratky probíhají stejně jako u běžných karetních plateb.

Poplatky

Při použití Apple Pay ve vašem e-shopu je nutné se držet pravidel stanovených v Apple Payments Terms for Apple Pay. Kromě běžných omezení plateb za ilegální aktivity věnujte, prosím, pozornost také pravidlům pro prodej cigaret, tabákových výrobků a nabíjení virtuálních peněženek (kreditu). Pravidla také stanovují povinnost nabídnout Apple Pay jako první platební metodu v případě, že uživatel platí na zařízení, které podporuje Apple Pay a uživatel má v Apple Pay aktivní kartu.

Pro obchodníky je Apple Pay zdarma. Apple sice na placení vydělává, ale poplatky si vybírá od vydavatelů karet.

Nákupní data (nákupní košík) pro Apple Pay a platební bránu

Při zakládání platby do Apple Pay prosím používejte alespoň popis nákupu, v lepším případě i položkový košík. Apple Pay je hlavním místem interakce zákazníka s platbou, místem, kde dává souhlas s provedením platby. Platební bránu zákazník v průběhu Apple Pay platby neuvidí. Proto není (na rozdíl od běžné karetní platby) posílán na platební bránu nákupní košík.

Pozor! Do Apple Pay a následně na platební bránu je nutné poslat stejnou (nebo nižší) částku. Důvodem jsou pravidla silné autentizace klienta dle Směrnice PSD2, která vyžaduje autorizaci (provádí platební brána) na stejnou (nebo nižší) částku než autentizovanou částku (autentizaci provádí Apple Pay).

Ověření Apple Pay plateb

Platby Apple Pay jsou ověřené Face ID, Touch ID nebo na hodinkách Apple Watch a to bez ohledu na to, z jakého zařízení je platba prováděna (iPhone, iPad, Mac). Pro zvýšení úspěšnosti autorizace Apple Pay plateb nicméně platební brána sbírá dodatečná data o platbě stejným způsobem jako pro Google Pay a OneClick platby.

Ověření v iOS / Android mobilních aplikacích a použití SDK

Pro Apple Pay platby v nativních mobilních aplikacích je možné použít mobilní SDK, které je globálně technicky standardizováno na platformě EMV. Toto SDK sbírá technická data o zařízení uživatele (pro rizikovou analýzu vydavatele karty). SDK není vázané na platební bránu a můžete tak použít jakékoli SDK s EMV certifikací. Seznam jejich poskytovatelů najdete v seznamu. ČSOB pracuje s mobilním SDK společnosti NetCetera – budete-li o něj mít zájem, kontaktujte, prosím, [email protected]. Předávání výstupů z SDK a získávání parametrů pro SDK z platební brány najdete v technické specifikaci Apple Pay plateb.

Implementace - Registrace obchodníka pro Apple Pay

Kromě samotné integrace s platební bránou je nutné registrovat se jako obchodník u Applu na https://developer.apple.com/. Součástí registrace je i úhrada ročního členství. Podmínky registrace najdete zde.

Následně je zapotřebí vytvořit dva certifikáty. První certifikát si vytvoříte sami, pro druhý si vygenerujete žádost (certificate request) v systému ČSOB POS Merchant, předáte ji Applu k vytvoření certifikátu a výsledek nahrajete zpět do systému ČSOB POS Merchant. Tento certifikát bude zabezpečovat platební údaje mezi Apple Pay a platební bránou.

Vytvoření Merchant ID

1. přihlásit se do https://developer.apple.com/
2. přejít do sekce "Certificates, Identifiers & Profiles"
3. v sekci "Identifiers / Merchant IDs" registrovat nové Merchant ID

Vytvoření žádosti pro "Apple Pay Payment Processing Certificate" v ČSOB POS Merchant

1. přihlásit se do ČSOB POS Merchant a přejít do sekce "Platební brány"
2. vyhledat příslušnou platební bránu, pro kterou má být provedena registrace do Apple Pay
3. u vybrané platební brány kliknout na ikonku "Apple Pay certifikáty" a poté na tlačítko "Nový"
4. ve formuláři pro vytvoření žádosti (certificate request) vyplnit následující informace:
   • Common Name (Název certifikátu) - označení (název), které bude uvedeno ve výsledném certifikátu, doporučujeme zadat hodnotu obsahující Merchant ID
   • Email Address - může odpovídat použitému Apple ID, pod kterým je obchodník přihlášený do https://developer.apple.com/
   • Country Name (stát) - ve formátu "2 letter code", např. CZ
   • Locality Name (sídlo) - zadejte sídlo (město) obchodníka
   • Organization Name (název organizace) - název obchodníka
   • Org. Unit Name (název oddělení) - název oddělení/obchodního místa/název e-shopu
5. po odeslání formuláře vygeneruje platební brána klíč a dále žádost pro vydání certifikátu, v seznamu certifikátů je zobrazen nový záznam, lze stáhnout soubor s žádostí (s příponou .CSR)

Vygenerování "Apple Pay Payment Processing Certificate"

1. přihlásit se do https://developer.apple.com/
2. přejít do sekce "Certificates, Identifiers & Profiles"
3. u příslušného Merchant ID zvolit v části "Apple Pay Payment Processing Certificate" možnost "Create Certificate"
4. provést upload .CSR souboru, který obchodník vytvořil v předchozí části v ČSOB POS Merchant
5. provést download vygenerovaného certifikátu - jedná se o soubor s příponou .CER

Nahrání a aktivace "Apple Pay Payment Processing Certificate" v ČSOB POS Merchant

1. přihlásit se do ČSOB POS Merchant a přejít do sekce "Platební brány"
2. vyhledat příslušnou platební bránu, pro kterou má být provedeno nahrání "Apple Pay Payment Processing Certificate" do Apple Pay
3. u vybrané platební brány kliknout na ikonku "Apple Pay certifikáty", vyhledat v seznamu certifikátů příslušný záznam a provést nahrání souboru s příponou .CER z předchozí části
4. provést aktivaci vybraného certifikátu v ČSOB POS Merchant (vždy může být aktivní pouze jeden certifikát, aktivní certifikát musí odpovídat platnému "aktivnímu" certifikátu evidovanému v rámci https://developer.apple.com/)

Výše uvedený postup zaručí bezpečné vygenerování klíče, který bude použit na straně platební brány k dešifrování payloadu obsahujícího údaje pro autorizaci Apple Pay platby. Pouze platební brána jako vlastník klíče bude moci payload dešifrovat a provést autorizaci.

Upozornění: Certifikát má dobu platnosti 25 měsíců, bude jej tedy potřeba před uplynutím doby platnosti nahradit novějším.

Ověření domény (integrace Apple Pay na e-shopu obchodníka)

1. u Merchant ID vytvořeného v rámci https://developer.apple.com/ zvolit možnost "Add domain" v části "Apple Pay Payment Processing on the Web"
2. zadat doménu odpovídající e-shopu obchodníka
3. provést download souboru apple-developer-merchantid-domain-association.txt a umístit jej do odpovídajícího adresáře .well-known v rootu webserveru
4. provést verifikaci https://developer.apple.com/ (Apple ověří, že na zadané doméně je přístupný apple-developer-merchantid-domain-association.txt soubor a provede ověření jeho konzistence)

Upozornění: výše popsané ověření domény, ze které lze platit pomocí Apple Pay, bude nutné periodicky obnovovat, má omezenou platnost.

Vytvoření "Apple Pay Merchant Identity Certificate"  

Níže uvedený postup zaručí bezpečné vygenerování klíče a vystavení klientského certifikátu (Apple Pay Merchant Identity Certificate), který bude použit na straně obchodníka k navázání https spojení na servery Apple pro získání Apple Pay Session.

1. obchodník si vygeneruje certificate request, např. pomocí příkazu

openssl req -new -newkey rsa:2048 -nodes -keyout merchant_identity.key -out merchant_identity.csr

2. u Merchant ID vytvořeného v předchozí části zvolit možnost "Create Certificate" v části "Apple Pay Merchant Identity Certificate"
3. provést upload souboru merchant_identity.csr vytvořeného v prvním kroku
4. provést download vygenerovaného "Apple Pay Merchant Identity Certificate" (soubor s příponou .CER, v dalším popisu je používán název merchant_identity.cer)
5. soubory merchant_identity.key a merchant_identity.cer nastaví obchodník v konfiguraci e-shopu tak, aby pomocí nich bylo možné provést https spojení pomocí klientského certifikátu na servery Apple pro získání Apple Pay Session (viz dále).

Upozornění: Certifikát má dobu platnosti 25 měsíců, bude jej tedy potřeba před uplynutím doby platnosti měnit. "Apple Pay Merchant Identity Certificate" je použitý jen na straně obchodníka, platební brána jej pro applepay@shop nepotřebuje a nijak s ním nepracuje.

Integrace Apple Pay do e-shopu obchodníka

Apple umožňuje integrovat Apple Pay do e-shopu obchodníka buď pomocí Payment Request API (určeno pro iOS 11.3 a vyšší), nebo pomocí Apple Pay JS (pro iOS 10 a vyšší), volba konkrétního frameworku je na obchodníkovi, v případě Payment Request API se doporučuje implementovat Apple Pay JS jako fallback scénář. Viz detailní informace.

Ukázka integrace Apple Pay JS je k dispozici na https://applepaydemo.apple.com/ - je zde uveden detailní popis integrace obslužného javascriptu pro Apple Pay platbu. Obchodník musí na straně e-shopu v rámci obslužného js nastavit parametry platby (cena, košík, akceptované karty apod.) a dále musí naimplementovat dva endpointy pro založení Apple Pay Session a pro autorizaci platby.

Implementace endpointu pro založení Apple Pay Session  

Obchodník implementuje na straně e-shopu endpoint pro založení Apple Pay Session. Provede https požadavek na validationUrl získanou z requestu (volá se na server Apple, který provede validaci požadavku a vytvoří Apple Pay Session), pro ustanovení spojení je vyžadován klientský certifikát (viz Apple Pay Merchant Identity Certificate. Viz také Apple dokumentace.

Implementace endpointu pro poslání autorizačního požadavku

Obchodník implementuje na straně e-shopu endpoint, přes který provádí zpracování autorizačního požadavku. Přijatá data ve formátu JSON mají následující strukturu (hodnoty jednotlivých atributů jsou pro přehlednost zkráceny):

{
  "paymentData": {
    "version":"EC_v1",
    "data":"zDwclQ1....",
    "signature":"MIAGCSqGSI...",
    "header": {
      "ephemeralPublicKey":"MFkwEwY...",
      "publicKeyHash":"bHAaZK2k0SM...",
      "transactionId":"5324b499fab7..."
    }
  },
  "paymentMethod": {
    "displayName":"MasterCard 1234",
    "network":"MasterCard",
    "type":"debit"
  },
  "transactionIdentifier":"5324B499F..."
}

Obchodník vezme obsah parametru paymentData ...

{"version":"EC_v1","data":"zDwclQ1....","signature":"MIAGCSqGSI...","header": {"ephemeralPublicKey":"MFkwEwY...","publicKeyHash":"bHAaZK2k0SM...","transactionId":"5324b499fab7..."}}

... zakóduje jej do Base64 a přepošle na platební bránu ČSOB. Volá přitom metodu applepay/init, kde v parametru payload předává paymentData zakódovaná do Base64), viz specifikace Apple Pay API metod.