Webes kliens integrációja

A natív mobiltárcás fizetőeszköz-regisztráció kizárólag Barion Smart Gateway Google Pay esetén érhető el: a SimplePay egyik natív mobiltárcás fizetési módja sem támogatja, Apple Pay esetén pedig egyik fizetési szolgáltatónál sem támogatott.

Az oldal további része helyenként a SimplePay beállításait is említi, ezeket ezen az oldalon hagyja figyelmen kívül.

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.

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: 'barion',
            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.