Webes kliens integrációja

Működés

A natív mobiltárcás fizetéshez a kereskedő weboldalán meg kell jeleníteni a mobiltárca fizetési gombját, majd a mobiltárcától kapott fizetési tokent a kereskedő szerverének kell továbbítani. Ez az oldal a kereskedő oldalának, vagyis a böngészőben futó résznek a feladatait foglalja össze, a kereskedő szerveréről indított műveleteket a tranzakció inicializálása (InitWallet), a tranzakció indítása (StartWallet) és a hitelesítés lezárása (CompleteWallet) fejezetek ismertetik.

A mobiltárcák webes kliensét minden esetben a mobiltárca szolgáltatója (Apple, illetve Google) adja ki, rendszerünk ehhez nem biztosít saját JavaScript könyvtárat.

A kereskedő oldala soha nem hívja közvetlenül a fizetési API-nkat. Kizárólag a kereskedő saját szerverének végpontjait hívja, a hitelesítési adatok (StoreName, ApiKey) pedig nem kerülhetnek a böngészőbe.

A natív mobiltárcás fizetés kizárólag HTTPS protokollal működik. A fizetési oldal domainjének meg kell egyeznie az inicializálás során átadott Wallet.ShopUrl értékkel és a fizetési szolgáltatónál regisztrált domainnel.

Apple Pay

Az Apple Pay webes fizetéshez a következő elemeket kell a kereskedő oldalára integrálni:

Elem	Forrás	Szerepe
Apple Pay JS API (ApplePaySession)	A böngésző beépített API-ja, külön betöltést nem igényel.	A fizetési munkamenet létrehozása és eseményeinek kezelése.
Apple Pay JS SDK	https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js	Az Apple által előírt megjelenésű fizetési gomb (<apple-pay-button>) megjelenítése.
Domain hitelesítő fájl	A fizetési szolgáltatótól kapott apple-developer-merchantid-domain-association fájl.	A domain hitelesítése; a webkiszolgáló /.well-known/ könyvtárából kell kiszolgálni.

A kereskedő oldalának feladatai a fizetés során:

1. A kereskedő oldala a window.ApplePaySession megléte és az ApplePaySession.canMakePayments() hívás alapján ellenőrzi az Apple Pay elérhetőségét a vásárló eszközén, és csak támogatott eszközön jeleníti meg a fizetési gombot,

2. Ezután a gomb megnyomásakor létrehozza a fizetési munkamenetet a rendelés összegével, devizanemével, az elfogadott kártyahálózatokkal és a kereskedői képességekkel.

3. A munkamenet onvalidatemerchant eseményében a kereskedő oldala elküldi a kereskedő szerverének a fizetési oldal címét és az esemény validationURL értékét, majd a válaszként kapott munkamenet adatokat változatlanul átadja a completeMerchantValidation() függvénynek.

4. A munkamenet onpaymentauthorized eseményében a kereskedő oldala elküldi a kereskedő szerverének a teljes event.payment.token objektumot, majd a szerver válasza alapján a completePayment() függvénnyel lezárja a fizetési felületet.

5. Az oncancel eseményben a kereskedő oldala kezeli a fizetés megszakítását.

// A rendelés adatai, az elfogadott kártyahálózatok és a kereskedői képességek.
// Az összegnek és a devizanemnek meg kell egyeznie az InitWallet során átadott
// értékekkel, a supportedNetworks és a merchantCapabilities pedig az elfogadói
// szerződéshez igazodik.
const paymentRequest = {
    countryCode: 'HU',
    currencyCode: 'HUF',
    total: { label: 'Shop Example', amount: '1000' },
    supportedNetworks: ['visa', 'masterCard'],
    merchantCapabilities: ['supports3DS']
};

if (window.ApplePaySession && ApplePaySession.canMakePayments()) {
    const session = new ApplePaySession(3, paymentRequest);

    session.onvalidatemerchant = async (event) => {
        // A kereskedő szervere InitWallet kérést küld, és az Apple Pay merchant session objektumot adja vissza.
        const merchantSession = await postToMerchantServer('/apple-pay/validate-merchant', {
            validationUrl: event.validationURL,
            shopUrl: window.location.origin
        });
        session.completeMerchantValidation(merchantSession);
    };

    session.onpaymentauthorized = async (event) => {
        // A kereskedő szervere StartWallet kérést küld a teljes tokennel.
        const result = await postToMerchantServer('/apple-pay/authorize', {
            token: event.payment.token
        });
        session.completePayment(result.success
            ? ApplePaySession.STATUS_SUCCESS
            : ApplePaySession.STATUS_FAILURE);
    };

    session.begin();
}

