Přeskočit na hlavní obsah

Apple Pay

Tento článek popisuje jednotlivé kroky potřebné pro integraci tlačítka Apple Pay do mobilní aplikace a získání platebního tokenu, který lze následně zpracovat přes platební bránu Comgate. Postup se skládá z následujících kroků, kterými vás provede tento článek:

1. Apple Developer Program (DAP)​

Pro integraci Apple Pay je potřeba nakonfigurovat aplikaci v DAP a vytvořit Payment Processing certifikát.

Vytvoření Merchant ID​

Jděte do své Apple Developer Konzole

  1. V sekci Certificates, IDs & Profiles klikněte na odkaz Identifiers
https://developer.apple.com/account

alt text

  1. V dropdown menu vyberte hodnotu Merchant IDs
https://developer.apple.com/account/resources/identifiers/list

alt text

  1. V pravé horní části v klikněte na tlačítko +, mělo by být hned vedle nadpisu Identifiers
https://developer.apple.com/account/resources/identifiers/list/merchant

alt text

  1. Na stránce Register a new identifier budete mít jíž předvybranou hodnotu Merchant IDs, pokračujte tedy kliknutím na tlačítko Continue v pravém horním rohu
https://developer.apple.com/account/resources/identifiers/add/merchant

alt text

  1. Na stránce Register a Merchant ID vyplňte políčka Description a Identifier a klikněte na tlačítko Continue v pravém horním rohu
https://developer.apple.com/account/resources/identifiers/merchant/add/

alt text

  1. Klikněte na tlačítko Register v pravém horním rohu
https://developer.apple.com/account/resources/identifiers/merchant/add/

alt text

Výměna Payment Processing certifikátu​

Pro zajištění funkčnosti Apple Pay je nutné vygenerovat Payment Processing certifikát.

Poznámka

Certifikát má omezenou dobu platnosti (obvykle 2 roky). Na blížící se expiraci budete včas upozorněni ze strany společnosti Apple.

Proces zřízení nebo výměny certifikátu probíhá v následujících krocích:

  1. Kontaktujte podporu Comgate a požádejte o vystavení nového souboru CSR (Certificate Signing Request).
  2. Jakmile obdržíte CSR, přihlaste se do Apple Developer Programu.
  3. Přejděte do sekce Certificates, Identifiers & Profiles → Identifiers a vpravo nahoře zvolte typ Merchant IDs.
  4. Vyberte Merchant ID, pro které chcete certifikát vygenerovat.
  5. V sekci Apple Pay Payment Processing Certificate klikněte na tlačítko Create Certificate.
  6. Nahrajte poskytnutý CSR soubor od Comgate a potvrďte kliknutím na Continue.
    ⚠️ Certifikát zatím neaktivujte. Předčasná aktivace znemožní zpracování plateb.
  7. Po úspěšném vytvoření certifikátu klikněte na tlačítko Download a certifikát si stáhněte.
  8. Stažený certifikát (soubor s příponou .cer) zašlete zpět na podporu Comgate.
  9. Certifikát bude nahrán na straně Comgate a propojen s vaším Merchant ID.
  10. Po úspěšném nahrání certifikátu vás bude kontaktovat zákaznická podpora Comgate.
  11. Po potvrzení od podpory Comgate aktivujte připravený Payment Processing certifikát v Apple Developer portálu.
Upozornění

Upozorňujeme, že v krajních případech může celý proces výměny certifikátu trvat až 14 dní. Proto prosím zahajte proces co nejdříve, abyste předešli případným problémům s platbami.

Nastavení Apple Pay v projektu (Xcode)​

  1. Otevřete Xcode a otevřete svůj iOS projekt.
  2. V horním menu klikněte na Xcode → Settings (Nastavení).
  3. V sekci Accounts (Účty) se přihlaste ke svému Apple Developer účtu (pomocí Apple ID).
  4. Zavřete okno s nastavením.
  5. V levém panelu klikněte na název svého projektu (modrá ikona v horní části seznamu souborů).
  6. Vyberte cílovou aplikaci (target) v hlavní části obrazovky.
  7. Přejděte na záložku Signing & Capabilities.
  8. Klikněte na tlačítko + Capability.
  9. V seznamu vyberte Apple Pay.
  10. Objeví se nové nastavení s názvem Apple Pay. Klikněte na nabídku u „Merchant IDs“ a vyberte svůj nakonfigurovaný Merchant ID.
  11. V souboru Shared/Configuration (nebo jiném konfiguračním souboru vašeho projektu) nastavte merchant identifier tak, aby odpovídal Merchant ID zvolenému v předchozím kroku.
Poznámka

Pokud jste členem vývojového týmu, ujistěte se, že máte v nastavení v sekci Accounts vybraný správný tým.

