Barion Smart Gateway

A Barion wikiből
  • Tervezet
  • Üzlet
  • Informatika
  • Pénzügy
  • Jog
  • 80%
  • Online elfogadó
  • Mobil elfogadó
  • Pénztárgép
  • Feltöltés
  • Piactér
  • Nonprofit
  • Parkolas

Smartg-gateway-montage-1024-doksiba.png

Mi a Barion Smart Gateway?

Mielőtt nekivágsz a fejlesztésnek, érdemes elolvasni a "marketing dumát" is, azaz hogy mire is való, mire is képes a Barion új fizető megoldása. Különösen az Extrák pontot érdemes átnézni, mert a Barion Smart Gateway tud pár olyan dolgot, amit más fizető kapuk nem tudnak, pl. fizetés harmadik félnek, vagy éppen jutalékok kezelése.

https://www.barion.com/smartgateway

Közösség és support

Alapfogalmak

API, API hívás

A Barion REST API segítségével kommunikál az integrált rendszerekkel. A kommunikáció minden esetben 2048 bites titkosított csatornán történik https protokollon keresztül.

API verzió

A Barion folyamatosan fejlődik és ez megköveteli a szolgáltatások rendszeres frissítését is. A szolgáltatások verziózását a híváshoz használt url kiegészítésével kezeli a rendszer. A https://{host}/{verzió}/{szolgáltatás_címe} mintára illeszkedve lehet a megfelelő verziójú szolgáltatást elérni a teszt vagy éles Barion környezetben. Az egyes szolgáltatások dokumentációiban érhető el a legfrissebb verzió is. A régebbi verziók csak korlátozott ideig elérhetőek, így az integrátorok feladata, hogy a lehető legfrissebb szolgáltatásokkal dolgozzanak.

Authentikáció, authorizáció

A szolgáltatások hívásához a hívónak azonosítania kell magát. Ehhez szükség van egy Barion felhasználóra, amelyik a megfelelő környezetben regisztrálva lett(teszt vagy éles). A legtöbb híváshoz nem elegendő egy felhasználó létrehozása, hanem a felhasználónak rendelkezni kell POS-al a Barion rendszerében, amit a teszt környezetben létrehozás után a rendszer automatikusan jóváhagy. Éles környezetben ez több időt vesz igénybe, mivel humán operátor végzi ezt a feladatot az adatok ellenőrzését követően. Az egyes szolgáltatások leírásaiban található módon authentikálnia kell magát a hívónak. Authentikáció után a rendszer ellenőrzi, hogy van-e jogosultsága a hívónak a feladat elvégzéséhez és ennek megfelelő választ kap a hívó.

JSON formátum

A Barion API JSON formátumú üzenetekkel kommunikál az integrált rendszerekkel. A JSON formátumról bővebben itt. Ahhoz, hogy az API biztosan helyesen dolgozza fel a kérésben átadott információt a híváskor a HTTP HEADER résznek tartalmaznia kell a "content-type: application/json" paramétert.

Felhasználó, vásárló

Barion rendszer számára felhasználó minden olyan email címmel rendelkező személy, aki a regisztrációs felületen az általános szerződési feltételeket elfogadta és regisztrációját egy aktiválással jóváhagyta vagy nem regisztrált, de vásárlásakor az email címét megadta és a vásárláskor az általános szerződési feltételeket elfogadta. Vásárló az a regisztrált vagy nem regisztrált Barion felhasználó, aki valamelyik integrált rendszerben vásárol.

POS

Barion-t elfogadni vagy a Barion segítségével fizetéseket lebonyolítani előre regisztrált POS-ok segítségével lehetséges. Ehhez annak, aki Barion-t szeretne elfogadni regisztrálnia kell egy POS-t a Barion rendszerben.

POSKey vs POSId

A regisztrált POS-hoz a könnyebb és biztonságosabb API kommunikáció lebonyolításához tartozik két azonosító. A POSKey a POS titkos azonosítója, a POSId pedig a POS publikus azonosítója.