A 4. lépésben a teljes event.payment.token objektumot továbbítsa, ne csak annak paymentData mezőjét. A fizetési szolgáltató felé szükséges Base64-kódolást rendszerünk végzi el.

A kereskedő által megadandó mezők

A mintakódban szereplő mezők közül az alábbiak értékét a kereskedőnek kell beállítania. A kereskedő szerverének hívott végpontjai (a példában /apple-pay/validate-merchant és /apple-pay/authorize) szabadon választhatók.

Mező	Érték	Leírás
countryCode	az elfogadóhely országkódja	A kereskedő országának két karakteres ISO kódja, például HU.
currencyCode	tranzakciónként változó	A rendelés devizaneme. Egyeznie kell az InitWallet kérés Currency értékével.
total.label	szabadon választható	A fizetési lap végösszeg sorában, az összeg mellett megjelenő felirat. A vásárló ebből azonosítja, kinek fizet, ezért a kereskedő vagy a bolt nevét adja meg.
total.amount	tranzakciónként változó	A rendelés bruttó végösszege. Egyeznie kell az InitWallet kérés Amount értékével.
supportedNetworks	az elfogadói szerződés szerint	Az elfogadott kártyahálózatok.
merchantCapabilities	supports3DS	Az Apple által megkövetelt érték, e nélkül a fizetési munkamenet nem hozható létre. Nem jelent külön 3-D Secure hitelesítést: a vásárló hitelesítése az eszközén történik.
new ApplePaySession(…)	3	Az első paraméter az Apple Pay JS API verziója; a mintakód ezt használja.
shopUrl	a fizetési oldal címe	A window.location.origin értéke. Egyeznie kell az InitWallet kérés Wallet.ShopUrl értékével és a fizetési szolgáltatónál regisztrált domainnel.

Szerveroldali végpontok

Esemény a kereskedő oldalán	A kereskedő szerverének feladata	Válasz a kereskedő oldalának
Apple Pay onvalidatemerchant	InitWallet kérés a validationURL és a fizetési oldal címének átadásával.	Az Apple Pay merchant session objektum.
Apple Pay onpaymentauthorized	StartWallet kérés a tárolt tranzakció azonosítóval és a teljes fizetési tokennel.	A fizetés indításának eredménye, szükség esetén a RedirectUrl cím.

Tesztelés

• Apple Pay teszteléséhez az Apple fejlesztői fiókjában létrehozott sandbox tesztfelhasználó és támogatott Apple eszköz szükséges. A domain hitelesítő fájlnak a teszt domainen is elérhetőnek kell lennie.

Hivatalos fejlesztői dokumentáció

• Apple Pay on the Web – a webes integráció áttekintése és a kapcsolódó API-k.

• Configuring Your Environment – kereskedői azonosító, tanúsítványok és domain hitelesítés. A fizetési szolgáltató által kezelt beállításokat az adott szolgáltatóval egyeztesse.

• ApplePaySession API-referencia – a fizetési munkamenet, események és függvények, köztük a kereskedő hitelesítése és a fizetési felület lezárása.

• Sandbox Testing – a tesztkörnyezet előkészítése, sandbox felhasználók és tesztkártyák.

Google Pay

A Google Pay webes fizetéshez a következő elemeket kell a kereskedő oldalára integrálni:

Elem	Forrás	Szerepe
Google Pay API JavaScript könyvtár	https://pay.google.com/gp/p/js/pay.js	A fizetési kliens (google.payments.api.PaymentsClient) létrehozása.
Google Pay fizetési gomb	A könyvtár createButton() függvénye.	A Google által előírt megjelenésű fizetési gomb megjelenítése.
Kereskedői azonosító	A Google Pay & Wallet Console felületén igényelt azonosító.	Éles környezetben a merchantInfo.merchantId értéke.

A kereskedő oldalának feladatai a fizetés során:

1. A kereskedő oldala létrehozza a fizetési klienst a fizetési környezetnek megfelelő beállítással (TEST vagy PRODUCTION), majd az isReadyToPay() függvénnyel ellenőrzi a fizetési mód elérhetőségét a vásárló eszközén, és csak támogatott eszközön jeleníti meg a fizetési gombot,