2. Implementace​

V této části jsou popsány jednotlivé kroky potřebné pro integraci Apple Pay tlačítka do mobilní aplikace, od nastavení tlačítka až po získání platebního tokenu.

Vzorový projekt​

Doporučujeme stáhnout si oficiální vzorový projekt Apple Pay jako referenci pro implementaci. Tato dokumentace vychází ze struktury a ukázek kódu uvedených ve vzorovém projektu.

Přidání tlačítka Apple Pay​

Pro přidání a konfiguraci tlačítka Apple Pay postupujte podle oficiálního tutoriálu od společnosti Apple.

Informace

Pro zajištění bezchybného zpracování platby je nezbytné dodržet níže uvedené pokyny pro konfiguraci tlačítka. Pouze tak může být token předaný na API Comgate úspěšně zpracován.

Sestavení Payment request objektu​

Payment Request je konfigurační objekt, který definuje parametry platby přes Apple Pay. Obsahuje informace jako částku, měnu, identifikátor obchodníka, podporované karetní sítě a další údaje potřebné pro inicializaci a zpracování platby.

Ve vzorovém projektu jeho definici naleznete v souboru Shared/PaymentHandler.swift, kde je implementována funkce startPayment. V této funkci dochází ke skládání objektu paymentRequest.

Upravte tento objekt podle následujících pokynů:

  1. Hodnota merchantIdentifier musí odpovídat hodnotě identifikátoru, který jste vytvořili v DAP.
    • Hodnota je dostupná v sekci Certificates, Identifiers & Profiles → Identifiers → Merchant IDs.
  2. Hodnota countryCode musí být vždy "CZ".
  3. Hodnota currencyCode musí odpovídat měně, ve které byla platba založena v systému Comgate.
  4. Podporované sítě v supportedNetworks jsou pouze .masterCard a .visa. Ostatní sítě je potřeba zakomentovat.
  5. Údaje o dopravě Comgate nevyžaduje ani nezpracovává. Proto je možné zakomentovat klíče shippingType, shippingMethods a requiredShippingContactFields. Pokud je však zvládnete správně využít, můžete je ponechat. Platba bude zpracována v obou případech.
  6. Comgate neposkytuje ani nezpracovává slevové kódy. Je nutné zakomentovat klíč supportsCouponCode. Funkcionalitu slevových kódů je třeba implementovat v předchozích krocích checkout procesu na vaší straně.
  7. Comgate nepodporuje definici vlastností recurringPaymentRequest, automaticReloadPaymentRequest, deferredPaymentRequest, applePayLaterAvailability a multiTokenContexts.
Upozornění

V případě, že definujete některou z výše uvedených vlastností, Comgate nezaručuje správné zpracování platby.
Opakované a odložené platby přes Apple Pay jsou podporovány, přičemž Comgate je zpracovává prostřednictvím základního objektu paymentRequest.

Zobrazení tlačítka Apple Pay​

Pokud dodržíte všechny výše uvedené pokyny, tlačítko Apple Pay se zobrazí ve vaší aplikaci. Po kliknutí na tlačítko se plátci zobrazí standardní Apple Pay obrazovka s detaily platby a možností jejího potvrzení.

Získání payment tokenu​

Po autorizaci platby plátcem Apple Pay vygeneruje zašifrovaný platební token, který je nezbytný pro další zpracování platby.

Informace

Potvrzení platby prostřednictvím Apple Pay nezpůsobí automatické zpracování platby. Pokud token nezašlete na naše API, platba nebude provedena. Token je platný pouze po omezenou dobu a je určen výhradně pro jedno použití.

Platební token se získá v callbacku paymentAuthorizationController(...) v souboru Shared/PaymentHandler.swift. Callback je volán po úspěšném potvrzení platby plátcem.

V rámci tohoto callbacku je potřeba získaný token zpracovat a odeslat na server Comgate spolu s dodatečnými údaji (paymentDetails). Token je dostupný v parametru payment.token.paymentData jako objekt PKPaymentToken. Pro jeho odeslání je nutné převést data na formát Base64 pomocí metody base64EncodedString().

let paymentToken = payment.token.paymentData.base64EncodedString()
let paymentDetails: [String: Any] = [
    "displayName": payment.token.paymentMethod.displayName,
    "network": payment.token.paymentMethod.network?.rawValue,
    "cardType": payment.token.paymentMethod.type.rawValue
]

Zpracování tokenu​

Platební token je nutné spolu s dodatečnými údaji odeslat na API Comgate. Toto API je jednotné pro platby realizované prostřednictvím Google Pay i Apple Pay.

Postup zpracování získaného tokenu je popsán v dokumentaci Zpracování platby.