Közvetítő a fizetés lebonyolításánál

A Barion-al többféle fizetési eset is megvalósítható. Az egyszerűbbek esetében elegendő a POS-hoz tartozó információkat felhasználni, a legtöbb esetben ez elegendő is az integrációhoz. Az egyszerű eset alkalmas egy webáruház integrációjához. Bonyolultabb esetekben, amikor a fizetést kezdeményező nem vagy nem a teljes összeget kapja meg, hanem csak közvetítőként vesz részt a fizetésben, akkor a POS-t közvetítőnek(facilitator) hívjuk.

Fizetési tranzakció, tranzakciók

A Barion-nal történő fizetés során a hívónak definiálnia kell milyen tranzakciókat szeretne a felhasználóval fizettetni. A tranzakciókat egy fizetési tranzakció fogja össze, hogy azok könnyen, csoportosan kezelhetőek legyenek. Ezeknek az előre definiált tranzakcióknak az összege nem változhat.

Azonnali tranzakciók, befoglalásos tranzakciók

A Barion-al történő fizetés során a fizetési tranzakció inicializálásakor kell definiálni, hogy azonnali vagy befoglalásos tranzakciót szeretne indítani. Azonnal tranzakciók a felhasználói jóváhagyás után azonnal végbemennek, a kezdeményező által megnevezett felhasználók azonnal rendelkezhetnek a megkapott összeg felett.

Befoglalásos esetben különbség van a Barion e-pénz egyenlegről és a bankkártyáról való fizetés között. Kártya esetében a pénz azonnal jóváíródik a kedvezményezettnél, növeli annak egyenlegét, és ott kerül befoglalásra, azaz jogilag a kereskedőé, de nem tud vele rendelkezni. E-pénz esetében a pénz a vásárlónál kerül befoglalásra, még az övé, de nem tud vele rendelkezni. Ez fontos különbség könyvelés szempontjából, így javasoljuk a könyvelő értesítését.

A fizetési tranzakció véglegesíthető kisebb összeggel is, mint amennyivel indítva lett. Kisebb összegű véglegesítésnél a felhasználó visszakapja a különbözetet e-pénz tárcájába, ha e-pénzzel fizetett vagy bankkártyára, ha azzal fizetett.

Beágyazott tranzakciók(PayeeTransaction)

Barion-al történő fizetés esetén lehetőség van a fizetési tranzakciókhoz a tranzakció összegéig beágyazott tranzakciókat létrehozni. Ez azt jelenti, hogy a vásárló kifizeti a megadott összeget, amit az eladó megkap, majd az eladó tárcájából átvezetésre kerül egy vagy több megadott tárcába az előre definiált összeg. A beágyazott tranzakciókat a fizetés inicializálásánál kell megadni, azok nem visszavonhatóak. Befoglalásos esetben a beágyazott tranzakciók összegeit módosíthatja az eladó.

Fizetési tranzakció és tranzakció állapotának lekérdezése

A fizetési tranzakció és a fizetési tranzakcióhoz rendelt további tranzakciók állapotait az API-n keresztül lekérdezhetik a fizetési tranzakcióban érintett felhasználók.

Díjak

A Barion a felhasználóktól nem von díjat a fizetési tranzakciók során, viszont vonhat a POS tulajdonosától. A díjvonás függ a fizetésben szereplő tranzakciók összegétől, a fizetés során felhasznált fizetőeszköztől(e-pénz vagy bankkártya), illetve a díj számítási mód függ az egyéni szerződési feltételektől. Díjakról az alábbi oldalon tájékozódhat: https://www.barion.com/hu/kereskedok/kereskedoi-dijcsomagok/

Folyamat

Smart-gw-overview.png


