Payment-StartTransaction-v1

A Barion wikiből


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

Tranzakció indítása

POST /Payment/StartTransaction

Az alábbi hívással egy bolt új tranzakciót indíthat egy adott összeggel. A tranzakció indításához meg kell adnia a saját barionos azonosítóját, a tranzakció összegét, valamint a tranzakció saját oldalán tárolt azonosítóját. Amennyiben minden adat érvényes, a Barion rendszere elindít egy függőben levő vásárlási tranzakciót. A hívás válaszában visszaküldi a boltnak ezen tranzakció barionos azonosítóját, valamint azt az URL-t, amelyet a bolt a tranzakcióhoz tartozó QR kód generálásához használhat fel.

Ez az eset áll fenn például egy helyszíni bolti fizetés lebonyolításakor, amikor a vevő Barionnal fizet: a bolt egy új tranzakciót indít a Barion rendszerében, majd az előállt tranzakciós azonosító alapján egy QR kódot jelenít meg a vevőnek, aki így azt mobilkészülékével kifizetheti (amennyiben a készülék képes a közelségi fizetés lebonyolítására, a folyamat sokkal egyszerűbb és korszerűbb). Ezt az API hívást használja továbbá minden online webshop, amikor a vásárló Barionnal kíván fizetni.

Ezzel az API hívással lehet egy online elfogadóhely esetében olyan vásárlást indítani, ahol a vásárló Barionnal fizet. Megkülönböztetünk két típusú vásárlást attól függően, hogy a tranzakció azonnal létrejön-e. Azonnali vásárlás esetén a vásárló pénze azonnal átvezetésre kerül a bolt tárcájába míg a befoglalásos vásárlás esetén a pénzösszeg először zárolásra kerül és később, amikor a bolt úgy dönt, hogy a tényleges vásárlás megtörtént, akkor kerül átvezetésre a bolt tárcájába.

Ezek mellett lehetőség van közelségi fizetésre illetve fizikai beolvasásra is. Közelségi fizetés esetén Bluetooth technológiával és a Barion szerverek segítségével történik a korszerű fizetés, míg fizikai beolvasás esetén egy QR kód beolvasásával.

Bemenet

Mező neve Mező típusa Kötelező Megkötések Alapértelmezett érték Leírás Formátum / Példa
UserName string Kötelező min. 6, max. 254 karakter nincs Az API hívás hívójának Barion azonosító e-mail címe. user@example.com
Password string Kötelező min. 8, max. 100 karakter nincs Az API hívás hívójának jelszava. EgySimaJelszo
ApplicationId GUID Kötelező nincs nincs A tranzakciót indító Barion bolt egyedi azonosítója. Ezt a Barion rendszerébe belépve az adott bolt részleteinél láthatjuk. (Funkciók/Bolt kezelése menüpont alatt található boltlistában a Részletek gombra kell kattintani) c82e38cc-6de0-41a1-8816-ee70c37f3c22
Amount integer Kötelező Pozitív egész szám, min. 1 nincs A bolt által indított tranzakció összege, ezres elválasztók és pénznem feltüntetése nélkül. Független a Products listában megadott termékek összegétől, ezért akár kedvezményes árat is meg lehet adni. 1000
Products Products Opcionális nincs nincs Vásárlási tranzakció esetén a vásárolt termékek listája. Products
ShopTransactionId string Kötelező nincs nincs A tranzakció azonosítója a bolt saját rendszerén belül. TRANS-0001
IsReservation boolean Opcionális nincs False Igaz értékre kell állítani, ha befoglalást szeretnénk indítani és nem azonnali fizetést. False
ReservationPeriod TimeSpan Kötelező, ha IsReservation=true nincs nincs Azt az időtartamot jelenti, ameddig a befoglalt pénzt még véglegesíteni lehet. Az időtartam letelte után a tranzakció véglegesítése nem lehetséges, a felhasználó visszakapja a befoglalt összeget. Csak IsReservation=True esetben veszi figyelembe a rendszer. 12:00:00 (tizenkét óra)

Kimenet

A kimenet minden hívás esetén hasonló felépítésű. Amennyiben sikeres hívás történt az ErrorList hibatömb üresen érkezik. Ha hiba történt, akkor a hibatömbben láthatóak ezek a hibák, de ilyen esetben is megkapjuk a többi kimeneti paramétert, csak üresen vagy pedig egy default alapértékkel.

Mező Típus Leírás Formátum / Példa
TransactionId GUID A létrejött tranzakció egyedi azonosítója a Barionban. 04ED8C89-C9BD-4C17-92F6-A0964587BBFF
QRUrl string A tranzakcióhoz tartozó QR kód generálásához szükséges URL. Ezt az URL-t használhatja fel a bolt, hogy a tranzakciót QR kódolvasás segítségével kifizettesse például helyszíni bolti fizetés esetén. Fontos: a kapott URL önmagában nem elég a QR kód generálásához, ahhoz hozzá kell fűzni az authentikációs paramétereket (UserName, Password) is! Lásd: QR-Generate-v1 https://api.barion.com/qr/generate?transactionId=179c29f8-4571-482f-97cf-d26dd9456f9d&size=Large
ErrorList Errorlist A kérés során esetlegesen felmerülő hibákat tartalmazó tömb. Sikeres hívás esetén ez a tömb üres. Errorlist

