Payment-Start-v2

A Barion wikiből


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

Tranzakció indítása

POST /v2/Payment/Start

A bolttulajdonos vagy a szolgáltatója ezzel a hívással tud fizetési tranzakciót indítani a Barion Smart Gateway-en.

A rendszer két fajta fizetési tranzakciót támogat:

  • azonnalit - a fizető fél pénze azonnal átkerül a fizetést kapóhoz, vagy
  • befoglalásost - a fizető féltől levonásra kerül az adott összeg és befoglalásra kerül, a fizetést kapó a véglegesítésig nem használhatja fel a kapott összeget.

A Barion két fajta díjat számol fel:

  • kártyahasználati díj,
  • gateway használati díj.

A díjak minden esetben a fizetési tranzakciót indítótól kerülnek levonásra.

A Barion Smart Gateway lehetővé teszi, hogy a fizetési tranzakciót hívó és a fizetést megkapó különböző legyen.

Ha a fizetést indító felhasználó a fizetési tranzakció során nem kap elég pénzt a Barion díjak fedezésére, akkor a díjakat a rendszer a fizetést indító felhasználó egyenlegéből vonja. Amennyiben az egyenleg nem fedezi a díjakat, a tranzakció indítás visszautasításra kerül. Befoglalásos esetben, mivel a véglegesítéskor akár a teljes összeget vissza lehet adni a fizető félnek, a tranzakciót kezdeményező felhasználónak a tárcájában kell rendelkeznie elegendő egyenleggel a tranzakció elindításához.

Azonnali tranzakció

  • A fizető fél azonnal kifizethet egy, vagy több tranzakciót
    • A hívónak
    • Más Barion felhasználónak
  • A hívónak lehetősége van díjakat levonni a pénzt kapó felektől más Barion felhasználók felé
    • A tranzakciók fogadó felektől a hívó felé
    • A tranzakciót fogadó felektől harmadik fél felé

Visszahívás (Callback)

A v2-es API a fizetés indításakor megadott visszahívási URL-t használja, illetve ha nem volt megadva, akkor a bolt adatainál megadottat. Abban különbözik a két hívás, hogy itt nem TransactionId, hanem PaymentId paraméterrel történik a hívás, ami a létrejött fizetés Barion egyedi azonosítóját tartalmazza.

Payment-Callback-v2

Bemenet

