Könyvelés támogatás és tranzakciók pénzügyi elszámolása (PayBook)

A PayBook szolgáltatás használatával lekérdezheti egy virtuális terminálon keletkezett tranzakciók pénzügyi kimutatásait. A PayBook azonosítja a kereskedő és a fizetési szolgáltató között létrejött pénzügyi elszámoláshoz tartozó tranzakciókat rendszerünkben, ezzel megkönnyíti a rendszerünkben keletkezett tranzakciók pénzügyi elszámolását.

A lekérdezés időzítése

Felhívjuk a figyelmét, hogy egy adott nap kimutatásait csupán egy nappal később töltjük le a fizetési szolgáltatóktól. A letöltést és feldolgozást rendszerünk automatikusan végrehajtja, amennyiben az adott fizetési szolgáltató biztosítja a kimutatások elérését (pl. FTP tárhelyen, vagy API-n keresztül). A feldolgozás biztos lefutásához a kereskedőnek célszerű a lekérdezés pillanatához képest legalább 2 nappal korábbi kimutatásokat lekérdezni.

A kiegészítő szolgáltatásokat, így a PayBook használatát is külön kell kérelmezni ügyfélszolgálatunkon, amit a következő címre írt üzenettel tehet meg:

[e-mail]

A pénzügyi kimutatások lekérdezése a következő fizetési szolgáltatók esetén érhető el:

• Teya RPG

• CIB Bank

• Global Payments

• K&H SZÉP Kártya (manuális feltöltés)

• MBH SZÉP Kártya (manuális feltöltés)

• OTP SZÉP Kártya

• PayPal REST

• PayU REST

• SimplePay

• Viva Wallet (manuális feltöltés)

• Worldline - Saferpay

Egyes szolgáltatók esetén a kimutatásokat kizárólag manuális feltöltés után tudjuk feldolgozni. Manuális feltöltéshez előbb töltse le a kimutatást az adott fizetési szolgáltató felületéről (ha azt nem kapta meg email-ben), majd töltse fel ezeket a kimutatásokat a PayBook admin felületén, amit a következő hivatkozáson is elérhet:

PayBook - Kimutatás feltöltése (tesztrendszer)

PayBook - Kimutatás feltöltése (éles rendszer)

A manuális feltöltéshez kövesse ezeket a lépéseket:

1. Válassza ki a kimutatáshoz tartozó boltot, szolgáltatót és a terminált a legördülő menükből,

2. adja meg meg a fizetési szolgáltatótól letöltött kimutatás létrehozásának idejét,

3. majd válassza ki a megfelelő kimutatást és töltse fel rendszerünkbe.

A korábban feltöltött és feldolgozott kimutatások megtekintésére is lehetőség nyílik az PayBook admin felületen. A megfelelő szűréshez a fenti lépéseken túl ki kell választani a pénznemet és opcionálisan megadható egy kimutatáshoz tartozó banki utalási közlemény is. A kimutatások áttekintését erről a hivatkozásról is elérheti:

PayBook - Kimutatások áttekintése

Működés

Használja a Settlement funkciót az adott terminálon létrejött pénzügyi kimutatások lekérdezéséhez.

API kérés paraméterek

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

Művelet	HTTP kérés	Adatok
Settlement	POST	method=Settlement json={JSON encode-olt paraméterek}

Az API kérésekhez kapcsolódó paramétereket két táblázatban 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

Kötelező paraméterek