Hibakódok

Hiba kódja Hiba leírása
1 Nem megfelelő felhasználónév vagy jelszó.
999 Ismeretlen hiba történt a kérés feldolgozása során.
1003 A bemeneti paraméterek valamelyike nem felelt meg az előírásoknak. Ez a hiba annyiszor szerepel(het) a kimenetben, ahány mező hibás volt. Ez esetben az ErrorMessage mezőben található a konkrét hiba: a Validation Error után látható a hibás mező megnevezése, a Value pedig a hiba leírását tartalmazza.
3 A bolt tulajdonosa felfüggesztésre került.
4 A bolt tulajdonosa törlésre került a rendszerből.
201 A befoglalt összeg már nem véglegesíthető, mert a befoglalásra szánt időtartam lejárt.
202 A befoglalás időtartama nincs megadva vagy nem megfelelő formátumú. Amennyiben az IsReservation igazra van állítva, akkor a ReservationPeriod megadása kötelező.
1001 A megadott Barion bolt azonosítója nem található a Barionban.
1002 A megadott Barion bolt azonosítója formailag helytelen (nem GUID formátumú).
1004 A bolt le van zárva a Barionban, nem indíthat vásárlást.
1007 A bolt törölve van a Barionban.

Példák

Vásárlási tranzakció sikeres indítása

Az alábbi példában a bolt egy új vásárlási tranzakciót indít 650 forint összeggel. A Barion által adott válaszban automatikusan megkapja a tranzakciót kifizettető QR kód generálásához szükséges URL-t is.

Bemenet

{
    UserName: "bolt@example.com",
    Password: "ABoltJelszava",
    ApplicationId: "c82e38cc-6de0-41a1-8816-ee70c37f3c22",
    Amount: 650,
    Products: [
       {
             Name: "Lángos",
             Description: "Sajtos tejfölös lángos",
             Quantity: 1,
             Unit: "db",
             Price: 650,
             SKU: ""
       }
    ],
    ShopTransactionId: "TRANS-0001"
}

Kimenet

{
    TransactionId: "179c29f8-4571-482f-97cf-d26dd9456f9d",
    QRUrl: "https://api.barion.com/qr/generate?transactionId=179c29f8-4571-482f-97cf-d26dd9456f9d&size=Large",
    ErrorList: []
}

Befoglálásos tranzakció sikeres indítása

Az alábbi példában a bolt egy új tranzakciót indít 4500 forint összeggel. A Barion által adott válaszban automatikusan megkapja a tranzakciót kifizettető QR kód generálásához szükséges URL-t is.

Bemenet

{
    UserName: "bolt@example.com",
    Password: "ABoltJelszava",
    ApplicationId: "c82e38cc-6de0-41a1-8816-ee70c37f3c22",
    Amount: 4500,
    Products: [
       {
             Name: "Autómosás",
             Description: "Autótisztítás és mosás",
             Quantity: 1,
             Unit: "db",
             Price: 4500,
             SKU: "CLEAN-0057"
       }
    ]
    ShopTransactionId: "TRANS-0001",
    IsReservation: true,
    ReservationPeriod: "01:00:00" // Egy óra
}

Kimenet

{
    "TransactionId": "1799e90f-e794-441f-a34c-359ff0b1aca0"
    "QRUrl": "https://api.barion.com/qr/generate?transactionId=1799e90f-e794-441f-a34c-359ff0b1aca0&size=Large"
    "ErrorList": []
}

Sikertelen tranzakcióindítás

Hibás bolt azonosító

Az alábbi példában a Barion szerver válasza látható sikertelen tranzakcióindítás esetén. Jelen esetben hibásan adtuk meg a bolt Barionban található azonosítóját.

Bemenet

{
    UserName: "bolt@example.com",
    Password: "ABoltJelszava",
    ApplicationId: "12345678-abcd-abcd-1234-123456789ab",
    Amount: 2000,
    ShopTransactionId: "TRANS-0002"
}

Kimenet

{
    "TransactionId": null,
    "QRUrl": null,
    "ErrorList": [
        {
            "ErrorNumber": 1002,
            "ErrorMessage": "Not Valid ApplicationId",
            "Details": null
        }
    ]
}

Hibás bemeneti paraméterek

Az alábbi példában elfelejtettük megadni a bolt rendszerén belüli egyedi tranzakció azonosítót.

Bemenet

{
    UserName: "bolt@example.com",
    Password: "ABoltJelszava",
    ApplicationId: "c82e38c0c-6de0-41a1-8816-ee70c37f3c22",
    Amount: 3000
}

Kimenet

{
    "TransactionId": null,
    "QRUrl": null,
    "ErrorList": [
        {
            "ErrorNumber": 1003,
            "ErrorMessage": "Validation Error: model.ShopTransactionId Value: The ShopTransactionId field is required.",
            "Details": null
        }
    ]
}