Apple Pay v košíku e-shopu

Postup implementace Apple Pay v rámci košíku e-shopu

Tento článek popisuje integraci Apple Pay přímo do košíku e-shopu tak, že nedochází k přesměrování plátce na karetní bránu, ale platba je hrazena přímo v prostředí e-shopu. Jedná se o nejpokročilejší způsob integrace Apple Pay. Platební brána Comgate nabízí i další, výrazně jednodušší způsoby integrace Apple Pay, které jsou popsány zde: https://help.comgate.cz/docs/apple-pay.

Tento článek vás detailně provede celou implementací Apple Pay přímo do košíku e-shopu.

Ověření domény

Pro používání Apple Pay v rámci košíku e-shopu je nezbytné provést ověření domény. Ověření domény se provádí pomocí nahrání speciálního verifikačního souboru do adresářové struktury Vašeho webu. Tento soubor je možné získat v Klientském portálu Comgate (Integrace -> Nastavení obchodů -> Váš obchod -> Nastavení Apple Pay). 

Zde je ke stažení soubor s názvem apple-developer-merchantid-domain-association, který je nutné nahrát na váš web tak, aby byl přístupný přes adresu: https://www.e-shop.cz/.well-known/apple-developer-merchantid-domain-association 

Následně provedete verifikaci správného umístění v Klientském portálu Comgate pomocí tlačítka Zkontrolovat v sekci Integrace -> Nastavení obchodů -> Váš obchod -> Nastavení Apple Pay. 

Implementace do frontendu e-shopu

Apple Pay se do e-shopu obchodníka integruje 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ář. Detailní informace jsou dostupné na stránkách Apple: https://developer.apple.com/documentation/apple_pay_on_the_web/choosing_an_api_for_implementing_apple_pay_on_your_website. 

Následující odstavce popisují implementaci pomocí Apple Pay JS.

Zjištění podpory Apple Pay na zařízení uživatele a zobrazení platební metody

Apple Pay je dostupné pouze na některých zařízeních Apple (s dostupnou biometrickou ochranou) a to pouze v prohlížeči Safari. Proto doporučujeme zobrazovat tlačítko Apple Pay v objednávce pouze klientům, kteří takto skutečně mohou zaplatit. Tlačítku je možné snadno definovat styly s využitím zabudovaných CSS stylů Safari. Variantou je i využití JS knihovny apple-pay-sdk.js, která však v této dokumentaci nebude dále rozebírána. 

CSS + HTML E-shop (frontend)

<style>
    .apple-pay-button {
	 display: none;
        -webkit-appearance: -apple-pay-button;
        -apple-pay-button-type: continue;
        -apple-pay-button-style: white-outline;
    }

</style>

<button type="button" id="apple-pay" lang="cs" class="apple-pay-button"></button>

<script>
    // pokud je k dispozici Apple Pay JS API (v prohlížeči Safari)
    // a pouze v případě, že používané zařízení podporuje Apple Pay ve verzi 4
    if(window.ApplePaySession 
        && window.ApplePaySession.supportsVersion(4)
        && window.ApplePaySession.canMakePayments()) {
            // hodnota z klientského portálu Integrace >  Apple Pay session > displayName
            var shop = "www.e-shop.cz";  
            if(window.ApplePaySession.canMakePaymentsWithActiveCard(shop)) {
               // zobrazit zlačítko pro zahájení platby Apple Pay
               document.getElementById("apple-pay").style.display = "inline-block";
            }
    }
</script>

Prostřednictvím volání metod canMakePayments() a supportsVersion() se ověřuje, zda je k dispozici Apple Pay JS API (to je zabudováno pouze v prohlížeči Safari) a také jeho dostupná verze. 

Druhá kontrola canMakePaymentsWithActiveCard() ověří skutečnost, zda má uživatel aktivní kartu ve své Apple Wallet a může provádět platby. Tím je možné zajistit, aby celý proces proběhl hladce.

Podrobné návody naleznete na stránkách Apple v těchto článcích:

• https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/checking_for_apple_pay_availability
• https://developer.apple.com/apple-pay/marketing/ 
• https://developer.apple.com/design/human-interface-guidelines/apple-pay/overview/buttons-and-marks/ 
• https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css

Zpracování platby

Diagram níže zobrazuje celý průběh zpracování platby prostřednictvím Apple Pay.

Ukázka použití 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.). Zároveň je nezbytné naimplementovat komunikaci s dvěma endpointy platební brány Comgate. Jeden slouží pro založení Apple Pay Session a druhý pro autorizaci transakce.

1.Vytvoření Apple Pay Session