Mező neve Mező típusa Kötelező Megkötések Alapértelmezett érték Leírás Formátum / Példa
POSKey Guid Kötelező nincs nincs A Barion által generált titkos azonosító, amely fizetések indítására felhatalmaz, de a Barion tárcához hozáférést nem biztosít. 999FFDDA-04FF-333F-CCCC-345FCB555FFC
PaymentType PaymentType Kötelező nincs "Immediate", "Reservation" Vásárlás típusa, ami lehet befoglalásos(Reservation) vagy azonnali(Immediate). Mindkét esetben megtörténik a fizetés, viszont a befoglalásos esetben a boltnak lehetősége van a megadott időkorláton belül módosítani a tranzakciók összegét azzal a feltétellel, hogy az összeg nem lehet nagyobb, mint az eredeti összeg. Immediate
ReservationPeriod TimeSpan (n:óó:pp:mm) Befoglalás esetén kötelező min 1 perc max 1 év n/a A befoglalás időtartama. Csak befoglalás típusú vásárlás esetén használható, minden más esetben figyelmen kívül hagyja a rendszer. Ennyi ideje van a boltnak, hogy a felhasználó által már kifizetett tranzakciókat véglegesítse. Amennyiben ez nem történik meg a rendszer automatikusan átvezeti a befoglalt összegeket a fizetést végző felhasználóhoz. Alapértelmezetten 30 perc. 7.00:00:00 (egy hét)
PaymentWindow TimeSpan (n:óó:pp:mm) Opcionális min 1 perc max 1 hét "00:30:00" A tranzakció létrehozása és a kifizetése közötti maximális idő. Ennyi idő áll a felhasználó rendelkezésére, hogy a bolt által létrehozott tranzakciót kifizesse. Alapértelemezetten 30 perc. 01:00:00 (egy óra)
GuestCheckOut bool (true/false, 1/0 nem jó) Kötelező nincs nincs A tranzakciót anonim felhasználó is kifizetheti. Azok a felhasználók, akik még nem tagjai a Barion rendszernek csak bankkártyával fizethetnek és az email cím megadása kötelező a kártyás csalások csökkentése miatt. true
InitiateRecurrence bool (true/false, 1/0 nincs) Opcionális nincs nincs Ezzel jelezheti a bolt, hogy ismétlődő fizetést kezdeményez és a felhasználónak a Barion felületén ezt is el kell fogadnia. Csak ismétlődő fizetéskor kell megadni. true
RecurrenceId string Opcionális max 100 karakter nincs Az ismétlődő fizetéshez használt azonosító. Csak ismétlődő fizetéskor szabad megadni. Nem ismétlődő fizetéskor a paramétert sem kell megadni. Boltonként és felhasználókként egyedi kell, hogy legyen. (Lehetőség van arra is, hogy egy felhasználó fizetési módjai között is különbséget tegyünk. Ez az integrációra van bízva, hogy mi alapján generálja az azonosítót.) RecurrenceId_01
FundingSources FundingSourceType[] Kötelező nincs nincs A tranzakció kifizetésére felkínált módok. Mindenképpen tartalmaznia kell a Barion tárcás fizetés lehetőségét. FundingSourceType
PaymentRequestId string Opcionális max 100 karakter nincs A bolt rendszerében a fizetés azonosítója. Az exportált számlatörténetben megjelenik, így könnyedén felhasználható a könyvelés megkönnyítéséhez. fa-01
PayerHint string Opcionális max 256 karakter nincs A kifizetést végrehajtó személy Barion felhasználóneve. Ez csupán kényelmi funkció, bárki végrehajthatja a fizetést attól függetlenül, hogy ki lett megadva. Amennyiben ez a mező nem üres, úgy a felületen a bejelentkezéshez előre kitöltésre kerülnek a mezők ezzel is gyorsítva a vásárlási folyamatot. payer@barion.com
RedirectUrl string Opcionális max. 2000 karakter nincs URL, ahova az adott fizetés befejeztével a felhasználó átirányításra kerül. Ehhez a címhez query stringben automatikusan hozzáfűződik a "paymentId" paraméter. Amennyiben nincs megadva, a rendszer a bolthoz kapcsolódó átirányítási URL-t fogja használni. http://shop.example.com/thank-you-page
CallbackUrl string Opcionális max. 2000 karakter nincs URL, ahova az adott fizetés befejeztével a Barion rendszer visszahív. Ehhez a címhez query stringben automatikusan hozzáfűződik a "paymentId" paraméter. Amennyiben nincs megadva, a rendszer a bolthoz kapcsolódó visszahívási URL-t fogja használni. http://shop.example.com/callback
Transactions PaymentTransaction[] Kötelező nincs nincs A vásárláshoz kapcsolódó tranzakciók listája (egy PaymentTransaction típusú objektumokat tartalmazó tömb) PaymentTransaction
OrderNumber string Opcionális max 100 karakter nincs A tranzakciót indító fél oldalán a megrendeléshez tartozó azonosító. A Barion és az integráló fél rendszerének könnyebb illesztését segíti elő. A generált havi számlakivonaton és az exportált számlatörténetben megjelenik, így könnyedén felhasználható a könyvelés megkönnyítéséhez is. Order_01
ShippingAddress ShippingAddress Opcionális max 100 karakter nincs A megrendelés szállítási címe. Bár nem kötelező, ha meg van adva, javítja az antifraud rendszer hatékonyságát, ezért érdemes átadni. 2016. szeptember 1-től hazsnálható! ShippingAddress
Locale string Kötelező max 10 karakter nincs Milyen nyelven jelenjen meg a fizető felület. Az alkalmazható nyelvek listája itt elérhető: https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx A rendszer jelenleg magyar(hu-HU), angol(en-US), szlovák(sk-SK), szlovén(sl-SI), német(de-DE), spanyol(es-ES) és francia(fr-FR) nyelvet támogat. Ha valaki szeretne más nyelvet, a stringeket egy Excelben át tudjuk adni, és ha visszakapjuk lefordítva, feltelepítjük. Keressétek a supportot. hu-HU
Currency string Kötelező 3 karakter nincs A fizetés devizaneme. A devizanemet ISO 4217-es formátumban kell megadni. Elfogadott értékek: HUF, EUR, USD. HUF

Kimenet

A kimenet minden hívás esetén hasonló felépítésű. Amennyiben sikeres hívás történt az Error hibatömb üresen érkezik. Ha hiba történt, akkor a hibatömbben láthatóak ezek a hibák, de ilyen esetben csak a hibákat tartalmazó tömb érkezik a hívóhoz.

Sikeres