2. Ezután a gomb megnyomásakor a loadPaymentData() függvénnyel megnyitja a Google Pay fizetési felületét.

3. A vásárló jóváhagyása után a kereskedő oldala elküldi a kereskedő szerverének a fizetési tokent (paymentData.paymentMethodData.tokenizationData.token) és a vásárló e-mail címét (paymentData.email).

4. A kereskedő oldala a kereskedő szerverének válasza alapján tájékoztatja a vásárlót, illetve nem üres visszairányítási URL cím (RedirectUrl) esetén megnyitja azt.

const paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' });

const cardPaymentMethod = {
    type: 'CARD',
    parameters: {
        allowedAuthMethods: ['PAN_ONLY'],
        allowedCardNetworks: ['MASTERCARD', 'VISA']
    },
    tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
            gateway: 'simplepay',
            gatewayMerchantId: 'GATEWAY_MERCHANT_ID'
        }
    }
};

// Az elérhetőség-ellenőrzéshez a tokenizációs adatok nélküli fizetési mód kell.
const baseCardPaymentMethod = {
    type: cardPaymentMethod.type,
    parameters: cardPaymentMethod.parameters
};

const readyToPay = await paymentsClient.isReadyToPay({
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedPaymentMethods: [baseCardPaymentMethod]
});

if (!readyToPay.result) {
    // Nem támogatott eszköz: a Google Pay gombot nem szabad megjeleníteni.
    return;
}

// A gomb megjelenítése a createButton() függvénnyel, majd gombnyomásra:
const paymentData = await paymentsClient.loadPaymentData({
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedPaymentMethods: [cardPaymentMethod],
    merchantInfo: { merchantId: 'GOOGLE_MERCHANT_ID', merchantName: 'Shop Example' },
    emailRequired: true,
    transactionInfo: { totalPriceStatus: 'FINAL', totalPrice: '1000', currencyCode: 'HUF' }
});

// A kereskedő szervere InitWallet, majd StartWallet kérést küld.
await postToMerchantServer('/google-pay/pay', {
    token: paymentData.paymentMethodData.tokenizationData.token,
    email: paymentData.email
});

A tokenizációs beállítások (gateway, gatewayMerchantId), az elfogadott hitelesítési módok (allowedAuthMethods) és a vásárlói e-mail cím bekérésének feltételei fizetési szolgáltatónként eltérnek. Ezeket a SimplePay és a Barion Smart Gateway oldalain részletezzük.

A fizetési tokent változatlan szöveges formában továbbítsa a kereskedő szerverének. A klienskörnyezet (TEST vagy PRODUCTION) a teszt-, illetve éles fizetési környezethez igazodjon, az inicializálás során átadott Wallet.Environment értéke azonban mindkét esetben web.

Az allowedAuthMethods lista tartalmát a fizetési konstrukció határozza meg: fizetőeszköz-regisztrációnál kizárólag a PAN_ONLY hitelesítési mód szerepelhet, már az első fizetés tokenjének létrehozásakor is. Egyszeri fizetésnél a CRYPTOGRAM_3DS mód is engedélyezhető. A szolgáltatónkénti feltételeket a SimplePay és a Barion Smart Gateway oldalain részletezzük.

A kereskedő által megadandó mezők

A mintakódban szereplő mezők közül az alábbiak értékét a kereskedőnek kell beállítania. A kereskedő szerverének hívott végpontja (a példában /google-pay/pay) szabadon választható.

