Tranzakció inicializálása (InitWallet)

Működés

Az InitWallet létrehozza a natív mobiltárcás tranzakciót. Apple Pay esetén kereskedői munkamenetet is visszaad. A fizetési tokent egyik mobiltárcánál sem ez a kérés tartalmazza: azt a tranzakció indítása (StartWallet) adja át.

API kérés paraméterek

Az API kérés általános információi

Művelet	HTTP kérés	Adatok
InitWallet	POST	method=InitWallet json={JSON encode-olt paraméterek}

A kérés a fizetési API végpontjára küldendő. A hitelesítés, az általános kötelező és opcionális paraméterek az Init műveletével azonosak. Adja át a StoreName, ProviderName, ResponseUrl, NotificationUrl, Amount mezőket és a vásárlás PSD2/SCA adatait. A szolgáltatót OTPSimple vagy Barion2 néven adja meg.

A natív folyamatban a vásárló nem hagyja el a kereskedő oldalát, kivéve, ha a tranzakció indítására (StartWallet) nem üres visszairányítási URL cím (RedirectUrl) érkezik. Erre a visszatérésre az Extra paraméterben átadott redirectMode érték is hatással van, amelyet a Visszairányítási módok fejezet ismertet.

A Wallet JSON objektum az alábbi mezőket tartalmazza:

Kötelező paraméterek

Paraméter	Típus	Érték	Leírás
Wallet.Type	string	apple_pay, google_pay	A natív fizetési mód.
Wallet.Environment	string	web	A kliens típusa; teszt- és éles fizetéskor is web.

Kötelező paraméterek Apple Pay esetén

Paraméter	Típus	Érték	Leírás
Wallet.ShopUrl	string	például https://shop.example.com	A fizetési weboldal címe. Teljes https:// kezdetű cím vagy önálló domainnév adható meg. A domainnek egyeznie kell a fizetési szolgáltatónál regisztrált domainnel és azzal a domainnel, ahonnan az Apple domain-hitelesítő fájlt kiszolgálja.
Wallet.ValidationUrl	string	az aktuális validationURL	Az Apple onvalidatemerchant eseményének validationURL értéke. Mindkét fizetési szolgáltatónál kötelező. Az eseményből kapott címet változtatás nélkül adja át.