Mező Típus Leírás Formátum / Példa
PaymentId Guid A Barion által regisztrált fizetési tranzakció azonosítója. 494be593-57d8-4553-aff3-9345740bdc3d
PaymentRequestId string A fizetést kezdeményező fél által megadott tranzakció azonosító. "FAC-PAY-ID-01"
Status PaymentStatus A fizetési tranzakció állapota a Barion rendszerben Prepared
QRUrl string A fizetéshez tartozó QR kód letöltésére használható URL. "https://api.barion.com/qr/generate?paymentId=7F47019C6D6A482DB316792ABA6220E6"
RecurrenceResult RecurrenceResult Ismétlődő fizetés állapotára utaló információ. Ha van a Start hívásban érvényes recurrenceID, de nincs TRUE értékű initiate, akkor az egy felhasználói interakció nélküli fizetés. A RecurrenceResult paraméterben látszik az eredmény. Recurring paymentél már a Start végrehajtja a chargeolást, nincs szükség GetPaymentState-re. Lehetséges értékek: None – nem volt recurring kérés; Successful – első hívás esetén azt jelenti, hogy létrejött a recurrence, a többinél azt, hogy sikeres volt a terhelés; Failed – első hívás esetén nem sikerült a recurrence létrehozása, korábban sikeres utáni hívás esetén nem sikerült az újraterhelés; NotFound – nem található olyan fizetés, amire ez a recurrenceId hivatkozik "None"
Transactions TransactionResponseModel A fizetéshez tartozó összes Barionban nyilvántartott e-pénz tranzakció. TransactionResponseModel
GatewayUrl string A Barion Smart Gateway címe, ahová a fizető felhasználót át kell irányítani http://secure.barion.com/Pay?id=7F47019C6D6A482DB316792ABA6220E6
CallbackUrl string A fizetéshez kapcsolódó visszahívási URL, ahova a fizetés után a Barion rendszere visszahívást intéz.
RedirectUrl string A fizetéshez kapcsolódó átirányítási URL, ahova a felhasználó a sikeres fizetés után átirányításra kerül.

Sikertelen

Hiba esetén a válasz egy hibalistát ad vissza. Ebben megtalálhatóak az előforduló hibák. A lista formátuma:

{
    Errors: [
        {
            ErrorCode: "",
            Title: "",
            Description: ""
        }
    ]
}
Hiba kódja Hiba leírása
AuthenticationFailed Nem megfelelő felhasználónév és jelszó. Ellenőrizd, hogy az adott Barion környezetben létezik-e a megadott felhasználó és a jelszó helyes-e.
InvalidShop Nem megfelelő bolt. Ellenőrizd, hogy a megadott azonosítóval létezik-e bolt a megadott Barion környezetben.
InvalidUser Nem megfelelő felhasználó. Ellenőrizd, hogy az adott Barion környezetben létezik-e a megadott felhasználó.
RecurrencePaymentNotAllowed A hívó számára nincs engedélyezve az ismétlődő fizetés funkció használata. Vedd fel a kapcsolatot az ügyfélszolgálattal és kérd, hogy engedélyezzék neked ezt a funkciót.
InvalidRecurrenceId Nem megfelelő azonosító az ismétlődő fizetés indításához. Valószínűleg a megadott környezetben még nem inicializáltál ezzel az azonosítóval fizetést vagy a falhasználó még nem hagyta azt jóvá.
UserCantReceiveEMoney A felhasználó nem fogadhat pénzt. Valószínűleg a felhasználó még nem a Barion rendszer része vagy már törölt felhasználó. A Barion fizetési rendszert használva nem fizethetsz nem regisztrált, regisztrált, de nem aktivált vagy törölt felhasználóknak.
TransactionAmountLessThanSumOfSubTransactionsAmount Befoglalásos fizetés esetén kaphatod ezt a hibaüzenetet. Amennyiben a tranzakció összeget meghaladják a beágyazott tranzakciók összegei, akkor nem tudod lezárni a befoglalásos fizetést.
UserCantMakeOutgoingTransaction A felhasználó nem kezdeményezhet kimenő tranzakciókat. Valószínűleg felfüggesztésre került az a felhasználó, akivel a fizetést kezdeményezni szeretnéd, esetleg egy vagy több felhasználó a beágyazott tranzakciókban résztvevők közül.
DoNotHaveEnoughMoneyToPreparePayment A bolt felhasználónak nincs elegendő pénze a tranzakció kezdeményezéséhez. Amennyiben csak közvetítőként veszel részt a fizetési tranzakcióban és kártyahasználati díjat kell fizetned, akkor rendelkezned kell megfelelő egyenleggel a fizetés indításához. A vonatkozó díjakat közvetítői részvétel esetén vagy befoglalásos fizetési tranzakciók esetén automatikusan előre befoglalja a rendszer. Ezeket automatikusan visszakapod ha a fizetés meghiúsul.
OriginalPaymentWasntSuccessful Ismétlődő fizetés esetén, ha a RecurrenceId-ban olyan korábbi fizetési tranzakcióra hivatkozunk, ami nem volt sikeres (lejárt, felhasználó megszakította), akkor nem lehet rá ismételten fizetést indítani.

