API hívás alapok

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

Sandbox vagy Teszt rendszer

A sandbox vagy tesz szerver bárki által használható tesztelésre, fejlesztésre a nap 24 órájában. A teszt rendszer minden szempontból megegyezik az éles rendszerrel, az egyedüli különbség, hogy nem valós elektronikus pénzt tartalmaz. Az egyes API hívások viselkedését ez azonban nem befolyásolja, így minden valós életben elképzelhető pénzügyi szituáció megteremthető benne egy alkalmazás tesztelése során.

FIGYELEM! A teszt rendszer teljesen külön áll az éles rendszertől, így az itt regisztrált tárcák és elfogadóhelyek az éles szerveren nem működnek, ott külön kell regisztrálni, újra kell elfogadóhelyet nyitni, és mivel ott már valódi pénzzel megy minden, ezért ott vannak szabályok! A teszt szerveren lehet szabadon "garázdálkodni".

Teszt regisztráció

A teszt rendszeren tetszőleges számú felhasználót lehet regisztrálni, a folyamat ugyanaz, mint az éles szerveren.

https://test.barion.com/Registration

Tranzakciók a teszt szerveren

Minden tranzakció működik, kivéve a banki átutalást (visszaváltást) és a banki átutalással történő feltöltést. A bankkártya tranzakciókat teszt bankkártyával lehet tesztelni, lásd alább.

Recurring, azaz ismétlődő tranzakciókat a teszt szerveren is lehet csinálni. Az éles szerveren ehhez külön engedély kell, lásd: Recurring Payment engedélyezésének feltételei

Vigyázat, a pénzmosási limiteket ne lépjétek túl, hacsak nem ezt akarjátok tesztelni, mert a rendszer automatikusan felfüggeszti a szóban forgó tárca használatát, pont úgy, mint az éles rendszerben. A felfüggesztett felhasználó pénzt fogadni tud, de küldeni nem. Ha be kell azonosítani a felhasználót, hívjátok az ügyfélszolgálatot vagy írjatok a support@barion.com-ra.

Elfogadóhely nyitás

Fizetés elfogadáshoz elfogadóhelyet is kell nyitni. A teszt szerveren az elfogadóhely nyitás után az elfogadóhely azonnal automatikusan jóváhagyásra kerül, de figyelem, az éles szerveren jóváhagyás kell.

Teszt bolt

Ebben a teszt boltban lemezeket lehet venni, persze játékpénzért, és soha nem szállítjuk ki. :-)

http://testshop.test.barion.com/

Teszt bankkártya

Az alábbi teszt bankkártyával bármely teszt felhasználónak tetszőleges összeget lehet feltölteni. Tudnotok kell, hogy ez játék pénz, igazi értéket nem képvisel, csak tesztelési célokat szolgál. A tranzakció azonban valódi, tehát megjárja a banki rendszert, azaz a sebessége ingadozó lehet, mint az éles működésnél, illetve nem működik, ha a bank leáll, ami évente 1-2 alkalommal előfordul karbantartás miatt.

Kártyaszám: 4908 3660 9990 0425
Lejárat: bármilyen jövőbeni dátum
CVC2: 823

FONTOS: A tesztkártyáról időnként sajnos elfogyhat a pénz. Általában legkésőbb másnapra megjavul a helyzet, de sajnos erre az összegre nincs ráhatásunk. Kérünk mindenkit, hogy amennyiben teheti, kis összegekkel teszteljen!

Barion Mobil App tesztszerverre csatlakoztatása

A hivatalos, legfrissebb Barion alkalmazást kell letölteni, viszont loginnál a test# előtagot kell az e-mail elő biggyeszteni, így be lehet lépni a teszt szerverre. Természestesen ehhez a teszt szerveren kell usert regisztrálni. A parkolás is működik, de az NMFR teszt szerverén (ami nem mindig működik), azaz ha ezzel parkolsz, megbüntetnek, mert ez csak teszt, nem igazi parkolás!

test#youremail@example.com

Barion API URL

A Barion API, illetve a teszt API az alábbi URL-eken keresztül érhető el. A dokumentációban található API hívások elérési útvonalai minden esetben az alábbi base URL-ek után írva értendők. Minden API hívás szigorúan biztonságos HTTPS protokollon keresztül kell, hogy történjen. A dokumentációban található API hívások minden esetben az éles rendszerre értendők.

Base URL éles rendszer esetén

https://api.barion.com/

Base URL teszt rendszer esetén

https://api.test.barion.com/

Fontos: amennyiben a teszt rendszerhez kapcsolódáskor SSL-t szeretnénk használni, az API hívások működéséhez a hívó gépen telepíteni kell az alábbi certificate-et: https://certs.godaddy.com/repository/gd_bundle-g2.crt

API hívások módja