Mező	Érték	Leírás
environment	TEST PRODUCTION	A klienskörnyezet a teszt-, illetve az éles fizetéshez igazodik.
type	CARD	A fizetési mód típusa.
allowedAuthMethods	PAN_ONLY CRYPTOGRAM_3DS	Fizetőeszköz-regisztrációnál kizárólag PAN_ONLY adható meg; egyszeri fizetésnél a CRYPTOGRAM_3DS is felvehető a listába.
allowedCardNetworks	az elfogadói szerződés szerint	Az elfogadott kártyahálózatok.
tokenizationSpecification.type	PAYMENT_GATEWAY	Fix érték.
gateway	simplepay barion	SimplePay esetén simplepay, Barion Smart Gateway esetén barion.
gatewayMerchantId	egyedi értékek	SimplePay esetén a fizetéshez kiválasztott terminál kereskedői azonosítója, Barion Smart Gateway esetén a bolt nyilvános POS azonosítója (POS GUID).
apiVersion, apiVersionMinor	2, illetve 0	Fix értékek.
merchantInfo.merchantId	egyedi értékek	A Google által kiadott kereskedői azonosító. TEST környezetben nem szükséges megadni.
merchantInfo.merchantName	szabadon választható	A vásárlónak megjelenő bolt neve.
emailRequired	fizetési szolgáltatónként eltérő	Barion Smart Gateway esetén true, mert a vásárló e-mail címét át kell adni az inicializáláskor.
transactionInfo.totalPriceStatus	FINAL	Fix érték.
transactionInfo.totalPrice	tranzakciónként változó	A rendelés bruttó végösszege. Egyeznie kell az InitWallet kérés Amount értékével.
transactionInfo.currencyCode	tranzakciónként változó	A rendelés devizaneme. Egyeznie kell az InitWallet kérés Currency értékével.

A Barion Smart Gateway webes hitelesítő kliense

Barion Smart Gateway Google Pay fizetésnél a tranzakció indítására (StartWallet) kapott nem üres ThreeDSAuthClientData érték további webes hitelesítést jelez. Ilyenkor a kereskedő oldalának be kell töltenie a Barion Smart Gateway webes hitelesítő kliensét, és a kapott értéket át kell adnia annak authenticate() függvényének. A hitelesítés befejeztével a kereskedő oldala értesíti a kereskedő szerverét, amely a hitelesítés lezárása (CompleteWallet) művelettel zárja le a fizetést rendszerünkben. A CompleteWallet kérés a hitelesítés kimenetelétől függetlenül kizárólag a tranzakció azonosítóját tartalmazza.

A webes hitelesítő kliens betöltését és használatát a Barion Off-site hitelesítés leírása ismerteti.

A kereskedő oldala és szervere közötti kapcsolat

A kereskedőnek a saját szerverén kell végpontokat készítenie a kereskedő oldalának hívásaihoz. Az egyes böngészőoldali események a következő API műveletekhez kapcsolódnak:

Esemény a kereskedő oldalán	A kereskedő szerverének feladata	Válasz a kereskedő oldalának
Google Pay loadPaymentData() sikeres lefutása	InitWallet kérés, majd StartWallet kérés a fizetési tokennel.	A fizetés indításának eredménye, szükség esetén a RedirectUrl cím vagy a ThreeDSAuthClientData érték.
A hitelesítés befejeződött (Barion Smart Gateway Google Pay)	CompleteWallet kérés a tranzakció azonosítójával.	A tranzakció státusza.

A rendelés állapotát ne a böngészőben kapott visszajelzés alapján állítsa be. A tranzakció végleges státuszát a kereskedő szerverén, az URL értesítés és a tranzakció eredményének lekérdezése (Result) alapján kezelje.

Tesztelés

• Google Pay teszteléséhez a fizetési klienst TEST környezetben hozza létre. Ebben a környezetben a Google által biztosított tesztkártyák használhatók, a merchantInfo.merchantId megadása pedig nem szükséges.

• A fizetési API kéréseket a teszt környezetünk címére küldje, és a fizetési szolgáltatónál is a teszt kereskedői beállításokat használja.

Hivatalos fejlesztői dokumentáció

Az alábbi, angol nyelvű útmutatók a mobiltárca webes kliensének beállítását és használatát ismertetik. A fizetési szolgáltatóhoz tartozó tokenizációs adatokat és korlátozásokat továbbra is a SimplePay, illetve a Barion Smart Gateway leírása szerint alkalmazza.

• Webes integrációs útmutató (Tutorial) – a Google Pay gomb és a fizetési folyamat beépítése lépésről lépésre.

• Client reference – a PaymentsClient, isReadyToPay(), createButton() és loadPaymentData() használata.

• Request objects – kérésparaméterek, tokenizáció, kereskedői adatok és az engedélyezett fizetési módok beállítása.

• Test card suite – tesztkártyák, gateway-specifikus tesztelés és a mock kártyák korlátai. A mock tokenek nem feltétlenül használhatók szolgáltatói tesztfizetésre.

• Integration checklist – az integráció működésének és megjelenésének ellenőrzése az élesítés előtt.