Példák

Az alábbi példák tartalmazzák a formátum helyes JSON példákat egyszerű és összetett vásárlási esetekre.

Azonnali vásárlás

Azonnali vásárlás, amikor a felhasználó a bolt oldaláról átírányításra kerül a Barion fizetési oldalára és ezen az oldalon a fizetés azonnal megtörténik. Ebben az esetben nincs lehetőség vásárláshoz tartozó tételek összegeinek befoglalására, hogy azokat a bolt később érvényesítse.

Egyszerű eset

Azonnali egyszerű vásárlásnak hívjuk azt, amikor a hívó egyben a Barion rendszerben a bolt, az e-pénz a hívó tárcájában íródik jóvá. Ebben az esetben nincsenek további jutalék tranzakciók sem. A bolt nem lehet közvetítő csak a komplex esetben.

Bemenet

{
    POSKey: "999FFDDA-04FF-333F-CCCC-345FCB555FFC",
    PaymentType: "Immediate",
    PaymentWindow: "00:30:00",
    PaymentRequestId: "fa-01",
    PayerHint: "payer@example.com", //itt lehet átadni az e-mail címet
    ShippingAddress: "1117 Budapest, Infopark sétány 1. V. em. 2. "
    GuestCheckOut: true,
    InitiateRecurrence: false,
    Currency: "HUF",
    FundingSources: [
        "All"
    ],
    OrderNumber: "Order-1234",
    Locale: "hu-HU",
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            Payee: "payee@example.com",
            Total: 4500,
            Items: [  //itt lehet átadni a kosártartalmat
                {
                    Name: "Tojás",
                    Description: "Friss tojás",
                    Quantity: 100,
                    Unit: "db",
                    UnitPrice: 45,
                    ItemTotal: 4500,
                    SKU: "EGG-0057"
                }
            ]
        }
    ]
}

Kimenet

{
    PaymentId: "edd81a0a35b0439f91803933d5b3f5ad",
    PaymentRequestId: "fa-01",
    Status: "Prepared",
    RecurrenceResult: "NotFound",
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            TransactionId: "d61bee740ba541c3a1ddd16037786eaa",
            Status: "Prepared",
            Currency: "HUF",
            TransactionTime: "2015-02-26T12:23:36.4497549Z"
        }
    ],
    GatewayUrl: "https://secure.barion.com/Pay?id=edd81a0a35b0439f91803933d5b3f5ad",
    CallbackUrl: "https://webshop.example.com/BarionExamplePayment",
    RedirectUrl: "https://webshop.example.com/PaymentResultExample?paymentId=edd81a0a35b0439f91803933d5b3f5ad",
    Errors: [ ]
}

Összetett eset

Összetett azonnali fizetés, amikor a vásárlást a Barion felületén a felhasználó véglegesíti és az e-pénz jóváíródik a megadott Barion tárcákban. Összetett esetben a tranzakciót indító felhasználó Bolttal kell rendelkezzen a Barion rendszerben, de a fizetés nem kötelezően ebben a boltban történik. A tranzakciót indító felhasználó megadhatja, hogy melyik felhasználóknak szeretné a fizetési tranzakciókat végrehajtani. A fizetési tranzakciók mellett, minden ilyen típusú tranzakcióhoz további jutalék tranzakciók definiálhatóak. A jutalék tranzakciók összege nem lehet nagyobb, mint a kiinduló tranzakció összege.

Bemenet

{
    POSKey: "999FFDDA-04FF-333F-CCCC-345FCB555FFC",
    PaymentType: "Immediate",
    PaymentWindow: "00:30:00",
    PaymentRequestId: "fa-01",
    PayerHint: "payer@example.com", //itt lehet átadni az e-mail címet
    ShippingAddress: "1117 Budapest, Infopark sétány 1. V. em. 2. "
    Locale: "hu-HU",
    Currency: "HUF",
    FundingSources: [
        "All"
    ],
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            Payee: "payee@example.com",
            Total: 5500,
            PayeeTransactions: [
                {
                    POSTransactionId: "TR-01-01-01",
                    Payee: "facilitator@example.com",
                    Total: 150,
                    Comment: "Fee for the facilitation: TR-01-01-01."
                },
                {
                    POSTransactionId: "TR-01-01-02",
                    Payee: "agent@example.com",
                    Total: 50,
                    Comment: "Fee for the agent: TR-01-01-02."
                },
            ],
            Items: [ //itt lehet átadni a kosár tartalmat
                {
                    Name: "Tojás",
                    Description: "Friss tojás",
                    Quantity: 100,
                    Unit: "perc",
                    UnitPrice: 43,
                    ItemTotal: 4300,
                    SKU: "EGG-0057"
                },
                {
                    Name: "Lekvár",
                    Description: "Házi készítésű baracklekvár",
                    Quantity: 10,
                    Unit: "l",
                    UnitPrice: 100,
                    ItemTotal: 1000,
                    SKU: "JAM-0057"
                }
            ]
        }
    ]
}