3. Testovací prostředí​

Pro testování Apple Pay máte dvě možnosti:

Fyzické iOS zařízení​

Pro plnohodnotné testování Apple Pay je doporučeno použít skutečné zařízení s přidanou testovací kartou v aplikaci Wallet. Zařízení musí být přihlášeno k Apple ID, které je členem vašeho vývojářského týmu. Testovací karty najdete v Apple dokumentaci pro testování Apple Pay.

Připojte své zařízení k vašemu systému pomocí kabelu (systém se nejspíše bude ptát na povolení, vše odsouhlaste).

  1. Připravte své zařízení:
    • Ujistěte se, že zařízení má nainstalovanou nejnovější verzi iOS.
    • Přihlaste se na zařízení ke stejnému Apple ID, které je součástí vašeho vývojářského týmu v Apple Developer programu.
    • Otevřete aplikaci Wallet.
  2. Přidejte testovací kartu:
    • Apple umožňuje přidání testovací platební karty v sandbox režimu.
    • Na zařízení běžně nelze přidat sandbox kartu ručně, ale Apple Pay v aplikaci ji při pokusu o platbu automaticky nabídne (pokud máte správně nastavené prostředí).
    • Pro přidání testovací karty do Walletu můžete použít Apple Configurator nebo simulovat přidání pomocí testovací platby.
    • Seznam testovacích karet je dostupný zde: https://developer.apple.com/apple-pay/sandbox-testing/
  3. Ujistěte se, že používáte sandbox prostředí:
    • Xcode automaticky spouští aplikaci v sandbox režimu, pokud jste přihlášeni k vývojářskému účtu a aplikace běží z Xcode.
  4. Spusťte aplikaci z Xcode na zařízení:
    • Připojte iOS zařízení k Macu pomocí kabelu nebo přes Wi-Fi.
    • Vyberte zařízení jako „target“ pro běh aplikace.
    • Stiskněte Run (⌘ + R) a spusťte aplikaci na zařízení.
  5. Otestujte platbu pomocí Apple Pay:
    • Po stisknutí tlačítka Apple Pay by se měla zobrazit obrazovka s výběrem karty.
    • Pokud je vše správně nastaveno, uvidíte testovací kartu a budete moci simulovat platbu (např. pomocí Face ID, Touch ID nebo dvojkliku na boční tlačítko).
    • Transakce nebude reálně zaúčtována – jedná se o testovací platbu v sandbox režimu.
Tip

Pokud se Apple Pay nezobrazuje, zkontrolujte, že máte správně nastavený merchantIdentifier, aplikace má povolení Apple Pay v sekci Signing & Capabilities, a že vaše zařízení podporuje Apple Pay.

iOS simulátor na MacOS​

Simulátor podporuje Apple Pay pouze v omezené míře. Lze otestovat zobrazení tlačítka Apple Pay a základní tok UI, ale samotnou platbu nelze dokončit. Pro testování je nutné zvolit simulátor s podporou Apple Pay (např. iPhone 14 nebo novější) a mít v nastavení simulátoru aktivovaný testovací účet.

Upozornění

Na iOS simulátoru není možné získat payment token, je to záměrné omezení od Applu.

  1. Spusťte iOS simulátor:
    • Otevřete svůj projekt v Xcode.
    • Vyberte iOS simulátor, který podporuje Apple Pay (např. iPhone 14 nebo novější).
    • Spusťte aplikaci pomocí tlačítka Run (⌘ + R).
  2. Povolte Apple Pay v simulátoru:
    • Otevřete aplikaci Settings přímo v simulátoru.
    • Přejděte do sekce Wallet & Apple Pay.
    • Pokud je možnost Add Card dostupná, aktivujte ji a přidejte testovací kartu (simulátor nepřipojuje k reálnému účtu – jedná se o fiktivní kartu).
  3. Zkontrolujte, že aplikace Apple Pay rozpozná:
    • Vaše aplikace by měla detekovat, že je Apple Pay dostupný (PKPaymentAuthorizationController.canMakePayments() by měl vracet true).
    • Můžete zobrazit Apple Pay tlačítko a vyzkoušet základní uživatelský tok (např. výběr karty, potvrzení platby).
  4. Omezení:
    • Platbu není možné v simulátoru plně dokončit – nelze simulovat Touch ID, Face ID nebo potvrzení platby.
    • Simulátor může někdy vracet chyby, i když je vše správně nastaveno – ověřte si proto funkčnost i na fyzickém zařízení.
Poznámka

Pokud v simulátoru není možnost přidat kartu, zkontrolujte, že jste vybrali podporovaný model zařízení (iPhone 8 a starší většinou Apple Pay v simulátoru nepodporují).