Na straně obchodníka (frontend), je nutné vytvořit javascriptovou ApplePaySession s konkrétní konfigurací.

E-shop (frontend)

var paymentRequest = {
    currencyCode: 'CZK',
    countryCode: 'CZ',
    total: { // informace pro zobrazení v platebním dialogu
        label: 'Informace o platbě', // libovolný popisek
        amount: 135.35 // hodnota finanční operace
    },
    supportedNetworks: ['maestro', 'masterCard', 'visa', 'vPay', 'jcb'],
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit']
};

var session = new ApplePaySession(4, paymentRequest);

Dokumentace ApplePaySession: https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/2320659-applepaysession 

Popis parametrů:

• currencyCode - je kód měny ve které bude platba probíhat
• countryCode - země, ve které bude platba realizována (vždy CZ)
• total.label - popisek, o probíhající platbě do apple modálního okna 
• total.amount - částka platby pro zobrazení do apple modální okna

Pro lokální session je potřeba definovat event handler onvalidatemerchant, který ve své implementaci provede HTTPS požadavek na endpoint platební brány Comgate: https://payments.comgate.cz/v1.0/applepaypaymentsession
čímž, dojde k zaregistrování session i v systémech Apple Pay (o to se postaráme za Vás) a vrácení konkrétní konfigurace. Tu je nutné následně předat zpět lokálně vytvořené session.  

E-shop (frontend)

session.onvalidatemerchant = function (e) {
    var xhr = new XMLHttpRequest();

    xhr.onload = function () {
        var merchantSession = JSON.parse(xhr.responseText);
        session.completeMerchantValidation(merchantSession);
    };

    var cgValidate = 'https://payments.comgate.cz/v1.0/applepaypaymentsession'
         + '?merchant=123456' // merchant
         + '&displayName=www.e-shop.cz' // displayName
         + '&initiativeContext=www.e-shop.cz'; // initiativeContext

    xhr.open('GET', cgValidate);
    xhr.send();
}

Jednotlivé parametry lze nalézt v Klientském portálu > Integrace >Nastavení obchodů > Váš e-shop > záložka Nastavení Apple Pay > v části Apple Pay session:

• merchant - ID merchanta používané pro zakládání plateb
• displayName - Jméno obchodu, zobrazované v Apple Pay modálním okně
• initiativeContext - Doména ve tvaru fully qualified domain names (FQDN)

2. Autorizace platby

O autorizaci platby se kompletně postará Apple. V této části tak není třeba nic implementovat.

3. Založení platby

K provedení platby je nutné definovat event handler onpaymentauthorized. V němž dojde k založení platby v systému Comgate a jejímu následnému provedení. Celý tento proces byl maximálně zjednodušen. Platbu prostřednictvím Apple Pay je tak možné jedním voláním založit a současně i provést. Postup je následující. 

Poté, co uživatel platbu autorizoval pomocí biometrických senzorů, je nezbytné z frontendu zavolat API e-shopu, kterému jsou mimojiné  předány šifrované platební instrukce. Ty je možné snadno získat uvnitř volání handleru onpaymentauthorized, jemuž je předán object ApplePayPaymentAuthorizedEvent (v ukázce nazvaný 'e'). Tento objekt obsahuje kompletní platební instrukce (e.payment.token.paymentData), které je nutné zakódované předat na backend vašeho e-shopu. Při kódování se musí JSON data převést na text a ten do formátu base64 (více níže v ukázce). Při zakládání platby (pouze z backendu Vašeho e-shopu!) jsou veškeré parametry pro vytvoření platby a to včetně platebních instrukcí předány do našeho systému, který se již postará o provedení celé platby. Volání probíhá postřednictvím našeho API na adrese https://payments.comgate.cz/v1.0/create. 

Podmínkou pro automatické provedení platby ApplePay po jejím založení jsou nastavené parametry:

• method=APPLEPAY_E-SHOP
• applePayPayload=kodovana_payment_data
• + další parametry pro vytvoření platby

Více informací o založení platby: https://help.comgate.cz/docs/api-protokol#zalo%C5%BEen%C3%AD-platby 

E-shop (frontend)

session.onpaymentauthorized = function (e) {
    // předání platebních údajů na backend e-shopu a provedení platby

    var xhr = new XMLHttpRequest();

    var eshopPayment = 'https://www.e-shop.cz/api/zaplat-applepay'
        + '&payload=' + btoa(JSON.stringify(e.payment.token.paymentData))
        + '&id=' + id; // ID vaší objednávky
        // + další libovolné parametry

    // synchronní dotaz k založení a provedení platby (trvá několik sekund)
    xhr.open('GET', eshopPayment, false);
    xhr.send();

    // Stav platby (dle toho, co vrátí Váš endpoint)
    if ('PAID' === xhr.responseText && 200 === xhr.status) {
        // platba byla zaplacena
        session.completePayment(window.ApplePaySession.STATUS_SUCCESS);
    } else {
        // platbu se nepodařilo zaplatit nebo stále probíhá (stav je tak nutné zjistit později)
        session.completePayment(window.ApplePaySession.STATUS_FAILURE);
    }
}