Adott termékek vagy szolgáltatások weben történő kifizetésének használati esete az alábbi módon zajlik: a felhasználó – amennyiben az elfogadóhely weboldalán a barionos fizetési módot választotta – átirányításra kerül a Barion Smart Gateway oldalára. Itt egy köztes fizetési felület fogadja, ahol kétféleképpen fizethet:

  • Ha már Barion felhasználó, bejelentkezhet a Barion rendszerébe (e-mail és jelszó párossal), hogy végrehajtsa a tranzakciót e-pénz egyenlegének vagy egyik tárolt bankkártyájának terhére
  • Ha nem Barion felhasználó, akkor kártyaadatainak megadásával fizethet. Ezt követően a rendszer felajánlja neki a Barion regisztrációt és ezzel a kártya adatainak biztonságos tárolását, így legközelebb semmilyen más barion elfogadónál nem kell többé kártyaadatokat megadnia

A fizetés után a felhasználót a Barion visszairányítja az elfogadóhely weboldalára, ahol a fizetés sikerességétől függően további információkat kaphat.

A folyamat technikai szinten a következő lépésekben zajlik:

  1. A felhasználó lezárja a kosarát és elindítja a fizetési folyamatot
  2. Az elfogadóhely rendszere egy kérést küld a Barion felé, amelyben elküldi a vásárlás összegét és minden egyéb paramétert, a saját tranzakciós azonosítóját
  3. A Barion válasz üzenetben jelzi a fizetés indításának sikerességét és átadja a fizetési tranzakcióhoz tartozó információt az elfogadóhely számára(például fizetés egyedi azonosítója)
  4. Az elfogadóhely a kapott azonosító alapján előállítja a redirect URL-t a Barion rendszerben, majd átirányítja a felhasználót. Figyelem! Az átirányítás nem lehet helyettesíteni iFrame-be történő beágyazással, ezt a rendszerünk nem támogatja!
  5. A felhasználó a Barion fizetési felületen bejelentkezik, majd jóváhagyja a tranzakciót a fent leírt két mód egyikével
  6. A tranzakció befejeződése után a Barion visszairányítja a felhasználót az elfogadóhely visszahívási URL-jére (ezt az elfogadóhely korábban a Barionban a saját beállításai között adta meg)

Amennyiben a tranzakció indításakor csak befoglalás történt, az elfogadóhelynek később lehetősége van a befoglalást véglegesíteni, maximum akkora összeggel, ami a befoglaláskor megadott

Az egyes esetek részletes fejlesztői segédletei itt elérhetőek.

Kapcsolódó API hívások

A Barion Smart Gateway integráció megkezdése előtt légy szíves olvasd át az API hívás alapok oldalt.

Az alábbi API hívások szükségesek a Barion Smart Gateway fizetés lebonyolításához.

Egyszerű és összetett fizetés indítása és eredményének lekérdezése

API hívás verzió Cél
Start v2 A fizetés folyamat indítása
GetPaymentState v2 A fizetési folyamat részleteinek lekérdezése

Átirányítás

A Start hívás után a felhasználót az integrátor elfogadóhelyből át kell irányítani a Barion rendszerébe, hogy a fizetés megtörténhessen.

Az URL, ahova át kell irányítani:

https://secure.barion.com/pay?id=[PaymentId]

Az URL-ben a PaymentId, az az azonosító, amit a Start hívás válaszában kapunk.

Például: https://secure.barion.com/pay?id=edd81a0a-35b0-439f-9180-3933d5b3f5ad

Callback hívás az eredményről

API hívás verzió Cél
Callback értesítés v2 A fizetés végén a Barion szerver, az elfogadóhely által a Start-nál megadott URL-t meghívja, így értesíti hogy a fizetés befejeződött

Összetett fizetések részleteinek lekérdezése, befoglalás véglegesítése

API hívás verzió Cél
GetTransactionState v2 A fizetés folyamatban szereplő egyes tranzakciók részelteinek lekérdezése, összetett tranzakciók esetében
FinishReservation v2 Befoglalásos fizetési folyamat véglegesítése

Refund, visszatérítés

Payment-Refund-v2