Minden egyes API hívásnál meg van adva, hogy az adott végpont milyen módon hívható. Ez lehet HTTP GET, HTTP POST vagy SignalR protokollon keresztüli eseménykezelés. Amennyiben egy API hívást nem a megfelelő módon hívunk, a rendszer egy XML formátumú hibaüzenetet küld.

Példa: GET módon próbálunk meg hívni egy POST típusú végpontot.

<Error>
  <Message>The requested resource does not support http method 'GET'.</Message>
</Error>

RESTful működés

A Barion API az úgynevezett RESTful (REpresentational State Transfer) működési elvet követi.

SignalR

FIGYELEM! A SignalR használata nem szükséges a Barion Smart Gateway online fizetések fejlesztéséhez.

A Barion API az azonnali üzenetek küldésére a SignalR csomagot használja. A SignalR egy olyan protokoll-csomag, amivel a valós idejű kommunikáció könnyebben megvalósítható. Alábbiakban bemutató jelleggel írunk a technológiáról, a részletes (angol nyelvű) dokumentációt a SignalR hivatalos oldalán találjuk. A SignalR képes arra, hogy a kliens és szerver között egy működő kétirányú kommunikációs csatornát nyisson a kliens és a szerver technikai lehetőségeihez mérten. Ezt a csatornát a SignalR mind a szerver oldalon mind a kliens oldalon folyamatosan nyitva tartja, ameddig csak tudja, hogy az üzenetküldés zavartalan legyen. A szerver oldalon ezt egy ún. HUB intézi, míg a kliens oldalon egy ún. proxy kliens. A szerver a Barion esetében a Barion API (azon belül pedig egy HUB), a kliens pedig lehet bármi, ami kapcsolódni szeretne: egy mobil, egy pénztárgép, egy másik szerver, stb. A lényeg, hogy a klienshez legyen elérhető egy SignalR implementáció a kliens programozási nyelvén.

A kommunikáció kölcsönös megegyezésen alapszik, a szerver meghatároz bizonyos nevű és a paraméterű metódusokat, amiket szeretne meghívni a kliensen. Ha kliens ezeket implementálja, akkor a szerver meg fogja tudni ezeket hívni, ha nem akkor ezek az üzenetek nem jutnak el a klienshez. A Barion esetében például a szerver szeretne időnként szólni a klienseknek, hogy új tranzakciójuk érkezett. Ehhez azt várja el, hogy a kliensek implementáljanak egy NewTransaction nevű metódust, aminek paramétere egy tranzakció (részletesebben lásd a NewTransaction-v1 oldalon). Ha a kliens ezt implementálja, akkor a szerver ezt adott pillanatban meg fogja hívni, átadja neki az adatokat és rábízza a kliensre, hogy mit csinál velük. Ez a működés fordítva is igaz, a szerver definiál olyan metódosukat, amiket a kliensek tudnak hívni. A barion esetében ilyen például a RegisterDevice szerver metódus, amiben kliensek tudják a SignalR kapcsolatukat beregisztrálni.

Használt protokollok

A SignalR csomag több kommunikációs protokollt is lehetővé tesz, hogy minden technikai felszereltségű szerver és kliens kommunikációt lehetővé tegyen. A legkorszerűbb protokoll, amely kliens és szerver között létrejöhet az a websocket kapcsolat, de amennyiben erre nincs lehetőség a SignalR megpróbál más protokollokat használni. Amennyiben a kliens és a szerver is képes egy adott protokoll kezelésére, akkor a SignalR azt fogja használni az üzenetek közvetítésére. Ha nem kompatibilisek egy adott protokollra nézve a felek, akkor a következő próbálkozási sorrendben halad a SignalR:

  1. Websocket
  2. Server Sent Events
  3. Forever Frame
  4. Longpolling

Kapcsolat kiépítése

Ahhoz, hogy a szerver és a kliens kommunikálni tudjon egymással ki kell építeni egy kapcsolatot közöttük. A SignalR csomag több programozási nyelven is elérhető, de mindegyik esetében nagyjából hasonlóan zajlik a kapcsolódás :

  1. Kapcsolat definiálása: beállítjuk a szerver címét.
  2. Proxy létrehozása: definiálunk egy kliens oldali proxyt, ami kezeli a kapcsolódást.
  3. Eseményekre feliratkozás: meghatározzuk, hogy melyik szerver által küldött üzenet esetén mit csináljon a kliensünk .
  4. Kapcsolat felépítése: elindítjuk a kapcsolatot.
  5. Szerver hívások indítása': Meghívjuk a szerver oldali metódosukat,

A szerveren egy speciális címen egy ún. HUB-hoz kell kapcsolódni, ez intézi ugyanis a SignalR hívások kezelését. A Barion esetében a SignalR elérési útvonalai a következők:

Barion SignalR URL éles rendszer esetén

https://api.barion.com/barionsignal

Barion SignalR URL teszt rendszer esetén

https://api.test.barion.com/barionsignal

Mindkét környezetben a HUB címe: barionHub.

Az alábbi példa javascript-ből kapcsolódik a Barion HUB-hoz illetve feliratkozik a myEvent hívásra

Ahhoz, hogy javascriptből csatlakozni tudjunk szükségünk lesz a következő javascript csomagokra:

  1. jQuery
    <script src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
  2. SignalR jQuery plugin
    <script src="~/jquery.signalr-2.1.2.min.js"></script>
  3. Barion SignalR kliens proxy
    <script src="https://api.barion.com/barionsignal/hubs"></script>
    Figyelem: A teszt környezetben ez a cím: https://api.test.barion.com/barionsignal/hubs

Ha ezeket hivatkoztuk az oldalunkba, akkor már csak a kapcsolódás van hátra:

var barionSignalR = 'https://api.barion.com/barionsignal';
var barionHubName = 'barionHub';
 
// 1. A kapcsolat definiálása
var myConnection = $.hubConnection(barionSignalR);
 
// 2. A proxy létrehozása
var barionHubProxy = myConnection.createHubProxy(barionHubName);
 
// 4. Kapcsolat felépítése
myConnection.start().done(function () {
 
   // The connection is established here...
 
});

Eszköz regisztrálása a rendszerbe

Miután kiépült a kapcsolat regisztrálnunk kell az eszközünket, különben nem kapjuk meg a feliratkozott események üzeneteit. Erről ITT találunk bővebb információt.

Feliratkozás szerver üzenetekre

Ahhoz, hogy értesüljünk a szerver üzeneteiről, azokra fel kell iratkoznunk. Ezt javascriptből úgy tehetjük, hogy a már definiált proxy-n feliratkozunk a távoli hívásra. Az alábbi példában javascriptből iratkozunk fel a myEvent üzenetekre.

barionHubProxy.on('myEvent', function (trDetail) {
    console.log(trDetail);
});

Szerver oldal meghívása

Lehetőségünk van a szerver felé is hívásokat intézni. Ehhez tudnunk kell, hogy mi a metódus neve és milyen paramétereket fogad. Fontos, hogy ezek a hívások csak a kapcsolat kiépülése után történhetnek.

Az alábbi példában a kliens a szerver oldali myServerMethod hívja és elküldi neki a someData objektumot. Amennyiben a szerver válaszul küld adatot, azt a returnValue paraméterben kapjuk meg.

var someData = {
    UserName: 'someone@example.com'
}
myConnection.start().done(function () {
 
    // Szerver oldali metódus meghívása
    barionHubProxy.invoke('myServerMethod', someData).done(function (returnValue) {
        console.log(returnValue);
    });
})

Hibakeresés

A kliens oldalon általában minden programnyelvi implementációjában a SignalR-nek lehetőség van a loggolás bekapcsolására. Javascriptben így lehet:

myConnection.logging = true;

A Barion API által használt adattípusok

string Karakterlánc típusú adat. A Barion APIban minden string UTF-8 kódolású.
integer 32 bites egész szám típusú érték.
GUID (Global Unique Identifier) Egyedi azonosító; 128 bit hosszú hexadecimális érték, 32 karakteren ábrázolva, az alábbi formátum szerint: 21EC2020-3AEA-4069-A2DD-08002B30309D. A Barion rendszerén belül kizárólagosan egyedi érték. Ezt használja az API például az egyes tranzakciók azonosítására.
datetime Dátum és idő, általában stringként ábrázolva az ISO-8601 szabvány szerint, az alábbi formátumban: 2014-12-06T08:35:46Z. Az egyes API hívások esetén kapott válaszban minden dátum stringként adódik át.
boolean Logikai igaz (TRUE) vagy hamis (FALSE) értéket tartalmazó típus.
byte Valamely meghatározott értékkészletű felsorolás (ENUM) egy eleme. Lényegében egy egész szám, csak a belső működés szempontjából tartozik hozzá egy ENUM érték. Ilyen adatokat tartalmaz például a tranzakciók típusát leíró lista.

Verziók

Azokban az esetekben, ahol olyan módosítás kerül bevezetésre az API-ba, ami az eddigi integrált rendszerek módosítását is megköveteli, verzióemelést hajtunk végre. Az API-t mindig verziószámmal hívjuk, hogy elkerüljük a hibákat! (Ha anélkül hívjuk, akkor az olyan, mintha az egyes verziót hívnánk).

A verziók nem a teljes API-ra vonatkoznak, hanem csak az egyes metódusokra.

Példa a verziózott API hívásra:

https://api.barion.com/v2/Payment/Start