# A dokumentáció megújult

A *Nevogate* szolgáltatásaihoz kapcsolódó dokumentáció megújult. Az új változatban kiemelt figyelmet szántunk a könnyű használatnak, ennek érdekében nem csak a dokumentáció tartalmát, hanem a szerkezetét is frissítettük. A korábbi változattól eltérően az új dokumentáció fizetési eszközökre bontva gyűjti össze a technikai bevezetéshez szükséges információkat.


# Dokumentáció ismertető

Ez a dokumentáció a fizetési megoldások bevezetéséhez és használatához szükséges fejlesztések leírását tartalmazza a Nevogate rendszerének segítségével.

## **Nevogate szemlélet**

Az online fizetés bevezetési módja fizetési szolgáltatónként változó, ezért a bevezetés műszakilag nem egységes, így mindegyik szolgáltató bekötése egyedi fejlesztést igényel. Ennek következménye egy elhúzódó, töredezett és időigényes fejlesztési folyamat, ezt követően pedig a fizetési szolgáltatók rendszereiben történő változások folyamatos követése jelent kihívást.

Erre kínál megoldást a *Nevogate* szolgáltatása mely egységes platformot kínál a fizetési szolgáltatók bevezetéséhez. A *Nevogate* egyetlen közös rendszerbe integrálja a piacon található fizetési szolgáltatók különböző megoldásait, így elegendő csupán a *Nevogate* rendszeréhez kapcsolódni az elérhető fizetési megoldások használatához.

Munkatársaink folyamatosan lekövetik a fizetési szolgáltatók rendszereinek változását, így ezek már nem követelnek további fejlesztést a kereskedő részéről. A fizetési szolgáltatók integrációja mellett a *Nevogate* további, fizetéshez kapcsolódó kiegészítő szolgáltatásokat kínál, amik a fizetési szolgáltatóknál nem mindig érhetők el. A *Nevogate* egy csomagban kínál megoldást az online fizetés teljes folyamatára.

## **A dokumentáció felépítése**

A könnyű használat érdekében a dokumentációt tematikus részre bontottuk, a tematikus részekben található fejezeteket pedig egymáshoz hasonló módon alakítottuk ki. A dokumentáció egyes fejezetei önmagukban is használhatók, így nem szükséges a teljes anyaggal megismerkedni a fejlesztés megkezdése előtt. A dokumentáció a következő módon épül fel:

#### **Kapcsolódás és kommunikáció**

* hitelesítés és kapcsolódás
* tesztrendszer
* éles rendszer

#### **Fizetés**

* egyszeri fizetések (one-time payment)
* egykattintásos fizetés (one-click payment)
* ismétlődő fizetések (recurring payment)
* bankkártya verifikáció

#### **Kiegészítő szolgáltatások**

* riasztási rendszer (*PayAlert*)
* számlázás (*PayBill*)
* könyvelés támogatás (*PayBook*)
* fizetési hivatkozások (*PayLink*)
* kifizetés (*PayOut*)
* SZÉP Kártya visszatérítés elszámolása (*SZÉP Refund*)

#### **Segédlet**

* tranzakció státuszok
* tranzakció állapotok
* erős ügyfél-hitelesítés (PSD2/SCA)
* visszairányítási módok
* extra paraméter szabályok
* fizetési szolgáltató specifikus adatok (feature matrix)
* fizetés integrációja mobilalkalmazásba

## **A dokumentáció használata**

A dokumentáció célja a fejlesztés megkönnyítése, ezért elsősorban gyakorlati tudást tartalmaz. Mindegyik fejezet a funkció rövid bemutatásával indul, ezután következik a folyamat részletes leírása, amit kapcsolódó folyamatábra is szemléltet.

Ezután az adott témához kapcsolódó fejlesztési feladatok leírása következik. Mindegyik fejlesztési feladat tartalmazza a hozzá tartozó API kérés és válasz paramétereket és az ezekhez kapcsolódó mintakódokat, amik felhasználhatók a fejlesztés során.

A funkciók többsége azonnal kipróbálható a fejezet végén elhelyezett hivatkozásokkal, amik a [*Nevogate DEMO*](https://demo.nevogate.com/) felületére mutatnak.


# Hitelesítés és kapcsolódás

Ez a fejezet a hitelesítéshez szükséges adatok előkészítését és a teszt vagy éles rendszerhez való kapcsolódást írja le.

A *Nevogate* rendszerét REST API hívásokon keresztül érheti el. Az éles rendszertől függetlenül egy tesztrendszert is biztosítunk a funkciók kipróbálásához. A kapcsolódáshoz mindkét esetben használjon összetartozó boltnév (`StoreName`) és API kulcs (`ApiKey`) párosokat. Mindkét rendszerhez (teszt és éles) kizárólag sikeres hitelesítést követően kapcsolódhat.


# Hitelesítési adatok előkészítése

Rendszerünk minden API hívást hitelesít a végrehajtás előtt. A kereskedő beazonosítására HTTP alapszintű hitelesítést használunk (HTTP Basic). A sikeres hitelesítéshez készítse elő a következő adatokat:

* `StoreName` és `ApiKey` páros
* `UserAgent` adatok

### **A `StoreName` és `ApiKey` páros előkészítése**

1. Kettősponttal kapcsolja össze a `StoreName` és `ApiKey` párost,
2. kódolja az így keletkezett párost Base64 kódolás segítségével,
3. helyezze el a kódot a HTTP kérés fejlécében (HTTP request header)**.**

#### Példa `StoreName` és `ApiKey` párosra

<table data-full-width="true"><thead><tr><th width="391">Művelet</th><th>Eredmény</th></tr></thead><tbody><tr><td><code>StoreName</code> érték</td><td>sdk_test</td></tr><tr><td><code>ApiKey</code> érték</td><td>86af3-80e4f-f8228-9498f-910ad</td></tr><tr><td>Kettősponttal összekapcsolt páros</td><td>sdk_test:86af3-80e4f-f8228-9498f-910ad</td></tr><tr><td>Az összekapcsolt páros Base64 kódolás után</td><td>c2RrX3Rlc3Q6ODZhZjMtODBlNGYtZjgyMjgtOTQ5OGYtOTEwYWQ=</td></tr><tr><td>Az így keletkezett HTTP kérés fejléce</td><td>authorization: Basic c2RrX3Rlc3Q6ODZhZjMtODBlNGYtZjgyMjgtOTQ5OGYtOTEwYWQ=</td></tr></tbody></table>

### **A `UserAgent` adatok előkészítése**

Minden API hívás esetén adja át `UserAgent` adatait, amit a következő elemekből állíthat össze:

* Hívott metódus neve
* Indított API kérés domain neve vagy IP címe
* Programozási nyelv neve
* Programozási nyelv verziószáma

#### Példa `UserAgent` adatokra

`Providers | merchant-store.com | PHP | 7.3.0`

### **Mintakódok és válaszok**

#### Mintakódok a hitelesítéshez

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --header 'authorization: Basic c2RrX3Rlc3Q6ODZhZjMtODBlNGYtZjgyMjgtOTQ5OGYtOTEwYWQ=' \
  --user-agent 'Providers | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Providers' \
  --data 'json=
    {
      "StoreName":"sdk_test"
    }'
```

{% endcode %}

vagy

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Providers | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Providers' \
  --data 'json=
    {
      "StoreName":"sdk_test"
    }'
```

{% endcode %}

#### A fenti kérésekre adott válasz

{% code overflow="wrap" %}

```php
{
    "Data": [
        {
            "provider_name": "CIB",
            "provider_long_name": "CIB Bank"
        },
        {
            "provider_name": "OTP",
            "provider_long_name": "OTP Bank"
        },
        ...
    ],
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047702"
}
```

{% endcode %}


# Kapcsolódás a tesztrendszerhez

Az elérhető funkciók kipróbálásához előbb kapcsolódjon tesztrendszerünkhöz a következő boltnév (`StoreName`) és API kulcs (`ApiKey`) segítségével.

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Érték</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>sdk_test</td></tr><tr><td><code>ApiKey</code></td><td>86af3-80e4f-f8228-9498f-910ad</td></tr></tbody></table>

{% hint style="info" %}
Egyedi hozzáférés igényléséhez, kérjük lépjen kapcsolatba ügyfélszolgálatunkkal a következő címen:\
\
<business@nevogate.com>
{% endhint %}

### Működés

Tesztrendszer esetében használja a következő URL végpontot az API kérések indításához:

<https://system-test.paymentgateway.hu/api/payment/>


# Kapcsolódás az éles rendszerhez

Az éles rendszer használatához egyedi boltnév (`StoreName`) és API kulcs (`ApiKey`) párosra van szüksége, amiket sikeres szerződéskötés után biztosítunk.

### Működés

Éles rendszer esetében használja a következő URL végpontot az API kérések indításához:

<https://system.paymentgateway.hu/api/payment/>


# Titkosítás és IP címek

A kapcsolódás biztonsága érdekében a teszt és éles rendszereink is előre megadott IP címekről indítanak csak hívásokat. Az említett rendszerek biztonsági tulajdonságai a következők:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Érték</th></tr></thead><tbody><tr><td>A kommunikáció titkosítási protokollja</td><td>TLS 1.2, TLS 1.3</td></tr><tr><td>A <strong>tesztrendszer</strong> a következő IP címekről indít hívást</td><td>79.139.61.237, 185.87.60.17, 185.87.60.18</td></tr><tr><td>Az <strong>éles rendszer</strong> a következő IP címekről indít hívást</td><td>92.119.120.119, 185.87.60.11, 185.87.60.12</td></tr></tbody></table>


# Általános ismertető

Az egyszeri fizetés (*One-time payment*) a legegyszerűbb fizetési forma, amely során a vásárló egyetlen alkalommal fizet. Az egyszeri fizetés szereplői a kereskedő, a vásárló és a fizetési szolgáltató (bank), ezeket a szereplőket a *Nevogate* rendszere köti össze.


# Bankkártya és mobiltárca

**Ebben a fejezetben a bankkártyás és mobiltárcás fizetési megoldások leírását találja.**&#x20;

Bankkártya és mobiltárca használatán túl az egyszeri fizetést a következő fizetési módokkal is igénybe lehet venni (ezekről a dokumentáció megfelelő részében olvashat további információkat):

* SZÉP Kártya
* online áruhitel
* átutalás


# Azonnali terhelés

Ennél a terhelés típusnál a vásárlás összegét közvetlenül a fizetés után vonják le a vásárló számlájáról. Egy másik fejezetben bemutatjuk a kétlépcsős fizetést, ahol a terhelésre a vásárlás után, egy későbbi időpontban kerül sor.


# Fizetési folyamat

A fizetési folyamat leírását három részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított három fő lépés adja, ezek a lépések a következők:

A. **`Init`** - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek\
B. **`Start`** - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - a tranzakció eredményének lekérése rendszerünkből

{% hint style="info" %}
A hármas felosztás ellenére a felsorolt pontok együttesen adják ki a teljes fizetési folyamatot. A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek**

1. A kereskedő oldala rögzíti a vásárló elektronikus fizetési szándékát,
2. ezután a kereskedő oldala új fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén).
5. A kereskedő oldala tárolja az egyedi tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli)

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló megadja bankkártya adatait (vagy kiválasztja a megfelelő mobiltárcát) a fizetési szolgáltató oldalán. (Ezen a ponton a vásárló átirányításra kerülhet a kártyakibocsátó bankhoz, ahol személyazonosságát 3DS hitelesítési folyamattal igazolhatja.)
4. A fizetési szolgáltató visszairányítja a vásárlót rendszerünkbe, a fizetés befejezése után.
5. Rendszerünk lekérdezi a tranzakció eredményét a fizetési szolgáltatótól, majd beállítja a tranzakció végleges státuszát a fizetési szolgáltató válasza alapján,
6. ezután rendszerünk a tranzakció azonosítóval visszairányítja a vásárlót a kereskedő oldalára (az inicializáció (`Init`) során megadott visszatérési URL címre (`ResponseUrl`)).
7. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is.

{% hint style="info" %}
A **B.3.** lépésben leírt 3DS hitelesítési folyamat (3D Secure vagy 3D Secure Code) a pénzügyi visszaélések megakadályozását célzó megoldás. Fizetés során a 3DS a kötelező kártyaadatok bekérésén túl egy egyszer használatos kóddal vagy a kártyakibocsátó bank applikációjában végrehajtott biometrikus azonosítással biztosítja a kártyabirtokos védelmét visszaélésekkel szemben. Használata egyszerű, a vásárlónak mindössze egy mobiltelefonra van szüksége.
{% endhint %}

#### **C. `Result` - a tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala a `ResponseUrl` hívás hatására egy tranzakció azonosítót tartalmazó `Result` kéréssel lekérdezi a tranzakció eredményét rendszerünkből.
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a tranzakció státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a tranzakció státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}


# Tranzakció inicializálása (Init)

### Műkődés

Használja az inicializálás (`Init`) funkciót egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a tranzakció és a vásárló adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

Az inicializálás során figyeljen a következőkre:

* Használjon erős ügyfél-hitelesítést (PSD2/SCA) a vásárló adatainak átadásához. Erről a következő oldalon olvashat részletesebben: [Erős ügyfél-hitelesítés (PSD2/SCA)](/egyszeri-fizetesek-one-time-payment/bankkartya-es-mobiltarca/azonnali-terheles/eros-uegyfel-hitelesites-psd2-sca)
* Tárolja le az `Init` kérésre visszaadott tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobilalkalmazásban**.
{% endhint %}

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="141">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>Barion2</li><li>Borgun (<em>Teya SecurePay</em>)</li><li>Borgun2 (Teya RPG)</li><li>CIB</li><li>GoPay</li><li>GP (<em>Global Payments</em>)</li><li>KHB (<em>K&#x26;H Bank</em>)</li><li>OTPSimple (<em>SimplePay</em>)</li><li>PayPal</li><li>PayPalRest</li><li>PayU2 (Classic)</li><li>PayURest</li><li>PSC (<em>Paysafecard</em>)</li><li>RaiffeisenUPC</li><li>Saferpay (Worldline)</li><li>Stripe</li><li>VivaWallet</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/AyUvdciGvvztBBDbuovo">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td>szabadon választható</td><td>Bruttó végösszeg amit a vásárló kifizet.<br><br>(Magyar forint (HUF) esetén értéke egész szám.)</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai az erős ügyfél-hitelesítéshez (<a href="/pages/8Pr1MPaLkJkIyysgyQfX">PSD2/SCA</a>).</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="141">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF (alapért.)</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Értékei fizetési szolgáltatónként és szerződésenként eltérőek lehetnek.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td>• “true” (alapért.)</td><td><p>Jelzi, hogy a bank azonnal vagy később hajtja végre a tranzakciót.<br></p><p>A paraméter átadása elhagyható, ilyenkor a tranzakciót azonnal végrehajtja a bank.</p></td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td>Kiegészítő vagy szolgáltató specifikus adatok (<a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméter használata</a>).</td></tr><tr><td><code>PaymentMethods</code></td><td>array</td><td><ul><li>apple_pay</li><li>google_pay</li><li>bank_card</li><li>...</li></ul></td><td><p>Megadható egyes szolgáltatók esetében, hogy mely fizetési módok legyenek engedélyezve. </p><p></p><p>Amennyiben ez a paraméter üresen marad, abban az esetben a fizetési szolgáltató oldalán az összes elérhető fizetési mód megjelenítésre kerül.</p><p></p><p>A fizetési módok kényszerített megjelenítését nem minden fizetési szolgáltató támogatja.</p><p></p><p><a href="/pages/iFWZ7LZuRF03TuukjNPy">Az elérhető fizetési módokkal kapcsolatos információk a Fizetési szolgáltató specifikus adatoknál találhatók.</a></p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "PaymentMethods":["bank_card", "google_pay"]
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="124">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p><br>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

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

{% endcode %}


# Erős ügyfél-hitelesítés (PSD2/SCA)

Minden elindított tranzakció esetén át kell adni a vásárló és a tranzakció adatait rendszerünknek. Rendszerünk továbbítja ezeket az adatokat a fizetési szolgáltató felé. A vásárló adatainak átadása törvényi kötelezettség a kereskedő számára.

### Működés

Használja az `Info` paramétert az ügyfél adatainak átadásához.

{% hint style="info" %}
A PSD2 *(Payment Services Directive 2)* az Európai Unió egyik irányelve, mely a pénzügyi szolgáltatások piacát szabályozza.

A PSD2-SCA *(Strong Customer Authentication)*, ügyfél-hitelesítési folyamat, mely a visszaélések megelőzését és a kártyacsalások felderítését segíti elő. A tranzakció létrehozása során az erős ügyfél-hitelesítéshez átadott adatokat a tranzakció végstátuszának rendszerünkben történő beállításától számított 48 óra elteltével töröljük rendszerünkből.
{% endhint %}

#### **Adatok lekérdezése**

Használja a `GetInfoData` paramétert az erős ügyfél-hitelesítés során átadott adatok lekérdezéséhez a következő API hívásokban:

* `Details`
* `PaymentLinkDetails`

#### **Adatok átadása az `Info` objektumban**

Készítse elő a vásárló és a tranzakció adatait, majd használja az `Info` több szintű objektumot az adatok átadásához a következő API hívások során:

* `Init`
* `InitRP`
* `PaymentLinkCreate`
* `Payout`

#### **Előkészületek**

Figyeljen a következőkre, hogy az `Info` mező megfelelő értéket vegyen fel:

1. tárolja az adatokat JSON kódolt objektumban
2. kódolja az így kapott string tartalmát base64 segítségével
3. cserélje le a következő karaktereket a base64 kódolt string-ben

<table data-full-width="true"><thead><tr><th align="center">A base64 kódolt string eredeti karaktere</th><th align="center">Csere karakter az Info paraméter számára</th></tr></thead><tbody><tr><td align="center">+</td><td align="center">-</td></tr><tr><td align="center">/</td><td align="center">_</td></tr><tr><td align="center">=</td><td align="center">.</td></tr></tbody></table>

Adja át az így keletkezett karakterláncot az `Info` paraméterben.

#### **Az `Info` objektum felépítése**

Az `Info` objektum számos különböző adatot tartalmaz, melyek két nagy csoportra bonthatók fel, a következő módon:

#### **Vásárlói adatok**

* általános adatok
* bolt specifikus adatok
* böngésző adatok

#### **Rendelési adatok**

* általános adatok
* számlázási adatok
* szállítási adatok
* termékadatok

Táblázatos formában összefoglalva

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="140">Típus</th><th width="114">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Info: Customer: General</code></td><td>JSON object</td><td><a href="/pages/mg7AKV52czfrzAFKmYJs">részletek</a></td><td>A vásárló általános adatai.</td></tr><tr><td><code>Info: Customer: StoreSpecific</code></td><td>JSON object</td><td><a href="/pages/8GOT2LSw47zkIRllYF7O">részletek</a></td><td>A vásárló bolt specifikus adatai.</td></tr><tr><td><code>Info: Customer: Browser</code></td><td>JSON object</td><td><a href="/pages/2hNtK078qjn8BK5XRDtw">részletek</a></td><td>A vásárló böngészőjének adatai.</td></tr><tr><td><code>Info: Order: General</code></td><td>JSON object</td><td><a href="/pages/qttFSIilf241K9TTDR9i">részletek</a></td><td>A megrendelés általános adatai.</td></tr><tr><td><code>Info: Order: BillingData</code></td><td>JSON object</td><td><a href="/pages/QU3tdzKkTTkumHiQtwCh">részletek</a></td><td>A számlázás adatai.</td></tr><tr><td><code>Info: Order: ShippingData</code></td><td>JSON object</td><td><a href="/pages/U8lrYIZQo4Bm4tv3WjYP">részletek</a></td><td>A szállítás adatai.</td></tr><tr><td><code>Info: Order: ProductItems</code></td><td>JSON object</td><td><a href="/pages/7b2eyYsJO90ZlF4ur8er">részletek</a></td><td>A vásárolt termékek adatai.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    ...,
    "Extra": 
    {
        ...
    },
    "Info":
    {
        "Customer":
        {
            "General": { ... },
            "StoreSpecific": { ... },
            "Browser": { ... }
        },
        "Order":
        {
            "General": { ... },
            "BillingData": { ... },
            "ShippingData": { ... },
            "ProductItems": [ { ... }, { ... }, ... ]
        }
    }
}
```

{% endcode %}


# Vásárlói adatok

A `Customer` objektum a megrendelés részletes adatait tartalmazza. A vásárló adatai három különböző típusra bonthatók:

* általános adatok (`General`)
* bolt specifikus adatok (`StoreSpecific`)
* böngésző adatok (`Browser`)


# Általános vásárlói adatok

A `General` objektum a vásárló személyes adatait tartalmazza. Egyes paraméterek átadása kötelező, míg más paraméterek opcionálisak.

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Ip</code></td><td>string<br><br>(45 karakter)</td><td><p>IPv4 vagy IPv6</p><p><strong>Figyelem!</strong> Az IP cím megadására az adott cím forrás országának törvényei irányadóak.</p><p>(Az adott törvényi előírások megismerése és betartása a kereskedő felelőssége.)</p></td><td>A vásárló IP címe.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>HomePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>HomePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Otthoni telefonszám.</td></tr><tr><td><code>MobilePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>MobilePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Mobiltelefonszám.</td></tr><tr><td><code>WorkPhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>WorkPhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Munkahelyi telefonszám.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "General":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "Ip":"",
                "HomePhoneCc":"",
                "HomePhone":"",
                "MobilePhoneCc":"",
                "MobilePhone":"",
                "WorkPhoneCc":"",
                "WorkPhone":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Bolt specifikus adatok

A `StoreSpecific` objektum a vásárló adott bolthoz kapcsolódó adatait és statisztikáit tartalmazza. Megadásuk a gyanús aktivitások felderítését segíti elő.

#### Paraméterek

<table data-full-width="true"><thead><tr><th width="365">Paraméter</th><th width="134">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>UpdateDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><p>A vásárlói profil módosításának utolsó dátuma.<br></p><p>(Pl. szállítási cím, számlázási cím, a kártya adatai, stb.)</p></td></tr><tr><td><code>UpdateDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (Ezen tranzakció során)</li><li>02 (Kevesebb, mint 30 napja)</li><li>03 (30-60 napja)</li><li>04 (Több, mint 60 napja)</li></ul></td><td>A fenti <code>UpdateDate</code> mező indikátora.</td></tr><tr><td><code>CreationDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárló regisztrációjának időpontja a kereskedő rendszerében.</td></tr><tr><td><code>CreationDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs regisztráció, vendég vásárlás)</li><li>02 (regisztráció ezen tranzakció során)</li><li>03 (regisztráció kevesebb, mint 30 napja)</li><li>04 (regisztráció 30-60 napja)</li><li>05 (regisztráció több, mint 60 napja)</li></ul></td><td>A fenti <code>CreationDate</code> mező indikátora.</td></tr><tr><td><code>PasswordChangeDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárlói jelszó módosításának utolsó dátuma.</td></tr><tr><td><code>PasswordChangeDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (a jelszó még egyszer sem változott meg)</li><li>02 (a jelszó megváltozott az aktuális tranzakció során)</li><li>03 (a jelszó kevesebb, mint 30 napja változott meg)</li><li>04 (a jelszó 30-60 napja változott meg)</li><li>05 (a jelszó több, mint 60 napja változott meg)</li></ul></td><td>A fenti <code>PasswordChangeDate</code> mező indikátora.</td></tr><tr><td><code>AuthenticationTimestamp</code></td><td><p>string</p><p></p><p>(19 karakter)</p></td><td>ÉÉÉÉ-HH-NN ÓÓ:PP:MM</td><td>A vásárló bejelentkezésének időpontja az adott tranzakció előtt.</td></tr><tr><td><code>AuthenticationMethod</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (vendég vásárlás, nem történt belépés)</li><li>02 (a kereskedő rendszere azonosította a vásárlót bejelentkezésnél)</li><li>03 (az egységesített beléptetés azonosította a vásárlót bejelentkezésnél (Federated ID))</li><li>04 (a kártya kibocsátó hitelesítette a vásárlót bejelentkezésnél)</li><li>05 (3rd party vásárlói azonosítás bejelentkezésnél)</li><li>06 (FIDO vásárlói azonosítás bejelentkezésnél)</li></ul></td><td>A vásárló bejelentkezésének módja a kereskedő rendszerébe az adott tranzakció előtt.</td></tr><tr><td><code>ChallengeIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs preferencia a vásárló azonosítására)</li><li>02 (nincs azonosítás kérés)</li><li>03 (azonosítás kérése: a kereskedő preferenciája szerint)</li><li>04 (azonosítás kérése: megbízás - csak a bankkártya első regisztrációjához kapcsolódó tranzakciónál szükséges átadni)</li></ul></td><td>Vásárló azonosításának módja a fizetési tranzakció során.</td></tr><tr><td><code>ShippingAddressFirstUse</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Az adott szállítási cím használatának első dátuma.</td></tr><tr><td><code>ShippingAddressFirstUseIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (az adott szállítási cím ezen tranzakció során került először megadásra)</li><li>02 (az adott szállítási cím kevesebb, mint 30 napja került először megadásra)</li><li>03 (az adott szállítási cím 30-60 napja került először megadásra)</li><li>04 (az adott szállítási cím több, mint 60 napja került először megadásra)</li></ul></td><td>A fenti <code>ShippingAddressFirstUse</code> mező indikátora.</td></tr><tr><td><code>CardTransactionsLastDay</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott kártya tokenizációs kísérleteinek száma az elmúlt 24 órában.</td></tr><tr><td><code>CardCreationDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><ul><li>Tokenizált kártyás vásárlás esetén az adott kártya mentésének időpontja.</li><li>Más esetben a tranzakció dátuma</li></ul></td></tr><tr><td><code>CardCreationDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs kártya mentés - vendég vásárlás)</li><li>02 (a kártyát az aktuális tranzakció során mentették)</li><li>03 (a kártyát kevesebb, mint 30 napja mentették)</li><li>04 (a kártyát 30-60 napja mentették)</li><li>05 (a kártyát több, mint 60 napja mentették)</li></ul></td><td>A fenti <code>CardCreationDate</code> mező indikátora.</td></tr><tr><td><code>TransactionsLastDay</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt 24 órában.</td></tr><tr><td><code>TransactionsLastYear</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt egy évben.</td></tr><tr><td><code>PurchasesLastSixMonths</code></td><td>number<br><br>(4 karakter)</td><td>pozitív egész szám</td><td>Az adott vásárló sikeres tranzakcióinak száma az elmúlt 6 hónap során.</td></tr><tr><td><code>SuspiciousActivity</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (nem észlelt)</li><li>02 (gyanús aktivitás)</li></ul></td><td>Jelzi a vásárló gyanús tevékenységének észlelését a kereskedő áruházában.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "StoreSpecific":
            {
                "UpdateDate":"",
                "UpdateDateIndicator":"",
                "CreationDate":"",
                "CreationDateIndicator":"",
                "PasswordChangeDate":"",
                "PasswordChangeDateIndicator":"",
                "AuthenticationTimestamp":"",
                "AuthenticationMethod":"",
                "ChallengeIndicator":"",
                "ShippingAddressFirstUse":"",
                "ShippingAddressFirstUseIndicator":"",
                "CardTransactionsLastDay":"",
                "CardCreationDate":"",
                "CardCreationDateIndicator":"",
                "TransactionsLastDay":"",
                "TransactionsLastYear":"",
                "PurchasesLastSixMonths":"",
                "SuspiciousActivity":""
            },
            ...
        }
```

{% endcode %}


# Böngésző adatok