Kimenet

{
    PaymentId: "edd81a0a-35b0-439f-9180-3933d5b3f5ad",
    PaymentRequestId: "fa-01",
    Status: "Prepared",
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            TransactionId: "d61bee74-0ba5-41c3-a1dd-d16037786eaa",
            Status: "Prepared",
            Currency: "HUF",
            TransactionTime: "2015-02-26T12:23:36.4497549Z"
        },
        {
            POSTransactionId: "TR-01-01-01",
            TransactionId: "c157e796-4ce3-4563-ae6d-2cd30e6fd90c",
            Status: "Prepared",
            Currency: "HUF",
            TransactionTime: "2015-02-26T12:23:36.4587574Z"
        },
        {
            POSTransactionId: "TR-01-01-02",
            TransactionId: "f9296660-b07e-4b9d-969d-e1678bd84e8a",
            Status: "Prepared",
            Currency: "HUF",
            TransactionTime: "2015-02-26T12:23:36.4607555Z"
        }
    ],
    RecurrenceResult: "NotFound",
    CallbackUrl: "https://webshop.example.com/BarionExamplePayment",
    RedirectUrl: "https://webshop.example.com/PaymentResultExample?paymentId=edd81a0a35b0439f91803933d5b3f5ad",
    Errors: [ ]
}

PHP példakód

PHP integrációhoz elérhető a Barion PHP library-je, amely példákat is tartalmaz.

Hibás esetek

Hibás hívás

Az alábbi példában nem létező POSKey-el indítunk hívást és emiatt a Barion rendszer hibát ad vissza. Bemenet

{
    POSKey: "999FFDDA-04FF-333F-CCCC-345FCB555FFC",
    PaymentType: "Immediate",
    PaymentWindow: "00:30:00",
    PaymentRequestId: "fa-01",
    PayerHint: "payer@example.com",
    Locale: "hu-HU",
    Currency: "HUF",
    FundingSources: [
        "All"
    ],
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            Payee: "payee@example.com",
            Total: 4500,
            Products: [
                {
                    Name: "Kecskesajt",
                    Description: "Frissen készült házi kecskesajt",
                    Quantity: 1,
                    Unit: "kg",
                    UnitPrice: 4500,
                    ItemTotal: 4500,
                    SKU: "CHE-0057"
                }
            ]
        }
    ]
}

Kimenet

{
    "Errors": [
        {
            ErrorCode: "AuthenticationFailed",
            Title: "User authentication failed.",
            Description: "The login information provided is incorrect. There is no such user in the system or the password is incorrect."
        }
    ]
}

Hiányzó paraméterek

Az alábbi példában nincs megadva a POSId és a PaymentRequestId paraméter, emitt hbát kapunk vissza a Barion rendszertől.

Bemenet

{
    POSKey: "999FFDDA-04FF-333F-CCCC-345FCB555FFC",
    PaymentType: "Immediate",
    PaymentWindow: "00:30:00",
    Currency: "HUF",
    FundingSources: [
        "All"
    ],
    Transactions: [
        {
            POSTransactionId: "fa-01-01",
            Payee: "payee@example.com",
            Total: 4500,
            Items: [
                {
                    Name: "Kecskesajt",
                    Description: "Frissen készült házi kecskesajt",
                    Quantity: 1,
                    Unit: "kg",
                    UnitPrice: 4500,
                    ItemTotal: 4500,
                    SKU: "CHE-0057"
                }
            ]
        }
    ]
}

Kimenet

{
    Errors: [
        {
            ErrorCode: "ModelValidationError",
            Title: "Model Validation Error",
            Description: "Required property 'POSId' not found in JSON. Path '', line 23, position 2."
        },
        {
            ErrorCode: "ModelValidationError",
            Title: "Model Validation Error",
            Description: "The PaymentRequestId field is required. "
        }
    ]
}