> For the complete documentation index, see [llms.txt](https://docs.nevogate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nevogate.com/egyszeri-fizetesek-one-time-payment/nativ-mobiltarca/kesobbi-terheles-ketlepcsos-fizetes/webes-kliens-integracioja.md).

# 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.

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

### Apple Pay

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

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

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.

{% code overflow="wrap" %}

```javascript
// 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();
}
```

{% endcode %}

{% hint style="warning" %}
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.
{% endhint %}

#### 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.

<table data-full-width="true"><thead><tr><th>Mező</th><th width="215">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>countryCode</code></td><td>az elfogadóhely országkódja</td><td>A kereskedő országának két karakteres ISO kódja, például <code>HU</code>.</td></tr><tr><td><code>currencyCode</code></td><td>tranzakciónként változó</td><td>A rendelés devizaneme. Egyeznie kell az <code>InitWallet</code> kérés <code>Currency</code> értékével.</td></tr><tr><td><code>total.label</code></td><td>szabadon választható</td><td>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.</td></tr><tr><td><code>total.amount</code></td><td>tranzakciónként változó</td><td>A rendelés bruttó végösszege. Egyeznie kell az <code>InitWallet</code> kérés <code>Amount</code> értékével.</td></tr><tr><td><code>supportedNetworks</code></td><td>az elfogadói szerződés szerint</td><td>Az elfogadott kártyahálózatok.</td></tr><tr><td><code>merchantCapabilities</code></td><td><code>supports3DS</code></td><td>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.</td></tr><tr><td><code>new ApplePaySession(…)</code></td><td><code>3</code></td><td>Az első paraméter az Apple Pay JS API verziója; a mintakód ezt használja.</td></tr><tr><td><code>shopUrl</code></td><td>a fizetési oldal címe</td><td>A <code>window.location.origin</code> értéke. Egyeznie kell az <code>InitWallet</code> kérés <code>Wallet.ShopUrl</code> értékével és a fizetési szolgáltatónál regisztrált domainnel.</td></tr></tbody></table>

#### Szerveroldali végpontok

<table data-full-width="true"><thead><tr><th>Esemény a kereskedő oldalán</th><th>A kereskedő szerverének feladata</th><th>Válasz a kereskedő oldalának</th></tr></thead><tbody><tr><td>Apple Pay <code>onvalidatemerchant</code></td><td><code>InitWallet</code> kérés a <code>validationURL</code> és a fizetési oldal címének átadásával.</td><td>Az Apple Pay merchant session objektum.</td></tr><tr><td>Apple Pay <code>onpaymentauthorized</code></td><td><code>StartWallet</code> kérés a tárolt tranzakció azonosítóval és a teljes fizetési tokennel.</td><td>A fizetés indításának eredménye, szükség esetén a <code>RedirectUrl</code> cím.</td></tr></tbody></table>

#### 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](https://developer.apple.com/documentation/applepayontheweb) – a webes integráció áttekintése és a kapcsolódó API-k.
* [Configuring Your Environment](https://developer.apple.com/documentation/applepayontheweb/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](https://developer.apple.com/documentation/applepayontheweb/applepaysession) – 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](https://developer.apple.com/apple-pay/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:

<table data-full-width="true"><thead><tr><th>Elem</th><th>Forrás</th><th>Szerepe</th></tr></thead><tbody><tr><td>Google Pay API JavaScript könyvtár</td><td><code>https://pay.google.com/gp/p/js/pay.js</code></td><td>A fizetési kliens (<code>google.payments.api.PaymentsClient</code>) létrehozása.</td></tr><tr><td>Google Pay fizetési gomb</td><td>A könyvtár <code>createButton()</code> függvénye.</td><td>A Google által előírt megjelenésű fizetési gomb megjelenítése.</td></tr><tr><td>Kereskedői azonosító</td><td>A Google Pay &#x26; Wallet Console felületén igényelt azonosító.</td><td>Éles környezetben a <code>merchantInfo.merchantId</code> értéke.</td></tr></tbody></table>

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.

<pre class="language-javascript" data-overflow="wrap"><code class="lang-javascript">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: <code class="expression">page.vars.Gateway</code>
            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
});
</code></pre>

{% hint style="info" %}
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](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/simplepay/nativ-mobiltarca) és a [Barion Smart Gateway](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/barion-smart-gateway/nativ-mobiltarca) oldalain részletezzük.
{% endhint %}

{% hint style="warning" %}
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`.
{% endhint %}

{% hint style="warning" %}
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](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/simplepay/nativ-mobiltarca) és a [Barion Smart Gateway](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/barion-smart-gateway/nativ-mobiltarca) oldalain részletezzük.
{% endhint %}

#### 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ó.

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

#### 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](https://docs.barion.com/Token_payment_3D_Secure#Off-site_3DS_v2_authentication) 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:

<table data-full-width="true"><thead><tr><th>Esemény a kereskedő oldalán</th><th>A kereskedő szerverének feladata</th><th>Válasz a kereskedő oldalának</th></tr></thead><tbody><tr><td>Google Pay <code>loadPaymentData()</code> sikeres lefutása</td><td><code>InitWallet</code> kérés, majd <code>StartWallet</code> kérés a fizetési tokennel.</td><td>A fizetés indításának eredménye, szükség esetén a <code>RedirectUrl</code> cím vagy a <code>ThreeDSAuthClientData</code> érték.</td></tr><tr><td>A hitelesítés befejeződött (Barion Smart Gateway Google Pay)</td><td><code>CompleteWallet</code> kérés a tranzakció azonosítójával.</td><td>A tranzakció státusza.</td></tr></tbody></table>

{% hint style="warning" %}
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.
{% endhint %}

#### 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](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/simplepay/nativ-mobiltarca), illetve a [Barion Smart Gateway](https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok/barion-smart-gateway/nativ-mobiltarca) leírása szerint alkalmazza.

* [Webes integrációs útmutató (Tutorial)](https://developers.google.com/pay/api/web/guides/tutorial) – a Google Pay gomb és a fizetési folyamat beépítése lépésről lépésre.
* [Client reference](https://developers.google.com/pay/api/web/reference/client) – a `PaymentsClient`, `isReadyToPay()`, `createButton()` és `loadPaymentData()` használata.
* [Request objects](https://developers.google.com/pay/api/web/reference/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](https://developers.google.com/pay-wallet/products/api/web/guides/test-and-deploy/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](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) – az integráció működésének és megjelenésének ellenőrzése az élesítés előtt.