A Wallet.ShopUrl értéke kétféle lehet: teljes cím (például https://shop.example.com) vagy önálló domainnév (például shop.example.com). A cím útvonalrésze nem számít, rendszerünk a domaint használja. Nem fogadható el, és WrongParameter eredménykódot ad:

• a https-től eltérő protokoll (például http://shop.example.com),

• a 443-tól eltérő port (például https://shop.example.com:8443),

• a címbe ágyazott felhasználónév vagy jelszó,

• a / karakter a protokoll nélkül megadott értékben (például shop.example.com/fizetes),

• az IP-cím (például https://192.0.2.10),

• a pontot nem tartalmazó hostnév (például localhost).

Hiányzó vagy üres érték esetén a válasz MissingParameter eredménykódot ad.

A Wallet.ValidationUrl kizárólag teljes cím lehet, és csak az Apple Pay gateway hosztjaira mutathat: apple-pay-gateway.apple.com, illetve az ugyanígy kezdődő regionális címek (például apple-pay-gateway-cert-eu-west.apple.com). Nem fogadható el, és WrongParameter eredménykódot ad:

• a https-től eltérő protokoll,

• a 443-tól eltérő port,

• a címbe ágyazott felhasználónév vagy jelszó,

• a protokoll nélkül megadott hostnév (például apple-pay-gateway.apple.com),

• minden más domain, beleértve az Apple domainre csak hasonlító címeket is (például apple-pay-gateway.apple.com.pelda.hu).

Az onvalidatemerchant eseményből kapott címet ezért mindig változtatás nélkül továbbítsa, és ne cserélje saját vagy közbeiktatott címre.

Kötelező paraméterek Google Pay esetén

Paraméter	Típus	Érték	Leírás
Wallet.PayerEmailAddress	string	a vásárló e-mail címe	A fizetési szolgáltató a Google Pay-fizetéshez megköveteli a vásárló e-mail-címét. Adja át a Google Pay által visszaadott paymentData.email értéket. Rendszerünk ellenőrzi az átadott e-mail-cím formátumát. Ha nem ad át értéket, a vásárlás Info adataiban szereplő e-mail-címet használjuk. Ha egyik forrásban sincs e-mail-cím, a fizetési szolgáltató elutasíthatja a fizetés indítását.

A natív fizetési módot a Wallet.Type határozza meg, külön PaymentMethods megadása nem szükséges.

A fizetési tokent az inicializálás nem tartalmazhatja. A Wallet.Token mező puszta jelenléte WrongParameter eredménykódot okoz, üres vagy null értékkel is. A tokent a tranzakció indítása (StartWallet) adja át, mindkét mobiltárcánál.

Mintakód

Az alábbi, a kereskedő szerveréről indított példa azonnali terhelésű SimplePay Apple Pay inicializálást mutat. A hitelesítési és rendelési adatokat cserélje saját értékekre, és egészítse ki a kérést az adott vásárlás SCA adataival. A példákban szereplő tokenek, munkamenetek és azonosítók szemléltető értékek.

curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'InitWallet | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=InitWallet' \
  --data 'json={
    "StoreName": "sdk_test",
    "ProviderName": "OTPSimple",
    "ResponseUrl": "https://shop.example.com/payment/response",
    "NotificationUrl": "https://shop.example.com/payment/notification",
    "Amount": 1000,
    "AutoCommit": "true",
    "Currency": "HUF",
    "OrderId": "ORDER-123",
    "Wallet": {
      "Type": "apple_pay",
      "Environment": "web",
      "ShopUrl": "https://shop.example.com",
      "ValidationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession"
    }
  }'

Barion Apple Pay esetén a Wallet objektum mezői azonosak, csak a ProviderName értéke Barion2.

A ValidationUrl helyére mindig az aktuális Apple esemény értékét tegye, a fenti cím csak szemléltetés.

Google Pay esetén mindkét szolgáltatónál az alábbi Wallet objektum használható az általános paraméterek mellett:

{
  "Type": "google_pay",
  "Environment": "web",
  "PayerEmailAddress": "[e-mail]"
}

API válasz paraméterek

Paraméter	Típus	Érték	Leírás
TransactionId	string / null	egyedi tranzakció azonosító	A létrehozott tranzakció azonosítója a Nevogate rendszerében. Tárolja a további kérésekhez.
ResultCode	string	SUCCESSFUL vagy hibakód	SUCCESSFUL, vagy a hiba eredménykódja.
ResultMessage	string / null	szöveges magyarázat vagy null	Az egyes ResultCode értékek szöveges magyarázata.
ResponseId	integer	egyedi válaszazonosító	A válaszüzenet egyedi azonosítója a Nevogate rendszerében.
ApplePaySessionResponse	object	Apple Pay kereskedői munkamenet	Kizárólag Apple Pay inicializálásnál, sikeres kereskedői munkamenet-hitelesítés esetén. A fizetési szolgáltatótól kapott objektumot változtatás nélkül adja át a böngésző completeMerchantValidation() hívásának. Más fizetési módnál a mező nem szerepel a válaszban.

Mintakód

Sikeres Google Pay inicializálás mintaválasza:

{
  "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
  "ResultCode": "SUCCESSFUL",
  "ResultMessage": null,
  "ResponseId": "3202109280600047703"
}

Sikeres Apple Pay inicializálás mintaválasza:

{
  "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
  "ResultCode": "SUCCESSFUL",
  "ResultMessage": null,
  "ResponseId": "3202109280600047703",
  "ApplePaySessionResponse": {
    "...": "az Apple által kiadott kereskedői munkamenet adatai"
  }
}

Az ApplePaySessionResponse objektum tartalmát ne módosítsa és ne is dolgozza fel: változatlan formában adja át a böngésző completeMerchantValidation(...) hívásának. A mező csak Apple Pay inicializálásnál szerepel a válaszban, más fizetési módnál hiányzik.

Gyakori hibák: MissingParameter (hiányzó mobiltárcás adat), WrongParameter (hibás típus, környezet vagy URL), UnauthorizedAccess (a natív mobiltárcás fizetés nincs engedélyezve a boltban), WrongProviderSettings (a kiválasztott mobiltárca nincs engedélyezve a szolgáltatónál). Az általános inicializálási és szolgáltatói hibák is előfordulhatnak.