A `Browser` objektum a vásárláshoz használt böngészőből kinyerhető adatokat tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>AcceptHeader</code></td><td>string<br><br>(2048 karakter)</td><td><p>MIME típusok és altípusok</p><p>(Például: text/html, image/*, <em>/</em>, stb.)</p></td><td>A böngésző által értelmezhető tartalom típusok.</td></tr><tr><td><code>JavaEnabled</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>1 (Java engedélyezett)</li><li>0 (Java nem engedélyezett)</li></ul></td><td>Java használata a böngészőben.</td></tr><tr><td><code>Language</code></td><td>string<br><br>(8 karakter)</td><td><p>IETF BCP47 által definiált formátumban</p><p>(Például: "hu", "hu-HU", "en", "en-US", stb.)</p></td><td><p>A böngésző nyelve.<br></p><p>(A <code>navigator.language</code> értéke.)</p></td></tr><tr><td><code>ColorDepth</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>1 (1 bit)</li><li>4 (4 bit)</li><li>8 (8 bit)</li><li>15 (15 bit)</li><li>16 (16 bit)</li><li>24 (24 bit)</li><li>32 (32 bit)</li><li>48 (48 bit)</li></ul></td><td>A böngésző által használt színmélység.</td></tr><tr><td><code>ScreenHeight</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak magassága.</td></tr><tr><td><code>ScreenWidth</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak szélessége.</td></tr><tr><td><code>TimeZone</code></td><td>string<br><br>(5 karakter)</td><td>egész szám</td><td><p>A vásárló saját időzónája és a UTC (világidő) idő közötti különbség percben megadva.<br></p><p>(A <code>dateObj.getTimezoneOffset()</code> értéke.)</p></td></tr><tr><td><code>UserAgent</code></td><td>string<br><br>(2048 karakter)</td><td>egyedi érték</td><td>A használt böngésző azonosítására szolgáló adatok.</td></tr><tr><td><code>WindowSize</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (250 x 400)</li><li>02 (390 x 400)</li><li>03 (500 x 600)</li><li>04 (600 x 400)</li><li>05 (teljes képernyő)</li></ul></td><td><p>A fizetés hitelesítését végző szolgáltató ablakának mérete. Az ablak tartalmát ehhez a mérethez kell igazítani a legjobb felhasználói élmény érdekében. (A hitelesítő felület (3DSecure) megjelenítésének paramétere.)<br></p><p>(A fizetési hitelesítő (ACS) szerepét jellemzően a kártyakibocsátó bank tölti be. Az ACS itt az Access Control Server-t jelöli.)</p></td></tr></tbody></table>

#### Mintakód

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "Browser":
            {
                "AcceptHeader":"",
                "JavaEnabled":"",
                "Language":"",
                "ColorDepth":"",
                "ScreenHeight":"",
                "ScreenWidth":"",
                "TimeZone":"",
                "UserAgent":"",
                "WindowSize":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Rendelési adatok

Az `Order` objektum a megrendelés részletes adatait tartalmazza. A rendelés adatainak négy különböző típusa a következő:

* általános rendelési adatok (`General`)
* számlázási adatok (`BillingData`)
* szállítási adatok (`ShippingData`)
* termékadatok (`ProductItems`)


# Általános rendelési adatok

A `General` objektum a vásárlás általános adatait tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="143">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>DeliveryEmail</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum<br><br>(maximum 1 db)</td><td>Elektronikus kézbesítés esetén az email cím (vagy a felhasználói fiókhoz tartozó email cím) amelyre az áru érkezik.</td></tr><tr><td><code>DeliveryTimeFrame</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (elektronikus kézbesítés (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb. esetén))</li><li>02 (kézbesítésre a megrendelés napján kerül sor)</li><li>03 (kézbesítésre éjszaka kerül sor)</li><li>04 (a kézbesítés 2 vagy több napot vesz igénybe)</li></ul></td><td>A kézbesítés ideje.</td></tr><tr><td><code>GiftCardAmount</code></td><td>number<br><br>(15 karakter)</td><td><p>pozitív szám, maximum 2 tizedesjeggyel<br></p><p>(Magyar forint (HUF) esetén értéke egész szám, tizedesjegyek nélkül.)</p></td><td>Utalványról vagy ajándékkártyáról felhasznált összeg.</td></tr><tr><td><code>GiftCardCount</code></td><td>number<br><br>(2 karakter)</td><td>pozitív egész szám</td><td>Utalvánnyal vagy ajándékkártyával kifizetett rendelések száma. (A részleges fizetés is bele számít.)</td></tr><tr><td><code>GiftCardCurrency</code></td><td>string<br><br>(3 karakter)</td><td>ISO 4217 által definiált formátum</td><td>Az utalvány vagy ajándékkártya pénzneme.</td></tr><tr><td><code>PreorderDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Előrendelés esetén az áru elérhetőségének várható dátuma.</td></tr><tr><td><code>Availability</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (a rendelést azonnal teljesíti a kereskedő)</li><li>02 (a rendelést egy későbbi időpontban teljesíti a kereskedő)</li></ul></td><td>Jelzi, hogy a rendelés azonnal (készletről) vagy egy későbbi időpontban kerül teljesítésre.</td></tr><tr><td><code>ReorderItems</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (az adott terméket először rendelik meg)</li><li>02 (az adott terméket ismételten rendelik meg)</li></ul></td><td>Jelzi, hogy az adott terméket első alkalommal vagy ismételten rendelik meg.</td></tr><tr><td><code>ShippingMethod</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék szállítása a számlázási címre)</li><li>02 (termék szállítása egy korábban megadott címre)</li><li>03 (termék szállítás a számlázási címtől eltérő címre)</li><li>04 (termék személyes, bolti átvétele esetén)</li><li>05 (termék digitális kézbesítése esetén (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))</li><li>06 (a termék utazásra vagy esemény látogatására szóló jegy)</li><li>07 (egyéb termékek esetén (játékok, digitális szolgáltatások, feliratkozások, stb.))</li></ul></td><td>A szállítás módja vagy a kézbesítés jellege.</td></tr><tr><td><code>AddressMatchIndicator</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>0 (eltérő számlázási és szállítási cím)</li><li>1 (megegyező számlázási és szállítási cím)</li></ul></td><td>Jelzi, hogy a számlázási cím és a szállítási cím megegyezik vagy eltér egymástól.</td></tr><tr><td><code>DifferentShippingName</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (megegyező számlázási és szállítási név)</li><li>02 (eltérő számlázási és szállítási név)</li></ul></td><td>Jelzi, hogy a számlázási név és a szállítási név megegyezik vagy eltér egymástól.</td></tr><tr><td><code>TransactionType</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék/szolgáltatás vásárlása)</li><li>03 (ellenőrzés/hitelesítés)</li><li>10 (számla finanszírozás)</li><li>11 (kvázi készpénz ügylet, pl. pénzutalvány, utazási csekk, deviza, szelvény, stb.)</li><li>28 (egyenleg feltöltés)</li><li>stb.</li></ul></td><td>A tranzakció típusa.<br><br>(Az ISO 8583 lista szerint.)</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "General":
            {
                "DeliveryEmail":"",
                "DeliveryTimeFrame":"",
                "GiftCardAmount":"",
                "GiftCardCount":"",
                "GiftCardCurrency":"",
                "PreorderDate":"",
                "Availability":"",
                "ReorderItems":"",
                "ShippingMethod":"",
                "AddressMatchIndicator":"",
                "DifferentShippingName":"",
                "TransactionType":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Számlázási adatok

A `BillingData` objektum a számlázási adatokat tartalmazza, ezek átadása kötelező. Viszont a számlázási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td>Keresztnév.<br><br>(Cég esetén cégnév.)</td></tr><tr><td><code>LastName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td><p>Vezetéknév.</p><p>(Cég esetén cégnév.)</p></td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td>string<br><br>(18 karakter)</td><td>számok</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.</p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím első sora.<br><br>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</td></tr><tr><td><code>PostalCode</code></td><td>string<br><br>(16 karakter)</td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p><br>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód</p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyarországon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        {    
            "BillingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Szállítási adatok

A `ShippingData` objektum a szállítási adatokat tartalmazza, átadása kötelező postázás vagy futárszolgálat igénybevétele esetén. Ugyanakkor a szállítási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

{% hint style="warning" %}
Személyes átvételnél és digitális kézbesítés esetén a szállítási adatok megadására nincs szükség. Ilyenkor jelezze a szállítás módját vagy a kézbesítés jellegét a `General` objektum `ShippingMethod` paraméterében.<br>

Az átadható értékek ilyen esetekben:

* 04 (termék személyes, bolti átvétel)
* 05 (termék digitális kézbesítése (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td><p>string</p><p>(254 karakter)</p></td><td><p>szabványos email formátum</p><p>(maximum 1 db)</p></td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td><p>string</p><p>(18 karakter)</p></td><td>számokek</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td><p>A cím első sora.<br></p><p>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</p></td></tr><tr><td><code>PostalCode</code></td><td><p>string</p><p>(16 karakter)</p></td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum<br></p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód<br></p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyaroszgágon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "ShippingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Termékadatok

A `ProductItems` objektum a vásárlás során kifizetett tételek megjelölésére szolgál. A megvásárolt terméken vagy szolgáltatáson túl ezek a tételek lehetnek például szállítási vagy kezelési költségek, jóváírások, kedvezmények, stb.

{% hint style="warning" %}
A `ProductItems` blokkban szereplő tételek összértéke meg kell egyezzen a tranzakció inicializálása során átadott `Amount` paraméter értékével. Vagyis az itt átadott `UnitPrice` \* `Quantity` = `Amount`. Amennyiben a tételek összértéke nem egyezik meg az `Amount` értékével a tranzakció elutasításra kerül.
{% endhint %}

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Sku</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td><p>A termék egyedi azonosítója a kereskedő áruházában.<br></p><p>(Pl. a termék cikkszáma, sorozatszáma, stb.)</p></td></tr><tr><td><code>Name</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td>A termék megnevezése.</td></tr><tr><td><code>Quantity</code></td><td><p>number</p><p>(10 karakter)</p></td><td>pozitív egész szám</td><td>A megvásárolt mennyiség.</td></tr><tr><td><code>QuantityUnit</code></td><td><p>string</p><p>(16 karakter)</p></td><td>egyedi értékek</td><td><p>Mennyiségi egység.<br></p><p>(Pl. darabszám, kilogramm, méter, stb.)</p></td></tr><tr><td><code>UnitPrice</code></td><td><p>number</p><p>(16 karakter)</p></td><td><ul><li>pozitív szám, maximum 2 tizedesjeggyel (egy eladott egység ára)</li><li>negatív szám, maximum 2 tizedesjeggyel (a kedvezmények vagy jóváírások megadására)</li></ul></td><td><p>A termék egységára.<br></p><p>Kedvezmények és jóváírások esetén negatív szám.<br></p><p>(A tizedesjegy elválasztó karakterként “.” használjon. Magyar forint (HUF) esetén a tizedesjegyek értéke kizárólag nulla lehet.)</p></td></tr><tr><td><code>ImageUrl</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi URL cím</td><td>Az elsődleges termékfotó URL címe.</td></tr><tr><td><code>Description</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td>A termék leírása.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "ProductItems":
            [
                {
                    "Sku":"",
                    "Name":"",
                    "Quantity":"",
                    "QuantityUnit":"",
                    "UnitPrice":"",
                    "ImageUrl":"",
                    "Description":""
                },
                ...
            ],
            ...
        }
    }
}
```

{% endcode %}


# Visszairányítási módok

### Működés

Használja a `redirectMode` paramétert, hogy fizetés után visszairányítsa a vásárlót a webáruházba a fizetési szolgáltató oldaláról.

A `redirectMode` paraméter értékét (és a visszairányítás módját) az inicializálás során (`Init`) adhatja meg, az `Extra` paraméteren belül.

{% hint style="info" %}
Amennyiben nem adja át a `redirectMode` értékét az `Extra` paraméterben, alapértelmezetten a 0 értékhez tartozó HTTP átirányítás lép működésbe.
{% endhint %}

A `redirectMode` segítségével a következő visszairányítási módok érhetők el:

<table data-full-width="true"><thead><tr><th width="90">Érték</th><th width="216">Eljárás</th><th>Leírás</th></tr></thead><tbody><tr><td>0</td><td>HTTP redirect</td><td>A vásárló HTTP 302-es átirányítással kerül vissza az inicializáció (<code>Init</code>) során megadott válasz URL címre (<code>ResponseUrl</code>).</td></tr><tr><td>1</td><td>top.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: top window.</td></tr><tr><td>2</td><td>parent.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: parent window.</td></tr><tr><td>3</td><td>top.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: top window.</p><p>(Nincs átirányítás!)</p></td></tr><tr><td>4</td><td>parent.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: parent window.<br></p><p>(Nincs átirányítás!)</p></td></tr></tbody></table>

A javascript alapú üzenetek tartalma a következő formátumú JSON string (a 3-as és 4-es `redirectMode` értékeknél):

{PMGWTransactionData: {TransactionId: “”, OrderId: “”, UserId: “”}}

**Window\.postMessage()** használata esetén a paraméterek a következő értékekkel rendelkeznek:

<table data-full-width="true"><thead><tr><th width="306">Paraméter</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>A tranzakció egyedi Nevogate azonosítója, melyet az <code>Init</code> hívás válaszában ad vissza rendszerünk.</td></tr><tr><td><code>OrderId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr><tr><td><code>UserId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr></tbody></table>


# Tranzakció indítása (Start)

### Műkődés

Tranzakció indításához irányítsa át a vásárlót rendszerünkbe az inicializáció (`Init`) során visszakapott tranzakció azonosítóval (`TransactionId`). Rendszerünk felépíti a kommunikációt a fizetési szolgáltatóval és tovább irányítja a vásárlót a fizetési felületre.

Tranzakció indításához **teszt környezetben** használja a következő címet:

<https://system-test.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]

Tranzakció indításához **éles környezetben** használja a következő címet:

<https://system.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]


# URL Értesítés

### Működés

Használja a `NotificationUrl` paramétert, hogy automatikusan értesüljön a tranzakciók státuszának változásáról. Az inicializáció (`Init`) során adja át az értesítési URL címet a `NotificationUrl` paraméterben. Rendszerünk ezt a címet hívja meg a tranzakció státuszának megváltozásakor.

Rendszerünk legfeljebb 5 alkalommal kísérli meg a megadott értesítési URL hívását, amíg a hívásra HTTP 200 választ nem kap. Az értesítés a tranzakció részletes adatait tartalmazza JSON formátumban (a `Details` hívás eredményének megfelelően), amit `application/json` típusként küldünk, így az adat a *raw request body*-ból nyerhető ki.

Jelezze vissza rendszerünk számára, hogy a kereskedő oldala értesült a tranzakció eredményéről. Ehhez indítson egy `Result` kérést minden rendszerünktől visszaérkező `NotificationUrl` hívás után. `Result` kérés hiányában a tranzakció “megválaszolhatatlan” állapotot kap a *PayAdmin* felületén.

Az alapértelmezett (lineáris időközönként maximum 5 alkalommal történő) URL értesítési eljárás mellett elérhető egy kiterjesztett URL értesítési eljárás is.

Ebben az esetben az értesítési kísérletek fokozatosan elnyújtott időközönként történnek az alábbi logika szerint:

* Azonnal a végstátusz beállítását követően.
* 5 másodperc elteltével.
* 10 másodperc elteltével.
* 30 másodperc elteltével.
* 1 perc elteltével.
* 5 perc elteltével.
* 15 perc elteltével.
* 30 perc elteltével.
* 1 óra elteltével.
* 3 óra elteltével.
* 6 óra elteltével.
* 12 óra elteltével.
* 1 nap elteltével.

A kiterjesztett URL értesítés igénybevételéhez vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.

{% hint style="warning" %}
A `NotificationUrl` átadása minden tranzakció inicializáció során kötelező.\
Továbbá figyeljen arra, hogy a megadott értesítési URL cím (`NotificationUrl`):

* rendelkezzen HTTPS protokollal
* legyen mindenkor publikusan elérhető
  {% endhint %}

{% hint style="danger" %}
A JSON formátumú értesítésben található paraméterek kis kezdőbetűkkel szerepelnek. Ezzel ellentétben a tranzakció részletes adatainak lekérdezésére (`Details` hívásra) adott válasz paraméterei nagy kezdőbetűvel rendelkeznek.
{% endhint %}

### Beállítás lépései

Végezze el a következő lépéseket az URL értesítés megfelelő működéséhez.

{% hint style="warning" %}
A leírt folyamatot minden egyes `NotificationUrl` híváskor végre kell hajtani.
{% endhint %}

1. Adjon meg egy értesítési URL címet a `NotificationUrl` paraméter segítségével.
2. Vizsgálja meg, hogy a *raw request body* tartalmaz JSON típusú adattartalmat (a rendszerünkből érkező `NotificationUrl` hívás során).
3. Nyerje ki az aktuális `TransactionId` értéket a *raw request body*-ból.
4. Indítson egy `Result` kérést melyben megadja a `NotificationUrl` törzséből kinyert `TransactionId` értéket.
5. Dolgozza fel a `Result` kérésre kapott választ, majd
6. mentse el a rendszerében a tranzakció végstátuszát (`ResultCode`).
7. Válaszoljon HTTP 200-as státusz kóddal a rendszerünkből érkező `NotificationUrl` hívásra.

{% hint style="info" %}
PHP használata esetén így nyerheti ki a `TransactionId` értékét:

```php
$json = file_get_contents('php://input');
$data = json_decode($json);
$transactionId = $data->commonData->transactionId;
```

{% endhint %}

### Példa (URL értesítés beállítására teszt környezetben)

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "NotificationUrl":"https://merchant.notification.url"
    }'
```

{% endcode %}


# Tranzakció eredményének lekérdezése (Result)

### Működés

Használja a `Result` hívást a tranzakció eredményének lekérdezéséhez. A fizetés után rendszerünk visszairányítja a vásárlót az áruházba, úgy, hogy meghívja azt a `ResponseUrl`-t, amit az inicializáció (`Init`) során adott meg a kereskedő oldala. Miután rendszerünk meghívja a `ResponseUrl`-t, a kereskedő oldala elindíthatja a `Result` hívást.

`Result` hívás indításához szüksége lesz az adott tranzakció azonosítójára. Ezért a rendszerünkből érkező `ResponseUrl` hívás kiegészül a `TransactionId` GET paraméterrel, amely az adott tranzakció azonosítót biztosítja.

Fontos, hogy minden rendszerünkből érkező `ResponseUrl` hívás után indítson egy `Result` hívást, a vásárlói munkamenettől függetlenül. Ennek oka, hogy előfordulhat, hogy a `ResponseUrl` hívásra később, aszinkron módon, a háttérben kerül sor.

Rendszerünk aszinkron módon elindítja a `NotificationUrl` hívást, abban az esetben, ha beállt az adott tranzakció végstátusza. A `NotificationUrl` az inicializáció (`Init`) során kötelezően átadandó URL cím. Itt is fontos, hogy minden rendszerünkből érkező `NotificationUrl` hívás után indítson egy `Result` hívást.

Rendszerünk a `Result` hívás hatására értesül arról, hogy a kereskedő oldala megkapta a tranzakció eredményét. Ezért amennyiben a `Result` hívásra nem kerül sor, a tranzakció rendszerünkben a "megválaszolhatatlan" állapotot veszi fel.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=result)

{% hint style="info" %}
További részletekért a `NotificationUrl` használatáról látogassa meg a következő hivatkozást: [URL Értesítés](/egyszeri-fizetesek-one-time-payment/bankkartya-es-mobiltarca/azonnali-terheles/url-ertesites)

A tranzakció állapotairól a rendszerünkben pedig a következő oldalon olvashat további információkat: [Tranzakció Állapotok](/segedlet/tranzakcio-allapotok)
{% endhint %}

{% hint style="warning" %}
Figyeljen arra, hogy `Result` kérést kizárólag `ResponseUrl` vagy `NotificationUrl` hívások hatására indítson. A kereskedő rendszeréből indokolatlanul, vagy ütemezett módon `Result` kérést indítani tilos!
{% endhint %}

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Result</code></td><td><code>POST</code></td><td>method=<code>Result</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Result` kérés egy (kötelező) paraméterrel rendelkezik

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### Mintakód

Tranzakció eredményének lekérése `Result` használatával

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Result | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Result' \
  --data 'json=
    {
        "TransactionId":"992c8e75435e6d4dfdf6415f0714cae8"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Result` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="345">Paraméter</th><th width="132">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>egyedi értékek</td><td>Rendszerünkben tárolt egyedi boltazonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A tranzakció státusza lehet:</p><ul><li>SUCCESSFUL</li><li>PENDING</li><li>OPEN</li><li>ERROR</li><li>CANCELED</li><li>TIMEOUT</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul></td><td>Jelzi a tranzakció eredményét.<br><br>A tranzakció státuszokról a következő oldalon olvashat további információkat: <a href="/pages/yzo9U4RLeMGLusg6Mrfl">Tranzakció státuszok</a></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>Anum</code></td><td>string</td><td>egyedi értékek</td><td><p>A tranzakció engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Csak bizonyos szolgáltatók esetén.)</p></td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td><p>A tranzakció bruttó végösszege.<br></p><p>(Az összeg amit a vásárló kifizetett.)</p></td></tr><tr><td><code>Currency</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>HUF</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td>A tranzakció devizaneme.</td></tr><tr><td><code>OrderId</code></td><td>string</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>OrderId</code>.)</p></td></tr><tr><td><code>UserId</code></td><td>string</td><td><p>egyedi értékek</p><p>(kivéve e-mail címek, illetve személyes adatok)</p></td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>UserId</code>.)</p></td></tr><tr><td><code>Language</code></td><td><p>string</p><p><br>(2 karakter)</p></td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>ProviderTransactionId</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“true”</li></ul></td><td><p>Jelzi, hogy a bank azonnal hajtja végre a tranzakciót.<br></p><p>(Az inicializáció során beállított <code>AutoCommit</code> értéke.)</p></td></tr><tr><td><code>CommitState</code></td><td>string</td><td><ul><li>APPROVED</li></ul></td><td>• APPROVED: a végleges összeg beterhelése megtörtént</td></tr><tr><td><code>PaywallPaymentName</code></td><td>string<br><br>(36 karakter)</td><td><ul><li>null</li><li>UUID</li></ul></td><td>A tranzakció <em>PayWall</em> azonosítója (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaywallRecurringPaymentEnabled</code></td><td>string</td><td><ul><li>"true"</li><li>"false"</li></ul></td><td>Jelzi a vásárló hozzájárulását, hogy a kereskedő a jövőben az adott tranzakcióra hivatkozva újabb, ismétlődő tranzakciókat indíthasson (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaymentRegistrationType</code></td><td>string</td><td><ul><li>null</li></ul></td><td>Jelzi a fizetési regisztráció típusát.</td></tr><tr><td><code>SzepPocket</code></td><td>string</td><td><ul><li>null</li></ul></td><td>A tranzakció inicializálása (<code>Init</code>) során megadott zsebazonosító (SZÉP Kártyás fizetés esetén).</td></tr><tr><td><code>ProviderResultCode</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>Barion2 (ErrorCode)</li><li>Borgun2 (ActionCode)</li><li>CIB (RC)</li><li>GoPay (Error Code)</li><li>GP (PRCODE)</li><li>KHB</li><li>OTPSimple (resultCode / errorCodes)</li><li>PayU2 (error_code)</li><li>PayURest (cardResponseCode)</li><li>RaiffeisenUPC (TranCode)</li><li>Saferpay (ErrorName)</li><li>Stripe (last_payment_error:code)</li><li>VivaWallet (statusId)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó elsődleges eredmény- vagy hibakód.</td></tr><tr><td><code>ProviderResultCode2</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>GP (SRCODE)</li><li>KHB</li><li>PayU2 (add_cc_response_code)</li><li>RaiffeisenUPC (HostCode)</li><li>Saferpay (ProcessorResult)</li><li>Stripe (last_payment_error:decline_code)</li><li>VivaWallet (EventId / ResponseEventId)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó másodlagos eredmény- vagy hibakód.</td></tr><tr><td><code>PaymentLinkName</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A fizetési hivatkozás azonosítója a <em>Nevogate</em> rendszerében (amennyiben a tranzakció <em>PayLink</em> segítségével jött létre).</td></tr><tr><td><code>Created</code></td><td>string</td><td>dátum</td><td>A tranzakció létrehozásának ideje.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Result` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "StoreName": "sdk_test",
    "ProviderName": "Borgun2",
    "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": "Sikeres tranzakció",
    "Anum": "006761",
    "Amount": "100",
    "Currency": "HUF",
    "OrderId": "TEST-ORDER-ID",
    "UserId": "TEST-USER-ID",
    "Language": "HU",
    "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
    "AutoCommit": "true",
    "CommitState": "APPROVED",
    "PaywallPaymentName": null,
    "PaywallRecurringPaymentEnabled": "false",
    "PaymentRegistrationType": null,
    "SzepPocket": null,
    "ProviderResultCode": "000",
    "ProviderResultCode2": null,
    "PaymentLinkName": null,
    "Created": "2020-03-14 11:19:07",
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Tranzakció részletes adatainak lekérdezése (Details)

### Működés

Használja a `Details` hívást a tranzakció részletes adatainak lekérdezéséhez. Míg a `Result` hívásra adott válasz csupán a tranzakció alapadatait hordozza, a `Details` hívás további részletes információkat is tartalmaz az adott tranzakcióról (pl. szolgáltató specifikus adatokat).

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=details)

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Details</code></td><td><code>POST</code></td><td>method=<code>Details</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Details` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` átadása kötelező**)

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="104">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>GetRelatedTransactions</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td>Olyan korábbi tranzakciók részletes adatainak lekérése, melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>GetInfoData</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td><p>Kérés a vásárlásra vonatkozó <code>Info</code> adatok visszaadására.<br></p><p>(<code>Init</code>, <code>InitRP</code> vagy <code>PaymentLinkCreate</code> hívások során átadott vásárlási adatok esetén.)</p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció részletes adatainak lekérése `Details` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Details | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Details' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "GetRelatedTransactions":false,
        "GetInfoData":false
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Details` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="251">Paraméter</th><th width="129">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>CommonData</code></td><td>JSON object</td><td>egyedi értékek</td><td><p>A tranzakció alapadatai.<br></p><p>(A <code>Result</code> hívás során is visszaadott adatok.)</p></td></tr><tr><td><code>ProviderSpecificData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Szolgáltató specifikus kiegészítő adatok.</td></tr><tr><td><code>RelatedTransactions</code></td><td>JSON object</td><td>egyedi értékek</td><td>Olyan korábbi tranzakciók adatai melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>InfoData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Az <code>Info</code> objektum adatai.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Details` kérésre adott válasz (formázást követően):

{% code overflow="wrap" %}

```php
{
    "CommonData":
    {
        "StoreName": "sdk_test",
        "ProviderName": "Borgun2",
        "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
        "ResultCode": "SUCCESSFUL",
        "ResultMessage": "Sikeres tranzakció",
        "Anum": "006766",
        "Amount": "100",
        "Currency": "HUF",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "Language": "HU",
        "ProviderTransactionId": "tr_GVaydOjpVySGJycK15glvGgbLGxmCQyf",
        "AutoCommit": "false",
        "CommitState": "APPROVED",
        "Created": "2020-03-14 11:19:07",
        "ResponseId": "3202109280600047706"
    },
    "ProviderSpecificData":
    {
        ...
        "Amount": "100",
        "Currency": "HUF",
        "Language": "HU",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "ResponseUrl": "https://demo.nevogate.com/response.php",
        "NotificationUrl": null,
        "MaxNotificationSendAttempts": 0,
        "NotificationSendAttempts": 0,
        "NotificationSendSuccess": 0,
        "Extra": null,
        "AutoCommit" : "0",
        "CommitState": "1",
        "HasRefund": "0",
        "Created": "2017-11-17 13:12:36",
        "LastModified": "2017-11-17 13:14:07",
        "InvoiceDate": null,
        "GatewayPaymentPage": null,
        "ModuleName": null,
        "ModuleVersion": null,
        "StoreProviderId": "3103",
        "Error": null,
        "ResultMessage": null
    },
    "RelatedTransactions": null,
    "InfoData": null,
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ProviderName": "Borgun2",
    "ResponseId": "3202109280600047706"
}
```

{% endcode %}


# Tranzakció összegének visszatérítése (Refund)

### Működés

Használja a `Refund` hívást egy sikeres tranzakció összegének teljes vagy részleges visszatérítésére. Visszatérítésre csak bizonyos fizetési szolgáltatóknál van lehetőség, továbbá ezt a funkciót jellemzően külön kell igényelni az adott fizetési szolgáltatótól.

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=refund)

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Refund</code></td><td><code>POST</code></td><td>method=<code>Refund</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Refund` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` és `Amount` átadása kötelező**):

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="120">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td>Visszatérítésre kerülő összeg az eredeti tranzakció pénznemében.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Egyéb illetve szolgáltató specifikus adatok.</p><p>(További részletekről az <a href="/pages/XaOHnljbNm5MGxPqLjdh">Extra adatok</a> pontban olvashat.)<br></p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció összegének részleges vagy teljes visszatérítése `Refund` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Refund | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Refund' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "Amount":100
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Refund` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="277">Paraméter</th><th width="133">Típus</th><th width="284">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A visszatérítés beküldésének eredménye a következők egyike lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi a visszatérítés beküldésének eredményét:</p><ul><li>SUCCESSFUL: a visszatérítés beküldése sikeres</li></ul><p><strong>(Nem a tényleges pénzvisszatérítés sikeres megtörténtét jelzi!)</strong></p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>RefundRequestId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés kérésének azonosítója a fizetési szolgáltató rendszerében.</p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundTransactionId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés azonosítója a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundAuthorizationCode</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundId</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A visszatérítés egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Refund` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "RefundRequestId": null,
    "RefundTransactionId": null,
    "RefundAuthorizationCode": null
    "RefundId": "rf_b0fd9b0381bb54568870a6c22d6a086f",
    "ResultMessage": null,
    "ResponseId": "3202109280600047707"
}
```

{% endcode %}


# Későbbi terhelés (kétlépcsős fizetés)

Ennél a terhelés típusnál a vásárlás összege csupán előzetes befoglalásra (zárolásra) kerül a vásárló számláján. Az összeg tényleges levonására (terhelésére) vagy a befoglalt összeg feloldására egy későbbi időpontban kerül sor, a kereskedő kérésének hatására.

Befoglalást követően a kereskedő egy újabb API hívás segítségével véglegesítheti a terhelést vagy oldhatja fel a befoglalt összeget. A terhelés véglegesítésére vagy a befoglalt összeg feloldására egy bizonyos időkeret áll rendelkezésre, ezután a befoglalt összeget a fizetési szolgáltató automatikusan feloldja a vásárló számláján. Ez az időkeret fizetési szolgáltatónként változó, pontos részletekért lépjen kapcsolatba az adott fizetési szolgáltatóval.

{% hint style="info" %}
A későbbi terhelést csak bizonyos fizetési szolgáltatók támogatják. Ez a funkció jelenleg a következő szolgáltatóknál érhető el:

* Barion Smart Gateway
* Teya RPG
* Global Payments
* GoPay
* K\&H Bank
* PayPal REST
* PayU Classic
* PayU REST
* Raiffeisen vPos
* SimplePay
* Stripe
* Viva Wallet
* Worldline - Saferpay
  {% endhint %}

### **Különbségek az azonnali és a későbbi terhelés közt**

A tranzakciókat alapértelmezetten azonnali terheléssel hajtja végre a fizetési szolgáltató. Az azonnali terhelés végrehajtásáért az `AutoCommit` paraméter felelős. Azonnali terhelésnél ennek a paraméternek az átadása elhagyható, vagy átadás esetén `"true"` értékkel kell beállítani.

Későbbi terhelés kezdeményezéséhez az `AutoCommit` paraméter átadása kötelező, melynek értéke ebben az esetben `"false"`. Ez az érték jelzi a fizetési szolgáltató rendszerének, hogy a tényleges terhelésre (vagy feloldásra) egy későbbi időpontban kerül sor, így a tranzakció összege csak befoglalásra kerül a vásárló számláján.

{% hint style="info" %}
A befoglalt összeg feloldásáról vagy végleges terheléséről egy későbbi fejezetben olvashat, melyet ide kattintva érhet el:

[Kétlépcsős tranzakció lezárása](/egyszeri-fizetesek-one-time-payment/bankkartya-es-mobiltarca/kesobbi-terheles-ketlepcsos-fizetes/ketlepcsos-tranzakcio-lezarasa-close)
{% endhint %}


# Fizetési folyamat

A fizetési folyamat leírását négy részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított négy fő lépés adja, ezek a lépések a következők:

A. **`Init`** - kétlépcsős tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek\
B. **`Start`** - kétlépcsős tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - kétlépcsős tranzakció eredményének lekérése rendszerünkből\
D. **`Close`** - kétlépcsős tranzakció lezárása

{% hint style="info" %}
Az A, B és C lépések együttesen adják ki a vásárló jelenlétében történő fizetési folyamatot, ami a tranzakciós összeg zárolásával végződik.

A D lépés az első három lépést követően később is elvégezhető, de ennek hatására fejeződik be a tranzakció terheléssel, vagy a zárolt összeg feloldásával.

A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - kétlépcsős tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek**

1. A kereskedő oldala rögzíti a vásárló elektronikus fizetési szándékát,
2. ezután a kereskedő oldala új, kétlépcsős fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén).
5. A kereskedő oldala tárolja az egyedi tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli)

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - kétlépcsős tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló megadja bankkártya adatait (vagy kiválasztja a megfelelő mobiltárcát) a fizetési szolgáltató oldalán. (Ezen a ponton a vásárló átirányításra kerülhet a kártyakibocsátó bankhoz, ahol személyazonosságát 3DS hitelesítési folyamattal igazolhatja.)
4. A fizetési szolgáltató visszairányítja a vásárlót rendszerünkbe majd megtörténik a **tranzakció összegének befoglalása**.
5. Rendszerünk lekérdezi a befoglalás eredményét a fizetési szolgáltatótól, majd beállítja a tranzakció státuszát a fizetési szolgáltató válasza alapján,
6. ezután rendszerünk a tranzakció azonosítóval visszairányítja a vásárlót a kereskedő oldalára (az inicializáció (`Init`) során megadott visszatérési URL címre (`ResponseUrl`)).
7. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is.

{% hint style="info" %}
A **B.3.** lépésben leírt 3DS hitelesítési folyamat (3D Secure vagy 3D Secure Code) a pénzügyi visszaélések megakadályozását célzó megoldás. Fizetés során a 3DS a kötelező kártyaadatok bekérésén túl egy egyszer használatos kóddal biztosítja a kártyabirtokos védelmét visszaélésekkel szemben. Használata egyszerű, a vásárlónak mindössze egy mobiltelefonra van szüksége.
{% endhint %}

#### **C. `Result` - kétlépcsős tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala a `ResponseUrl` hívás hatására egy tranzakció azonosítót tartalmazó `Result` kéréssel lekérdezi a befoglalás eredményét rendszerünkből.
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a befoglalás státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a befoglalás státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}

**D. `Close` - Kétlépcsős tranzakció lezárása**

1. A kereskedő kezdeményezi a tranzakció lezárását a tranzakció azonosító segítségével (`TransactionId`) és a lezárás módjának megadásával, mely lehet:\
   • a teljes befoglalt összeg terhelése\
   • a befoglalt összeg részterhelése (és a maradék összeg feloldása)\
   • a teljes befoglalt összeg feloldása
2. Rendszerünk hitelesíti a beérkezett kérést, majd továbbítja azt a fizetési szolgáltató felé, aki végrehajtja a tranzakció lezárását.
3. Ezután rendszerünk megválaszolja a lezárás eredményét a kereskedő oldalának (sikeres hitelesítés esetén).
4. A kereskedő oldala tárolja a kapott választ és értesíti a vásárlót a tranzakció eredményéről.


# Kétlépcsős tranzakció inicializálása (Init)

### Működés

Használja az inicializálás (`Init`) funkciót egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a vásárló adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

A kétlépcsős fizetés inicializálása során figyeljen a következőkre:

* Adja át az `AutoCommit` paramétert `"false"` értékkel későbbi terhelés engedélyezéséhez.
* Használjon erős ügyfél-hitelesítést (PSD2-SCA) a vásárló adatainak átadásához. Erről a következő oldalon olvashat részletesebben: [Erős ügyfél-hitelesítés (PSD2/SCA)](/egyszeri-fizetesek-one-time-payment/bankkartya-es-mobiltarca/kesobbi-terheles-ketlepcsos-fizetes/eros-uegyfel-hitelesites-psd2-sca)
* Tárolja le az `Init` kérésre visszaadott tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobil alkalmazásban.**
{% endhint %}

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>Barion2</li><li>Borgun2 (Teya RPG)</li><li>GP (<em>Global Payments</em>)</li><li>GoPay</li><li>KHB</li><li>OTPSimple (<em>SimplePay</em>)</li><li>PayPalRest</li><li>PayU2 (Classic)</li><li>PayURest</li><li>RaiffeisenUPC</li><li>Saferpay (Worldline)</li><li>Stripe</li><li>VivaWallet</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/2ejzhUB2i3eiW26CZnRU">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td>szabadon választható</td><td>Bruttó végösszeg amit a vásárló kifizet.<br><br>(Magyar forint (HUF) esetén értéke egész szám.)</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“false”</li></ul></td><td>Jelzi, hogy a vásárló kétlépcsős fizetést indít és a megadott összeget a bank befoglalhatja a vásárló számláján.</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai az erős ügyfél-hitelesítéshez (<a href="/pages/o3xgKoqH5By0KqWKVqnS">PSD2/SCA</a>).</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF (alapért.)</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Értékei fizetési szolgáltatónként és szerződésenként eltérőek lehetnek.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td>Kiegészítő vagy szolgáltató specifikus adatok. (<a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméter használata</a>)</td></tr><tr><td><code>PaymentMethods</code></td><td>array</td><td><p></p><ul><li>apple_pay</li><li>google_pay</li><li>bank_card</li><li>...</li></ul></td><td><p>Megadható egyes szolgáltatók esetében, hogy mely fizetési módok legyenek engedélyezve.</p><p></p><p>Amennyiben ez a paraméter üresen marad, abban az esetben a fizetési szolgáltató oldalán az összes elérhető fizetési mód megjelenítésre kerül.</p><p></p><p>A fizetési módok kényszerített megjelenítését nem minden fizetési szolgáltató támogatja.</p><p><a href="https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok">Az elérhető fizetési módokkal kapcsolatos információk a Fizetési szolgáltató specifikus adatoknál találhatók.</a></p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Kétlépcsős tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "AutoCommit":"false",
        "PaymentMethods":["bank_card", "google_pay"]
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="139">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p><br>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

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

{% endcode %}


# Erős ügyfél-hitelesítés (PSD2/SCA)

Minden elindított tranzakció esetén át kell adni a vásárló és a tranzakció adatait rendszerünknek. Rendszerünk továbbítja ezeket az adatokat a fizetési szolgáltató felé. A vásárló adatainak átadása törvényi kötelezettség a kereskedő számára.

### Működés

Használja az `Info` paramétert az ügyfél adatainak átadásához.

{% hint style="info" %}
A PSD2 *(Payment Services Directive 2)* az Európai Unió egyik irányelve, mely a pénzügyi szolgáltatások piacát szabályozza.

A PSD2-SCA *(Strong Customer Authentication)*, ügyfél-hitelesítési folyamat, mely a visszaélések megelőzését és a kártyacsalások felderítését segíti elő. A tranzakció létrehozása során az erős ügyfél-hitelesítéshez átadott adatokat a tranzakció végstátuszának rendszerünkben történő beállításától számított 48 óra elteltével töröljük rendszerünkből.
{% endhint %}

#### **Adatok lekérdezése**

Használja a `GetInfoData` paramétert az erős ügyfél-hitelesítés során átadott adatok lekérdezéséhez a következő API hívásokban:

* `Details`
* `PaymentLinkDetails`

#### **Adatok átadása az `Info` objektumban**

Készítse elő a vásárló és a tranzakció adatait, majd használja az `Info` több szintű objektumot az adatok átadásához a következő API hívások során:

* `Init`
* `InitRP`
* `PaymentLinkCreate`
* `Payout`

#### **Előkészületek**

Figyeljen a következőkre, hogy az `Info` mező megfelelő értéket vegyen fel:

1. tárolja az adatokat JSON kódolt objektumban
2. kódolja az így kapott string tartalmát base64 segítségével
3. cserélje le a következő karaktereket a base64 kódolt string-ben

<table data-full-width="true"><thead><tr><th align="center">A base64 kódolt string eredeti karaktere</th><th align="center">Csere karakter az Info paraméter számára</th></tr></thead><tbody><tr><td align="center">+</td><td align="center">-</td></tr><tr><td align="center">/</td><td align="center">_</td></tr><tr><td align="center">=</td><td align="center">.</td></tr></tbody></table>

Adja át az így keletkezett karakterláncot az `Info` paraméterben.

#### **Az `Info` objektum felépítése**

Az `Info` objektum számos különböző adatot tartalmaz, melyek két nagy csoportra bonthatók fel, a következő módon:

#### **Vásárlói adatok**

* általános adatok
* bolt specifikus adatok
* böngésző adatok

#### **Rendelési adatok**

* általános adatok
* számlázási adatok
* szállítási adatok
* termékadatok

Táblázatos formában összefoglalva

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="132">Típus</th><th width="108">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Info: Customer: General</code></td><td>JSON object</td><td><a href="/pages/SZHVpm6VW2Nrjbf9m5EM">részletek</a></td><td>A vásárló általános adatai.</td></tr><tr><td><code>Info: Customer: StoreSpecific</code></td><td>JSON object</td><td><a href="/pages/KQP2sPg3a9SlUAjufA6f">részletek</a></td><td>A vásárló bolt specifikus adatai.</td></tr><tr><td><code>Info: Customer: Browser</code></td><td>JSON object</td><td><a href="/pages/Jm6nSFiFavY1LrNn90iz">részletek</a></td><td>A vásárló böngészőjének adatai.</td></tr><tr><td><code>Info: Order: General</code></td><td>JSON object</td><td><a href="/pages/dmsBHMwQQQ8W6IGVzbJn">részletek</a></td><td>A megrendelés általános adatai.</td></tr><tr><td><code>Info: Order: BillingData</code></td><td>JSON object</td><td><a href="/pages/msF8O9c5P0U9IroDMLHd">részletek</a></td><td>A számlázás adatai.</td></tr><tr><td><code>Info: Order: ShippingData</code></td><td>JSON object</td><td><a href="/pages/xQi3rl1Z42PsnZoom2SN">részletek</a></td><td>A szállítás adatai.</td></tr><tr><td><code>Info: Order: ProductItems</code></td><td>JSON object</td><td><a href="/pages/L1u59fOnwILXsHfeiP95">részletek</a></td><td>A vásárolt termékek adatai.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    ...,
    "Extra": 
    {
        ...
    },
    "Info":
    {
        "Customer":
        {
            "General": { ... },
            "StoreSpecific": { ... },
            "Browser": { ... }
        },
        "Order":
        {
            "General": { ... },
            "BillingData": { ... },
            "ShippingData": { ... },
            "ProductItems": [ { ... }, { ... }, ... ]
        }
    }
}
```

{% endcode %}


# Vásárlói adatok

A `Customer` objektum a megrendelés részletes adatait tartalmazza. A vásárló adatai három különböző típusra bonthatók:

* általános adatok (`General`)
* bolt specifikus adatok (`StoreSpecific`)
* böngésző adatok (`Browser`)


# Általános vásárlói adatok

A `General` objektum a vásárló személyes adatait tartalmazza. Egyes paraméterek átadása kötelező, míg más paraméterek opcionálisak.

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Ip</code></td><td>string<br><br>(45 karakter)</td><td><p>IPv4 vagy IPv6</p><p><strong>Figyelem!</strong> Az IP cím megadására az adott cím forrás országának törvényei irányadóak.</p><p>(Az adott törvényi előírások megismerése és betartása a kereskedő felelőssége.)</p></td><td>A vásárló IP címe.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>HomePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>HomePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Otthoni telefonszám.</td></tr><tr><td><code>MobilePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>MobilePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Mobiltelefonszám.</td></tr><tr><td><code>WorkPhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>WorkPhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Munkahelyi telefonszám.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "General":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "Ip":"",
                "HomePhoneCc":"",
                "HomePhone":"",
                "MobilePhoneCc":"",
                "MobilePhone":"",
                "WorkPhoneCc":"",
                "WorkPhone":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Bolt specifikus adatok

A `StoreSpecific` objektum a vásárló adott bolthoz kapcsolódó adatait és statisztikáit tartalmazza. Megadásuk a gyanús aktivitások felderítését segíti elő.

#### Paraméterek

<table data-full-width="true"><thead><tr><th width="370">Paraméter</th><th width="139">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>UpdateDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><p>A vásárlói profil módosításának utolsó dátuma.<br></p><p>(Pl. szállítási cím, számlázási cím, a kártya adatai, stb.)</p></td></tr><tr><td><code>UpdateDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (Ezen tranzakció során)</li><li>02 (Kevesebb, mint 30 napja)</li><li>03 (30-60 napja)</li><li>04 (Több, mint 60 napja)</li></ul></td><td>A fenti <code>UpdateDate</code> mező indikátora.</td></tr><tr><td><code>CreationDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárló regisztrációjának időpontja a kereskedő rendszerében.</td></tr><tr><td><code>CreationDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs regisztráció, vendég vásárlás)</li><li>02 (regisztráció ezen tranzakció során)</li><li>03 (regisztráció kevesebb, mint 30 napja)</li><li>04 (regisztráció 30-60 napja)</li><li>05 (regisztráció több, mint 60 napja)</li></ul></td><td>A fenti <code>CreationDate</code> mező indikátora.</td></tr><tr><td><code>PasswordChangeDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárlói jelszó módosításának utolsó dátuma.</td></tr><tr><td><code>PasswordChangeDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (a jelszó még egyszer sem változott meg)</li><li>02 (a jelszó megváltozott az aktuális tranzakció során)</li><li>03 (a jelszó kevesebb, mint 30 napja változott meg)</li><li>04 (a jelszó 30-60 napja változott meg)</li><li>05 (a jelszó több, mint 60 napja változott meg)</li></ul></td><td>A fenti <code>PasswordChangeDate</code> mező indikátora.</td></tr><tr><td><code>AuthenticationTimestamp</code></td><td><p>string</p><p></p><p>(19 karakter)</p></td><td>ÉÉÉÉ-HH-NN ÓÓ:PP:MM</td><td>A vásárló bejelentkezésének időpontja az adott tranzakció előtt.</td></tr><tr><td><code>AuthenticationMethod</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (vendég vásárlás, nem történt belépés)</li><li>02 (a kereskedő rendszere azonosította a vásárlót bejelentkezésnél)</li><li>03 (az egységesített beléptetés azonosította a vásárlót bejelentkezésnél (Federated ID))</li><li>04 (a kártya kibocsátó hitelesítette a vásárlót bejelentkezésnél)</li><li>05 (3rd party vásárlói azonosítás bejelentkezésnél)</li><li>06 (FIDO vásárlói azonosítás bejelentkezésnél)</li></ul></td><td>A vásárló bejelentkezésének módja a kereskedő rendszerébe az adott tranzakció előtt.</td></tr><tr><td><code>ChallengeIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs preferencia a vásárló azonosítására)</li><li>02 (nincs azonosítás kérés)</li><li>03 (azonosítás kérése: a kereskedő preferenciája szerint)</li><li>04 (azonosítás kérése: megbízás - csak a bankkártya első regisztrációjához kapcsolódó tranzakciónál szükséges átadni)</li></ul></td><td>Vásárló azonosításának módja a fizetési tranzakció során.</td></tr><tr><td><code>ShippingAddressFirstUse</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Az adott szállítási cím használatának első dátuma.</td></tr><tr><td><code>ShippingAddressFirstUseIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (az adott szállítási cím ezen tranzakció során került először megadásra)</li><li>02 (az adott szállítási cím kevesebb, mint 30 napja került először megadásra)</li><li>03 (az adott szállítási cím 30-60 napja került először megadásra)</li><li>04 (az adott szállítási cím több, mint 60 napja került először megadásra)</li></ul></td><td>A fenti <code>ShippingAddressFirstUse</code> mező indikátora.</td></tr><tr><td><code>CardTransactionsLastDay</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott kártya tokenizációs kísérleteinek száma az elmúlt 24 órában.</td></tr><tr><td><code>CardCreationDate</code></td><td><p>string</p><p></p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><ul><li>Tokenizált kártyás vásárlás esetén az adott kártya mentésének időpontja.</li><li>Más esetben a tranzakció dátuma</li></ul></td></tr><tr><td><code>CardCreationDateIndicator</code></td><td><p>string</p><p></p><p>(2 karakter)</p></td><td><ul><li>01 (nincs kártya mentés - vendég vásárlás)</li><li>02 (a kártyát az aktuális tranzakció során mentették)</li><li>03 (a kártyát kevesebb, mint 30 napja mentették)</li><li>04 (a kártyát 30-60 napja mentették)</li><li>05 (a kártyát több, mint 60 napja mentették)</li></ul></td><td>A fenti <code>CardCreationDate</code> mező indikátora.</td></tr><tr><td><code>TransactionsLastDay</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt 24 órában.</td></tr><tr><td><code>TransactionsLastYear</code></td><td><p>number</p><p></p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt egy évben.</td></tr><tr><td><code>PurchasesLastSixMonths</code></td><td>number<br><br>(4 karakter)</td><td>pozitív egész szám</td><td>Az adott vásárló sikeres tranzakcióinak száma az elmúlt 6 hónap során.</td></tr><tr><td><code>SuspiciousActivity</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (nem észlelt)</li><li>02 (gyanús aktivitás)</li></ul></td><td>Jelzi a vásárló gyanús tevékenységének észlelését a kereskedő áruházában.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "StoreSpecific":
            {
                "UpdateDate":"",
                "UpdateDateIndicator":"",
                "CreationDate":"",
                "CreationDateIndicator":"",
                "PasswordChangeDate":"",
                "PasswordChangeDateIndicator":"",
                "AuthenticationTimestamp":"",
                "AuthenticationMethod":"",
                "ChallengeIndicator":"",
                "ShippingAddressFirstUse":"",
                "ShippingAddressFirstUseIndicator":"",
                "CardTransactionsLastDay":"",
                "CardCreationDate":"",
                "CardCreationDateIndicator":"",
                "TransactionsLastDay":"",
                "TransactionsLastYear":"",
                "PurchasesLastSixMonths":"",
                "SuspiciousActivity":""
            },
            ...
        }
```

{% endcode %}


# Böngésző adatok

A `Browser` objektum a vásárláshoz használt böngészőből kinyerhető adatokat tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>AcceptHeader</code></td><td>string<br><br>(2048 karakter)</td><td><p>MIME típusok és altípusok</p><p>(Például: text/html, image/*, <em>/</em>, stb.)</p></td><td>A böngésző által értelmezhető tartalom típusok.</td></tr><tr><td><code>JavaEnabled</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>1 (Java engedélyezett)</li><li>0 (Java nem engedélyezett)</li></ul></td><td>Java használata a böngészőben.</td></tr><tr><td><code>Language</code></td><td>string<br><br>(8 karakter)</td><td><p>IETF BCP47 által definiált formátumban</p><p>(Például: "hu", "hu-HU", "en", "en-US", stb.)</p></td><td><p>A böngésző nyelve.<br></p><p>(A <code>navigator.language</code> értéke.)</p></td></tr><tr><td><code>ColorDepth</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>1 (1 bit)</li><li>4 (4 bit)</li><li>8 (8 bit)</li><li>15 (15 bit)</li><li>16 (16 bit)</li><li>24 (24 bit)</li><li>32 (32 bit)</li><li>48 (48 bit)</li></ul></td><td>A böngésző által használt színmélység.</td></tr><tr><td><code>ScreenHeight</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak magassága.</td></tr><tr><td><code>ScreenWidth</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak szélessége.</td></tr><tr><td><code>TimeZone</code></td><td>string<br><br>(5 karakter)</td><td>egész szám</td><td><p>A vásárló saját időzónája és a UTC (világidő) idő közötti különbség percben megadva.<br></p><p>(A <code>dateObj.getTimezoneOffset()</code> értéke.)</p></td></tr><tr><td><code>UserAgent</code></td><td>string<br><br>(2048 karakter)</td><td>egyedi érték</td><td>A használt böngésző azonosítására szolgáló adatok.</td></tr><tr><td><code>WindowSize</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (250 x 400)</li><li>02 (390 x 400)</li><li>03 (500 x 600)</li><li>04 (600 x 400)</li><li>05 (teljes képernyő)</li></ul></td><td><p>A fizetés hitelesítését végző szolgáltató ablakának mérete. Az ablak tartalmát ehhez a mérethez kell igazítani a legjobb felhasználói élmény érdekében. (A hitelesítő felület (3DSecure) megjelenítésének paramétere.)<br></p><p>(A fizetési hitelesítő (ACS) szerepét jellemzően a kártyakibocsátó bank tölti be. Az ACS itt az Access Control Server-t jelöli.)</p></td></tr></tbody></table>

#### Mintakód

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "Browser":
            {
                "AcceptHeader":"",
                "JavaEnabled":"",
                "Language":"",
                "ColorDepth":"",
                "ScreenHeight":"",
                "ScreenWidth":"",
                "TimeZone":"",
                "UserAgent":"",
                "WindowSize":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Rendelési adatok

Az `Order` objektum a megrendelés részletes adatait tartalmazza. A rendelés adatainak négy különböző típusa a következő:

* általános rendelési adatok (`General`)
* számlázási adatok (`BillingData`)
* szállítási adatok (`ShippingData`)
* termékadatok (`ProductItems`)


# Általános rendelési adatok

A `General` objektum a vásárlás általános adatait tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="143">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>DeliveryEmail</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum<br><br>(maximum 1 db)</td><td>Elektronikus kézbesítés esetén az email cím (vagy a felhasználói fiókhoz tartozó email cím) amelyre az áru érkezik.</td></tr><tr><td><code>DeliveryTimeFrame</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (elektronikus kézbesítés (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb. esetén))</li><li>02 (kézbesítésre a megrendelés napján kerül sor)</li><li>03 (kézbesítésre éjszaka kerül sor)</li><li>04 (a kézbesítés 2 vagy több napot vesz igénybe)</li></ul></td><td>A kézbesítés ideje.</td></tr><tr><td><code>GiftCardAmount</code></td><td>number<br><br>(15 karakter)</td><td><p>pozitív szám, maximum 2 tizedesjeggyel<br></p><p>(Magyar forint (HUF) esetén értéke egész szám, tizedesjegyek nélkül.)</p></td><td>Utalványról vagy ajándékkártyáról felhasznált összeg.</td></tr><tr><td><code>GiftCardCount</code></td><td>number<br><br>(2 karakter)</td><td>pozitív egész szám</td><td>Utalvánnyal vagy ajándékkártyával kifizetett rendelések száma.</td></tr><tr><td><code>GiftCardCurrency</code></td><td>string<br><br>(3 karakter)</td><td>ISO 4217 által definiált formátum</td><td>Az utalvány vagy ajándékkártya pénzneme.</td></tr><tr><td><code>PreorderDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Előrendelés esetén az áru elérhetőségének várható dátuma.</td></tr><tr><td><code>Availability</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (a rendelést azonnal teljesíti a kereskedő)</li><li>02 (a rendelést egy későbbi időpontban teljesíti a kereskedő)</li></ul></td><td>Jelzi, hogy a rendelés azonnal (készletről) vagy egy későbbi időpontban kerül teljesítésre.</td></tr><tr><td><code>ReorderItems</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (az adott terméket először rendelik meg)</li><li>02 (az adott terméket ismételten rendelik meg)</li></ul></td><td>Jelzi, hogy az adott terméket első alkalommal vagy ismételten rendelik meg.</td></tr><tr><td><code>ShippingMethod</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék szállítása a számlázási címre)</li><li>02 (termék szállítása egy korábban megadott címre)</li><li>03 (termék szállítás a számlázási címtől eltérő címre)</li><li>04 (termék személyes, bolti átvétele esetén)</li><li>05 (termék digitális kézbesítése esetén (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))</li><li>06 (a termék utazásra vagy esemény látogatására szóló jegy)</li><li>07 (egyéb termékek esetén (játékok, digitális szolgáltatások, feliratkozások, stb.))</li></ul></td><td>A szállítás módja vagy a kézbesítés jellege.</td></tr><tr><td><code>AddressMatchIndicator</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>0 (eltérő számlázási és szállítási cím)</li><li>1 (megegyező számlázási és szállítási cím)</li></ul></td><td>Jelzi, hogy a számlázási cím és a szállítási cím megegyezik vagy eltér egymástól.</td></tr><tr><td><code>DifferentShippingName</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (megegyező számlázási és szállítási név)</li><li>02 (eltérő számlázási és szállítási név)</li></ul></td><td>Jelzi, hogy a számlázási név és a szállítási név megegyezik vagy eltér egymástól.</td></tr><tr><td><code>TransactionType</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék/szolgáltatás vásárlása)</li><li>03 (ellenőrzés/hitelesítés)</li><li>10 (számla finanszírozás)</li><li>11 (kvázi készpénz ügylet, pl. pénzutalvány, utazási csekk, deviza, szelvény, stb.)</li><li>28 (egyenleg feltöltés)</li><li>stb.</li></ul></td><td>A tranzakció típusa.<br><br>(Az ISO 8583 lista szerint.)</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "General":
            {
                "DeliveryEmail":"",
                "DeliveryTimeFrame":"",
                "GiftCardAmount":"",
                "GiftCardCount":"",
                "GiftCardCurrency":"",
                "PreorderDate":"",
                "Availability":"",
                "ReorderItems":"",
                "ShippingMethod":"",
                "AddressMatchIndicator":"",
                "DifferentShippingName":"",
                "TransactionType":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Számlázási adatok

A `BillingData` objektum a számlázási adatokat tartalmazza, ezek átadása kötelező. Viszont a számlázási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td>Keresztnév.<br><br>(Cég esetén cégnév.)</td></tr><tr><td><code>LastName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td><p>Vezetéknév.</p><p>(Cég esetén cégnév.)</p></td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td>string<br><br>(18 karakter)</td><td>számok</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.</p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím első sora.<br><br>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</td></tr><tr><td><code>PostalCode</code></td><td>string<br><br>(16 karakter)</td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p><br>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód</p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyarországon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        {    
            "BillingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Szállítási adatok

A `ShippingData` objektum a szállítási adatokat tartalmazza, átadása kötelező postázás vagy futárszolgálat igénybevétele esetén. Ugyanakkor a szállítási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

{% hint style="warning" %}
Személyes átvételnél és digitális kézbesítés esetén a szállítási adatok megadására nincs szükség. Ilyenkor jelezze a szállítás módját vagy a kézbesítés jellegét a `General` objektum `ShippingMethod` paraméterében.<br>

Az átadható értékek ilyen esetekben:

* 04 (termék személyes, bolti átvétel)
* 05 (termék digitális kézbesítése (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td><p>string</p><p>(254 karakter)</p></td><td><p>szabványos email formátum</p><p>(maximum 1 db)</p></td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td><p>string</p><p>(18 karakter)</p></td><td>számokek</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td><p>A cím első sora.<br></p><p>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</p></td></tr><tr><td><code>PostalCode</code></td><td><p>string</p><p>(16 karakter)</p></td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum<br></p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód<br></p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyaroszgágon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "ShippingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Termékadatok

A `ProductItems` objektum a vásárlás során kifizetett tételek megjelölésére szolgál. A megvásárolt terméken vagy szolgáltatáson túl ezek a tételek lehetnek például szállítási vagy kezelési költségek, jóváírások, kedvezmények, stb.

{% hint style="warning" %}
A `ProductItems` blokkban szereplő tételek összértéke meg kell egyezzen a tranzakció inicializálása során átadott `Amount` paraméter értékével. Vagyis az itt átadott `UnitPrice` \* `Quantity` = `Amount`. Amennyiben a tételek összértéke nem egyezik meg az `Amount` értékével a tranzakció elutasításra kerül.
{% endhint %}

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Sku</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td><p>A termék egyedi azonosítója a kereskedő áruházában.<br></p><p>(Pl. a termék cikkszáma, sorozatszáma, stb.)</p></td></tr><tr><td><code>Name</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td>A termék megnevezése.</td></tr><tr><td><code>Quantity</code></td><td><p>number</p><p>(10 karakter)</p></td><td>pozitív egész szám</td><td>A megvásárolt mennyiség.</td></tr><tr><td><code>QuantityUnit</code></td><td><p>string</p><p>(16 karakter)</p></td><td>egyedi értékek</td><td><p>Mennyiségi egység.<br></p><p>(Pl. darabszám, kilogramm, méter, stb.)</p></td></tr><tr><td><code>UnitPrice</code></td><td><p>number</p><p>(16 karakter)</p></td><td><ul><li>pozitív szám, maximum 2 tizedesjeggyel (egy eladott egység ára)</li><li>negatív szám, maximum 2 tizedesjeggyel (a kedvezmények vagy jóváírások megadására)</li></ul></td><td><p>A termék egységára.<br></p><p>Kedvezmények és jóváírások esetén negatív szám.<br></p><p>(A tizedesjegy elválasztó karakterként “.” használjon. Magyar forint (HUF) esetén a tizedesjegyek értéke kizárólag nulla lehet.)</p></td></tr><tr><td><code>ImageUrl</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi URL cím</td><td>Az elsődleges termékfotó URL címe.</td></tr><tr><td><code>Description</code></td><td><p>string</p><p>(254 karakter)</p></td><td>egyedi értékek</td><td>A termék leírása.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "ProductItems":
            [
                {
                    "Sku":"",
                    "Name":"",
                    "Quantity":"",
                    "QuantityUnit":"",
                    "UnitPrice":"",
                    "ImageUrl":"",
                    "Description":""
                },
                ...
            ],
            ...
        }
    }
}
```

{% endcode %}


# Visszairányítási módok

### Működés

Használja a `redirectMode` paramétert, hogy fizetés után visszairányítsa a vásárlót a webáruházba a fizetési szolgáltató oldaláról.

A `redirectMode` paraméter értékét (és a visszairányítás módját) az inicializálás során (`Init`) adhatja meg, az `Extra` paraméteren belül.

{% hint style="info" %}
Amennyiben nem adja át a `redirectMode` értékét az `Extra` paraméterben, alapértelmezetten a 0 értékhez tartozó HTTP átirányítás lép működésbe.
{% endhint %}

A `redirectMode` segítségével a következő visszairányítási módok érhetők el:

<table data-full-width="true"><thead><tr><th width="90">Érték</th><th width="216">Eljárás</th><th>Leírás</th></tr></thead><tbody><tr><td>0</td><td>HTTP redirect</td><td>A vásárló HTTP 302-es átirányítással kerül vissza az inicializáció (<code>Init</code>) során megadott válasz URL címre (<code>ResponseUrl</code>).</td></tr><tr><td>1</td><td>top.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: top window.</td></tr><tr><td>2</td><td>parent.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: parent window.</td></tr><tr><td>3</td><td>top.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: top window.</p><p>(Nincs átirányítás!)</p></td></tr><tr><td>4</td><td>parent.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: parent window.<br></p><p>(Nincs átirányítás!)</p></td></tr></tbody></table>

A javascript alapú üzenetek tartalma a következő formátumú JSON string (a 3-as és 4-es `redirectMode` értékeknél):

{PMGWTransactionData: {TransactionId: “”, OrderId: “”, UserId: “”}}

**Window\.postMessage()** használata esetén a paraméterek a következő értékekkel rendelkeznek:

<table data-full-width="true"><thead><tr><th width="306">Paraméter</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>A tranzakció egyedi Nevogate azonosítója, melyet az <code>Init</code> hívás válaszában ad vissza rendszerünk.</td></tr><tr><td><code>OrderId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr><tr><td><code>UserId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr></tbody></table>


# Tranzakció indítása (Start)

### Műkődés

Tranzakció indításához irányítsa át a vásárlót rendszerünkbe az inicializáció (`Init`) során visszakapott tranzakció azonosítóval (`TransactionId`). Rendszerünk felépíti a kommunikációt a fizetési szolgáltatóval és tovább irányítja a vásárlót a fizetési felületre.

Tranzakció indításához **teszt környezetben** használja a következő címet:

<https://system-test.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]

Tranzakció indításához **éles környezetben** használja a következő címet:

<https://system.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]


# URL Értesítés

### Működés

Használja a `NotificationUrl` paramétert, hogy automatikusan értesüljön a tranzakciók státuszának változásáról. Az inicializáció (`Init`) során adja át az értesítési URL címet a `NotificationUrl` paraméterben. Rendszerünk ezt a címet hívja meg a tranzakció státuszának megváltozásakor.

Rendszerünk legfeljebb 5 alkalommal kísérli meg a megadott értesítési URL hívását, amíg a hívásra HTTP 200 választ nem kap. Az értesítés a tranzakció részletes adatait tartalmazza JSON formátumban (a `Details` hívás eredményének megfelelően), amit `application/json` típusként küldünk, így az adat a *raw request body*-ból nyerhető ki.

Jelezze vissza rendszerünk számára, hogy a kereskedő oldala értesült a tranzakció eredményéről. Ehhez indítson egy `Result` kérést minden rendszerünktől visszaérkező `NotificationUrl` hívás után. `Result` kérés hiányában a tranzakció “megválaszolhatatlan” állapotot kap a *PayAdmin* felületén.

Az alapértelmezett (lineáris időközönként maximum 5 alkalommal történő) URL értesítési eljárás mellett elérhető egy kiterjesztett URL értesítési eljárás is.

Ebben az esetben az értesítési kísérletek fokozatosan elnyújtott időközönként történnek az alábbi logika szerint:

* Azonnal a végstátusz beállítását követően.
* 5 másodperc elteltével.
* 10 másodperc elteltével.
* 30 másodperc elteltével.
* 1 perc elteltével.
* 5 perc elteltével.
* 15 perc elteltével.
* 30 perc elteltével.
* 1 óra elteltével.
* 3 óra elteltével.
* 6 óra elteltével.
* 12 óra elteltével.
* 1 nap elteltével.

A kiterjesztett URL értesítés igénybevételéhez vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.

{% hint style="warning" %}
A `NotificationUrl` átadása minden tranzakció inicializáció során kötelező.\
Továbbá figyeljen arra, hogy a megadott értesítési URL cím (`NotificationUrl`):

* rendelkezzen HTTPS protokollal
* legyen mindenkor publikusan elérhető
  {% endhint %}

{% hint style="danger" %}
A JSON formátumú értesítésben található paraméterek kis kezdőbetűkkel szerepelnek. Ezzel ellentétben a tranzakció részletes adatainak lekérdezésére (`Details` hívásra) adott válasz paraméterei nagy kezdőbetűvel rendelkeznek.
{% endhint %}

### Beállítás lépései

Végezze el a következő lépéseket az URL értesítés megfelelő működéséhez.

{% hint style="warning" %}
A leírt folyamatot minden egyes `NotificationUrl` híváskor végre kell hajtani.
{% endhint %}

1. Adjon meg egy értesítési URL címet a `NotificationUrl` paraméter segítségével.
2. Vizsgálja meg, hogy a *raw request body* tartalmaz JSON típusú adattartalmat (a rendszerünkből érkező `NotificationUrl` hívás során).
3. Nyerje ki az aktuális `TransactionId` értéket a *raw request body*-ból.
4. Indítson egy `Result` kérést melyben megadja a `NotificationUrl` törzséből kinyert `TransactionId` értéket.
5. Dolgozza fel a `Result` kérésre kapott választ, majd
6. mentse el a rendszerében a tranzakció végstátuszát (`ResultCode`).
7. Válaszoljon HTTP 200-as státusz kóddal a rendszerünkből érkező `NotificationUrl` hívásra.

{% hint style="info" %}
PHP használata esetén így nyerheti ki a `TransactionId` értékét:

```php
$json = file_get_contents('php://input');
$data = json_decode($json);
$transactionId = $data->commonData->transactionId;
```

{% endhint %}

### Példa (URL értesítés beállítására teszt környezetben)

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "NotificationUrl":"https://merchant.notification.url"
    }'
```

{% endcode %}


# Tranzakció eredményének lekérdezése (Result)

### Működés

Használja a `Result` hívást a tranzakció eredményének lekérdezéséhez. A fizetés után rendszerünk visszairányítja a vásárlót az áruházba, úgy, hogy meghívja azt a `ResponseUrl`-t, amit az inicializáció (`Init`) során adott meg a kereskedő oldala. Miután rendszerünk meghívja a `ResponseUrl`-t, a kereskedő oldala elindíthatja a `Result` hívást.

`Result` hívás indításához szüksége lesz az adott tranzakció azonosítójára. Ezért a rendszerünkből érkező `ResponseUrl` hívás kiegészül a `TransactionId` GET paraméterrel, amely az adott tranzakció azonosítót biztosítja.

Fontos, hogy minden rendszerünkből érkező `ResponseUrl` hívás után indítson egy `Result` hívást, a vásárlói munkamenettől függetlenül. Ennek oka, hogy előfordulhat, hogy a `ResponseUrl` hívásra később, aszinkron módon, a háttérben kerül sor.

Rendszerünk aszinkron módon elindítja a `NotificationUrl` hívást, abban az esetben, ha beállt az adott tranzakció végstátusza. A `NotificationUrl` az inicializáció (`Init`) során kötelezően átadandó URL cím. Itt is fontos, hogy minden rendszerünkből érkező `NotificationUrl` hívás után indítson egy `Result` hívást.

Rendszerünk a `Result` hívás hatására értesül arról, hogy a kereskedő oldala megkapta a tranzakció eredményét. Ezért amennyiben a `Result` hívásra nem kerül sor, a tranzakció rendszerünkben a "megválaszolhatatlan" állapotot veszi fel.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=result)

{% hint style="info" %}
További részletekért a `NotificationUrl` használatáról látogassa meg a következő hivatkozást: [URL Értesítés](/egyszeri-fizetesek-one-time-payment/bankkartya-es-mobiltarca/kesobbi-terheles-ketlepcsos-fizetes/url-ertesites)

A tranzakció állapotairól a rendszerünkben pedig a következő oldalon olvashat további információkat: [Tranzakció Állapotok](/segedlet/tranzakcio-allapotok)
{% endhint %}

{% hint style="warning" %}
Figyeljen arra, hogy `Result` kérést kizárólag `ResponseUrl` vagy `NotificationUrl` hívások hatására indítson. A kereskedő rendszeréből indokolatlanul, vagy ütemezett módon `Result` kérést indítani tilos!
{% endhint %}

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Result</code></td><td><code>POST</code></td><td>method=<code>Result</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Result` kérés egy (kötelező) paraméterrel rendelkezik

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció eredményének lekérése `Result` használatával

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Result | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Result' \
  --data 'json=
    {
        "TransactionId":"992c8e75435e6d4dfdf6415f0714cae8"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Result` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="345">Paraméter</th><th width="132">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>egyedi értékek</td><td>Rendszerünkben tárolt egyedi boltazonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A tranzakció státusza lehet:</p><ul><li>SUCCESSFUL</li><li>PENDING</li><li>OPEN</li><li>ERROR</li><li>CANCELED</li><li>TIMEOUT</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul></td><td>Jelzi a tranzakció eredményét.<br><br>A tranzakció státuszokról a következő oldalon olvashat további információkat: <a href="/pages/yzo9U4RLeMGLusg6Mrfl">Tranzakció státuszok</a></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>Anum</code></td><td>string</td><td>egyedi értékek</td><td><p>A tranzakció engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Csak bizonyos szolgáltatók esetén.)</p></td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td><p>A tranzakció bruttó végösszege.<br></p><p>(Az összeg amit a vásárló kifizetett.)</p></td></tr><tr><td><code>Currency</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>HUF</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td>A tranzakció devizaneme.</td></tr><tr><td><code>OrderId</code></td><td>string</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>OrderId</code>.)</p></td></tr><tr><td><code>UserId</code></td><td>string</td><td><p>egyedi értékek</p><p>(kivéve e-mail címek, illetve személyes adatok)</p></td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>UserId</code>.)</p></td></tr><tr><td><code>Language</code></td><td><p>string</p><p><br>(2 karakter)</p></td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>ProviderTransactionId</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“false”</li></ul></td><td>Jelzi, hogy a bank később hajtja végre a tranzakciót.</td></tr><tr><td><code>CommitState</code></td><td>string</td><td><ul><li>PENDING</li><li>APPROVED</li><li>DECLINED</li></ul></td><td><p>Kétlépcsős tranzakció esetén jelzi a tranzakciós összeg állapotát.<br></p><p>• PENDING: az összeg zárolásra került, de még terhelésre vár (tranzakció lezárással)</p><p>• APPROVED: a végleges összeg beterhelése megtörtént</p><p>• DECLINED: a zárolt összeg feloldásra került (nem történt terhelés)</p></td></tr><tr><td><code>PaywallPaymentName</code></td><td>string<br><br>(36 karakter)</td><td><ul><li>null</li><li>UUID</li></ul></td><td>A tranzakció <em>PayWall</em> azonosítója (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaywallRecurringPaymentEnabled</code></td><td>string</td><td><ul><li>"true"</li><li>"false"</li></ul></td><td>Jelzi a vásárló hozzájárulását, hogy a kereskedő a jövőben az adott tranzakcióra hivatkozva újabb, ismétlődő tranzakciókat indíthasson (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaymentRegistrationType</code></td><td>string</td><td><ul><li>null</li></ul></td><td>Jelzi a fizetési regisztráció típusát.</td></tr><tr><td><code>SzepPocket</code></td><td>string</td><td><ul><li>null</li></ul></td><td>A tranzakció inicializálása (<code>Init</code>) során megadott zsebazonosító (SZÉP Kártyás fizetés esetén).</td></tr><tr><td><code>ProviderResultCode</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>Barion2 (ErrorCode)</li><li>Borgun2 (ActionCode)</li><li>GP (PRCODE)</li><li>GoPay (Error Code)</li><li>KHB</li><li>OTPSimple (resultCode / errorCodes)</li><li>PayU2 (error_code)</li><li>PayURest (cardResponseCode)</li><li>Saferpay (ErrorName)</li><li>Stripe (last_payment_error:code)</li><li>VivaWallet (statusId)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó elsődleges eredmény- vagy hibakód.</td></tr><tr><td><code>ProviderResultCode2</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>GP (SRCODE)</li><li>KHB</li><li>PayU2 (add_cc_response_code)</li><li>Saferpay (ProcessorResult)</li><li>Stripe (last_payment_error:decline_code)</li><li>VivaWallet (EventId / ResponseEventId)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó másodlagos eredmény- vagy hibakód.</td></tr><tr><td><code>PaymentLinkName</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A fizetési hivatkozás azonosítója a <em>Nevogate</em> rendszerében (amennyiben a tranzakció <em>PayLink</em> segítségével jött létre).</td></tr><tr><td><code>Created</code></td><td>string</td><td>dátum</td><td>A tranzakció létrehozásának ideje.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Result` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "StoreName": "sdk_test",
    "ProviderName": "Borgun2",
    "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": "Sikeres tranzakció",
    "Anum": "006761",
    "Amount": "100",
    "Currency": "HUF",
    "OrderId": "TEST-ORDER-ID",
    "UserId": "TEST-USER-ID",
    "Language": "HU",
    "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
    "AutoCommit": "true",
    "CommitState": "APPROVED",
    "PaywallPaymentName": null,
    "PaywallRecurringPaymentEnabled": "false",
    "PaymentRegistrationType": null,
    "SzepPocket": null,
    "ProviderResultCode": "000",
    "ProviderResultCode2": null,
    "PaymentLinkName": null,
    "Created": "2020-03-14 11:19:07",
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Tranzakció részletes adatainak lekérdezése (Details)

### Működés

Használja a `Details` hívást a tranzakció részletes adatainak lekérdezéséhez. Míg a `Result` hívásra adott válasz csupán a tranzakció alapadatait hordozza, a `Details` hívás további részletes információkat is tartalmaz az adott tranzakcióról (pl. szolgáltató specifikus adatokat).

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=details)

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Details</code></td><td><code>POST</code></td><td>method=<code>Details</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Details` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` átadása kötelező**)

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="124">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>GetRelatedTransactions</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td>Olyan korábbi tranzakciók részletes adatainak lekérése, melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>GetInfoData</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td><p>Kérés a vásárlásra vonatkozó Info adatok visszaadására.<br></p><p>(<code>Init</code>, <code>InitRP</code> vagy <code>PaymentLinkCreate</code> hívások során átadott vásárlási adatok esetén.)</p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció részletes adatainak lekérése `Details` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Details | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Details' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "GetRelatedTransactions":false,
        "GetInfoData":false
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Details` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="249">Paraméter</th><th width="128">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>CommonData</code></td><td>JSON object</td><td>egyedi értékek</td><td><p>A tranzakció alapadatai.<br></p><p>(A <code>Result</code> hívás során is visszaadott adatok.)</p></td></tr><tr><td><code>ProviderSpecificData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Szolgáltató specifikus kiegészítő adatok.</td></tr><tr><td><code>RelatedTransactions</code></td><td>JSON object</td><td>egyedi értékek</td><td>Olyan korábbi tranzakciók adatai melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>InfoData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Az <code>Info</code> objektum adatai.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Details` kérésre adott válasz (formázást követően):

{% code overflow="wrap" %}

```php
{
    "CommonData":
    {
        "StoreName": "sdk_test",
        "ProviderName": "Borgun2",
        "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
        "ResultCode": "SUCCESSFUL",
        "ResultMessage": "Sikeres tranzakció",
        "Anum": "006766",
        "Amount": "100",
        "Currency": "HUF",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "Language": "HU",
        "ProviderTransactionId": "tr_GVaydOjpVySGJycK15glvGgbLGxmCQyf",
        "AutoCommit": "false",
        "CommitState": "APPROVED",
        "Created": "2020-03-14 11:19:07",
        "ResponseId": "3202109280600047706"
    },
    "ProviderSpecificData":
    {
        ...
        "Amount": "100",
        "Currency": "HUF",
        "Language": "HU",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "ResponseUrl": "https://demo.nevogate.com/response.php",
        "NotificationUrl": null,
        "MaxNotificationSendAttempts": 0,
        "NotificationSendAttempts": 0,
        "NotificationSendSuccess": 0,
        "Extra": null,
        "AutoCommit" : "0",
        "CommitState": "1",
        "HasRefund": "0",
        "Created": "2017-11-17 13:12:36",
        "LastModified": "2017-11-17 13:14:07",
        "InvoiceDate": null,
        "GatewayPaymentPage": null,
        "ModuleName": null,
        "ModuleVersion": null,
        "StoreProviderId": "3103",
        "Error": null,
        "ResultMessage": null
    },
    "RelatedTransactions": null,
    "InfoData": null,
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ProviderName": "Borgun2",
    "ResponseId": "3202109280600047706"
}
```

{% endcode %}


# Kétlépcsős tranzakció lezárása (Close)

### Működés

Használja a `Close` hívást egy kétlépcsős tranzakció lezárásához. A `Close` segítségével jelezheti a fizetési szolgáltató számára, hogy a vásárló számláján korábban befoglalt összeget teljes egészében megterhelje, részben terhelje meg vagy szabadítsa fel.

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=close)

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Close</code></td><td><code>POST</code></td><td>method=<code>Close</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### Terhelés

Teljes összeg terhelésére a `Close` hívás során két lehetőség van (elég csupán az egyiket alkalmazni):

* a hívás során **ne** adja át az `ApprovedAmount` paramétert
* amennyiben mégis átadja az `ApprovedAmount` paramétert, annak értéke legyen `0`

Mindkét eljárás jelzi a fizetési szolgáltató számára, hogy a korábban befoglalt teljes összeggel terhelje meg a vásárló számláját.

### Részterhelés

Részösszeg terheléséhez, a `Close` hívás során adja át a terhelni kívánt részösszeget az `ApprovedAmount` paraméterben. Ilyen esetben kizárólag az `ApprovedAmount`-ban megadott részösszeg kerül terhelésre. Az eredetileg befoglalt összeg és a részösszeg közötti különbözet automatikusan feloldásra kerül a vásárló számláján (többszörös, egymást követő részösszeg terhelésre ezért nincs lehetőség).

{% hint style="info" %}
Részösszeg terhelését csak bizonyos fizetési szolgáltatók támogatják. Ez a funkció jelenleg a következő szolgáltatóknál érhető el:

* Barion Smart Gateway
* Global Payments
* GoPay
* K\&H Bank
* PayPal REST
* Raiffeisen vPos
* SimplePay
* Stripe
* Viva Wallet
* Wordline - Saferpay
  {% endhint %}

### Feloldás

Foglalás feloldásához, a `Close` hívás során adja át az `Approved` paramétert, melynek értéke legyen `"false"`. Ennek hatására a fizetési szolgáltató feloldja a teljes korábban befoglalt összeget a vásárló számláján (ezért részösszeg feloldására nincs lehetőség).

#### **API kérés paraméterek**

A `Close` kérés paraméterei közül a `TransactionId` átadása kötelező:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="134">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>Approved</code></td><td>string</td><td><ul><li>“true” (alapért.)</li><li>“false”</li></ul></td><td><p>Jelzi a befoglalt összeg terhelését vagy feloldását.<br></p><ul><li>“true” esetén a fizetési szolgáltató ténylegesen megterheli a korábban befoglalt összeget (vagy részösszeget) a vásárló számláján</li><li>“false” esetén a fizetési szolgáltató feloldja a korábban befoglalt teljes összeget a vásárló számláján</li></ul></td></tr><tr><td><code>ApprovedAmount</code></td><td>number</td><td><p>szabadon választható<br></p><p>(de legfeljebb az eredeti tranzakció összege)</p></td><td><p>Jelzi a terhelni kívánt részösszeg mértékét.<br></p><p>Ha ez a paraméter nem kerül átadásra, vagy az átadott értéke “0”, akkor a fizetési szolgáltató a teljes korábban befoglalt összeggel terheli meg a vásárló számláját.<br></p><p>(Amennyiben az <code>Approved</code> paraméter átadása <code>”false”</code> értékkel történik, úgy az <code>ApprovedAmount</code> paraméterben átadott érték nem lesz figyelembe véve és a teljes összeg feloldásra kerül a vásárló számláján.)</p></td></tr></tbody></table>

#### **Mintakód**

Kétlépcsős tranzakció lezárása `Close` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Close | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Close' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "Approved":"true"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Close` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="133">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az eredménykód a következők egyike lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát a Nevogate rendszerében:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApike</li><li>WrongParameter</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi a végleges terhelés, vagy a befoglalt összeg feloldásának eredményét.</p><ul><li>SUCCESSFUL: a befoglalt összeg végleges terhelése, részterhelése vagy feloldása sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata, hibaüzenet esetén.</td></tr><tr><td><code>Approved</code></td><td>boolean</td><td><ul><li>true</li><li>false</li></ul></td><td>Az <code>Close</code> hívás során megadott <code>Approved</code> paraméter értéke.</td></tr><tr><td><code>ApprovedAmount</code></td><td>number</td><td>értékét rendszerünk adja vissza</td><td><p>A terhelt összeg vagy részösszeg.</p><p>(Maximum értéke az előzetesen befoglalt összeg.)</p></td></tr><tr><td><code>ReservedAmount</code></td><td>number</td><td>vásárlás során kerül meghatározásra</td><td>A vásárlás során eredetileg befoglalt összeg.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Close` kérésre adott sikeres válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
    "ResultCode": "SUCCESSFUL",
    "Approved": true,
    "ApprovedAmount": 100,
    "ReservedAmount": 100,
    "ResultMessage": null,
    "ResponseId": "3202109280600047705"
}
```

{% endcode %}


# Tranzakció összegének visszatérítése (Refund)

### Működés

Használja a `Refund` hívást egy sikeres tranzakció összegének teljes vagy részleges visszatérítésére. Visszatérítésre csak bizonyos fizetési szolgáltatóknál van lehetőség, továbbá ezt a funkciót jellemzően külön kell igényelni az adott fizetési szolgáltatótól.

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=refund)

{% hint style="warning" %}
Kétlépcsős tranzakció esetén a visszatérítés (`Refund`) csak olyan lezárt tranzakciókra kérhető, ahol a befoglalt összeg már részben vagy egészben megterhelésre került (egy `Close` hívás segítségével). Befoglalt (de nem terhelt) összeg feloldásához használja a `Close` hívást a feloldásához szükséges paraméterekkel.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Refund</code></td><td><code>POST</code></td><td>method=<code>Refund</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Refund` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` és `Amount` átadása kötelező**):

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="115">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td>Visszatérítésre kerülő összeg az eredeti tranzakció pénznemében.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Egyéb illetve szolgáltató specifikus adatok.</p><p>(További részletekről az <a href="/pages/XaOHnljbNm5MGxPqLjdh">Extra adatok</a> pontban olvashat.)<br></p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció összegének részleges vagy teljes visszatérítése `Refund` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Refund | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Refund' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "Amount":100
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Refund` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="277">Paraméter</th><th width="133">Típus</th><th width="284">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A visszatérítés beküldésének eredménye a következők egyike lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi a visszatérítés beküldésének eredményét:</p><ul><li>SUCCESSFUL: a visszatérítés beküldése sikeres</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>RefundRequestId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés kérésének azonosítója a fizetési szolgáltató rendszerében.</p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundTransactionId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés azonosítója a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundAuthorizationCode</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundId</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A visszatérítés egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Refund` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "RefundRequestId": null,
    "RefundTransactionId": null,
    "RefundAuthorizationCode": null
    "RefundId": "rf_b0fd9b0381bb54568870a6c22d6a086f",
    "ResultMessage": null,
    "ResponseId": "3202109280600047707"
}
```

{% endcode %}


# SZÉP Kártya

**Ebben a fejezetben a SZÉP Kártyás fizetési megoldások leírását találja.**

Egyszeri fizetést a következő fizetési módokkal is igénybe lehet venni (ezekről a dokumentáció megfelelő részében olvashat további információkat):

* bankkártya, mobiltárca
* online áruhitel
* átutalás

{% hint style="info" %}
SZÉP Kártyás fizetésnél kizárólag azonnali terhelés érhető el, a bankkártyás vásárlásnál elérhető kétlépcsős fizetésre (és későbbi terhelésre) itt nincs lehetőség.
{% endhint %}

A SZÉP Kártya egy munkáltatók által nyújtott fizetésen kívüli juttatás (más néven cafeteria). Sajátossága, hogy a bankkártyával ellentétben nem csak egy, hanem egyszerre több alszámlához (úgynevezett zsebhez) is kapcsolódik. Ezért a vásárlás során az összegen túl a megfelelő alszámla azonosítóját is át kell adni. A SZÉP Kártyák jellemzően a következő alszámlákhoz kapcsolódnak:

* főszámla
* aktív magyarok alszámla

Rendszerünk jelenleg mindhárom elérhető SZÉP Kártya kibocsátó megoldását támogatja:

* K\&H Bank
* MBH Bank
* OTP Bank

Fontos, hogy a fizetésre használt alszámla (zseb) azonosítóját minden esetben a tranzakció inicializálása során kell átadni, azonban ennek pontos menete mindegyik kártyakibocsátó esetében eltérő. Ezeket a különbségeket a Tranzakció inicializálása (`Init`) fejezetben tárgyaljuk részletesen.

{% hint style="info" %}
A SZÉP Kártyához kapcsolódó alszámlákat a fizetési szolgáltatóval kötött szerződés keretében igényelheti a kereskedő, azok nem érhetőek el alapértelmezetten.
{% endhint %}

### SZÉP Kártya használata egykattintásos (One-click/CIT) fizetésekhez

Kibővítettük a SZÉP Kártyás fizetési lehetőségeket, így az egyszeri (One-time) fizetés mellett elérhető lett az egykattintásos (One-click/CIT) fizetési mód is SZÉP Kártya használata esetén. A fizetés módját a tranzakció létrehozása során átadott `ProviderName` értéke alapján különböztetjük meg, az alábbi táblázat szerint:

<table data-full-width="false"><thead><tr><th width="349">Egyszeri fizetés ProviderName értékei</th><th>Egykattintásos fizetés ProviderName értékei</th></tr></thead><tbody><tr><td><ul><li>KHBSZEP</li><li>MKBSZEP</li><li>OTP</li><li>RawKHBSZEP</li><li>RawMBHSZEP</li><li>RawOTPSZEP</li></ul></td><td><ul><li>RawKHBSZEP</li><li>RawMBHSZEP</li><li>RawOTPSZEP</li></ul></td></tr></tbody></table>

{% hint style="info" %}
Az egykattintásos (One-click/CIT) SZÉP Kártyás fizetések bevezetéséről a következő oldalon talál részletes technikai leírást:\
\
[SZÉP Kártyás egykattintásos (One-click/CIT) fizetések](/egykattintasos-fizetes-one-click-payment/szep-kartya)

\
A funkció elérhetőségéről az ügyfélszolgálatunk adhat további tájékoztatást.
{% endhint %}

{% hint style="info" %}
A SZÉP RAW szolgáltatók a *SZÉP Quick* szolgáltatás keretében vehetők igénybe. A *SZÉP Quick* szolgáltatás használata megrendelés és díjköteles. A szolgáltatás igénybevételével kapcsolatos bővebb információért vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.
{% endhint %}


# Fizetési folyamat

A fizetési folyamat leírását három részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított három fő lépés adja, ezek a lépések a következők:

A. **`Init`** - a tranzakció inicializálása\
B. **`Start`** - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - a tranzakció eredményének lekérése rendszerünkből

{% hint style="info" %}
A hármas felosztás ellenére a felsorolt pontok együttesen adják ki a teljes fizetési folyamatot. A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - a tranzakció inicializálása**

1. A kereskedő oldala rögzíti a vásárló elektronikus fizetési szándékát,
2. ezután a kereskedő oldala új fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén).
5. A kereskedő oldala tárolja az egyedi tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli. SZÉP Kártyák esetében ez csak azonnali lehet.)

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló megadja a SZÉP Kártya adatait a fizetési szolgáltató oldalán.
4. A fizetési szolgáltató visszairányítja a vásárlót rendszerünkbe, a fizetés befejezése után.
5. Rendszerünk lekérdezi a tranzakció eredményét a fizetési szolgáltatótól, majd beállítja a tranzakció végleges státuszát a fizetési szolgáltató válasza alapján,
6. ezután rendszerünk a tranzakció azonosítóval visszairányítja a vásárlót a kereskedő oldalára (az inicializáció (`Init`) során megadott visszatérési URL címre (`ResponseUrl`)).
7. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is.

{% hint style="info" %}
SZÉP Kártyás fizetés esetén nincs 3DS hitelesítés.
{% endhint %}

#### **C. `Result` - a tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala a `ResponseUrl` hívás hatására egy tranzakció azonosítót tartalmazó `Result` kéréssel lekérdezi a tranzakció eredményét rendszerünkből.
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a tranzakció státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a tranzakció státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}


# Tranzakció inicializálása (Init)

### Működés

Használja az inicializálás (`Init`) funkciót egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a tranzakció adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

Az inicializálás során tárolja le az `Init` kérésre visszaadott tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.\
\
\&#xNAN;*SZÉP Kártyás* fizetés esetén nincs szükség erős ügyfél-hitelesítés használatára (PSD2/SCA) a vásárló adatainak átadásához.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobilalkalmazásban**.
{% endhint %}

### **API kérés paraméterek**

SZÉP Kártyás vásárlásnál az API kérésben meg kell adni a vásárláshoz használt alszámla (*zseb*) azonosítóját is. A kérés paramétereinek jelentős része szolgáltatónként azonos, ugyanakkor az alszámla azonosító megadása minden szolgáltatónál eltérő módon történik. A könnyebb áttekinthetőség miatt, mindhárom szolgáltató (*K\&H*, *MBH* és *OTP*) esetében külön tárgyaljuk a paramétereket, az API kérésre vonatkozó általános információk után.

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>


# K\&H specifikus paraméterek

A *K\&H SZÉP Kártyás* fizetésnél az alszámla (*zseb*) adatai az `Extra` paraméterben kerülnek átadásra a `KhbCardPocketId` változó segítségével, vagy a `SzepPocket` változón keresztül.

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
  * `Extra` paraméterek
* opcionális paraméterek
  {% endhint %}

### **API kérés paraméterek**

#### Kötelező paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="144">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>KHBSZEP</li><li>RawKHBSZEP</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/zTAyqMVjv8jpa0c4nMWG">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td><p>szabadon választható</p><p>(egész szám)</p></td><td>Bruttó végösszeg amit a vásárló kifizet.</td></tr><tr><td><code>Extra</code> *</td><td>string</td><td><p><code>KhbCardPocketId</code> változó</p><p>(ezt a változót az <a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméterek értékeire vonatkozó szabályok</a> alapján kell létrehozni)</p></td><td><p>A fizetéshez használt alszámla (<em>zseb</em>) átadásának módja.<br><br>Részletekért látogassa meg a következő oldalt: <a href="/pages/WZPexCnBVK1qi3WzzdhF">K&#x26;H Extra paraméterek</a>)<br><br>* A <code>KhbCardPocketId</code> paramétert csak KHBSZEP <code>ProviderName</code> érték használata esetén kell átadni.</p><p>RawKHBSZEP <code>ProviderName</code> használata esetén a <code>SzepPocket</code> paraméter használata szükséges.</p></td></tr></tbody></table>

#### Opcionális paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="144">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Átadása nem befolyásolja a tranzakció devizanemét, mely <em>SZÉP Kártyánál</em> minden esetben HUF.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li></ul></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai (<a href="/pages/w2bB87azm3s2wK3Gnlgp">PSD2/SCA</a>).</td></tr><tr><td><code>SzepPocket</code> *</td><td>string</td><td><ul><li>foszamla (alapért.)</li><li>aktiv_magyarok</li></ul></td><td><p>A fizetéshez használt alszámla (<em>zseb</em>) azonosítója.</p><p>* A <code>SzepPocket</code> paramétert csak RawKHBSZEP <code>ProviderName</code> érték használata esetén lehet átadni.</p><p>KHBSZEP <code>ProviderName</code> használata esetén a <code>KhbCardPocketId</code> paraméter használata szükséges az <code>Extra</code> paraméteren keresztül.</p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"KHBSZEP",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "Extra":"eyJLaGJDYXJkUG9ja2V0SWQiOiIzIn0."
    }'
```

{% endcode %}

### API válasz paraméterek

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="134">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.<br></p><p>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a17f60f6a671139d5a8b7c1943307b9b",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# K\&H Extra paraméterek

#### Paraméterek

Az `Extra` paraméterben található `KhbCardPocketId` változó a következő értékeket veheti fel:

<table data-full-width="true"><thead><tr><th>Változó</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>KhbCardPocketId</code></td><td>number</td><td><ul><li>1 (főszámla)</li><li>3 (aktív magyarok alszámla, várható elfogadás banki oldalon jelenleg nem ismert)</li></ul></td><td>A fizetéshez használt alszámla (<em>zseb</em>) azonosítója.</td></tr></tbody></table>

Az `Extra` paraméterben található `KhbCardPocketId` változó értékének előkészítése:

1. Hozzon létre egy JSON kódolt string-et, melynek tartalma a `KhbCardPocketId` paraméter és a kiválasztott alszámla (*zseb*),
2. kódolja ezt a string-et Base64 használatával,
3. végezze el a karaktercserét a Base64 kódolt string-en.

<table data-full-width="true"><thead><tr><th align="center">Eredeti érték</th><th align="center">Karakter csere utáni érték</th></tr></thead><tbody><tr><td align="center">+</td><td align="center">-</td></tr><tr><td align="center">/</td><td align="center">_</td></tr><tr><td align="center">=</td><td align="center">.</td></tr></tbody></table>

#### **Példa**

<table data-full-width="true"><thead><tr><th>Lépés megnevezése</th><th>Példa az értékre</th></tr></thead><tbody><tr><td>Alszámlát (zsebet) jelző JSON kódolt string</td><td><code>{"KhbCardPocketId":"3"}</code></td></tr><tr><td>String értéke Base64 kódolás után</td><td><code>eyJLaGJDYXJkUG9ja2V0SWQiOiIzIn0=</code></td></tr><tr><td>Bas64 kódolt string a karakter csere után</td><td><code>eyJLaGJDYXJkUG9ja2V0SWQiOiIzIn0.</code></td></tr></tbody></table>


# MBH specifikus paraméterek

Az *MBH SZÉP Kártyás* fizetéshez a *Nevogate* biztosítja a fizetési felületet. Ebben az esetben a `GatewayPaymentPage` paraméter értéke jelzi, hogy a *Nevogate* fizetési felülete jelenik meg a vásárló számára.

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

### **API kérés paraméterek**

#### Kötelező paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="143">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>MKBSZEP</li><li>RawMBHSZEP</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/zTAyqMVjv8jpa0c4nMWG">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td><p>szabadon választható</p><p>(egész szám)</p></td><td>Bruttó végösszeg amit a vásárló kifizet.</td></tr><tr><td><code>GatewayPaymentPage</code></td><td>boolean</td><td><ul><li>true</li></ul></td><td>Jelzi, hogy a szolgáltató a <em>Nevogate</em> fizetési felületét használja a fizetés során.</td></tr><tr><td><code>MkbSzepCafeteriaId</code> *</td><td>number</td><td><ul><li>1111 (főszámla)</li><li>3333 (aktív magyarok alszámla)</li></ul></td><td><p>A fizetéshez használt alszámla (<em>zseb</em>) azonosítója.</p><p><br>* Az <code>MkbSzepCafeteriaId</code> paramétert csak MKBSZEP <code>ProviderName</code> érték használata esetén kell átadni.</p><p>RawMBHSZEP <code>ProviderName</code> használata esetén a <code>SzepPocket</code> paraméter használata szükséges.</p></td></tr></tbody></table>

#### Opcionális paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="145">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Átadása nem befolyásolja a tranzakció devizanemét, mely <em>SZÉP Kártyánál</em> minden esetben HUF.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li></ul></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai (<a href="/pages/w2bB87azm3s2wK3Gnlgp">PSD2/SCA</a>).</td></tr><tr><td><code>SzepPocket</code> *</td><td>string</td><td><ul><li>foszamla (alapért.)</li><li>aktiv_magyarok</li></ul></td><td><p>A fizetéshez használt alszámla (<em>zseb</em>) azonosítója.</p><p><br>* A <code>SzepPocket</code> paramétert csak RawMBHSZEP <code>ProviderName</code> érték használata esetén lehet átadni.</p><p>MKBSZEP <code>ProviderName</code> használata esetén az <code>MkbSzepCafeteriaId</code> paraméter használata szükséges.</p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"MKBSZEP",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "MkbSzepCafeteriaId":"3333",
        "GatewayPaymentPage":true
    }'
```

{% endcode %}

### API válasz paraméterek

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="123">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.</p><p>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "58dd6e396fd915838fa3fdf73a2edbdc",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# OTP specifikus paraméterek

Az *OTP Bank* esetében a hagyományos *SZÉP Kártyán* kívül úgynevezett *cafeteria* kártya is elérhető. A *cafeteria*, a *SZÉP Kártyához* képest más típusú alszámlákat (*zsebeket*) tartalmaz, ugyanakkor az alszámla azonosítók átadása a *SZÉP Kártyás* fizetéssel azonos módon történik.

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

### **API kérés paraméterek**

#### Kötelező paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="141">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code> *</td><td>string</td><td><ul><li>OTP</li><li>RawOTPSZEP</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.<br><br>* RawOTPSZEP használatánál a szolgáltató elvárja a vásárló email címének átadását az általános vásárlói adatok objektumban (ebben az esetben az <code>Info</code> paraméter átadása kötelező).</td></tr><tr><td><code>OtpCardPocketId</code> *</td><td>string</td><td><p>Cafeteria kártya esetén:</p><ul><li>01 (étel utalvány)</li><li>02 (meleg étkezési utalvány)</li><li>03 (iskolakezdési utalvány)</li><li>04 (kultúra utalvány)</li><li>05 (ajándék utalvány)</li><li>06 (sport utalvány)</li></ul><p>SZÉP Kártya esetén:</p><ul><li>09 (főszámla)</li><li>08 (aktív magyarok alszámla)</li></ul></td><td><p>A fizetéshez használt alszámla (<em>zseb</em>) azonosítója.<br><br>* Az <code>OtpCardPocketId</code> paramétert csak OTP <code>ProviderName</code> érték használata esetén kell átadni.</p><p>RawOTPSZEP <code>ProviderName</code> használata esetén a <code>SzepPocket</code> paraméter használata szükséges.<br><br>RawOTPSZEP <code>ProviderName</code> érték használatával csak SZÉP Kártya terhelhető.</p></td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/zTAyqMVjv8jpa0c4nMWG">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td><p>szabadon választható</p><p>(egész szám)</p></td><td>Bruttó végösszeg amit a vásárló kifizet.</td></tr></tbody></table>

#### Opcionális paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="142">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Átadása nem befolyásolja a tranzakció devizanemét, mely SZÉP Kártyánál minden esetben HUF.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li></ul></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Info</code> *</td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai (<a href="/pages/w2bB87azm3s2wK3Gnlgp">PSD2/SCA</a>).<br><br>* RawOTPSZEP használatánál a szolgáltató elvárja a vásárló email címének átadását az általános vásárlói adatok objektumban (ebben az esetben az <code>Info</code> paraméter átadása kötelező).</td></tr><tr><td><code>SzepPocket</code> *</td><td>string</td><td><ul><li>foszamla (alapért.)</li><li>aktiv_magyarok</li></ul></td><td><p>A fizetéshez használt alszámla (zseb) azonosítója.</p><p>* A <code>SzepPocket</code> paramétert csak RawOTPSZEP <code>ProviderName</code> érték használata esetén lehet átadni.<br>OTP <code>ProviderName</code> használata esetén az <code>OtpCardPocketId</code> paraméter használata szükséges.</p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"OTP",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "OtpCardPocketId":"08"
    }'
```

{% endcode %}

### API válasz paraméterek

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="121">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.</p><p>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "3df9aa96b538f2ee2916d8441e5302ca",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Visszairányítási módok

### Működés

Használja a `redirectMode` paramétert, hogy fizetés után visszairányítsa a vásárlót a webáruházba a fizetési szolgáltató oldaláról.

A `redirectMode` paraméter értékét (és a visszairányítás módját) az inicializálás során (`Init`) adhatja meg, az `Extra` paraméteren belül.

{% hint style="info" %}
Amennyiben nem adja át a `redirectMode` értékét az `Extra` paraméterben, alapértelmezetten a 0 értékhez tartozó HTTP átirányítás lép működésbe.
{% endhint %}

A `redirectMode` segítségével a következő visszairányítási módok érhetők el:

<table data-full-width="true"><thead><tr><th width="90">Érték</th><th width="216">Eljárás</th><th>Leírás</th></tr></thead><tbody><tr><td>0</td><td>HTTP redirect</td><td>A vásárló HTTP 302-es átirányítással kerül vissza az inicializáció (<code>Init</code>) során megadott válasz URL címre (<code>ResponseUrl</code>).</td></tr><tr><td>1</td><td>top.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: top window.</td></tr><tr><td>2</td><td>parent.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: parent window.</td></tr><tr><td>3</td><td>top.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: top window.</p><p>(Nincs átirányítás!)</p></td></tr><tr><td>4</td><td>parent.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: parent window.<br></p><p>(Nincs átirányítás!)</p></td></tr></tbody></table>

A javascript alapú üzenetek tartalma a következő formátumú JSON string (a 3-as és 4-es `redirectMode` értékeknél):

{PMGWTransactionData: {TransactionId: “”, OrderId: “”, UserId: “”}}

**Window\.postMessage()** használata esetén a paraméterek a következő értékekkel rendelkeznek:

<table data-full-width="true"><thead><tr><th width="306">Paraméter</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>A tranzakció egyedi Nevogate azonosítója, melyet az <code>Init</code> hívás válaszában ad vissza rendszerünk.</td></tr><tr><td><code>OrderId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr><tr><td><code>UserId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr></tbody></table>


# Tranzakció indítása (Start)

### Műkődés

Tranzakció indításához irányítsa át a vásárlót rendszerünkbe az inicializáció (`Init`) során visszakapott tranzakció azonosítóval (`TransactionId`). Rendszerünk felépíti a kommunikációt a fizetési szolgáltatóval és tovább irányítja a vásárlót a fizetési felületre.

Tranzakció indításához **teszt környezetben** használja a következő címet:

<https://system-test.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]

Tranzakció indításához **éles környezetben** használja a következő címet:

<https://system.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]


# URL Értesítés

### Működés

Használja a `NotificationUrl` paramétert, hogy automatikusan értesüljön a tranzakciók státuszának változásáról. Az inicializáció (`Init`) során adja át az értesítési URL címet a `NotificationUrl` paraméterben. Rendszerünk ezt a címet hívja meg a tranzakció státuszának megváltozásakor.

Rendszerünk legfeljebb 5 alkalommal kísérli meg a megadott értesítési URL hívását, amíg a hívásra HTTP 200 választ nem kap. Az értesítés a tranzakció részletes adatait tartalmazza JSON formátumban (a `Details` hívás eredményének megfelelően), amit `application/json` típusként küldünk, így az adat a *raw request body*-ból nyerhető ki.

Jelezze vissza rendszerünk számára, hogy a kereskedő oldala értesült a tranzakció eredményéről. Ehhez indítson egy `Result` kérést minden rendszerünktől visszaérkező `NotificationUrl` hívás után. `Result` kérés hiányában a tranzakció “megválaszolhatatlan” állapotot kap a *PayAdmin* felületén.

Az alapértelmezett (lineáris időközönként maximum 5 alkalommal történő) URL értesítési eljárás mellett elérhető egy kiterjesztett URL értesítési eljárás is.

Ebben az esetben az értesítési kísérletek fokozatosan elnyújtott időközönként történnek az alábbi logika szerint:

* Azonnal a végstátusz beállítását követően.
* 5 másodperc elteltével.
* 10 másodperc elteltével.
* 30 másodperc elteltével.
* 1 perc elteltével.
* 5 perc elteltével.
* 15 perc elteltével.
* 30 perc elteltével.
* 1 óra elteltével.
* 3 óra elteltével.
* 6 óra elteltével.
* 12 óra elteltével.
* 1 nap elteltével.

A kiterjesztett URL értesítés igénybevételéhez vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.

{% hint style="warning" %}
A `NotificationUrl` átadása minden tranzakció inicializáció során kötelező.\
Továbbá figyeljen arra, hogy a megadott értesítési URL cím (`NotificationUrl`):

* rendelkezzen HTTPS protokollal
* legyen mindenkor publikusan elérhető
  {% endhint %}

{% hint style="danger" %}
A JSON formátumú értesítésben található paraméterek kis kezdőbetűkkel szerepelnek. Ezzel ellentétben a tranzakció részletes adatainak lekérdezésére (`Details` hívásra) adott válasz paraméterei nagy kezdőbetűvel rendelkeznek.
{% endhint %}

### Beállítás lépései

Végezze el a következő lépéseket az URL értesítés megfelelő működéséhez.

{% hint style="warning" %}
A leírt folyamatot minden egyes `NotificationUrl` híváskor végre kell hajtani.
{% endhint %}

1. Adjon meg egy értesítési URL címet a `NotificationUrl` paraméter segítségével.
2. Vizsgálja meg, hogy a *raw request body* tartalmaz JSON típusú adattartalmat (a rendszerünkből érkező `NotificationUrl` hívás során).
3. Nyerje ki az aktuális `TransactionId` értéket a *raw request body*-ból.
4. Indítson egy `Result` kérést melyben megadja a `NotificationUrl` törzséből kinyert `TransactionId` értéket.
5. Dolgozza fel a `Result` kérésre kapott választ, majd
6. mentse el a rendszerében a tranzakció végstátuszát (`ResultCode`).
7. Válaszoljon HTTP 200-as státusz kóddal a rendszerünkből érkező `NotificationUrl` hívásra.

{% hint style="info" %}
PHP használata esetén így nyerheti ki a `TransactionId` értékét:

```php
$json = file_get_contents('php://input');
$data = json_decode($json);
$transactionId = $data->commonData->transactionId;
```

{% endhint %}

### Példa (URL értesítés beállítására teszt környezetben)

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "NotificationUrl":"https://merchant.notification.url"
    }'
```

{% endcode %}


# Tranzakció eredményének lekérdezése (Result)

### Működés

Használja a `Result` hívást a tranzakció eredményének lekérdezéséhez. A fizetés után rendszerünk visszairányítja a vásárlót az áruházba, úgy, hogy meghívja azt a `ResponseUrl`-t, amit az inicializáció (`Init`) során adott meg a kereskedő oldala. Miután rendszerünk meghívja a `ResponseUrl`-t, a kereskedő oldala elindíthatja a `Result` hívást.

`Result` hívás indításához szüksége lesz az adott tranzakció azonosítójára. Ezért a rendszerünkből érkező `ResponseUrl` hívás kiegészül a `TransactionId` GET paraméterrel, amely az adott tranzakció azonosítót biztosítja.

Fontos, hogy minden rendszerünkből érkező `ResponseUrl` hívás után indítson egy `Result` hívást, a vásárlói munkamenettől függetlenül. Ennek oka, hogy előfordulhat, hogy a `ResponseUrl` hívásra később, aszinkron módon, a háttérben kerül sor.

Rendszerünk aszinkron módon elindítja a `NotificationUrl` hívást, abban az esetben, ha beállt az adott tranzakció végstátusza. A `NotificationUrl` az inicializáció (`Init`) során kötelezően átadandó URL cím. Itt is fontos, hogy minden rendszerünkből érkező `NotificationUrl` hívás után indítson egy `Result` hívást.

Rendszerünk a `Result` hívás hatására értesül arról, hogy a kereskedő oldala megkapta a tranzakció eredményét. Ezért amennyiben a `Result` hívásra nem kerül sor, a tranzakció rendszerünkben a "megválaszolhatatlan" állapotot veszi fel.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=result)

{% hint style="info" %}
További részletekért a `NotificationUrl` használatáról látogassa meg a következő hivatkozást: [URL Értesítés](/egyszeri-fizetesek-one-time-payment/szep-kartya/url-ertesites)

A tranzakció állapotairól a rendszerünkben pedig a következő oldalon olvashat további információkat: [Tranzakció Állapotok](/segedlet/tranzakcio-allapotok)
{% endhint %}

{% hint style="warning" %}
Figyeljen arra, hogy `Result` kérést kizárólag `ResponseUrl` vagy `NotificationUrl` hívások hatására indítson. A kereskedő rendszeréből indokolatlanul, vagy ütemezett módon `Result` kérést indítani tilos!
{% endhint %}

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Result</code></td><td><code>POST</code></td><td>method=<code>Result</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Result` kérés egy (kötelező) paraméterrel rendelkezik

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="132">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció eredményének lekérése `Result` használatával

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Result | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Result' \
  --data 'json=
    {
        "TransactionId":"992c8e75435e6d4dfdf6415f0714cae8"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Result` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="350">Paraméter</th><th width="133">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>egyedi értékek</td><td>Rendszerünkben tárolt egyedi boltazonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A tranzakció státusza lehet:</p><ul><li>PENDING</li><li>SUCCESSFUL</li><li>ERROR</li><li>CANCELED</li><li>TIMEOUT</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul></td><td>Jelzi a tranzakció eredményét.<br><br>A tranzakció státuszokról a következő oldalon olvashat további információkat: <a href="/pages/yzo9U4RLeMGLusg6Mrfl">Tranzakció státuszok</a></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>Anum</code></td><td>string</td><td>egyedi értékek</td><td><p>A tranzakció engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Csak bizonyos szolgáltatók esetén.)</p></td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td><p>A tranzakció bruttó végösszege.<br></p><p>(Az összeg amit a vásárló kifizetett.)</p></td></tr><tr><td><code>Currency</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>HUF</li></ul></td><td>A tranzakció devizaneme.</td></tr><tr><td><code>OrderId</code></td><td>string</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>OrderId</code>.)</p></td></tr><tr><td><code>UserId</code></td><td>string</td><td><p>egyedi értékek</p><p>(kivéve e-mail címek, illetve személyes adatok)</p></td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>UserId</code>.)</p></td></tr><tr><td><code>Language</code></td><td><p>string</p><p><br>(2 karakter)</p></td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li></ul></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>ProviderTransactionId</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“true”</li></ul></td><td><p>Jelzi, hogy a bank azonnal hajtja végre a tranzakciót.<br></p><p>(Az inicializáció során beállított <code>AutoCommit</code> értéke.)</p></td></tr><tr><td><code>CommitState</code></td><td>string</td><td><ul><li>APPROVED</li></ul></td><td>• APPROVED: a végleges összeg beterhelése megtörtént</td></tr><tr><td><code>PaywallPaymentName</code></td><td>string<br><br>(36 karakter)</td><td><ul><li>null</li><li>UUID</li></ul></td><td>A tranzakció <em>PayWall</em> azonosítója (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaywallRecurringPaymentEnabled</code></td><td>string</td><td><ul><li>"true"</li><li>"false"</li></ul></td><td>Jelzi a vásárló hozzájárulását, hogy a kereskedő a jövőben az adott tranzakcióra hivatkozva újabb, ismétlődő tranzakciókat indíthasson (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaymentRegistrationType</code></td><td>string</td><td><ul><li>null</li></ul></td><td>Jelzi a fizetési regisztráció típusát.</td></tr><tr><td><code>SzepPocket</code></td><td>string</td><td><ul><li>null</li><li>foszamla</li><li>aktiv_magyarok</li></ul></td><td>A tranzakció inicializálása (<code>Init</code>) során megadott zsebazonosító (SZÉP Kártyás fizetés esetén).</td></tr><tr><td><code>ProviderResultCode</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>KHBSZEP</li><li>MKBSZEP</li><li>OTP (responsecode)</li><li>RawKHBSZEP (resultCode)</li><li>RawMBHSZEP (valaszKod)</li><li>RawOTPSZEP (status)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó elsődleges eredmény- vagy hibakód.</td></tr><tr><td><code>ProviderResultCode2</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>KHBSZEP</li><li>RawOTPSZEP (result / resultCode / errorCodes)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó másodlagos eredmény- vagy hibakód.</td></tr><tr><td><code>PaymentLinkName</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A fizetési hivatkozás azonosítója a <em>Nevogate</em> rendszerében (amennyiben a tranzakció <em>PayLink</em> segítségével jött létre).</td></tr><tr><td><code>Created</code></td><td>string</td><td>dátum</td><td>A tranzakció létrehozásának ideje.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Result` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "StoreName": "sdk_test",
    "ProviderName": "MKBSZEP",
    "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": "Sikeres tranzakció",
    "Anum": "006761",
    "Amount": "100",
    "Currency": "HUF",
    "OrderId": "TEST-ORDER-ID",
    "UserId": "TEST-USER-ID",
    "Language": "HU",
    "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
    "AutoCommit": "true",
    "CommitState": "APPROVED",
    "PaywallPaymentName": null,
    "PaywallRecurringPaymentEnabled": "false",
    "PaymentRegistrationType": null,
    "SzepPocket": "foszamla",
    "ProviderResultCode": "000",
    "ProviderResultCode2": null,
    "PaymentLinkName": null,
    "Created": "2020-03-14 11:19:07",
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Tranzakció részletes adatainak lekérdezése (Details)

### Működés

Használja a `Details` hívást a tranzakció részletes adatainak lekérdezéséhez. Míg a `Result` hívásra adott válasz csupán a tranzakció alapadatait hordozza, a `Details` hívás további részletes információkat is tartalmaz az adott tranzakcióról (pl. szolgáltató specifikus adatokat).

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=details)

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Details</code></td><td><code>POST</code></td><td>method=<code>Details</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Details` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` átadása kötelező**)

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="124">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>GetRelatedTransactions</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td>Olyan korábbi tranzakciók részletes adatainak lekérése, melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>GetInfoData</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td><p>Kérés a vásárlásra vonatkozó Info adatok visszaadására.<br></p><p>(<code>Init</code>, <code>InitRP</code> vagy <code>PaymentLinkCreate</code> hívások során átadott vásárlási adatok esetén.)</p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció részletes adatainak lekérése `Details` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Details | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Details' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "GetRelatedTransactions":false,
        "GetInfoData":false
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Details` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="250">Paraméter</th><th width="128">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>CommonData</code></td><td>JSON object</td><td>egyedi értékek</td><td><p>A tranzakció alapadatai.<br></p><p>(A <code>Result</code> hívás során is visszaadott adatok.)</p></td></tr><tr><td><code>ProviderSpecificData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Szolgáltató specifikus kiegészítő adatok.</td></tr><tr><td><code>RelatedTransactions</code></td><td>JSON object</td><td>egyedi értékek</td><td>Olyan korábbi tranzakciók adatai melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>InfoData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Az <code>Info</code> objektum adatai.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Details` kérésre adott válasz (formázást követően):

{% code overflow="wrap" %}

```php
{
    "CommonData":
    {
        "StoreName": "sdk_test",
        "ProviderName": "MKBSZEP",
        "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
        "ResultCode": "SUCCESSFUL",
        "ResultMessage": "Sikeres tranzakció",
        "Anum": "006761",
        "Amount": "100",
        "Currency": "HUF",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "Language": "HU",
        "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
        "AutoCommit": "true",
        "CommitState": "APPROVED",
        "PaywallPaymentName": null,
        "PaywallRecurringPaymentEnabled": "false",
        "PaymentRegistrationType": null,
        "SzepPocket": "foszamla",
        "ProviderResultCode": "000",
        "ProviderResultCode2": null,
        "PaymentLinkName": null,
        "Created": "2020-03-14 11:19:07",
        "ResponseId": "3202109280600047703"
    },
    "ProviderSpecificData":
    {
        ...
        "Amount": "100",
        "Currency": "HUF",
        "Language": "HU",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "ResponseUrl": "https://demo.nevogate.com/response.php",
        "NotificationUrl": null,
        "MaxNotificationSendAttempts": 0,
        "NotificationSendAttempts": 0,
        "NotificationSendSuccess": 0,
        "Extra": null,
        "AutoCommit" : "0",
        "CommitState": "1",
        "HasRefund": "0",
        "Created": "2017-11-17 13:12:36",
        "LastModified": "2017-11-17 13:14:07",
        "InvoiceDate": null,
        "GatewayPaymentPage": null,
        "ModuleName": null,
        "ModuleVersion": null,
        "StoreProviderId": "3103",
        "Error": null,
        "ResultMessage": null
    },
    "RelatedTransactions": null,
    "InfoData": null,
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ProviderName": "MKBSZEP",
    "ResponseId": "3202109280600047706"
}
```

{% endcode %}


# Tranzakció összegének visszatérítése (SZÉP Refund)

## SZÉP Kártya visszatérítések esetei

A *SZÉP Kártyás* fizetések visszatérítésének esete speciális terület, melyre a fizetési szolgáltatók nem biztosítanak egységes API szintű megoldást. A jelenlegi gyakorlat szerint a visszatérítéseket a kereskedő e-mailben kérheti az adott *SZÉP Kártya* szolgáltatótól, ami nehézkes és körülményes ügyintézést jelent.

A fentiek alól kivételt képez a K\&H SZÉP Kártya (Raw) típusú fizetési módja ami natív API kapcsolaton keresztül képes fogadni a visszatérítési igényeket, és az *MBH SZÉP* sztornó megoldása, amely API szintű visszatérítést is lehetővé tesz az e-mail kérések beküldésétől függetlenül. Ugyanakkor az *MBH SZÉP* sztornó kizárólag a tranzakció napján vehető igénybe a teljes összeg visszatérítésére. Ennek oka, hogy a tranzakció napján az *MBH SZÉP Kártyás* fizetés még nem kerül be az elszámolási körbe, így szinte azonnal visszatéríthető a vásárló számára. Napon túli tranzakciókra és részösszeg visszatérítésére viszont már nem használható a sztornó, ilyen esetben továbbra is emailben kell megkeresni az *MBH SZÉP Kártya* szolgáltatóját.

## SZÉP Refund áthidaló megoldása

Mivel a *SZÉP Kártyás* fizetések visszatérítése fragmentált, ezért a *Nevogate* kidolgozott egy *SZÉP Refund* nevű API szintű áthidaló megoldást, hogy megkönnyítse ezek kezelését a kereskedők számára. A *SZÉP Refund* áthidaló megoldása kiegészítő szolgáltatásként vehető igénybe és két elemre bontható:

1. visszatérítési igény **beküldése** (a bankkártyás fizetésnél is használt `Refund` funkcióval)
2. visszatérítési igény **lekérdezése** (az erre létrehozott `SettlementRefund` funkcióval)

{% hint style="info" %}
A *SZÉP Refund* kizárólag *SZÉP Kártyás* visszatérítések kezelésére vehető igénybe.
{% endhint %}

{% hint style="info" %}
A *SZÉP Refund* szolgáltatás használata megrendelés és díjköteles. A szolgáltatás igénybevételével kapcsolatos bővebb információért vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.
{% endhint %}

## SZÉP Kártya visszatérítések összefoglalója

A kereskedő jelenleg három különböző módon intézheti a *SZÉP Kártyás* fizetések visszatérítését:

* e-mailben (mindegyik *SZÉP Kártya* szolgáltató esetében)
* K\&H SZÉP Kártya (Raw) fizetési mód esetén API-n keresztül
* *MBH SZÉP* sztornó segítségével (kizárólag *MBH SZÉP Kártya* esetén, korlátozott funkcionalitással)
* *SZÉP Refund* kiegészítő szolgáltatásunkkal, amely a `Refund` és `SettlementRefund` API hívás párossal váltja ki az email alapú ügyintézést (mindegyik SZÉP Kártya szolgáltató esetében használható, korlátozások nélkül)


# Visszatérítési igény beküldése (Refund)

A *SZÉP Refund* kiegészítő szolgáltatással *SZÉP Kártyás* tranzakciók esetén is beküldhető egy visszatérítési kérés (`Refund`) API hívás segítségével a rendszerünk felé. A *SZÉP Kártyás* visszatérítési kérésekről a beküldés másnapján egy csv állományt generálunk, mely tartalmazza a visszatérítés végrehajtásához szükséges információkat a fizetési szolgáltatók számára. Ezeket az állományokat naponta továbbítjuk a fizetési szolgáltatók felé email vagy SFTP segítségével. Igény esetén ezeket a csv állományokat a kereskedő számára is továbbítjuk e-mailben (befogadási e-mail cím megadását követően).

{% hint style="warning" %}
A visszatérítési igények sikeres beküldését követően a teljesítés minden esetben az adott fizetési szolgáltató hatáskörébe tartozik és akár több napot, vagy több hetet is igénybe vehet.
{% endhint %}

### Működés

Használja a `Refund` hívást egy sikeres tranzakció összegének teljes vagy részleges visszatérítésére.

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=refund)

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Refund</code></td><td><code>POST</code></td><td>method=<code>Refund</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Refund` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` és `Amount` átadása kötelező**):

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="111">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td>Visszatérítésre kerülő összeg az eredeti tranzakció pénznemében.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Egyéb illetve szolgáltató specifikus adatok.</p><p>(További részletekről az <a href="/pages/XaOHnljbNm5MGxPqLjdh">Extra adatok</a> pontban olvashat.)<br></p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció összegének részleges vagy teljes visszatérítése `Refund` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Refund | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Refund' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "Amount":100
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Refund` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="277">Paraméter</th><th width="132">Típus</th><th width="284">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A visszatérítés beküldésének eredménye a következők egyike lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi a visszatérítés beküldésének eredményét:</p><ul><li>SUCCESSFUL: a visszatérítés beküldése sikeres</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>RefundRequestId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés kérésének azonosítója a fizetési szolgáltató rendszerében.</p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundTransactionId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés azonosítója a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundAuthorizationCode</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundId</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A visszatérítés egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Refund` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "RefundRequestId": null,
    "RefundTransactionId": null,
    "RefundAuthorizationCode": null
    "RefundId": "rf_b0fd9b0381bb54568870a6c22d6a086f",
    "ResultMessage": null,
    "ResponseId": "3202109280600047707"
}
```

{% endcode %}


# MBH SZÉP Kártya sztornó

A sztornó funkció a tranzakciók összegének azonnali visszatérítésére szolgál *MBH SZÉP Kártya* esetén. Használata előtt vegye figyelembe a következőket:

* kizárólag a tranzakció **teljes összegére** kérhető (nincs részösszeg visszatérítés)
* kizárólag a tranzakció **létrejöttének napján** kérhető

Az *MBH SZÉP Kártya* sztornó funkcióhoz tartozó `Extra` paramétert a `Refund` kérésben adhatja át. Ez a sztornó funkció a következő szolgáltató specifikus `Extra` paraméterrel rendelkezik:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>storno</code></td><td>boolean</td><td><p>• true</p><p>• false</p></td><td><p></p><p>Tranzakció azonnali visszatérítéshez használt paraméter.</p></td></tr></tbody></table>

#### Mintakód

{% code overflow="wrap" %}

```php
{
    "storno":true
}
```

{% endcode %}

{% hint style="info" %}
Az *MBH SZÉP Kártya* sztornó funkciója a `Szép Refund` kiegészítő szolgáltatástól függetlenül, önállóan is használható díjmentesen.
{% endhint %}


# Visszatérítési igény lekérdezése (SettlementRefund)

Használja a `SettlementRefund` kérést a korábban leadott *SZÉP Kártya* visszatérítések adatainak lekérdezésére (abban az esetben, ha a *SZÉP Kártya* visszatérítéseket a *SZÉP Refund* kiegészítő szolgáltatás segítségével indította). A *SZÉP Kártyás* visszatérítési kérésekről a beküldés másnapján egy csv állományt generálunk, mely tartalmazza a visszatérítés végrehajtásához szükséges információkat a fizetési szolgáltatók számára. Ezeket az állományokat naponta továbbítjuk a fizetési szolgáltatók felé email vagy SFTP segítségével. Igény esetén ezeket a csv állományokat a kereskedő számára is továbbítjuk e-mailben (befogadási e-mail cím megadását követően).

Elkészítettünk egy minta csv kimutatást is, melyet a következő hivatkozáson tölthet le:

[*SZÉP Refund* csv minta](https://www.nevogate.com/static/downloads/refund_111111_20201126_72ab2a61.csv)

{% hint style="info" %}
A kiegészítő szolgáltatásokat, így a *SZÉP Refund* használatát is külön kell kérelmezni ügyfélszolgálatunkon, amit a következő email címen tehet meg:\
\
<business@nevogate.com>\
\
A fizetési szolgáltatók által ténylegesen teljesített visszatérítési tranzakciók eredményét és a pénzügyi elszámolási adatokat a *PayBook* kiegészítő szolgáltatásunk segítségével kérdezheti le a *PayAdmin* felületén manuálisan, vagy API kérés segítségével automatizálva.

További részletekért a funkció használatáról látogassa meg a következő oldalt:

[Könyvelés támogatás és tranzakciók pénzügyi elszámolása (*PayBook*)](/kiegeszito-szolgaltatasok/koenyveles-tamogatas-es-tranzakciok-penzuegyi-elszamolasa-paybook)
{% endhint %}

### Működés

Használja a `SettlementRefund` funkciót a korábban leadott *SZÉP Kártya* visszatérítési igények lekérdezéséhez. A lekérdezés a következő adatokat adhatja vissza:

* visszatérítési **elszámolásnaphoz** tartozó tranzakciók
* visszatérítési **azonosítóhoz** tartozó tranzakciók

### API kérés paraméterek

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>SettlementRefund</code></td><td><code>POST</code></td><td><p>method=<code>SettlementRefund</code></p><p>json={JSON encode-olt paraméterek}</p></td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="112">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Meghatározza a lekérdezett visszatérítéshez tartozó fizetési szolgáltatót.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>KHBSZEP</li><li>MKBSZEP</li><li>OTP</li><li>RawMBHSZEP</li><li>RawOTPSZEP</li></ul></td><td>A visszatérítési elszámolás lekérdezéséhez kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TerminalId</code></td><td>string</td><td>egyedi értékek</td><td>A kereskedő virtuális termináljának (VPOS) egyedi azonosítója.</td></tr><tr><td><code>Limit</code></td><td>number</td><td>maximum 1000 tétel</td><td><p>Az adott lekérdezés során visszaadott tételek maximális száma.</p><p>(Opcionálisan használja az <code>Offset</code> paramétert további tételek lekérdezéséhez, amennyiben az aktuális lekérdezéshez több tétel tartozik, mint a <code>Limit</code> paraméterben megadott érték.)</p></td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="114">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>RefundSettlementDate</code></td><td>string</td><td><p>dátum, a következő formátumban:<br></p><p>ÉÉÉÉ-HH-NN</p></td><td><p>A visszatérítési elszámolás létrehozásának ideje.</p><p>Megadása <strong>kötelező, amennyiben</strong> a <code>RefundSettlementId</code> paraméter nem kerül átadásra.</p></td></tr><tr><td><code>RefundSettlementId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítési elszámolás kérésének azonosítója.</p><p>Megadása <strong>kötelező, amennyiben</strong> a <code>RefundSettlementDate</code> paraméter nem kerül átadásra.</p></td></tr><tr><td><code>GetBatches</code></td><td>boolean</td><td><ul><li>true (alapért.)</li><li>false</li></ul></td><td>Meghatározza, hogy a lekérdezett válasz tartalmazzon vagy ne tartalmazzon köteg adatokat.</td></tr><tr><td><code>GetItems</code></td><td>boolean</td><td><ul><li>true (alapért.)</li><li>false</li></ul></td><td>Meghatározza, hogy a lekérdezett válasz tartalmazzon vagy ne tartalmazzon tétel adatokat.</td></tr><tr><td><code>Offset</code></td><td>number</td><td>egyedi értékek</td><td><p>Jelzi a lekérdezett tételek számához tartozó eltolást.</p><p>Abban az esetben, amikor egy kötegben a tételek száma (<code>NumberOfItems</code>) meghaladja a lekérdezésben beállított limitet (<code>Limit</code>), használja az eltolást a limitet meghaladó további tételek lekérdezéséhez.</p></td></tr></tbody></table>

#### **Mintakód**

Visszatérítési elszámolás lekérdezése `SettlementRefund` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'SettlementRefund | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=SettlementRefund' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"MKBSZEP",
        "TerminalId":"111111",
        "RefundSettlementDate":"2020-11-26",
        "Limit":1000
    }'
```

{% endcode %}

### API válasz paraméterek

A `SettlementRefund` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="256">Paraméter</th><th width="124">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Data</code></td><td>JSON string</td><td>egyedi értékek</td><td>Sikeres lekérdezés esetén tartalmazza a <a href="/pages/POIhmiY50hLZewVuwjMN">köteg (Batches) és tétel (Items) adatok</a>at.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><ul><li>SUCCESSFUL (a pénzügyi visszatérítési elszámolás lekérdezése sikeres volt)</li></ul><p><br>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>FunctionNotImplemented</li><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li></ul></td><td>Jelzi a visszatérítési elszámolás lekérdezésének eredményét.</td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `SettlementRefund` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "Data":"
    {
        \"Batches\":[
            {
                \"RefundSettlementId\":\"72ab2a61\",
                \"RefundSettlementDate\":\"2020-11-26\",
                \"RefundSettlementFileName\":\"refund_111111_20201126_72ab2a61.csv\",
                \"TransferNotice\":\"refund 2020-11-26 111111 72ab2a61\",
                \"ProviderName\":\"MKBSZEP\",
                \"ProviderAccountNumber\":\"10300002-13000203-00894901\",
                \"TerminalId\":\"111111\",
                \"NumberOfItems\":2,
                \"TotalRefundRequestAmount\":5500
            }
        ],
        \"Items\":[
            {
                \"RefundSettlementId\":\"72ab2a61\",
                \"OriginalTransactionId\":\"41a441422609b5bcd66bd0971386e76f\",
                \"OriginalProviderTransactionId\":\"49239229\",
                \"OriginalTransactionAnum\":\"566129\",
                \"OriginalTransactionAmount\":\"3000\",
                \"OriginalTransactionCreatedTime\":\"2020-11-26 10:34:59\",
                \"RefundRequestId\":\"49239229\",
                \"RefundTransactionId\":\"26a738c456df39af5d0685ec3844bfdc\",
                \"RefundRequestAmount\":\"3000\",
                \"RefundRequestTime\":\"2020-11-26 10:36:07\"
            },
            {
                \"RefundSettlementId\":\"72ab2a61\",
                \"OriginalTransactionId\":\"f88796bb3aebba12d816f878fc08f0aa\",
                \"OriginalProviderTransactionId\":\"49239230\",
                \"OriginalTransactionAnum\":\"559655\",
                \"OriginalTransactionAmount\":\"5000\",
                \"OriginalTransactionCreatedTime\":\"2020-11-26 10:35:36\",
                \"RefundRequestId\":\"49239230\",
                \"RefundTransactionId\":\"61e34cb499d96450718b14a083140d40\",
                \"RefundRequestAmount\":\"2500\",
                \"RefundRequestTime\":\"2020-11-26 10:36:23\"
            }
        ]
    }",
    "ResultCode": "SUCCESSFUL",
    "RefundId": "rf_b0fd9b0381bb54568870a6c22d6a086f",
    "ResultMessage": null,
    "ResponseId": "3202109280600047731"
}
```

{% endcode %}


# Köteg (Batches) és tétel (Items) adatok visszatérítéseknél

Sikeres lekérdezés esetén a köteg adatok (`Batches`) és az azokhoz tartozó tételek (`Items`) egyaránt a `Data` változóban kerülnek visszaadásra.

#### **Köteg (`Batches`) elemei**

A kérésre visszaadott `Batches` a következő elemeket tartalmazhatja:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="135">Típus</th><th>Leírás</th></tr></thead><tbody><tr><td><code>RefundSettlementId</code></td><td><p>string<br></p><p>(12 karakter)</p></td><td>Köteg azonosítója.</td></tr><tr><td><code>RefundSettlementDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>Visszatérítési elszámolás létrehozásának dátuma.</td></tr><tr><td><code>RefundSettlementFileName</code></td><td><p>string</p><p>(64 karakter)</p></td><td>A létrehozott visszatérítési elszámolás (csv) fájlneve.</td></tr><tr><td><code>TransferNotice</code></td><td><p>string</p><p>(95 karakter)</p></td><td>A visszatérítés összegének utalásához szükséges banki közlemény.</td></tr><tr><td><code>ProviderName</code></td><td><p>string</p><p>(20 karakter)</p></td><td>Fizetési szolgáltató azonosítója.</td></tr><tr><td><code>ProviderAccountNumber</code></td><td><p>string</p><p>(26 karakter)</p></td><td>A fizetési szolgáltató számlaszáma, amire a kereskedő a visszatérítést utalja.</td></tr><tr><td><code>TerminalId</code></td><td><p>string</p><p>(64 karakter)</p></td><td>Terminál azonosító.</td></tr><tr><td><code>NumberOfItems</code></td><td><p>number</p><p>(10 karatker)</p></td><td>Tételek száma a kötegben.</td></tr><tr><td><code>TotalRefundRequestAmount</code></td><td><p>number</p><p>(24 karakter)</p></td><td>Az összes visszatérítés kérés szumma összege.</td></tr></tbody></table>

#### **Tétel (`Items`) elemei**

A kérésre visszaadott Items a következő elemeket tartalmazhatja:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="141">Típus</th><th>Leírás</th></tr></thead><tbody><tr><td><code>RefundSettlementId</code></td><td><p>string</p><p>(12 karakter)</p></td><td>Köteg azonosító.</td></tr><tr><td><code>OriginalTransactionId</code></td><td><p>string</p><p>(32 karakter)</p></td><td>Az eredeti tranzakció <em>Nevogate</em> azonosítója.</td></tr><tr><td><code>OriginalProviderTransactionId</code></td><td><p>string</p><p>(64 karakter)</p></td><td>Az eredeti tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>OriginalTransactionAnum</code></td><td><p>string</p><p>(16 karakter)</p></td><td>Az eredeti tranzakció banki engedélyszáma.</td></tr><tr><td><code>OriginalTransactionAmount</code></td><td><p>number</p><p>(24 karakter)</p></td><td>Az eredeti tranzakció összege.</td></tr><tr><td><code>OriginalTransactionCreatedTime</code></td><td><p>string</p><p>(19 karakter)</p></td><td>Az eredeti tranzakció létrehozásának ideje a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>RefundRequestId</code></td><td><p>string</p><p>(128 karakter)</p></td><td>Visszatérítés kérés azonosítója.</td></tr><tr><td><code>RefundTransactionId</code></td><td><p>string</p><p>(128 karakter)</p></td><td>Visszatérítési tranzakció azonosítója.</td></tr><tr><td><code>RefundRequestAmount</code></td><td><p>number</p><p>(24 karakter)</p></td><td>Visszatérítendő összeg.</td></tr><tr><td><code>RefundRequestTime</code></td><td><p>string</p><p>(19 karakter)</p></td><td>Visszatérítés kérés időpontja.</td></tr></tbody></table>


# Online áruhitel

Az online áruhitel igénylés során a vásárló a fizetésnél kiválasztja az áruhitel opciót, ezután a hitelt nyújtó bank felületére kerül, ahol megadhatja a hiteligényléshez szükséges adatokat. Mivel a hiteligénylés elbírálása időt vesz igénybe a bank részéről, a vásárlót nem irányítjuk vissza a kereskedő oldalára, ahogy az a bankkártyás vagy SZÉP Kártyás fizetés esetén történik.

Felhívjuk a figyelmét, hogy a hitelkérelem elbírálásáig a tranzakció az `OPEN` státuszt veszi fel (a bankkártyás vagy *SZÉP Kártyás* fizetésből ismert `PENDING` státusz helyett). Az `OPEN` státusz jelzi, hogy a hiteligénylés elbírálása még folyamatban van.

{% hint style="info" %}
Online áruhitel igénylésnél kizárólag azonnali terhelés érhető el, a bankkártyás vásárlásnál elérhető kétlépcsős fizetésre (és későbbi terhelésre) itt nincs lehetőség.
{% endhint %}


# Fizetési folyamat

A fizetési folyamat leírását három részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított három fő lépés adja, ezek a lépések a következők:

A. **`Init`** - a tranzakció inicializálása\
B. **`Start`** - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - a tranzakció eredményének lekérése rendszerünkből

{% hint style="info" %}
A hármas felosztás ellenére a felsorolt pontok együttesen adják ki a teljes fizetési folyamatot. A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - a tranzakció inicializálása**

1. A kereskedő oldala rögzíti a vásárló online áruhitel igénylési szándékát,
2. ezután a kereskedő oldala új fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén).
5. A kereskedő oldala tárolja az egyedi tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli)

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló megadja személyes adatait az online áruhitel elbírálásához.
4. Rendszerünk adott időközönként lekérdezi a hiteligénylés eredményét a fizetési szolgáltatótól a háttérben, majd a fizetési szolgáltató válasza alapján beállítja a tranzakció végleges státuszát,
5. ezután rendszerünk a tranzakció azonosítóval kiegészítve, aszinkron módon meghívja az inicializáció (`Init`) során megadott visszatérési URL címet (`ResponseUrl`).
6. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is.

#### **C. `Result` - a tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala lekérdezi a tranzakció eredményét rendszerünkből a `ResponseUrl` hívás hatására (a tranzakció azonosító segítségével).
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a tranzakció státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a tranzakció státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}


# Tranzakció inicializálása (Init)

### Műkődés

Használja az inicializálás (`Init`) funkciót egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a tranzakció és a vásárló adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

Az inicializálás során figyeljen a következőkre:

* Tárolja le az `Init` kérésre visszaadott tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobilalkalmazásban**.
{% endhint %}

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="143">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>BBAruhitel (MBH Online <em>Áruhitel</em>)</li><li>OTPAruhitel (<em>OTP Bank Áruhitel</em>)</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/SPPb1ID37SrcT6PYj5Gz">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td>szabadon választható</td><td>Bruttó végösszeg amit a vásárló kifizet.<br><br>(Magyar forint (HUF) esetén értéke egész szám.)</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai (<a href="/pages/w2bB87azm3s2wK3Gnlgp">PSD2/SCA</a>).</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="144">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF</li></ul></td><td><p>A hiteligénylés devizaneme.<br></p><p>(Értékei fizetési szolgáltatónként és szerződésenként eltérőek lehetnek.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Kiegészítő vagy szolgáltató specifikus adatok (<a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméter használata</a>).<br><br>Részletekért látogassa meg a következő oldalakat:</p><ul><li><a href="/pages/4hhXRXz0u6fTIQHSHY9g">MBH Online Áruhitel paraméterek</a></li><li><a href="/pages/MhvXT3xppf4uz8DYesHA">OTP Áruhitel Extra paraméterek</a></li></ul></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"OTPAruhitel",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID"
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="129">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p><br>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

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

{% endcode %}


# MBH Online Áruhitel specifikus paraméterek

#### Paraméterek

Az `Extra` paraméterben átadható bankspecifikus adatok a következők:

<table data-full-width="true"><thead><tr><th>Változó</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td>firstName</td><td>string</td><td>egyedi értékek</td><td>A hiteligénylő keresztneve.</td></tr><tr><td>lastName</td><td>string</td><td>egyedi értékek</td><td>A hiteligénylő vezetékneve.</td></tr><tr><td>e-mail</td><td>string</td><td><p>Szabványos email formátum.<br></p><p>(maximum 1 db)</p></td><td>A hiteligénylő email címe.</td></tr><tr><td>term</td><td>number</td><td>A hitelkonstrukció határozza meg.</td><td>A kiválasztott hitel futamideje.</td></tr><tr><td>offerId</td><td>string</td><td>A hitelkonstrukció határozza meg.</td><td>A kiválasztott hitelkonstrukció azonosítója.</td></tr><tr><td>testMode</td><td>boolean</td><td><ul><li>true</li><li>false</li></ul></td><td><p>Jelzi a <em>Nevogate</em> tesztfelületének használatát.<br></p><p>(Opcionális paraméter, kizárólag a teszt mód használatához.)</p></td></tr></tbody></table>

#### Mintakód

{% code overflow="wrap" %}

```php
{
    "firstName":"",
    "lastName":"",
    "e-mail":"",
    "term":"",
    "offerId":"",
    "testMode":false
}
```

{% endcode %}


# OTP Áruhitel specifikus paraméterek

#### Paraméterek

Az `Extra` paraméterben átadható bankspecifikus adatok a következők:

<table data-full-width="true"><thead><tr><th>Változó</th><th width="107">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>ConstructionGroup</code></td><td>string</td><td>A hitelkonstrukció határozza meg.</td><td>A kiválasztott hitelkonstrukció azonosítója.</td></tr><tr><td><code>Term</code></td><td>number</td><td>A hitelkonstrukció határozza meg.</td><td>A kiválasztott hitelkonstrukció futamideje.</td></tr><tr><td><code>Contribution</code></td><td>number</td><td>A hitelkonstrukció határozza meg.</td><td>A kiválasztott hitelkonstrukcióhoz kapcsolodó önerő összege.</td></tr></tbody></table>

#### Mintakódok

{% code overflow="wrap" %}

```php
{
    "ConstructionGroup":"",
    "Term":"",
    "Contribution":""
}
```

{% endcode %}


# Tranzakció indítása (Start)

### Műkődés

Tranzakció indításához irányítsa át a vásárlót rendszerünkbe az inicializáció (`Init`) során visszakapott tranzakció azonosítóval (`TransactionId`). Rendszerünk felépíti a kommunikációt a fizetési szolgáltatóval és tovább irányítja a vásárlót a fizetési felületre.

Tranzakció indításához **teszt környezetben** használja a következő címet:

<https://system-test.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]

Tranzakció indításához **éles környezetben** használja a következő címet:

<https://system.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]


# URL Értesítés

### Működés

Használja a `NotificationUrl` paramétert, hogy automatikusan értesüljön a tranzakciók státuszának változásáról. Az inicializáció (`Init`) során adja át az értesítési URL címet a `NotificationUrl` paraméterben. Rendszerünk ezt a címet hívja meg a tranzakció státuszának megváltozásakor.

Rendszerünk legfeljebb 5 alkalommal kísérli meg a megadott értesítési URL hívását, amíg a hívásra HTTP 200 választ nem kap. Az értesítés a tranzakció részletes adatait tartalmazza JSON formátumban (a `Details` hívás eredményének megfelelően), amit `application/json` típusként küldünk, így az adat a *raw request body*-ból nyerhető ki.

Jelezze vissza rendszerünk számára, hogy a kereskedő oldala értesült a tranzakció eredményéről. Ehhez indítson egy `Result` kérést minden rendszerünktől visszaérkező `NotificationUrl` hívás után. `Result` kérés hiányában a tranzakció “megválaszolhatatlan” állapotot kap a *PayAdmin* felületén.

Az alapértelmezett (lineáris időközönként maximum 5 alkalommal történő) URL értesítési eljárás mellett elérhető egy kiterjesztett URL értesítési eljárás is.

Ebben az esetben az értesítési kísérletek fokozatosan elnyújtott időközönként történnek az alábbi logika szerint:

* Azonnal a végstátusz beállítását követően.
* 5 másodperc elteltével.
* 10 másodperc elteltével.
* 30 másodperc elteltével.
* 1 perc elteltével.
* 5 perc elteltével.
* 15 perc elteltével.
* 30 perc elteltével.
* 1 óra elteltével.
* 3 óra elteltével.
* 6 óra elteltével.
* 12 óra elteltével.
* 1 nap elteltével.

A kiterjesztett URL értesítés igénybevételéhez vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.

{% hint style="warning" %}
A `NotificationUrl` átadása minden tranzakció inicializáció során kötelező.\
Továbbá figyeljen arra, hogy a megadott értesítési URL cím (`NotificationUrl`):

* rendelkezzen HTTPS protokollal
* legyen mindenkor publikusan elérhető
  {% endhint %}

{% hint style="danger" %}
A JSON formátumú értesítésben található paraméterek kis kezdőbetűkkel szerepelnek. Ezzel ellentétben a tranzakció részletes adatainak lekérdezésére (`Details` hívásra) adott válasz paraméterei nagy kezdőbetűvel rendelkeznek.
{% endhint %}

### Beállítás lépései

Végezze el a következő lépéseket az URL értesítés megfelelő működéséhez.

{% hint style="warning" %}
A leírt folyamatot minden egyes `NotificationUrl` híváskor végre kell hajtani.
{% endhint %}

1. Adjon meg egy értesítési URL címet a `NotificationUrl` paraméter segítségével.
2. Vizsgálja meg, hogy a *raw request body* tartalmaz JSON típusú adattartalmat (a rendszerünkből érkező `NotificationUrl` hívás során).
3. Nyerje ki az aktuális `TransactionId` értéket a *raw request body*-ból.
4. Indítson egy `Result` kérést melyben megadja a `NotificationUrl` törzséből kinyert `TransactionId` értéket.
5. Dolgozza fel a `Result` kérésre kapott választ, majd
6. mentse el a rendszerében a tranzakció végstátuszát (`ResultCode`).
7. Válaszoljon HTTP 200-as státusz kóddal a rendszerünkből érkező `NotificationUrl` hívásra.

{% hint style="info" %}
PHP használata esetén így nyerheti ki a `TransactionId` értékét:

```php
$json = file_get_contents('php://input');
$data = json_decode($json);
$transactionId = $data->commonData->transactionId;
```

{% endhint %}

### Példa (URL értesítés beállítására teszt környezetben)

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "NotificationUrl":"https://merchant.notification.url"
    }'
```

{% endcode %}


# Tranzakció eredményének lekérdezése (Result)

### Működés

Használja a `Result` hívást a tranzakció eredményének lekérdezéséhez. Az online hiteligénylés után a vásárló nem kerül visszairányításra a kereskedő oldalára (ahogy a bankkártyás vagy *SZÉP Kártyás* fizetés során történik). Ilyen esetben rendszerünk, megadott időközönként a háttérben kérdezi le a hiteligénylés eredményét a fizetési szolgáltatótól (bank). A fizetési szolgáltató válasza alapján rendszerünk beállítja a tranzakció végleges státuszát, majd a tranzakció azonosítóval kiegészítve, aszinkron módon meghívja az Inicializáció (`Init`) során megadott visszatérési URL címet (`ResponseUrl`). Miután rendszerünk meghívja a `ResponseUrl`-t, a kereskedő oldala elindíthatja a `Result` hívást.

`Result` hívás indításához szüksége lesz az adott tranzakció azonosítójára. Ezért a rendszerünkből érkező `ResponseUrl` hívás kiegészül a `TransactionId` GET paraméterrel, amely az adott tranzakció azonosítót biztosítja.

Fontos, hogy minden rendszerünkből érkező `ResponseUrl` hívás után indítson egy `Result` hívást, a vásárlói munkamenettől függetlenül.

Rendszerünk aszinkron módon elindítja a `NotificationUrl` hívást, abban az esetben, ha beállt az adott tranzakció végstátusza. A `NotificationUrl` az inicializáció (`Init`) során kötelezően átadandó URL cím. Itt is fontos, hogy minden rendszerünkből érkező `NotificationUrl` hívás után indítson egy `Result` hívást.

Rendszerünk a `Result` hívás hatására értesül arról, hogy a kereskedő oldala megkapta a tranzakció eredményét. Ezért amennyiben a `Result` hívásra nem kerül sor, a tranzakció rendszerünkben a "megválaszolhatatlan" állapotot veszi fel.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=result)

{% hint style="info" %}
További részletekért a `NotificationUrl` használatáról látogassa meg a következő hivatkozást: [URL Értesítés](/egyszeri-fizetesek-one-time-payment/online-aruhitel/url-ertesites)

A tranzakció állapotairól a rendszerünkben pedig a következő oldalon olvashat további információkat: [Tranzakció Állapotok](/segedlet/tranzakcio-allapotok)
{% endhint %}

{% hint style="warning" %}
Figyeljen arra, hogy `Result` kérést kizárólag `ResponseUrl` vagy `NotificationUrl` hívások hatására indítson. A kereskedő rendszeréből indokolatlanul, vagy ütemezett módon `Result` kérést indítani tilos!
{% endhint %}

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Result</code></td><td><code>POST</code></td><td>method=<code>Result</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Result` kérés egy (kötelező) paraméterrel rendelkezik

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="133">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció eredményének lekérése `Result` használatával

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Result | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Result' \
  --data 'json=
    {
        "TransactionId":"992c8e75435e6d4dfdf6415f0714cae8"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Result` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="346">Paraméter</th><th width="135">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>egyedi értékek</td><td>Rendszerünkben tárolt egyedi boltazonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A tranzakció státusza lehet:</p><ul><li>SUCCESSFUL</li><li>PENDING</li><li>OPEN</li><li>ERROR</li><li>CANCELED</li><li>TIMEOUT</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul></td><td>Jelzi a tranzakció eredményét.<br><br>A tranzakció státuszokról a következő oldalon olvashat további információkat: <a href="/pages/yzo9U4RLeMGLusg6Mrfl">Tranzakció státuszok</a></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>Anum</code></td><td>string</td><td>egyedi értékek</td><td><p>A tranzakció engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Csak bizonyos szolgáltatók esetén.)</p></td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td><p>A tranzakció bruttó végösszege.<br></p><p>(Az összeg amit a vásárló kifizetett.)</p></td></tr><tr><td><code>Currency</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>HUF</li></ul></td><td>A tranzakció devizaneme.</td></tr><tr><td><code>OrderId</code></td><td>string</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>OrderId</code>.)</p></td></tr><tr><td><code>UserId</code></td><td>string</td><td><p>egyedi értékek</p><p>(kivéve e-mail címek, illetve személyes adatok)</p></td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>UserId</code>.)</p></td></tr><tr><td><code>Language</code></td><td><p>string</p><p><br>(2 karakter)</p></td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>ProviderTransactionId</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“true”</li></ul></td><td><p>Jelzi, hogy a bank azonnal hajtja végre a tranzakciót.<br></p><p>(Az inicializáció során beállított <code>AutoCommit</code> értéke.)</p></td></tr><tr><td><code>CommitState</code></td><td>string</td><td><ul><li>APPROVED</li></ul></td><td>• APPROVED: a végleges összeg beterhelése megtörtént</td></tr><tr><td><code>PaywallPaymentName</code></td><td>string<br><br>(36 karakter)</td><td><ul><li>null</li><li>UUID</li></ul></td><td>A tranzakció <em>PayWall</em> azonosítója (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaywallRecurringPaymentEnabled</code></td><td>string</td><td><ul><li>"false"</li></ul></td><td>Jelzi a vásárló hozzájárulását, hogy a kereskedő a jövőben az adott tranzakcióra hivatkozva újabb, ismétlődő tranzakciókat indíthasson (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaymentRegistrationType</code></td><td>string</td><td><ul><li>null</li></ul></td><td>Jelzi a fizetési regisztráció típusát.</td></tr><tr><td><code>SzepPocket</code></td><td>string</td><td><ul><li>null</li></ul></td><td>A tranzakció inicializálása (<code>Init</code>) során megadott zsebazonosító (SZÉP Kártyás fizetés esetén).</td></tr><tr><td><code>ProviderResultCode</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>OTPAruhitel (status)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó elsődleges eredmény- vagy hibakód.</td></tr><tr><td><code>ProviderResultCode2</code></td><td>string</td><td><ul><li>null</li></ul></td><td>A fizetési szolgáltató rendszeréből származó másodlagos eredmény- vagy hibakód.</td></tr><tr><td><code>PaymentLinkName</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A fizetési hivatkozás azonosítója a <em>Nevogate</em> rendszerében (amennyiben a tranzakció <em>PayLink</em> segítségével jött létre).</td></tr><tr><td><code>Created</code></td><td>string</td><td>dátum</td><td>A tranzakció létrehozásának ideje.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Result` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "StoreName": "sdk_test",
    "ProviderName": "OTPAruhitel",
    "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": "Sikeres tranzakció",
    "Anum": "006761",
    "Amount": "100",
    "Currency": "HUF",
    "OrderId": "TEST-ORDER-ID",
    "UserId": "TEST-USER-ID",
    "Language": "HU",
    "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
    "AutoCommit": "true",
    "CommitState": "APPROVED",
    "PaywallPaymentName": null,
    "PaywallRecurringPaymentEnabled": "false",
    "PaymentRegistrationType": null,
    "SzepPocket": null,
    "ProviderResultCode": "000",
    "ProviderResultCode2": null,
    "PaymentLinkName": null,
    "Created": "2020-03-14 11:19:07",
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Tranzakció részletes adatainak lekérdezése (Details)

### Működés

Használja a `Details` hívást a tranzakció részletes adatainak lekérdezéséhez. Míg a `Result` hívásra adott válasz csupán a tranzakció alapadatait hordozza, a `Details` hívás további részletes információkat is tartalmaz az adott tranzakcióról (pl. szolgáltató specifikus adatokat).

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=details)

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Details</code></td><td><code>POST</code></td><td>method=<code>Details</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Details` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` átadása kötelező**)

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="121">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>GetRelatedTransactions</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td>Olyan korábbi tranzakciók részletes adatainak lekérése, melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>GetInfoData</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td><p>Kérés a vásárlásra vonatkozó Info adatok visszaadására.<br></p><p>(<code>Init</code>, <code>InitRP</code> vagy <code>PaymentLinkCreate</code> hívások során átadott vásárlási adatok esetén.)</p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció részletes adatainak lekérése `Details` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Details | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Details' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "GetRelatedTransactions":false,
        "GetInfoData":false
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Details` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="248">Paraméter</th><th width="129">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>CommonData</code></td><td>JSON object</td><td>egyedi értékek</td><td><p>A tranzakció alapadatai.<br></p><p>(A <code>Result</code> hívás során is visszaadott adatok.)</p></td></tr><tr><td><code>ProviderSpecificData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Szolgáltató specifikus kiegészítő adatok.</td></tr><tr><td><code>RelatedTransactions</code></td><td>JSON object</td><td>egyedi értékek</td><td>Olyan korábbi tranzakciók adatai melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>InfoData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Az <code>Info</code> objektum adatai.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Details` kérésre adott válasz (formázást követően):

{% code overflow="wrap" %}

```php
{
    "CommonData":
    {
        "StoreName": "sdk_test",
        "ProviderName": "OTPAruhitel",
        "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
        "ResultCode": "SUCCESSFUL",
        "ResultMessage": "Sikeres tranzakció",
        "Anum": "006766",
        "Amount": "100",
        "Currency": "HUF",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "Language": "HU",
        "ProviderTransactionId": "tr_GVaydOjpVySGJycK15glvGgbLGxmCQyf",
        "AutoCommit": "false",
        "CommitState": "APPROVED",
        "Created": "2020-03-14 11:19:07",
        "ResponseId": "3202109280600047706"
    },
    "ProviderSpecificData":
    {
        ...
        "Amount": "100",
        "Currency": "HUF",
        "Language": "HU",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "ResponseUrl": "https://demo.nevogate.com/response.php",
        "NotificationUrl": null,
        "MaxNotificationSendAttempts": 0,
        "NotificationSendAttempts": 0,
        "NotificationSendSuccess": 0,
        "Extra": null,
        "AutoCommit" : "0",
        "CommitState": "1",
        "HasRefund": "0",
        "Created": "2017-11-17 13:12:36",
        "LastModified": "2017-11-17 13:14:07",
        "InvoiceDate": null,
        "GatewayPaymentPage": null,
        "ModuleName": null,
        "ModuleVersion": null,
        "StoreProviderId": "3103",
        "Error": null,
        "ResultMessage": null
    },
    "RelatedTransactions": null,
    "InfoData": null,
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ProviderName": "OTPAruhitel",
    "ResponseId": "3202109280600047706"
}
```

{% endcode %}


# Átutalás

Az átutalást jelenleg a következő fizetési szolgáltatók támogatják:

* *Gránit FairPay*
* *PayU Classic*
* *PayU Rest*
* *RaiffeisenPay*
* *SimplePay*
* *Worldline - Saferpay*


# Fizetési folyamat

A fizetési folyamat leírását három részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított három fő lépés adja, ezek a lépések a következők:

A. **`Init`** - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek\
B. **`Start`** - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - a tranzakció eredményének lekérése rendszerünkből

{% hint style="info" %}
A hármas felosztás ellenére a felsorolt pontok együttesen adják ki a teljes fizetési folyamatot. A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek**

1. A kereskedő oldala rögzíti a vásárló elektronikus fizetési szándékát,
2. ezután a kereskedő oldala új fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén).
5. A kereskedő oldala tárolja az egyedi tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli)

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló átutalja a megfelelő összeget a kereskedő által megadott számlaszámra.
4. Rendszerünk adott időközönként lekérdezi az átutalás eredményét a fizetési szolgáltatótól a háttérben, majd a fizetési szolgáltató válasza alapján beállítja a tranzakció végleges státuszát,
5. ezután rendszerünk a tranzakció azonosítóval kiegészítve, aszinkron módon meghívja az inicializáció (`Init`) során megadott visszatérési URL címet (`ResponseUrl`).
6. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is

{% hint style="info" %}
A tranzakció időtúllépéssel szakad meg, amennyiben a vásárló egy bizonyos időkereten belül nem utalja el az összeget a kereskedő számlájára (B.3. pont). Az időtúllépés kerete fizetési szolgáltatónként eltérő.
{% endhint %}

#### **C. `Result` - a tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala a `ResponseUrl` hívás hatására egy tranzakció azonosítót tartalmazó `Result` kéréssel lekérdezi a tranzakció eredményét rendszerünkből.
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a tranzakció státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a tranzakció státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}


# Tranzakció inicializálása (Init)

### Működés

Használja az inicializálás (`Init`) funkciót egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a tranzakció és a vásárló adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

Az inicializálás során figyeljen a következőkre:

* Tárolja le az `Init` kérésre visszaadott tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobilalkalmazásban**.
{% endhint %}

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="142">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>Granit (Gránit FairPay)</li><li>OTPSimple (<em>SimplePay</em>)</li><li>OTPSimpleRtp (<em>SimplePay</em>)</li><li>OTPSimpleWire (<em>SimplePay Instant Transfer</em>)</li><li>PayU2 (PayU Classic)</li><li>PayURest</li><li>RaiffeisenPay</li><li>Saferpay (Worldline)</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/570jAUbqyQeDvDFTCm9n">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td>szabadon választható</td><td>Bruttó végösszeg amit a vásárló kifizet.<br><br>(Magyar forint (HUF) esetén értéke egész szám.)</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai (<a href="/pages/w2bB87azm3s2wK3Gnlgp">PSD2/SCA</a>).</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="145">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF (alapért.)</li><li>EUR</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Értékei fizetési szolgáltatónként és szerződésenként eltérőek lehetnek.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Kiegészítő vagy szolgáltató specifikus adatok (<a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméter használata</a>).<br><br>Részletekért látogassa meg a következő oldalakat:</p><ul><li><a href="/pages/QW3YicXEdiBNfv85VCpl">Gránit FairPay Extra paraméterek</a></li><li><a href="/pages/KRIiuqN428P0yfn814fu">RaiffeisenPay Extra paraméterek</a></li><li><a href="/pages/UK0flBTbWk0uP4Gdpf5y">SimplePay Extra paraméterek</a></li><li><a href="/pages/f42YDqlAD33rd4WN9seI">SimplePayRtp Extra paraméterek</a></li><li><a href="/pages/Ik64WduOkKPY8RRyOVuo">Worldline - Saferpay Extra paraméterek</a></li></ul></td></tr><tr><td><code>PaymentMethods</code></td><td>array</td><td><p></p><ul><li>qvik_eam</li><li>qvik_rtp</li></ul></td><td><p>Megadható egyes szolgáltatók esetében, hogy mely fizetési módok legyenek engedélyezve. </p><p></p><p>Amennyiben ez a paraméter üresen marad, abban az esetben a fizetési szolgáltató oldalán az összes elérhető fizetési mód megjelenítésre kerül.</p><p></p><p>A fizetési módok kényszerített megjelenítését nem minden fizetési szolgáltató támogatja.</p><p></p><p><a href="/pages/iFWZ7LZuRF03TuukjNPy">Az elérhető fizetési módokkal kapcsolatos információk a Fizetési szolgáltató specifikus adatoknál találhatók.</a></p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"RaiffeisenPay",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "PaymentMethods":["qvik_rtp"]
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="123">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p><br>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

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

{% endcode %}


# Worldline - Saferpay specifikus paraméterek

#### Paraméterek

Az `Extra` paraméterben átadható bankspecifikus adatok a következők:

<table data-full-width="true"><thead><tr><th>Változó</th><th width="174">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PaymentMethods</code></td><td>array</td><td><ul><li>DIRECTDEBIT</li><li>EPRZELEWY</li><li>EPS</li><li>GIROPAY</li><li>IDEAL</li><li>SOFORT</li></ul></td><td>A <em>Worldline -Saferpay</em> által támogatott fizetési módok, melyek közül több érték is megadható.</td></tr><tr><td><code>PayerNote</code></td><td><p>string</p><p>(max 50 karakter)</p></td><td></td><td>A vásárló bankszámlakivonatán megjelenő szöveg (jellemzően 10-12 karakter).</td></tr><tr><td><code>MandateId</code></td><td><p>string<br></p><p>(max. 35 karakter)</p></td><td><p>a következő karakterek használhatók:</p><ul><li>betűk (ékezet nélkül)</li><li>számok</li><li>szóköz</li></ul></td><td><p>SEPA fizetéshez szükséges azonosító (megbízási referencia), mely lehetővé teszi, hogy a fizetés szolgáltató megterhelje a vásárló számláját.</p><p><br>Adja át <code>MandateId</code> paramétert a tranzakció inicializálása (<code>Init</code>) során. Ha a kereskedő nem ad át <code>MandateId</code> paramétert, alapértelmezetten a <code>TransactionId</code> paraméter értéke kerül átadásra a fizetési szolgáltatónak.</p></td></tr><tr><td><code>BankAccount</code></td><td>JSON object</td><td>egyedi értékek</td><td>A terhelendő számla adatai <code>DIRECTDEBIT</code> fizetési mód esetén.</td></tr><tr><td><code>BankAccount:HolderName</code></td><td><p>string<br></p><p>(max. 50 karakter)</p></td><td>egyedi értékek</td><td>A bankszámla tulajdonosának neve.</td></tr><tr><td><code>BankAccount:IBAN</code></td><td><p>string<br></p><p>(max. 50 karakter)</p></td><td>egyedi értékek</td><td>A vásárló bankszámlaszáma IBAN formátumban.</td></tr><tr><td><code>BankAccount:BIC</code></td><td><p>string<br></p><p>(max. 11 karakter)</p></td><td>egyedi értékek</td><td>A vásárló számlavezető bankjának BIC kódja.</td></tr><tr><td><code>BankAccount:BankName</code></td><td>string</td><td>egyedi értékek</td><td>A vásárló számlavezető bankjának neve.</td></tr></tbody></table>

#### Kivétel: SEPA tranzakció

A SEPA tranzakció indításához figyeljen a következőkre:

* adja meg egyedüli fizetési módként a `DIRECTDEBIT` módot a `PaymentMethods` mezőben
* adja meg a terhelendő számlainformációkat a `BankAccount` objektumban

#### Mintakódok

{% code overflow="wrap" %}

```php
{
    "PaymentMethods":
    [
        "DIRECTDEBIT",
        "EPRZELEWY",
        "EPS",
        "GIROPAY",
        "IDEAL",
        "SOFORT"
    ],
    "PayerNote": "Monthly service fee",
    "MandateId": "YjpDXK6WevnfDLjP",
    "BankAccount":
    [
        "IBAN": "DE17970000011234567890",
        "BIC": "DEUTDEDB983",
        "BankName": "Deutsche Bank",
        "HolderName": "John Doe"
    ]
}
```

{% endcode %}


# Visszairányítási módok

### Működés

Használja a `redirectMode` paramétert, hogy fizetés után visszairányítsa a vásárlót a webáruházba a fizetési szolgáltató oldaláról.

A `redirectMode` paraméter értékét (és a visszairányítás módját) az inicializálás során (`Init`) adhatja meg, az `Extra` paraméteren belül.

{% hint style="info" %}
Amennyiben nem adja át a `redirectMode` értékét az `Extra` paraméterben, alapértelmezetten a 0 értékhez tartozó HTTP átirányítás lép működésbe.
{% endhint %}

A `redirectMode` segítségével a következő visszairányítási módok érhetők el:

<table data-full-width="true"><thead><tr><th width="90">Érték</th><th width="216">Eljárás</th><th>Leírás</th></tr></thead><tbody><tr><td>0</td><td>HTTP redirect</td><td>A vásárló HTTP 302-es átirányítással kerül vissza az inicializáció (<code>Init</code>) során megadott válasz URL címre (<code>ResponseUrl</code>).</td></tr><tr><td>1</td><td>top.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: top window.</td></tr><tr><td>2</td><td>parent.window.location</td><td>A vásárló javascript hívással kerül átirányításra ide: parent window.</td></tr><tr><td>3</td><td>top.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: top window.</p><p>(Nincs átirányítás!)</p></td></tr><tr><td>4</td><td>parent.postMessage</td><td><p>A vásárló javascript alapú üzenetet kap ide: parent window.<br></p><p>(Nincs átirányítás!)</p></td></tr></tbody></table>

A javascript alapú üzenetek tartalma a következő formátumú JSON string (a 3-as és 4-es `redirectMode` értékeknél):

{PMGWTransactionData: {TransactionId: “”, OrderId: “”, UserId: “”}}

**Window\.postMessage()** használata esetén a paraméterek a következő értékekkel rendelkeznek:

<table data-full-width="true"><thead><tr><th width="306">Paraméter</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>A tranzakció egyedi Nevogate azonosítója, melyet az <code>Init</code> hívás válaszában ad vissza rendszerünk.</td></tr><tr><td><code>OrderId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr><tr><td><code>UserId</code></td><td>Megegyezik a <code>Init</code> során átadott értékkel.</td></tr></tbody></table>


# Tranzakció indítása (Start)

### Műkődés

Tranzakció indításához irányítsa át a vásárlót rendszerünkbe az inicializáció (`Init`) során visszakapott tranzakció azonosítóval (`TransactionId`). Rendszerünk felépíti a kommunikációt a fizetési szolgáltatóval és tovább irányítja a vásárlót a fizetési felületre.

Tranzakció indításához **teszt környezetben** használja a következő címet:

<https://system-test.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]

Tranzakció indításához **éles környezetben** használja a következő címet:

<https://system.paymentgateway.hu/Start?TransactionId=> \[az `Init` hívásra visszakapott `TransactionId`]


# URL Értesítés

### Működés

Használja a `NotificationUrl` paramétert, hogy automatikusan értesüljön a tranzakciók státuszának változásáról. Az inicializáció (`Init`) során adja át az értesítési URL címet a `NotificationUrl` paraméterben. Rendszerünk ezt a címet hívja meg a tranzakció státuszának megváltozásakor.

Rendszerünk legfeljebb 5 alkalommal kísérli meg a megadott értesítési URL hívását, amíg a hívásra HTTP 200 választ nem kap. Az értesítés a tranzakció részletes adatait tartalmazza JSON formátumban (a `Details` hívás eredményének megfelelően), amit `application/json` típusként küldünk, így az adat a *raw request body*-ból nyerhető ki.

Jelezze vissza rendszerünk számára, hogy a kereskedő oldala értesült a tranzakció eredményéről. Ehhez indítson egy `Result` kérést minden rendszerünktől visszaérkező `NotificationUrl` hívás után. `Result` kérés hiányában a tranzakció “megválaszolhatatlan” állapotot kap a *PayAdmin* felületén.

Az alapértelmezett (lineáris időközönként maximum 5 alkalommal történő) URL értesítési eljárás mellett elérhető egy kiterjesztett URL értesítési eljárás is.

Ebben az esetben az értesítési kísérletek fokozatosan elnyújtott időközönként történnek az alábbi logika szerint:

* Azonnal a végstátusz beállítását követően.
* 5 másodperc elteltével.
* 10 másodperc elteltével.
* 30 másodperc elteltével.
* 1 perc elteltével.
* 5 perc elteltével.
* 15 perc elteltével.
* 30 perc elteltével.
* 1 óra elteltével.
* 3 óra elteltével.
* 6 óra elteltével.
* 12 óra elteltével.
* 1 nap elteltével.

A kiterjesztett URL értesítés igénybevételéhez vegye fel a kapcsolatot az ügyfélszolgálatunkkal a <business@nevogate.com> címen.

{% hint style="warning" %}
A `NotificationUrl` átadása minden tranzakció inicializáció során kötelező.\
Továbbá figyeljen arra, hogy a megadott értesítési URL cím (`NotificationUrl`):

* rendelkezzen HTTPS protokollal
* legyen mindenkor publikusan elérhető
  {% endhint %}

{% hint style="danger" %}
A JSON formátumú értesítésben található paraméterek kis kezdőbetűkkel szerepelnek. Ezzel ellentétben a tranzakció részletes adatainak lekérdezésére (`Details` hívásra) adott válasz paraméterei nagy kezdőbetűvel rendelkeznek.
{% endhint %}

### Beállítás lépései

Végezze el a következő lépéseket az URL értesítés megfelelő működéséhez.

{% hint style="warning" %}
A leírt folyamatot minden egyes `NotificationUrl` híváskor végre kell hajtani.
{% endhint %}

1. Adjon meg egy értesítési URL címet a `NotificationUrl` paraméter segítségével.
2. Vizsgálja meg, hogy a *raw request body* tartalmaz JSON típusú adattartalmat (a rendszerünkből érkező `NotificationUrl` hívás során).
3. Nyerje ki az aktuális `TransactionId` értéket a *raw request body*-ból.
4. Indítson egy `Result` kérést melyben megadja a `NotificationUrl` törzséből kinyert `TransactionId` értéket.
5. Dolgozza fel a `Result` kérésre kapott választ, majd
6. mentse el a rendszerében a tranzakció végstátuszát (`ResultCode`).
7. Válaszoljon HTTP 200-as státusz kóddal a rendszerünkből érkező `NotificationUrl` hívásra.

{% hint style="info" %}
PHP használata esetén így nyerheti ki a `TransactionId` értékét:

```php
$json = file_get_contents('php://input');
$data = json_decode($json);
$transactionId = $data->commonData->transactionId;
```

{% endhint %}

### Példa (URL értesítés beállítására teszt környezetben)

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "NotificationUrl":"https://merchant.notification.url"
    }'
```

{% endcode %}


# Tranzakció eredményének lekérdezése (Result)

### Működés

Használja a `Result` hívást a tranzakció eredményének lekérdezéséhez. A fizetés után rendszerünk visszairányítja a vásárlót az áruházba, úgy, hogy meghívja azt a `ResponseUrl`-t, amit az inicializáció (`Init`) során adott meg a kereskedő oldala. Átutalás esetén a vásárló nem minden esetben kerül visszairányításra a kereskedő oldalára (ahogy a bankkártyás vagy *SZÉP Kártyás* fizetés során történik). Ilyen esetben rendszerünk, megadott időközönként a háttérben kérdezi le az átutalás eredményét a fizetési szolgáltatótól. A fizetési szolgáltató válasza alapján rendszerünk beállítja a tranzakció végleges státuszát, majd a tranzakció azonosítóval kiegészítve, aszinkron módon meghívja az Inicializáció (`Init`) során megadott visszatérési URL címet (`ResponseUrl`). Miután rendszerünk meghívja a `ResponseUrl`-t, a kereskedő oldala elindíthatja a `Result` hívást.

`Result` hívás indításához szüksége lesz az adott tranzakció azonosítójára. Ezért a rendszerünkből érkező `ResponseUrl` hívás kiegészül a `TransactionId` GET paraméterrel, amely az adott tranzakció azonosítót biztosítja.

Fontos, hogy minden rendszerünkből érkező `ResponseUrl` hívás után indítson egy `Result` hívást, a vásárlói munkamenettől függetlenül. Ennek oka, hogy előfordulhat, hogy a `ResponseUrl` hívásra később, aszinkron módon, a háttérben kerül sor.

Rendszerünk aszinkron módon elindítja a `NotificationUrl` hívást, abban az esetben, ha beállt az adott tranzakció végstátusza. A `NotificationUrl` az inicializáció (`Init`) során kötelezően átadandó URL cím. Itt is fontos, hogy minden rendszerünkből érkező `NotificationUrl` hívás után indítson egy `Result` hívást.

Rendszerünk a `Result` hívás hatására értesül arról, hogy a kereskedő oldala megkapta a tranzakció eredményét. Ezért amennyiben a `Result` hívásra nem kerül sor, a tranzakció rendszerünkben a "megválaszolhatatlan" állapotot veszi fel.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=result)

{% hint style="info" %}
További részletekért a `NotificationUrl` használatáról látogassa meg a következő hivatkozást: [URL Értesítés](/egyszeri-fizetesek-one-time-payment/atutalas/url-ertesites)

A tranzakció állapotairól a rendszerünkben pedig a következő oldalon olvashat további információkat: [Tranzakció Állapotok](/segedlet/tranzakcio-allapotok)
{% endhint %}

{% hint style="warning" %}
Figyeljen arra, hogy `Result` kérést kizárólag `ResponseUrl` vagy `NotificationUrl` hívások hatására indítson. A kereskedő rendszeréből indokolatlanul, vagy ütemezett módon `Result` kérést indítani tilos!
{% endhint %}

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Result</code></td><td><code>POST</code></td><td>method=<code>Result</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Result` kérés egy (kötelező) paraméterrel rendelkezik

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string<br><br>(32 karakter)</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció eredményének lekérése `Result` használatával

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Result | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Result' \
  --data 'json=
    {
        "TransactionId":"992c8e75435e6d4dfdf6415f0714cae8"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Result` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="347">Paraméter</th><th width="134">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>egyedi értékek</td><td>Rendszerünkben tárolt egyedi boltazonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A tranzakció státusza lehet:</p><ul><li>SUCCESSFUL</li><li>PENDING</li><li>OPEN</li><li>ERROR</li><li>CANCELED</li><li>TIMEOUT</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul></td><td>Jelzi a tranzakció eredményét.<br><br>A tranzakció státuszokról a következő oldalon olvashat további információkat: <a href="/pages/yzo9U4RLeMGLusg6Mrfl">Tranzakció státuszok</a></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>Anum</code></td><td>string</td><td>egyedi értékek</td><td><p>A tranzakció engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Csak bizonyos szolgáltatók esetén.)</p></td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td><p>A tranzakció bruttó végösszege.<br></p><p>(Az összeg amit a vásárló kifizetett.)</p></td></tr><tr><td><code>Currency</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>HUF</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td>A tranzakció devizaneme.</td></tr><tr><td><code>OrderId</code></td><td>string</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>OrderId</code>.)</p></td></tr><tr><td><code>UserId</code></td><td>string</td><td><p>egyedi értékek</p><p>(kivéve e-mail címek, illetve személyes adatok)</p></td><td><p>A vásárló azonosítója a kereskedő áruházában.<br></p><p>(Az inicializáció során átadott <code>UserId</code>.)</p></td></tr><tr><td><code>Language</code></td><td><p>string</p><p><br>(2 karakter)</p></td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>ProviderTransactionId</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakció azonosítója a fizetési szolgáltató rendszerében.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td><ul><li>“true”</li></ul></td><td><p>Jelzi, hogy a bank azonnal hajtja végre a tranzakciót.<br></p><p>(Az inicializáció során beállított <code>AutoCommit</code> értéke.)</p></td></tr><tr><td><code>CommitState</code></td><td>string</td><td><ul><li>APPROVED</li></ul></td><td>• APPROVED: a végleges összeg beterhelése megtörtént</td></tr><tr><td><code>PaywallPaymentName</code></td><td>string<br><br>(36 karakter)</td><td><ul><li>null</li><li>UUID</li></ul></td><td>A tranzakció <em>PayWall</em> azonosítója (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaywallRecurringPaymentEnabled</code></td><td>string</td><td><ul><li>"true"</li><li>"false"</li></ul></td><td>Jelzi a vásárló hozzájárulását, hogy a kereskedő a jövőben az adott tranzakcióra hivatkozva újabb, ismétlődő tranzakciókat indíthasson (kizárólag a <em>PayWall</em> segítségével indított fizetések esetén).</td></tr><tr><td><code>PaymentRegistrationType</code></td><td>string</td><td><ul><li>null</li></ul></td><td>Jelzi a fizetési regisztráció típusát.</td></tr><tr><td><code>SzepPocket</code></td><td>string</td><td><ul><li>null</li></ul></td><td>A tranzakció inicializálása (<code>Init</code>) során megadott zsebazonosító (SZÉP Kártyás fizetés esetén).</td></tr><tr><td><code>ProviderResultCode</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>Granit (statusCode)</li><li>OTPSimple (resultCode / errorCodes)</li><li>OTPSimpleRtp (resultCode)</li><li>PayU2 (errorCode / responseCode)</li><li>PayURest (cardResponseCode)</li><li>RaiffeisenPay (transactionStatus)</li><li>Saferpay (ErrorName)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó elsődleges eredmény- vagy hibakód.</td></tr><tr><td><code>ProviderResultCode2</code></td><td>string</td><td><p>egyedi értékek, melyek csak az alábbi fizetési szolgáltatóktól származhatnak (szolgáltató és hozzá tartozó kód párosként felsorolva):</p><ul><li>RaiffeisenPay (trxStatusReasonCd / transactionReasonCode / transactionReasonProprietary)</li><li>Saferpay (ProcessorResult)</li></ul></td><td>A fizetési szolgáltató rendszeréből származó másodlagos eredmény- vagy hibakód.</td></tr><tr><td><code>PaymentLinkName</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A fizetési hivatkozás azonosítója a <em>Nevogate</em> rendszerében (amennyiben a tranzakció <em>PayLink</em> segítségével jött létre).</td></tr><tr><td><code>Created</code></td><td>string</td><td>dátum</td><td>A tranzakció létrehozásának ideje.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Result` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "StoreName": "sdk_test",
    "ProviderName": "RaiffeisenPay",
    "TransactionId": "992c8e75435e6d4dfdf6415f0714cae8",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": "Sikeres tranzakció",
    "Anum": "006761",
    "Amount": "100",
    "Currency": "HUF",
    "OrderId": "TEST-ORDER-ID",
    "UserId": "TEST-USER-ID",
    "Language": "HU",
    "ProviderTransactionId": "tr_tzftXkC-fcwaVPiAVVNgotmIhY_QXydL",
    "AutoCommit": "true",
    "CommitState": "APPROVED",
    "PaywallPaymentName": null,
    "PaywallRecurringPaymentEnabled": "false",
    "PaymentRegistrationType": null,
    "SzepPocket": null,
    "ProviderResultCode": "000",
    "ProviderResultCode2": null,
    "PaymentLinkName": null,
    "Created": "2020-03-14 11:19:07",
    "ResponseId": "3202109280600047703"
}
```

{% endcode %}


# Tranzakció részletes adatainak lekérdezése (Details)

### Működés

Használja a `Details` hívást a tranzakció részletes adatainak lekérdezéséhez. Míg a `Result` hívásra adott válasz csupán a tranzakció alapadatait hordozza, a `Details` hívás további részletes információkat is tartalmaz az adott tranzakcióról (pl. szolgáltató specifikus adatokat).

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=details)

{% hint style="warning" %}
A fizetési tranzakcióhoz kapcsolódó adatok közül a kommunikációs naplóbejegyzések (log) a fizetési tranzakció létrehozását követő 2 évig, míg minden egyéb adat a szolgáltatási szerződés megszűnéséig érhető el.
{% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Details</code></td><td><code>POST</code></td><td>method=<code>Details</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Details` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` átadása kötelező**)

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="117">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>GetRelatedTransactions</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td>Olyan korábbi tranzakciók részletes adatainak lekérése, melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>GetInfoData</code></td><td>boolean</td><td><ul><li>true</li><li>false (alapért.)</li></ul></td><td><p>Kérés a vásárlásra vonatkozó Info adatok visszaadására.<br></p><p>(<code>Init</code>, <code>InitRP</code> vagy <code>PaymentLinkCreate</code> hívások során átadott vásárlási adatok esetén.)</p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció részletes adatainak lekérése `Details` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Details | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Details' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "GetRelatedTransactions":false,
        "GetInfoData":false
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Details` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="249">Paraméter</th><th width="133">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>CommonData</code></td><td>JSON object</td><td>egyedi értékek</td><td><p>A tranzakció alapadatai.<br></p><p>(A <code>Result</code> hívás során is visszaadott adatok.)</p></td></tr><tr><td><code>ProviderSpecificData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Szolgáltató specifikus kiegészítő adatok.</td></tr><tr><td><code>RelatedTransactions</code></td><td>JSON object</td><td>egyedi értékek</td><td>Olyan korábbi tranzakciók adatai melyek <code>OrderId</code> paramétere megegyezik az aktuális tranzakció <code>OrderId</code> értékével.</td></tr><tr><td><code>InfoData</code></td><td>JSON object</td><td>egyedi értékek</td><td>Az <code>Info</code> objektum adatai.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td>egyedi értékek</td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Details` kérésre adott válasz (formázást követően):

{% code overflow="wrap" %}

```php
{
    "CommonData":
    {
        "StoreName": "sdk_test",
        "ProviderName": "RaiffeisenPay",
        "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
        "ResultCode": "SUCCESSFUL",
        "ResultMessage": "Sikeres tranzakció",
        "Anum": "006766",
        "Amount": "100",
        "Currency": "HUF",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "Language": "HU",
        "ProviderTransactionId": "tr_GVaydOjpVySGJycK15glvGgbLGxmCQyf",
        "AutoCommit": "false",
        "CommitState": "APPROVED",
        "Created": "2020-03-14 11:19:07",
        "ResponseId": "3202109280600047706"
    },
    "ProviderSpecificData":
    {
        ...
        "Amount": "100",
        "Currency": "HUF",
        "Language": "HU",
        "OrderId": "TEST-ORDER-ID",
        "UserId": "TEST-USER-ID",
        "ResponseUrl": "https://demo.nevogate.com/response.php",
        "NotificationUrl": null,
        "MaxNotificationSendAttempts": 0,
        "NotificationSendAttempts": 0,
        "NotificationSendSuccess": 0,
        "Extra": null,
        "AutoCommit" : "0",
        "CommitState": "1",
        "HasRefund": "0",
        "Created": "2017-11-17 13:12:36",
        "LastModified": "2017-11-17 13:14:07",
        "InvoiceDate": null,
        "GatewayPaymentPage": null,
        "ModuleName": null,
        "ModuleVersion": null,
        "StoreProviderId": "3103",
        "Error": null,
        "ResultMessage": null
    },
    "RelatedTransactions": null,
    "InfoData": null,
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ProviderName": "RaiffeisenPay",
    "ResponseId": "3202109280600047706"
}
```

{% endcode %}


# Tranzakció összegének visszatérítése (Refund)

### Működés

Használja a `Refund` hívást egy sikeres tranzakció összegének teljes vagy részleges visszatérítésére. Átutalás visszatérítésre csak bizonyos fizetési szolgáltatóknál van lehetőség, továbbá ezt a funkciót jellemzően külön kell igényelni az adott fizetési szolgáltatótól.

{% hint style="info" %}
Átutalás visszatérítésére jelenleg a SimplePay és a Worldline fizetési szolgáltatók biztosítanak lehetőséget.
{% endhint %}

[<mark style="background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=refund)

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Refund</code></td><td><code>POST</code></td><td>method=<code>Refund</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

A `Refund` kérés a következő paraméterekkel rendelkezik (**a `TransactionId` és `Amount` átadása kötelező**):

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="106">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>Amount</code></td><td>number</td><td>egyedi értékek</td><td>Visszatérítésre kerülő összeg az eredeti tranzakció pénznemében.</td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td><p>Egyéb illetve szolgáltató specifikus adatok.</p><p>(További részletekről az <a href="/pages/XaOHnljbNm5MGxPqLjdh">Extra adatok</a> pontban olvashat.)<br></p></td></tr></tbody></table>

#### **Mintakód**

A tranzakció összegének részleges vagy teljes visszatérítése `Refund` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Refund | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Refund' \
  --data 'json=
    {
        "TransactionId":"a4d6f6f27f2116da21da62d705dbd7ef",
        "Amount":100
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Refund` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="277">Paraméter</th><th width="133">Típus</th><th width="284">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>A visszatérítés beküldésének eredménye a következők egyike lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi a visszatérítés beküldésének eredményét:</p><ul><li>SUCCESSFUL: a visszatérítés beküldése sikeres</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>RefundRequestId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés kérésének azonosítója a fizetési szolgáltató rendszerében.</p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundTransactionId</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés azonosítója a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundAuthorizationCode</code></td><td>string</td><td>egyedi értékek</td><td><p>A visszatérítés engedélyszáma a fizetési szolgáltató rendszerében.<br></p><p>(Egyes fizetési szolgáltatóknál nem rendelkezik értékkel.)</p></td></tr><tr><td><code>RefundId</code></td><td>string<br><br>(35 karakter)</td><td>egyedi értékek</td><td>A visszatérítés egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A fenti `Refund` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "a4d6f6f27f2116da21da62d705dbd7ef",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "RefundRequestId": null,
    "RefundTransactionId": null,
    "RefundAuthorizationCode": null
    "RefundId": "rf_b0fd9b0381bb54568870a6c22d6a086f",
    "ResultMessage": null,
    "ResponseId": "3202109280600047707"
}
```

{% endcode %}


# Tranzakció érvénytelenítése (Cancel)

### Működés

Használja a `Cancel` hívást a tranzakció érvénytelenítéséhez. Tranzakció érvénytelenítésére mindaddig lehetőség van, amíg a tranzakció `PENDING`, vagy `OPEN` státuszban van. A sikeres érvénytelenítés hatására a tranzakció `CANCELED` státuszba kerül, így innentől már sikeres tranzakció létrehozása nem lehetséges.

{% hint style="info" %}
Az érvénytelenítés művelet jelenleg a következő fizetési szolgáltatók esetén érhető el:

* *Gránit FairPay*
* *Raiffeisen Pay*
* *SimplePay*
  {% endhint %}

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Cancel</code></td><td><code>POST</code></td><td>method=<code>Cancel</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

### **API kérés paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="117">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

A tranzakció érvénytelenítése `Cancel` használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Cancel | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Cancel' \
  --data 'json=
    {
        "TransactionId":"b8156ec464a00c34b947a1aac4891e0d"
    }'
```

{% endcode %}

### **API válasz paraméterek**

A `Cancel` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th width="249">Paraméter</th><th width="133">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td>32 karakter hosszú md5 hash</td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Az API kérés eredménye lehet:</p><ul><li>SUCCESSFUL</li></ul><p>Hiba esetén a következő eredménykódok jelölik a hiba okát:</p><ul><li>InactiveStore</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownStore</li><li>UnknownTransaction</li><li>WrongApikey</li><li>WrongTransactionStatus</li></ul><p>(Továbbá a szolgáltatókra vonatkozó specifikus eredménykódok is megjelenhetnek itt.)</p></td><td><p>Jelzi az API kérés eredményét:</p><ul><li>SUCCESSFUL: az API kérés sikeres.</li></ul></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

**Mintakód**

A fenti `Cancel` kérésre adott válasz:

{% code overflow="wrap" %}

```php
{
    "TransactionId": "b8156ec464a00c34b947a1aac4891e0d",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3382412101354326635"
}
```

{% endcode %}


# Általános CIT ismertető

A CIT (*Customer Initiated Transaction*) típusú egykattintásos (*One-click*) fizetéseket a vásárló kezdeményezi akinek végig jelen kell lennie a fizetési folyamat során. Ezeknél a fizetéseknél a fizetés gyakorisága, időpontja és összege is változó lehet, közös jellemzőjük, hogy a vásárló rendszeresen és viszonylag gyakran tér vissza a kereskedő oldalára. Jellemző felhasználási területei az ételrendelés, jegyvásárlás, stb.

Egykattintásos fizetéshez a vásárlónak előbb regisztrálnia kell egy fizetőeszközt vagy ki kell választania egyet a korábban regisztrált fizetőeszközök közül. Ez meggyorsítja a rákövetkező fizetéseket, mivel a fizetőeszköz-regisztrációt követő újabb tranzakciók esetén a vásárlónak már nem kell ismételten megadni a fizetőeszköz adatait.

Az egykattintásos fizetés esetén a kereskedő minden alkalommal **köteles** az alábbi választási lehetőségeket biztosítani a vásárló számára:

* egyszeri (*One-time*) fizetés fizetőeszköz-regisztráció nélkül
* fizetés és a fizetéshez használt fizetőeszköz-regisztrációja
* egykattintásos (*One-click*) fizetés korábban regisztrált fizetőeszközzel (rákövetkező fizetés)

Opcionálisan, az egykattintásos fizetés esetén a kereskedő a következő lehetőségeket is biztosíthatja a vásárló számára:

* bankkártya verifikáció terhelés nélküli fizetőeszköz-regisztrációhoz (kizárólag bankkártya használata esetén érhető el meghatározott fizetési szolgáltatóknál, jelenleg a *Global Payments* támogatja)
* korábban regisztrált fizetőeszköz-regisztrációjának érvénytelenítése (az érvénytelenítést a kereskedő oldalán, a vásárlói fiókban javasolt kezelni. Egyes fizetési szolgáltatók kötelezően elvárják a kereskedőtől, hogy biztosítsa ezt a funkciót a vásárlói számára.)

{% hint style="info" %}
Bankkártya használata esetén *3DSecure* hitelesítésre is szükség lehet a tranzakció sikeres végrehajtásához.
{% endhint %}

### CIT fizetések bevezetésének háttere

A vásárló által kezdeményezett CIT tranzakciók az eddig alkalmazott egykattintásos (*One-click*) fizetés helyére lépnek. A változtatás háttere, hogy bevezetésre került az Európai Unió pénzforgalmi szolgáltatásokra vonatkozó második irányelve (eredeti nevén a *Payment Services Directive 2* vagy röviden PSD2).

A bevezetett irányelv értelmében megváltoztak a bankkártya regisztrációjára és a regisztrált bankkártyák felhasználására vonatkozó szabályok. Mivel az egykattintásos (*One-click*) fizetések feltétele a vásárló fizetőeszközének előzetes regisztrációja, ezek a tranzakciók is a szabályozás hatálya alá kerülnek. A PSD2 által bevezetett új CIT fizetéstípus célja, hogy a vásárló részt vegyen a bankkártyaadatok újbóli megadása nélküli fizetési folyamatban is, mert 3DS hitelesítésre bármikor kötelezheti a vásárlót a kártyakibocsátó bank, abból a célból, hogy a tranzakció kifejezetten csak a kártyabirtokos engedélyével jöhessen létre.


# Bankkártya és mobiltárca

**Ebben a fejezetben a bankkártyás és mobiltárcás&#x20;*****CIT*****&#x20;fizetési megoldások leírását találja.**

A vásárló által kezdeményezett *CIT* fizetések indítására bankkártyás és mobiltárcás fizetőeszközök regisztrációjával van mód. A *CIT* fizetés szereplői a kereskedő, a vásárló és a fizetési szolgáltató/bank, ezeket a szereplőket *Nevogate* rendszere köti össze.


# Azonnali terhelés

Ennél a terhelés típusnál a vásárlás összegét közvetlenül a fizetés után vonják le a vásárló számlájáról. Egy másik fejezetben bemutatjuk a kétlépcsős fizetést, ahol a terhelésre a vásárlás után, egy későbbi időpontban kerül sor.

{% hint style="info" %}
Az egykattintásos fizetést azonnali terhelés esetén csak bizonyos fizetési szolgáltatók támogatják. Ez a funkció jelenleg a következő szolgáltatóknál érhető el:

* Barion Smart Gateway
* Teya RPG
* CIB Bank
* GoPay
* Global Payments
* K\&H Bank
* PayPal REST
* PayU REST
* Raiffeisen vPos
* SimplePay
* Worldline - Saferpay
  {% endhint %}


# Fizetés fizetőeszköz-regisztrációval

A fizetőeszköz-regisztráció menete megegyezik egy normál fizetés menetével, azonban ilyenkor a tranzakció végén a fizetési szolgáltató rendszere eltárolja a fizetőeszköz adatait, ezzel létrehozva a **referencia tranzakciót**.

A referencia tranzakció egy fizetőeszköz sikeres regisztrációja során jön létre. Referencia tranzakció létrehozásához használja az erős ügyfél-hitelesítés (*PSD2/SCA*) során átadható fizetési paramétereket. A regisztráció elvégezhető fizetéssel egybekötve, vagy bankkártya verifikáció segítségével. Verifikáció esetén pénzügyi terhelésre nem kerül sor.

A jövőben, a rákövetkező fizetések a referencia tranzakcióra hivatkozva kerülnek végrehajtásra. Ilyenkor a korábban regisztrált fizetőeszköz adatainak ismételt megadására már nincs szükség, azonban a kártyakibocsátó kérheti a *3DSecure* hitelesítés végrehajtását a vásárlótól (kizárólag bankkártya esetén).

{% hint style="info" %}
Az erős ügyfél-hitelesítésről (*PSD2/SCA*) a következő hivatkozáson olvashat további részleteket: [Erős ügyfél-hitelesítés (*PSD2/SCA*)](/egykattintasos-fizetes-one-click-payment/bankkartya-es-mobiltarca/azonnali-terheles/fizetes-fizetoeszkoez-regisztracioval/eros-uegyfel-hitelesites-psd2-sca)

További részletekért a bankkártya verifikációról látogassa meg a következő hivatkozást: [Fizetőeszköz-verifikáció](/fizetoeszkoz-verifikacio/altalanos-ismerteto)
{% endhint %}

{% hint style="warning" %}
A fizetőeszköz-regisztrációjára minden esetben, egyértelmű módon fel kell hívni a vásárló figyelmét, a regisztrációra kizárólag a vásárló beleegyezésével kerülhet sor.

A regisztrált fizetési eszköz érzékeny adatait (pl. bankkártyaszám) kizárólag a fizetési szolgáltató tárolja. A fizetőeszköz-regisztráció során ezek az adatok **nem kerülnek tárolásra** a *Nevogate* rendszerében és **nem jutnak vissza** a kereskedő rendszerébe.
{% endhint %}


# Fizetési folyamat (fizetőeszköz-regisztrációhoz)

A fizetési folyamat leírását három részre bontottuk a könnyebb átláthatóság miatt. Az elválasztás alapját a kereskedő boltjából indított három fő lépés adja, ezek a lépések a következők:

A. **`Init`** - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek\
B. **`Start`** - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz\
C. **`Result`** - a tranzakció eredményének lekérése rendszerünkből

{% hint style="info" %}
A hármas felosztás ellenére a felsorolt pontok együttesen adják ki a teljes fizetési folyamatot. A felsorolt pontok egy sikeres fizetési folyamatot írnak le.
{% endhint %}

#### **A. `Init` - a tranzakció inicializálása és a vásárló adatainak átadása rendszerünknek**

1. A kereskedő oldala rögzíti a vásárló elektronikus fizetési szándékát,
2. ezután a kereskedő oldala új fizetési tranzakciót kezdeményez rendszerünkben.
3. Rendszerünk hitelesíti a beérkezett kérést (autentikáció),
4. ezután rendszerünk egy egyedi tranzakció azonosítót (`TransactionId`) küld vissza a kereskedőnek (sikeres hitelesítés esetén). Ez a tranzakció azonosító lesz a referencia tranzakció azonosító, amit később a rákövetkező fizetéseknél meg kell adni.
5. A kereskedő oldala tárolja az egyedi referencia tranzakció azonosítót.

Hitelesítés (autentikáció) során rendszerünk a következőket ellenőrzi:

* a kereskedő boltja szerepel rendszerünkben a megadott boltnév (`StoreName`) és API kulcs (`ApiKey`) párossal
* az API kérés a kereskedő által előre megadott IP címről érkezik (az engedélyezett IP címeket a *PayAdmin* felületén adhatja meg a megfelelő jogosultsággal rendelkező felhasználó)
* a kereskedő boltjához hozzá van rendelve a tranzakcióban szereplő szolgáltatás, devizanem és végrehajtási mód (a szolgáltatás ebben az esetben a fizetési szolgáltatót takarja, a végrehajtási mód pedig az azonnali vagy későbbi terhelést jelöli)
* a kereskedő boltjánál engedélyezve van az egykattintásos fizetés funkció

{% hint style="info" %}
A `TransactionId` olyan egyedi azonosító melyet a *Nevogate* rendszere hoz létre. Segítségével egy tranzakció egyértelműen beazonosítható rendszerünkben és a *PayAdmin* felületén. Fontos, hogy a `TransactionId` nem azonos a `ProviderTransactionId` azonosítóval. Utóbbi az egyes fizetési szolgáltatók saját rendszereiben azonosítja be az adott tranzakciót.
{% endhint %}

#### **B. `Start` - a tranzakció indítása és a vásárló átirányítása a fizetési szolgáltatóhoz**

1. A kereskedő oldala átirányítja a vásárlót rendszerünkbe (HTTP Redirect) a tárolt referencia tranzakció azonosítóval.
2. Rendszerünk ellenőrzi a referencia tranzakció azonosítót és átirányítja a vásárlót a fizetési szolgáltatóhoz (sikeres ellenőrzés esetén).
3. A vásárló megadja bankkártya adatait (vagy kiválasztja a megfelelő mobiltárcát) a fizetési szolgáltató oldalán. (Ezen a ponton a vásárló átirányításra kerülhet a kártyakibocsátó bankhoz, ahol személyazonosságát 3DS hitelesítési folyamattal igazolhatja.)
4. A fizetési szolgáltató eltárolja a fizetőeszköz adatait és visszairányítja a vásárlót rendszerünkbe, a fizetés befejezése után.
5. Rendszerünk lekérdezi a tranzakció eredményét a fizetési szolgáltatótól, majd beállítja a tranzakció végleges státuszát a fizetési szolgáltató válasza alapján,
6. ezután rendszerünk a referencia tranzakció azonosítóval visszairányítja a vásárlót a kereskedő oldalára (az inicializáció (`Init`) során megadott visszatérési URL címre (`ResponseUrl`)).
7. Ezzel párhuzamosan rendszerünk a tranzakció végstátuszának beállítását követően aszinkron módon meghívja az inicializáció (`Init`) során átadott `NotificationUrl` címet is.

{% hint style="info" %}
A **B.3.** lépésben leírt 3DS hitelesítési folyamat (3D Secure vagy 3D Secure Code) a pénzügyi visszaélések megakadályozását célzó megoldás. Fizetés során a 3DS a kötelező kártyaadatok bekérésén túl egy egyszer használatos kóddal biztosítja a kártyabirtokos védelmét visszaélésekkel szemben. Használata egyszerű, a vásárlónak mindössze egy mobiltelefonra van szüksége.
{% endhint %}

#### **C. `Result` - a tranzakció eredményének lekérése rendszerünkből**

1. A kereskedő oldala a `ResponseUrl` hívás hatására egy tranzakció azonosítót tartalmazó `Result` kéréssel lekérdezi a tranzakció eredményét rendszerünkből.
2. Rendszerünk ellenőrzi a tranzakció azonosítót,
3. ezután rendszerünk megválaszolja a tranzakció státuszát a kereskedő oldalának (sikeres ellenőrzés esetén).
4. A kereskedő oldala tárolja a tranzakció státuszát és értesíti a vásárlót a tranzakció eredményéről.

{% hint style="warning" %}
Figyeljen arra, hogy minden `NotificationUrl` hívást követően is indítson egy `Result` kérést rendszerünk felé.
{% endhint %}


# Tranzakció inicializálása (Init) (fizetőeszköz-regisztrációhoz)

### Működés

Használja az inicializálás (`Init`) funkciót fizetőeszköz-regisztrációjához és egy új fizetési tranzakció kezdeményezésére. Az inicializálás során a kereskedő oldala átadja a tranzakció és a vásárló adatait rendszerünknek. Ennek hatására rendszerünk létrehoz egy új tranzakciós rekordot a kereskedőtől kapott adatok felhasználásával. Sikeres inicializálás esetén az új rekord mellett rendszerünk létrehoz egy új referencia tranzakció azonosítót is (`TransactionId`), majd visszaadja ezt az azonosítót a kereskedő oldalának.

Az inicializálás során figyeljen a következőkre:

* Adja meg a kereskedő rendszerében tárolt, **egyedi** `UserId` paramétert **(megadása fizetőeszköz-regisztrációnál kötelező)**. Az egyes vásárlók az inicializálás során átadott `UserId` paraméter segítségével azonosíthatók be (egy vásárló akár több fizetőeszközt is regisztrálhat).
* Adja át a `PaymentRegistration` és a `PaymentRegistrationType` paramétereket a sikeres fizetőeszköz-regisztrációhoz.
* Használjon erős ügyfél-hitelesítést (PSD2/SCA) a vásárló adatainak átadásához. Erről a következő oldalon olvashat részletesebben: [Erős ügyfél-hitelesítés (PSD2/SCA)](/egykattintasos-fizetes-one-click-payment/bankkartya-es-mobiltarca/azonnali-terheles/fizetes-fizetoeszkoez-regisztracioval/eros-uegyfel-hitelesites-psd2-sca)
* Tárolja le az `Init` kérésre visszaadott referencia tranzakció azonosítót, mivel később ennek segítségével hivatkozhat az adott tranzakcióra.

[<mark style="color:blue;background-color:blue;">**Próbálja ki ezt a funkciót!**</mark>](https://demo.nevogate.com/views/?action=start)

{% hint style="info" %}
Az inicializációban a fizetési szolgáltatók nem vesznek részt, ez a folyamat kizárólag a kereskedő oldala és a *Nevogate* rendszere között zajlik.
{% endhint %}

{% hint style="warning" %}
Mobilalkalmazás fejlesztésnél biztosítsa, hogy az inicializációra a szerver oldalon kerüljön sor. Biztonsági okokból az **inicializáció nem történhet meg a mobilalkalmazásban**.
{% endhint %}

Az egykattintásos fizetési tranzakciók esetén a Nevogate a kereskedőnél megvalósult fizetőeszköz-regisztráció céljából indított fizetési tranzakció adatai alapján egyedi tranzakciós lenyomatot, ún. **referencia tranzakciót hoz létre**. Ezt egyértelműen hozzárendeli a kereskedő által a tranzakció során átadott `UserId` paraméterhez, amely a vásárló egyedi azonosítására szolgál a kereskedő rendszerén belül.

{% hint style="danger" %}
A kereskedőnek a funkció igénybevétele során biztosítania kell, hogy **saját rendszerén belül minden vásárlójához egyedi** `UserId`**-t rendeljen**. Kiemelt fontosságú, hogy egy már kiosztott azonosító semmilyen körülmények között ne kerülhessen újra hozzárendelésre egy másik vásárlóhoz. Amennyiben ez nem teljesül, kritikus adatintegritási és biztonsági sebezhetőség jön létre: ha két vagy több vásárlóhoz ugyanaz az `UserId` tartozik, az egyikük által regisztrált fizetőeszközzel egy másik vásárló tranzakciói is teljesülhetnek.

A fenti utasítások be nem tartásából eredő hibáért és az ebből fakadó esetleges károkért a Nevogate-et felelősség nem terheli, azért **kizárólag a kereskedő felelős**.
{% endhint %}

{% hint style="warning" %}
Raiffeisen vPos szolgáltató esetén a fizetőeszköz regisztráció kizárólag abban az esetben lesz sikeres, amennyiben a fizető felületen megjelenő "Kártyaadatok biztonságos mentése" jelölőnégyzetet a vásárló bejelöli. Ennek elmúlasztása a tranzakció eredményét nem befolyásolja, de a regisztrált fizetőeszköz érvénytelen lesz. &#x20;
{% endhint %}

### **API kérés paraméterek**

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

<table data-full-width="true"><thead><tr><th>Művelet</th><th>HTTP kérés</th><th>Adatok</th></tr></thead><tbody><tr><td><code>Init</code></td><td><code>POST</code></td><td>method=<code>Init</code><br><br>json={JSON encode-olt paraméterek}</td></tr></tbody></table>

{% hint style="info" %}
Az API kérésekhez kapcsolódó paramétereket két táblázatba soroljuk fel a könnyebb átláthatóság kedvéért. Természetesen az egyes paraméterek megjelenhetnek ugyanabban az API kérésben.

Az API paraméterek felosztása a következő:

* kötelező paraméterek
* opcionális paraméterek
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th width="280">Paraméter</th><th width="141">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>StoreName</code></td><td>string</td><td>A <em>Nevogate</em> szerződésben kerül meghatározásra.</td><td>Rendszerünkben tárolt egyedi bolt azonosító.</td></tr><tr><td><code>ProviderName</code></td><td>string</td><td><ul><li>Barion2</li><li>Borgun2 (Teya RPG)</li><li>CIB</li><li>GoPay</li><li>GP (<em>Global Payments</em>)</li><li>KHB</li><li>OTPSimple (<em>SimplePay</em>)</li><li>PayPalRest</li><li>PayURest</li><li>RaiffeisenUPC</li><li>Saferpay (Worldline)</li></ul></td><td>A tranzakcióhoz kiválasztott fizetési szolgáltató.</td></tr><tr><td><code>ResponseUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Visszatérési URL: tranzakciót követően, rendszerünk erre a címre irányítja vissza a vásárlót.</td></tr><tr><td><code>NotificationUrl</code></td><td>string<br><br>(255 karakter)</td><td>szabadon választható</td><td>Rendszerünk ezen a címen értesíti a kereskedőt a tranzakció státuszának változásáról (<a href="/pages/zSEGWuAWXckAARuGkEC6">URL értesítés</a>).</td></tr><tr><td><code>Amount</code></td><td>number</td><td>szabadon választható</td><td>Bruttó végösszeg amit a vásárló kifizet.<br><br>(Magyar forint (HUF) esetén értéke egész szám.)</td></tr><tr><td><code>UserId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td>A vásárló azonosítója a kereskedő áruházában.</td></tr><tr><td><code>PaymentRegistration</code></td><td>boolean</td><td><ul><li>true</li></ul></td><td>Jelzi a fizetőeszköz-regisztráció indítását.</td></tr><tr><td><code>PaymentRegistrationType</code></td><td><p>string<br></p><p>(3 karakter)</p></td><td><ul><li>CIT</li></ul><p>(a regisztrációra hivatkozó későbbi tranzakciók egykattintásos fizetéseket hoznak létre)</p></td><td>Meghatározza a (PSD2 szabványos) fizetőeszköz-regisztráció típusát.</td></tr><tr><td><code>Info</code></td><td>string</td><td>egyedi értékek</td><td>A vásárlás és a vásárló adatai az erős ügyfél-hitelesítéshez (<a href="/pages/oGVAYdo208ImMYLRri4B">PSD2/SCA</a>).</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th width="279">Paraméter</th><th width="141">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Currency</code></td><td>string<br><br>(3 karakter)</td><td><ul><li>HUF (alapért.)</li><li>EUR</li><li>USD</li><li>...</li></ul></td><td><p>A fizetés devizaneme.<br></p><p>(Értékei fizetési szolgáltatónként és szerződésenként eltérőek lehetnek.)</p></td></tr><tr><td><code>OrderId</code></td><td>string<br><br>(255 karakter)</td><td>egyedi értékek<br><br>(kivéve e-mail címek, illetve személyes adatok)</td><td><p>A megrendelés azonosítója a kereskedő áruházában.</p><p>(Lehetővé teszi a tranzakció visszakeresését, használata erősen javasolt.)</p></td></tr><tr><td><code>Language</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>HU (alapért.)</li><li>EN</li><li>DE</li><li>...</li></ul><p>(ISO 639-1 alapján)</p></td><td>A fizetési felület nyelve.</td></tr><tr><td><code>AutoCommit</code></td><td>string</td><td>• “true” (alapért.)</td><td><p>Jelzi, hogy a bank azonnal vagy később hajtja végre a tranzakciót.<br></p><p>Azonnali terhelés esetén a paraméter átadása elhagyható, ilyenkor a tranzakciót azonnal végrehajtja a bank.</p></td></tr><tr><td><code>Extra</code></td><td>string</td><td>egyedi értékek</td><td>Kiegészítő vagy szolgáltató specifikus adatok (<a href="/pages/XaOHnljbNm5MGxPqLjdh">extra paraméter használata</a>).</td></tr><tr><td><code>PaymentMethods</code></td><td>array</td><td><p></p><ul><li>apple_pay</li><li>google_pay</li><li>bank_card</li><li>...</li></ul></td><td><p>Megadható egyes szolgáltatók esetében, hogy mely fizetési módok legyenek engedélyezve.</p><p></p><p>Amennyiben ez a paraméter üresen marad, abban az esetben a fizetési szolgáltató oldalán az összes elérhető fizetési mód megjelenítésre kerül.</p><p></p><p>A fizetési módok kényszerített megjelenítését nem minden fizetési szolgáltató támogatja.</p><p><a href="https://docs.nevogate.com/segedlet/fizetesi-szolgaltato-specifikus-adatok">Az elérhető fizetési módokkal kapcsolatos információk a Fizetési szolgáltató specifikus adatoknál találhatók.</a></p></td></tr><tr><td><code>ModuleName</code></td><td>string<br><br>(32 karakter)</td><td>egyedi értékek</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. megnevezése.</td></tr><tr><td><code>ModuleVersion</code></td><td>string<br><br>(8 karakter)</td><td>verziószám</td><td>A kereskedő oldalán használt szervizcsomag, programnyelv, keretrendszer, modul, stb. verziószáma.</td></tr></tbody></table>

#### **Mintakód**

Tranzakció inicializálása `Init` kérés használatával:

{% code overflow="wrap" %}

```php
curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Init | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Init' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"Borgun2",
        "ResponseUrl":"https://demo.nevogate.com/response.php",
        "NotificationUrl":"https://www.notification.url/",
        "Amount":100,
        "Currency":"HUF",
        "OrderId":"TEST-ORDER-ID",
        "UserId":"TEST-USER-ID",
        "PaymentRegistration":true,
        "PaymentRegistrationType":"CIT",
        "PaymentMethods":["bank_card"]
    }'
```

{% endcode %}

### **API válasz paraméterek**

Az `Init` kérés eredményét JSON formában válaszoljuk meg. A válasz a következő paramétereket tartalmazza:

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="94">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>TransactionId</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>32 karakter hosszú md5 hash</li></ul><p>Sikertelen inicializálás:</p><ul><li>null</li></ul></td><td>A tranzakció azonosítója a <em>Nevogate</em> rendszerében.</td></tr><tr><td><code>ResultCode</code></td><td>string</td><td><p>Sikeres inicializálás:</p><ul><li>SUCCESSFUL</li></ul><p>Sikertelen inicializálás:</p><ul><li>InactiveStore</li><li>InactiveProvider</li><li>MissingParameter</li><li>MissingRemoteAddress</li><li>UnauthorizedAccess</li><li>UnauthorizedRemoteAddress</li><li>UnknownParameter</li><li>UnknownProvider</li><li>UnknownProviderForStore</li><li>UnknownStore</li><li>WrongApikey</li><li>WrongParameter</li><li>WrongProviderSettings</li></ul><p>Illetve további szolgáltató specifikus eredménykódok.</p></td><td><p>Jelzi a tranzakció inicializálás eredményét.<br><br>Sikertelen inicializálás esetén jelzi a hiba okát.</p><p><br>A felsoroltakon kívül további szolgáltató specifikus eredménykódokat is tartalmazhat.</p></td></tr><tr><td><code>ResultMessage</code></td><td>string</td><td>leírás</td><td>Az egyes <code>ResultCode</code> értékek szöveges magyarázata.</td></tr><tr><td><code>ResponseId</code></td><td>integer</td><td>egyedi értékek</td><td>A válaszüzenet egyedi azonosítója a <em>Nevogate</em> rendszerében.</td></tr></tbody></table>

#### **Mintakód**

Sikeres inicializálásra adott válasz:

{% code overflow="wrap" %}

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

{% endcode %}


# Erős ügyfél-hitelesítés (PSD2/SCA)

Minden elindított tranzakció esetén át kell adni a vásárló és a tranzakció adatait rendszerünknek. Rendszerünk továbbítja ezeket az adatokat a fizetési szolgáltató felé. A vásárló adatainak átadása törvényi kötelezettség a kereskedő számára.

### Működés

Használja az `Info` paramétert az ügyfél adatainak átadásához.

{% hint style="info" %}
A PSD2 *(Payment Services Directive 2)* az Európai Unió egyik irányelve, mely a pénzügyi szolgáltatások piacát szabályozza.

A PSD2-SCA *(Strong Customer Authentication)*, ügyfél-hitelesítési folyamat, mely a visszaélések megelőzését és a kártyacsalások felderítését segíti elő. A tranzakció létrehozása során az erős ügyfél-hitelesítéshez átadott adatokat a tranzakció végstátuszának rendszerünkben történő beállításától számított 48 óra elteltével töröljük rendszerünkből.
{% endhint %}

#### **Adatok lekérdezése**

Használja a `GetInfoData` paramétert az erős ügyfél-hitelesítés során átadott adatok lekérdezéséhez a következő API hívásokban:

* `Details`
* `PaymentLinkDetails`

#### **Adatok átadása az `Info` objektumban**

Készítse elő a vásárló és a tranzakció adatait, majd használja az `Info` több szintű objektumot az adatok átadásához a következő API hívások során:

* `Init`
* `InitRP`
* `PaymentLinkCreate`
* `Payout`

#### **Előkészületek**

Figyeljen a következőkre, hogy az `Info` mező megfelelő értéket vegyen fel:

1. tárolja az adatokat JSON kódolt objektumban
2. kódolja az így kapott string tartalmát base64 segítségével
3. cserélje le a következő karaktereket a base64 kódolt string-ben

<table data-full-width="true"><thead><tr><th align="center">A base64 kódolt string eredeti karaktere</th><th align="center">Csere karakter az Info paraméter számára</th></tr></thead><tbody><tr><td align="center">+</td><td align="center">-</td></tr><tr><td align="center">/</td><td align="center">_</td></tr><tr><td align="center">=</td><td align="center">.</td></tr></tbody></table>

Adja át az így keletkezett karakterláncot az `Info` paraméterben.

#### **Az `Info` objektum felépítése**

Az `Info` objektum számos különböző adatot tartalmaz, melyek két nagy csoportra bonthatók fel, a következő módon:

#### **Vásárlói adatok**

* általános adatok
* bolt specifikus adatok
* böngésző adatok

#### **Rendelési adatok**

* általános adatok
* számlázási adatok
* szállítási adatok
* termékadatok

Táblázatos formában összefoglalva

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="134">Típus</th><th width="111">Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>Info: Customer: General</code></td><td>JSON object</td><td><a href="/pages/BtynQeqy0lkF7xq3SDrc">részletek</a></td><td>A vásárló általános adatai.</td></tr><tr><td><code>Info: Customer: StoreSpecific</code></td><td>JSON object</td><td><a href="/pages/0YzBhkfp4bP9sseSwWKq">részletek</a></td><td>A vásárló bolt specifikus adatai.</td></tr><tr><td><code>Info: Customer: Browser</code></td><td>JSON object</td><td><a href="/pages/cPujR1hAzu63Z6CkT9NY">részletek</a></td><td>A vásárló böngészőjének adatai.</td></tr><tr><td><code>Info: Order: General</code></td><td>JSON object</td><td><a href="/pages/p78tGbdizj0vcVf36N9O">részletek</a></td><td>A megrendelés általános adatai.</td></tr><tr><td><code>Info: Order: BillingData</code></td><td>JSON object</td><td><a href="/pages/XQdQTnkWGBTIX6rbOQ9N">részletek</a></td><td>A számlázás adatai.</td></tr><tr><td><code>Info: Order: ShippingData</code></td><td>JSON object</td><td><a href="/pages/JSZLbizSOZ5tZidVimTY">részletek</a></td><td>A szállítás adatai.</td></tr><tr><td><code>Info: Order: ProductItems</code></td><td>JSON object</td><td><a href="/pages/IAXwI7dDdD0l4PBBFqOy">részletek</a></td><td>A vásárolt termékek adatai.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    ...,
    "Extra": 
    {
        ...
    },
    "Info":
    {
        "Customer":
        {
            "General": { ... },
            "StoreSpecific": { ... },
            "Browser": { ... }
        },
        "Order":
        {
            "General": { ... },
            "BillingData": { ... },
            "ShippingData": { ... },
            "ProductItems": [ { ... }, { ... }, ... ]
        }
    }
}
```

{% endcode %}


# Vásárlói adatok

A `Customer` objektum a megrendelés részletes adatait tartalmazza. A vásárló adatai három különböző típusra bonthatók:

* általános adatok (`General`)
* bolt specifikus adatok (`StoreSpecific`)
* böngésző adatok (`Browser`)


# Általános vásárlói adatok

A `General` objektum a vásárló személyes adatait tartalmazza. Egyes paraméterek átadása kötelező, míg más paraméterek opcionálisak.

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Ip</code></td><td>string<br><br>(45 karakter)</td><td><p>IPv4 vagy IPv6</p><p><strong>Figyelem!</strong> Az IP cím megadására az adott cím forrás országának törvényei irányadóak.</p><p>(Az adott törvényi előírások megismerése és betartása a kereskedő felelőssége.)</p></td><td>A vásárló IP címe.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>HomePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>HomePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Otthoni telefonszám.</td></tr><tr><td><code>MobilePhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>MobilePhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Mobiltelefonszám.</td></tr><tr><td><code>WorkPhoneCc</code></td><td>string<br><br>(3 karakter)</td><td>ITU-E.164 alapján csak számok</td><td>Országkód.</td></tr><tr><td><code>WorkPhone</code></td><td>string<br><br>(maximum 18 karakter)</td><td>egyedi érték</td><td>Munkahelyi telefonszám.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "General":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "Ip":"",
                "HomePhoneCc":"",
                "HomePhone":"",
                "MobilePhoneCc":"",
                "MobilePhone":"",
                "WorkPhoneCc":"",
                "WorkPhone":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Bolt specifikus adatok

A `StoreSpecific` objektum a vásárló adott bolthoz kapcsolódó adatait és statisztikáit tartalmazza. Megadásuk a gyanús aktivitások felderítését segíti elő.

#### Paraméterek

<table data-full-width="true"><thead><tr><th width="364">Paraméter</th><th width="129">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>UpdateDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><p>A vásárlói profil módosításának utolsó dátuma.<br></p><p>(Pl. szállítási cím, számlázási cím, a kártya adatai, stb.)</p></td></tr><tr><td><code>UpdateDateIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (Ezen tranzakció során)</li><li>02 (Kevesebb, mint 30 napja)</li><li>03 (30-60 napja)</li><li>04 (Több, mint 60 napja)</li></ul></td><td>A fenti <code>UpdateDate</code> mező indikátora.</td></tr><tr><td><code>CreationDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárló regisztrációjának időpontja a kereskedő rendszerében.</td></tr><tr><td><code>CreationDateIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (nincs regisztráció, vendég vásárlás)</li><li>02 (regisztráció ezen tranzakció során)</li><li>03 (regisztráció kevesebb, mint 30 napja)</li><li>04 (regisztráció 30-60 napja)</li><li>05 (regisztráció több, mint 60 napja)</li></ul></td><td>A fenti <code>CreationDate</code> mező indikátora.</td></tr><tr><td><code>PasswordChangeDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>A vásárlói jelszó módosításának utolsó dátuma.</td></tr><tr><td><code>PasswordChangeDateIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (a jelszó még egyszer sem változott meg)</li><li>02 (a jelszó megváltozott az aktuális tranzakció során)</li><li>03 (a jelszó kevesebb, mint 30 napja változott meg)</li><li>04 (a jelszó 30-60 napja változott meg)</li><li>05 (a jelszó több, mint 60 napja változott meg)</li></ul></td><td>A fenti <code>PasswordChangeDate</code> mező indikátora.</td></tr><tr><td><code>AuthenticationTimestamp</code></td><td><p>string</p><p>(19 karakter)</p></td><td>ÉÉÉÉ-HH-NN ÓÓ:PP:MM</td><td>A vásárló bejelentkezésének időpontja az adott tranzakció előtt.</td></tr><tr><td><code>AuthenticationMethod</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (vendég vásárlás, nem történt belépés)</li><li>02 (a kereskedő rendszere azonosította a vásárlót bejelentkezésnél)</li><li>03 (az egységesített beléptetés azonosította a vásárlót bejelentkezésnél (Federated ID))</li><li>04 (a kártya kibocsátó hitelesítette a vásárlót bejelentkezésnél)</li><li>05 (3rd party vásárlói azonosítás bejelentkezésnél)</li><li>06 (FIDO vásárlói azonosítás bejelentkezésnél)</li></ul></td><td>A vásárló bejelentkezésének módja a kereskedő rendszerébe az adott tranzakció előtt.</td></tr><tr><td><code>ChallengeIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (nincs preferencia a vásárló azonosítására)</li><li>02 (nincs azonosítás kérés)</li><li>03 (azonosítás kérése: a kereskedő preferenciája szerint)</li><li>04 (azonosítás kérése: megbízás - csak a bankkártya első regisztrációjához kapcsolódó tranzakciónál szükséges átadni)</li></ul></td><td>Vásárló azonosításának módja a fizetési tranzakció során.</td></tr><tr><td><code>ShippingAddressFirstUse</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Az adott szállítási cím használatának első dátuma.</td></tr><tr><td><code>ShippingAddressFirstUseIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (az adott szállítási cím ezen tranzakció során került először megadásra)</li><li>02 (az adott szállítási cím kevesebb, mint 30 napja került először megadásra)</li><li>03 (az adott szállítási cím 30-60 napja került először megadásra)</li><li>04 (az adott szállítási cím több, mint 60 napja került először megadásra)</li></ul></td><td>A fenti <code>ShippingAddressFirstUse</code> mező indikátora.</td></tr><tr><td><code>CardTransactionsLastDay</code></td><td><p>number</p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott kártya tokenizációs kísérleteinek száma az elmúlt 24 órában.</td></tr><tr><td><code>CardCreationDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td><ul><li>Tokenizált kártyás vásárlás esetén az adott kártya mentésének időpontja.</li><li>Más esetben a tranzakció dátuma</li></ul></td></tr><tr><td><code>CardCreationDateIndicator</code></td><td><p>string</p><p>(2 karakter)</p></td><td><ul><li>01 (nincs kártya mentés - vendég vásárlás)</li><li>02 (a kártyát az aktuális tranzakció során mentették)</li><li>03 (a kártyát kevesebb, mint 30 napja mentették)</li><li>04 (a kártyát 30-60 napja mentették)</li><li>05 (a kártyát több, mint 60 napja mentették)</li></ul></td><td>A fenti <code>CardCreationDate</code> mező indikátora.</td></tr><tr><td><code>TransactionsLastDay</code></td><td><p>number</p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt 24 órában.</td></tr><tr><td><code>TransactionsLastYear</code></td><td><p>number</p><p>(3 karakter)</p></td><td>pozitív egész szám</td><td>Az adott vásárló sikeres és sikertelen fizetési próbálkozásainak száma az elmúlt egy évben.</td></tr><tr><td><code>PurchasesLastSixMonths</code></td><td>number<br><br>(4 karakter)</td><td>pozitív egész szám</td><td>Az adott vásárló sikeres tranzakcióinak száma az elmúlt 6 hónap során.</td></tr><tr><td><code>SuspiciousActivity</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (nem észlelt)</li><li>02 (gyanús aktivitás)</li></ul></td><td>Jelzi a vásárló gyanús tevékenységének észlelését a kereskedő áruházában.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "StoreSpecific":
            {
                "UpdateDate":"",
                "UpdateDateIndicator":"",
                "CreationDate":"",
                "CreationDateIndicator":"",
                "PasswordChangeDate":"",
                "PasswordChangeDateIndicator":"",
                "AuthenticationTimestamp":"",
                "AuthenticationMethod":"",
                "ChallengeIndicator":"",
                "ShippingAddressFirstUse":"",
                "ShippingAddressFirstUseIndicator":"",
                "CardTransactionsLastDay":"",
                "CardCreationDate":"",
                "CardCreationDateIndicator":"",
                "TransactionsLastDay":"",
                "TransactionsLastYear":"",
                "PurchasesLastSixMonths":"",
                "SuspiciousActivity":""
            },
            ...
        }
```

{% endcode %}


# Böngésző adatok

A `Browser` objektum a vásárláshoz használt böngészőből kinyerhető adatokat tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>AcceptHeader</code></td><td>string<br><br>(2048 karakter)</td><td><p>MIME típusok és altípusok</p><p>(Például: text/html, image/*, <em>/</em>, stb.)</p></td><td>A böngésző által értelmezhető tartalom típusok.</td></tr><tr><td><code>JavaEnabled</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>1 (Java engedélyezett)</li><li>0 (Java nem engedélyezett)</li></ul></td><td>Java használata a böngészőben.</td></tr><tr><td><code>Language</code></td><td>string<br><br>(8 karakter)</td><td><p>IETF BCP47 által definiált formátumban</p><p>(Például: "hu", "hu-HU", "en", "en-US", stb.)</p></td><td><p>A böngésző nyelve.<br></p><p>(A <code>navigator.language</code> értéke.)</p></td></tr><tr><td><code>ColorDepth</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>1 (1 bit)</li><li>4 (4 bit)</li><li>8 (8 bit)</li><li>15 (15 bit)</li><li>16 (16 bit)</li><li>24 (24 bit)</li><li>32 (32 bit)</li><li>48 (48 bit)</li></ul></td><td>A böngésző által használt színmélység.</td></tr><tr><td><code>ScreenHeight</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak magassága.</td></tr><tr><td><code>ScreenWidth</code></td><td>string<br><br>(6 karakter)</td><td>pozitív egész szám</td><td>A böngésző ablak szélessége.</td></tr><tr><td><code>TimeZone</code></td><td>string<br><br>(5 karakter)</td><td>egész szám</td><td><p>A vásárló saját időzónája és a UTC (világidő) idő közötti különbség percben megadva.<br></p><p>(A <code>dateObj.getTimezoneOffset()</code> értéke.)</p></td></tr><tr><td><code>UserAgent</code></td><td>string<br><br>(2048 karakter)</td><td>egyedi érték</td><td>A használt böngésző azonosítására szolgáló adatok.</td></tr><tr><td><code>WindowSize</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (250 x 400)</li><li>02 (390 x 400)</li><li>03 (500 x 600)</li><li>04 (600 x 400)</li><li>05 (teljes képernyő)</li></ul></td><td><p>A fizetés hitelesítését végző szolgáltató ablakának mérete. Az ablak tartalmát ehhez a mérethez kell igazítani a legjobb felhasználói élmény érdekében. (A hitelesítő felület (3DSecure) megjelenítésének paramétere.)<br></p><p>(A fizetési hitelesítő (ACS) szerepét jellemzően a kártyakibocsátó bank tölti be. Az ACS itt az Access Control Server-t jelöli.)</p></td></tr></tbody></table>

#### Mintakód

{% code overflow="wrap" %}

```php
{
    "Info":
    {
        "Customer":
        {
            "Browser":
            {
                "AcceptHeader":"",
                "JavaEnabled":"",
                "Language":"",
                "ColorDepth":"",
                "ScreenHeight":"",
                "ScreenWidth":"",
                "TimeZone":"",
                "UserAgent":"",
                "WindowSize":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Rendelési adatok

Az `Order` objektum a megrendelés részletes adatait tartalmazza. A rendelés adatainak négy különböző típusa a következő:

* általános rendelési adatok (`General`)
* számlázási adatok (`BillingData`)
* szállítási adatok (`ShippingData`)
* termékadatok (`ProductItems`)


# Általános rendelési adatok

A `General` objektum a vásárlás általános adatait tartalmazza.

#### Paraméterek

<table data-full-width="true"><thead><tr><th>Paraméter</th><th width="142">Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>DeliveryEmail</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum<br><br>(maximum 1 db)</td><td>Elektronikus kézbesítés esetén az email cím (vagy a felhasználói fiókhoz tartozó email cím) amelyre az áru érkezik.</td></tr><tr><td><code>DeliveryTimeFrame</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (elektronikus kézbesítés (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb. esetén))</li><li>02 (kézbesítésre a megrendelés napján kerül sor)</li><li>03 (kézbesítésre éjszaka kerül sor)</li><li>04 (a kézbesítés 2 vagy több napot vesz igénybe)</li></ul></td><td>A kézbesítés ideje.</td></tr><tr><td><code>GiftCardAmount</code></td><td>number<br><br>(15 karakter)</td><td><p>pozitív szám, maximum 2 tizedesjeggyel<br></p><p>(Magyar forint (HUF) esetén értéke egész szám, tizedesjegyek nélkül.)</p></td><td>Utalványról vagy ajándékkártyáról felhasznált összeg.</td></tr><tr><td><code>GiftCardCount</code></td><td>number<br><br>(2 karakter)</td><td>pozitív egész szám</td><td>Utalvánnyal vagy ajándékkártyával kifizetett rendelések száma.</td></tr><tr><td><code>GiftCardCurrency</code></td><td>string<br><br>(3 karakter)</td><td>ISO 4217 által definiált formátum</td><td>Az utalvány vagy ajándékkártya pénzneme.</td></tr><tr><td><code>PreorderDate</code></td><td><p>string</p><p>(10 karakter)</p></td><td>ÉÉÉÉ-HH-NN</td><td>Előrendelés esetén az áru elérhetőségének várható dátuma.</td></tr><tr><td><code>Availability</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (a rendelést azonnal teljesíti a kereskedő)</li><li>02 (a rendelést egy későbbi időpontban teljesíti a kereskedő)</li></ul></td><td>Jelzi, hogy a rendelés azonnal (készletről) vagy egy későbbi időpontban kerül teljesítésre.</td></tr><tr><td><code>ReorderItems</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (az adott terméket először rendelik meg)</li><li>02 (az adott terméket ismételten rendelik meg)</li></ul></td><td>Jelzi, hogy az adott terméket első alkalommal vagy ismételten rendelik meg.</td></tr><tr><td><code>ShippingMethod</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék szállítása a számlázási címre)</li><li>02 (termék szállítása egy korábban megadott címre)</li><li>03 (termék szállítás a számlázási címtől eltérő címre)</li><li>04 (termék személyes, bolti átvétele esetén)</li><li>05 (termék digitális kézbesítése esetén (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))</li><li>06 (a termék utazásra vagy esemény látogatására szóló jegy)</li><li>07 (egyéb termékek esetén (játékok, digitális szolgáltatások, feliratkozások, stb.))</li></ul></td><td>A szállítás módja vagy a kézbesítés jellege.</td></tr><tr><td><code>AddressMatchIndicator</code></td><td>string<br><br>(1 karakter)</td><td><ul><li>0 (eltérő számlázási és szállítási cím)</li><li>1 (megegyező számlázási és szállítási cím)</li></ul></td><td>Jelzi, hogy a számlázási cím és a szállítási cím megegyezik vagy eltér egymástól.</td></tr><tr><td><code>DifferentShippingName</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (megegyező számlázási és szállítási név)</li><li>02 (eltérő számlázási és szállítási név)</li></ul></td><td>Jelzi, hogy a számlázási név és a szállítási név megegyezik vagy eltér egymástól.</td></tr><tr><td><code>TransactionType</code></td><td>string<br><br>(2 karakter)</td><td><ul><li>01 (termék/szolgáltatás vásárlása)</li><li>03 (ellenőrzés/hitelesítés)</li><li>10 (számla finanszírozás)</li><li>11 (kvázi készpénz ügylet, pl. pénzutalvány, utazási csekk, deviza, szelvény, stb.)</li><li>28 (egyenleg feltöltés)</li><li>stb.</li></ul></td><td>A tranzakció típusa.<br><br>(Az ISO 8583 lista szerint.)</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "General":
            {
                "DeliveryEmail":"",
                "DeliveryTimeFrame":"",
                "GiftCardAmount":"",
                "GiftCardCount":"",
                "GiftCardCurrency":"",
                "PreorderDate":"",
                "Availability":"",
                "ReorderItems":"",
                "ShippingMethod":"",
                "AddressMatchIndicator":"",
                "DifferentShippingName":"",
                "TransactionType":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Számlázási adatok

A `BillingData` objektum a számlázási adatokat tartalmazza, ezek átadása kötelező. Viszont a számlázási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td>Keresztnév.<br><br>(Cég esetén cégnév.)</td></tr><tr><td><code>LastName</code></td><td>string<br><br>(45 karakter)</td><td>egyedi értékek</td><td><p>Vezetéknév.</p><p>(Cég esetén cégnév.)</p></td></tr><tr><td><code>Email</code></td><td>string<br><br>(254 karakter)</td><td>szabványos email formátum (maximum 1 db)</td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td>string<br><br>(18 karakter)</td><td>számok</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.</p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím első sora.<br><br>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</td></tr><tr><td><code>PostalCode</code></td><td>string<br><br>(16 karakter)</td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p><br>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód</p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyarországon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td>string<br><br>(50 karakter)</td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        {    
            "BillingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}


# Szállítási adatok

A `ShippingData` objektum a szállítási adatokat tartalmazza, átadása kötelező postázás vagy futárszolgálat igénybevétele esetén. Ugyanakkor a szállítási adatokhoz kapcsolódó kiegészítő elemek opcionálisak (pl. a cím megadása kötelező, viszont a cím 2. és 3. sorának megadása opcionális).

{% hint style="warning" %}
Személyes átvételnél és digitális kézbesítés esetén a szállítási adatok megadására nincs szükség. Ilyenkor jelezze a szállítás módját vagy a kézbesítés jellegét a `General` objektum `ShippingMethod` paraméterében.<br>

Az átadható értékek ilyen esetekben:

* 04 (termék személyes, bolti átvétel)
* 05 (termék digitális kézbesítése (szolgáltatások, szoftverek, ajándékkártyák, utalványok, stb.))
  {% endhint %}

#### **Kötelező paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>FirstName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Keresztnév.</td></tr><tr><td><code>LastName</code></td><td><p>string</p><p>(45 karakter)</p></td><td>egyedi értékek</td><td>Vezetéknév.</td></tr><tr><td><code>Email</code></td><td><p>string</p><p>(254 karakter)</p></td><td><p>szabványos email formátum</p><p>(maximum 1 db)</p></td><td>Email cím.</td></tr><tr><td><code>Phone</code></td><td><p>string</p><p>(18 karakter)</p></td><td>számokek</td><td>Telefonszám.</td></tr><tr><td><code>City</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Város.</td></tr><tr><td><code>Country</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>Ország vagy állam.</td></tr><tr><td><code>CountryCode2</code></td><td><p>string</p><p>(2 karakter)</p></td><td><p>Alpha-2 formátum</p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “HU”)</p></td></tr><tr><td><code>Line1</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td><p>A cím első sora.<br></p><p>(közterület neve, típusa, házszám, emelet, ajtó, helyrajzi szám, stb.)</p></td></tr><tr><td><code>PostalCode</code></td><td><p>string</p><p>(16 karakter)</p></td><td>egyedi értékek</td><td>Irányítószám.</td></tr></tbody></table>

#### **Opcionális paraméterek**

<table data-full-width="true"><thead><tr><th>Paraméter</th><th>Típus</th><th>Érték</th><th>Leírás</th></tr></thead><tbody><tr><td><code>PhoneCc</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>kizárólag számok</p><p>(ITU-E.164 alapján)</p></td><td>Országkód.</td></tr><tr><td><code>CountryCode1</code></td><td><p>string</p><p>(3 karakter)</p></td><td><p>numerikus formátum<br></p><p>(ISO 3166-1 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Magyarország kódja “348”)</p></td></tr><tr><td><code>CountryCode3</code></td><td><p>string</p><p>(6 karakter)</p></td><td><p>földrajzi kód<br></p><p>(ISO 3166-2 alapján)</p></td><td><p>Országkód.<br></p><p>(pl. Budapest kódja Magyaroszgágon “HU-BU”)</p></td></tr><tr><td><code>Line2</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím második sora.</td></tr><tr><td><code>Line3</code></td><td><p>string</p><p>(50 karakter)</p></td><td>egyedi értékek</td><td>A cím harmadik sora.</td></tr></tbody></table>

#### **Mintakód**

{% code overflow="wrap" %}

```php
{
    "Info": 
    {
        "Order":
        { 
            "ShippingData":
            {
                "FirstName":"",
                "LastName":"",
                "Email":"",
                "PhoneCc":"",
                "Phone":"",
                "City":"",
                "Country":"",
                "CountryCode1":"",
                "CountryCode2":"",
                "CountryCode3":"",
                "Line1":"",
                "Line2":"",
                "Line3":"",
                "PostalCode":""
            },
            ...
        }
    }
}
```

{% endcode %}




---

[Next Page](/llms-full.txt/1)