Paraméter	Típus	Érték	Leírás
StoreName	string	A BIG FISH Payment Gateway szerződésben kerül meghatározásra.	Meghatározza a lekérdezett kimutatásokhoz tartozó kereskedői boltot.
ProviderName	string	Borgun2 (Teya RPG) CIB GP (Global Payments) KHBSZEP MKBSZEP OTP OTPSimple (SimplePay) PayPalRest PayURest RawMBHSZEP RawOTPSZEP Saferpay (Worldline) VivaWallet	A kimutatáshoz/elszámoláshoz kiválasztott fizetési szolgáltató.
TerminalId	string	egyedi értékek	A kereskedő virtuális termináljának (VPOS) egyedi azonosítója.
TransactionCurrency	string (3 karakter)	HUF EUR USD ...	Az adott terminálhoz beállított devizanem (azonos azzal a devizanemmel amiben a tranzakció létrejött).
Limit	number	maximum 1000 tétel	Az adott lekérdezés során visszaadott tételek maximális száma. (Opcionálisan használhatja az Offset paramétert további tételek lekérdezésére, amennyiben az aktuális lekérdezéshez több tétel tartozik, mint a Limit paraméterben megadott érték.)

Opcionális paraméterek

Felhívjuk figyelmét, hogy a következő paraméterek valamelyikének megadása opcionálisan kötelező:

• SettlementDate

• TransferNotice

• SettlementBatchId

Paraméter	Típus	Érték	Leírás
SettlementDate	string (10 karakter)	dátum, a következő formátumban: ÉÉÉÉ-HH-NN	A kimutatás létrehozásának ideje. Megadása kötelező, amennyiben a TransferNotice és a SettlementBatchId paraméterek egyike sem kerül átadásra.
TransferNotice	string	egyedi értékek (SimplePay esetén, az utalási közleményben található, első szóközt követő rész.)	A bank utalási közleménye. Megadása kötelező, amennyiben a SettlementDate és a SettlementBatchId paraméterek egyike sem kerül átadásra.
SettlementBatchId	number (8 karakter)	egyedi érték	Köteg azonosító. Megadása kötelező, amennyiben a SettlementDate és a TransferNotice paraméterek egyike sem kerül átadásra.
GetBatches	boolean	true (alapért.) false	Meghatározza, hogy a lekérdezett válasz tartalmazzon vagy ne tartalmazzon köteg adatokat.
GetItems	boolean	true (alapért.) false	Meghatározza, hogy a lekérdezett válasz tartalmazzon vagy ne tartalmazzon tétel adatokat.
Offset	number	egyedi értékek	Jelzi a lekérdezett tételek számához tartozó eltolást. Abban az esetben, amikor egy kötegben a tételek száma (NumberOfItems) meghaladja a lekérdezésben beállított limitet (Limit), használja az eltolást a limitet meghaladó további tételek lekérdezéséhez.

Mintakód

Kimutatás lekérdezése Settlement használatával:

curl --url 'https://system-test.paymentgateway.hu/api/payment/' \
  --user 'sdk_test:86af3-80e4f-f8228-9498f-910ad' \
  --user-agent 'Settlement | merchant-store.com | PHP | 7.3.0' \
  --request 'POST' \
  --data 'method=Settlement' \
  --data 'json=
    {
        "StoreName":"sdk_test",
        "ProviderName":"OTPSimple",
        "TerminalId":"P000401",
        "SettlementDate":"2019-03-25",
        "TransactionCurrency":"HUF",
        "Limit":1000
    }'

API válasz paraméterek

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

Paraméter	Típus	Érték	Leírás
Data	JSON string	egyedi érték	Sikeres lekérdezés esetén tartalmazza a köteg (Batches) és tétel (Items) adatokat.
ResultCode	string	SUCCESSFUL (a pénzügyi kimutatás lekérdezése sikeres volt) Hiba esetén a következő eredménykódok jelölik a hiba okát: FunctionNotImplemented InactiveStore MissingParameter MissingRemoteAddress UnauthorizedAccess UnauthorizedRemoteAddress UnknownProvider UnknownProviderForStore UnknownStore WrongApikey WrongParameter	Jelzi a pénzügyi lekérdezés eredményét.
ResultMessage	string	leírás	Az egyes ResultCode értékek szöveges magyarázata.
ResponseId	integer	egyedi értékek	A válaszüzenet egyedi azonosítója a BIG FISH Payment Gateway rendszerében.

Mintakód

A fenti Settlement kérésre adott válasz:

{
    "Data":"
    {
        \"Batches\":[
            {
                \"SettlementBatchId\":\"5\",
                \"SettlementDate\":\"2019-03-25\",
                \"ProviderName\":\"OTPSimple\",
                \"TerminalId":\"P000401\",
                \"TransferNotice\":\"P000401_84_060426\",
                \"NumberOfItems\":\"5\",
                \"TransactionCurrency\":\"HUF\",
                \"TotalTransactionNonRefundAmount\":\"6000.00\",
                \"TotalTransactionRefundAmount\":\"-700.00\",
                \"TotalTransactionAmount\":\"5300.00\",
                \"SettlementCurrency\":\"HUF\",
                \"TotalSettlementNonRefundAmount\":\"6000.00\",
                \"TotalSettlementRefundAmount\":\"-700.00\",
                \"TotalSettlementAmount\":\"5300.00\",
                \"TotalSettlementCommissionAmount\":\"-60.00\",
                \"TotalSettlementCommissionReducedAmount\":\"5240.00\",
                \"TotalChargebackAmount\":null,
                \"PreviousAccumulatedAmount\":null,
                \"CurrentAccumulatedAmount\":null,
                \"TransferredAmount\":\"5240.00\"
            }
        ],
        \"Items\":[
            {
                \"SettlementBatchId\":\"5\",
                \"SettlementDate\":\"2019-03-25\",
                \"ProviderName\":\"OTPSimple\",
                \"TerminalId\":\"P000401\",
                \"TransferNotice\":\"P000401_84_060426\",
                \"SettlementFileName\":\"P000401_84_060426.csv\",
                \"SettlementId\":null,
                \"AuthCode\":\"\",
                \"SettlementTransactionId\":\"99573216\",
                \"ProviderTransactionId\":\"99573216\",
                \"TransactionId\":\"aaca335d825d6c2dde6a8c43ef663b55\",
                \"OrderId\":\"PMGW-ORDER-1\",
                \"UserId\":\"PMGW-USER-1\",
                \"StoreName\":\"sdk_test\",
                \"TransactionCreatedTime\":\"2019-03-21 07:48:20\",
                \"ProviderTransactionCreatedTime\":\"2019-03-21 07:48:20\",
                \"TransactionCurrency\":\"HUF\",
                \"TransactionAmount\":\"1000\",
                \"SettlementCurrency\":\"HUF\",
                \"SettlementAmount\":\"1000\",
                \"SettlementCommissionAmount\":\"-10\",
                \"SettlementCommissionReducedAmount\":\"990\"
            },
            {
                \"SettlementBatchId\":\"5\",
                \"SettlementDate\":\"2019-03-25\",
                \"ProviderName\":\"OTPSimple\",
                \"TerminalId\":\"P000401\",
                \"TransferNotice\":\"P000401_84_060426\",
                \"SettlementFileName\":\"P000401_84_060426.csv\",
                \"SettlementId\":null,
                \"AuthCode\":\"\",
                \"SettlementTransactionId\":\"99573217\",
                \"ProviderTransactionId\":\"99573216\",
                \"TransactionId\":\"aaca335d825d6c2dde6a8c43ef663b55\",
                \"OrderId\":\"PMGW-ORDER-1\",
                \"UserId\":\"PMGW-USER-1\",
                \"StoreName\":\"sdk_test\",
                \"TransactionCreatedTime\":\"2019-03-21 07:48:20\",
                \"ProviderTransactionCreatedTime\":\"2019-03-21 07:48:32\",
                \"TransactionCurrency\":\"HUF\",
                \"TransactionAmount\":\"-300\",
                \"SettlementCurrency\":\"HUF\",
                \"SettlementAmount\":\"-300\",
                \"SettlementCommissionAmount\":\"0\",
                \"SettlementCommissionReducedAmount\":\"-300\"
            },
            ...
        ]
    }",
    "ResultCode": "SUCCESSFUL",
    "ResultMessage": null,
    "ResponseId": "3202109280600047729"
}