E-shop (backend)

<?php
// sample za použití symfony/http-client
$client = (new HttpClient())::create();
 
// načíst všechna data o objednávce
 
$params = [
    'merchant' => '123456', // váš ComGate identifikátor e-shopu
    'secret' => 'ZCtehKrMein...', // Vaše heslo pro komunikaci (zkráceno)
    'price' => '100', // 1,00 Kč - hodnota platby
    'curr' => 'CZK', // měna 
    'label' => 'Testovací platba', // popis platby
    'refId' => '123456789', // Variabilní symbol / Váš identifikátor platby
    'method' => 'APPLEPAY_ESHOP', // striktní definice parametru
    'email' => 'email@platce.cz',
    'applePayPayload' => 'eyJkYXRhIjoiNWNySzVKekJnOEU5SmV2...', // payload z předchozího příkladu (zkráceno pro ukázku)
];
 
// připraví query string
$query = http_build_query($params);
 
// odešle požadavek na ComGate server
$response = $client->request(
    'POST',
    'https://payments.comgate.cz/v1.0/create?' . $query
);
 
$statusCode = $response->getStatusCode();
if (200 === $statusCode) {
    // server vrátil validní odpověď
    $responseContent = $response->getContent(); // načte odpověď serveru
    parse_str($responseContent, $resParams); // a rozparsuje ji
 
    if (0 == $resParams['code']) {
        // platba byla úspěšně založena
        switch ($resParams['applepay']) {
            case 'PAID':
                return ...; // platba byla zaplacena
            case 'PENDING':
                return ...; // platba stále probíhá
            case 'BANK-REJECT':
                return ...; // platba byla zamítnuta bankou
            case 'FAILED':
            default:
        }
        // platba nebyla provedena
        return ...;
 
    } else {
        // platbu se nepodařilo založit
    }
} else {
    // chyba při komunikaci
}
?>

4. Stav platby

Server na volání o provedení platby vrací přesnou strukturu odpovědi, která je ve formátu:

code=0&message=OK&transId=XXXX-XXXX-XXXX
&applepayMessage=Platba+provedena&applepay=PAID

Kde:

• code - Návratový kód vytvoření transakce
• message - popis vytvoření transakce
• transId - kód transakce XXXX-XXXX-XXXX
• applepay - stav provedení transakce ApplePay v bance (PAID, PENDING, FAILED, BANK-REJECT)
• applepayMessage - popis stavu zpracování transakce ApplePay
• + může obsahovat i další parametry, které jsou v tomto případě nepodstatné

* applepay, applepayMessage se v odpovědi nemusí vždy vyskytovat (typicky při chybě založení platby)

Popis návratových stavů applepay:

• PAID - platba proběhla v pořádku
• PENDING - platba stále probíhá, stav je potřeba ověřit později
• BANK-REJECT - platba byla zamítnuta bankou
• FAILED - obecná chyba, specifikována v applepayMessage

5. Deklarace dalších event handlerů a spuštění procesu platby

Pro správné fungování potřebuje ApplePaySession deklarovat ještě další dva event handlery. První oncancel nemusí vykonávat žádnou funkcionalitu. Druhý onpaymentmethodselected provede jednoduché volání. Na závěr je potřeba celou session placení zahájit.

E-shop (frontend)

session.oncancel = function(e) {}

session.onpaymentmethodselected = function(e) {
   var newTotal = {type: 'final', label: 'Informace o platbě', amount: 135.35 };
   var newLineItems = [];
   session.completePaymentMethodSelection(newTotal, newLineItems);
}

session.begin();

Platba by následně měla úspěšně proběhnout.

Poznámky

• JSON posílaný do ApplePaySession musí obsahovat tyto definice:
       - supportedNetworks: ['maestro', 'masterCard', 'visa', 'vPay', 'jcb'],
       - merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit']

• V části session.onvalidatemerchant volat endpoint:
  - https://payments.comgate.cz/v1.0/applepaypaymentsession?merchant=123456&displayName=JmenoE-shopu&initiativeContext=url
  
  
• V části session.onpaymentauthorized volat endpoint
  - https://payments.comgate.cz/v1.0/create