A Webáruháznak kizárólag a BIG FISH Payment Gateway központi tranzakciós szerveréhez kell kapcsolódnia, amely elvégzi a tranzakciók végrehajtásával kapcsolatos kommunikációs feladatokat a Webáruház által választott fizetési szolgáltatókkal.


Payment Gateway SDK

A Payment Gateway SDK egyszerűsíti és meggyorsítja a fizetési szolgáltatások beépítését a weboldalakba, vagy alkalmazásokba. Az alábbi SDK-k tartalmazzák a függvénykönyvtárakat, amelyek szükségesek a Payment Gateway funkcióinak eléréséhez.

Technológia Letöltés
PHP SDK GitHub
Packagist
iOS SDK Letöltés (.zip)
Android SDK Letöltés (.zip)

A PHP SDK konfigurálása:

$config = new \BigFish\PaymentGateway\Config();
	
$config->storeName = "storeName";
$config->apiKey = "apiKey";
$config->encryptPublicKey = "publicKey"; //Bizonyos szolgáltatásoknál szükséges (MKB SZÉP Kártyás fizetés, OTP kétszereplős fizetés)
$config->testMode = true;
	
BigFish\PaymentGateway::setConfig($config);

A mobil SDK-k konfigurációs állományaiban két fontos beállítás szerepel: [BIGFISH_PAYMENTGATEWAY_STORE_NAME] (bolt azonosító) és [BIGFISH_PAYMENTGATEWAY_API_KEY] (API kulcs).

Bolt azonosító és API kulcs igényléséhez kattintson ide!

Payment Gateway DEMO

A demo kód elérhető a GitHub-on: https://github.com/bigfish-hu/payment-gateway-demo

A részletes DEMO kódrészleteket tartalmazó fejlesztő segédlet elérhető az alábbi linken: http://demo.paymentgateway.hu

eCommerce csomagok

eCommerce motor Csomag elérhetősége
Drupal Commerce http://drupal.org/project/commerce_bigfish_paymentgateway
Drupal UberCart (sandbox) https://www.drupal.org/sandbox/bigfishdev/2059889
Magento https://www.magentocommerce.com/magento-connect/big-fish-payment-gateway.html
OpenCart (1.5.4.1) opencart_bigfish_paymentgateway.zip
OpenCart (2.x.x.x) http://www.opencart.com/index.php?route=extension/extension/info&extension_id=25317
PrestaShop bigfishpaymentgateway_1.0.1.zip
VirtueMart (Joomla) /fejlesztoknek/virtuemart/
WooCommerce (WordPress) https://wordpress.org/plugins/big-fish-payment-gateway-for-woocommerce/
ZenCart https://www.zen-cart.com/downloads.php?do=file&id=2005

Payment Gateway API

Amennyiben más technológiával szeretnéd használni a Payment Gateway-t, használhatod az alábbi API-t:

REST API

Authentikáció

HTTP basic access authentication: Wikipédia szócikk.

Használat

Azaz a HTTP REQUEST header-ben kell küldeni:

Authorization: Basic Ym9sdG5ldmU6NGQ4NDgtYzhhYzAtMmJkZTctNWE3YzktNDcxZGY=

ahol az Ym9sdG5ldmU6NGQ4NDgtYzhhYzAtMmJkZTctNWE3YzktNDcxZGY= PHP esetében így állítható elő:

base64_encode("boltneve:4d848-c8ac0-2bde7-5a7c9-471df")

Bolt azonosító és API kulcs igényléséhez kattintson ide!

A fizetési tranzakció folyamata

  • A vásárló véglegesíti a megrendelést a Webáruházban és elektronikus fizetést választ.
  • A Webáruház saját adatbázisában rögzíti a megrendelést úgy, hogy a fizetés függőben van.
  • A Webáruház a háttérben jelzi az új fizetési tranzakciót a Payment Gateway-nek (Init).
  • A Payment Gateway visszaigazolja a sikeres tranzakció kezdeményezést a Webáruháznak.
  • A Webáruház letárolja a Payment Gateway-től kapott tranzakció azonosítót és átküldi a vásárlót a Payment Gateway-hez fizetni (Start).
  • A Payment Gateway lebonyolítja a fizetést a választott szolgáltató és a vásárló között.
  • A Payment Gateway visszaigazolja a tranzakció eredményét a vásárlónak.
  • A Payment Gateway visszaküldi a vásárlót a Webáruház oldalára.
  • A Webáruház lekérdezi a tranzakció eredményét a Payment Gateway-től (Result).
  • A Webáruház – a tranzakció eredményétől függően – sikeres fizetés esetén véglegesíti a megrendelést, vagy sikertelen fizetés esetén felkínálja az újrapróbálkozás lehetőségét, illetve alternatív fizetési módokat ajánl a vásárló részére.

Payment Gateway funkciók

1. Init

Az Init funkció az új fizetési tranzakciók kezdeményezésére szolgál. A Webáruház és a Payment Gateway közötti kommunikáció a háttérben, azaz a vásárló elől rejtve zajlik.

1.1. Példa a Webáruházból indított tranzakció inicializálásra (PHP SDK)

$request = new \BigFish\PaymentGateway\Request\Init();

$request->setProviderName("CIB") // A felhasználó által választott fizetési mód
	->setResponseUrl("http://www.webaruhaz.hu/payment_gateway_valasz_url.php") // Visszatérési URL
	->setAmount(250) // Összeg
	->setCurrency("HUF") // Valutanem
	->setOrderId("order123") // Megrendelés azonosító
	->setUserId("user123") // Vásárló / felhasználó azonosító
	->setLanguage("HU"); // Nyelv

$response = \BigFish\PaymentGateway::init($request);
	

1.2. REST hívás (HTTP POST)

method=Init&json={"StoreName":"boltneve","ProviderName":"CIB","ResponseUrl":"http:\/\/www.webaruhaz.hu\/payment_gateway_valasz_url.php","Amount":"250","Currency":"HUF","OrderId":"order123","UserId":"user123","Language":"HU"}

1.3. A paraméterek magyarázata

Paraméter Kötelező? Alapértelmezett érték Típus Értékkészlet
ProviderName Kötelező Nincs Szöveges (max. 20 karakter)
  • ABAQOOS
  • Borgun
  • CIB
  • Escalion
  • FHB
  • KHB
    (K&H Bank)
  • KHBSZEP
  • MKBSZEP
  • OTP
    (bankkártya, SZÉP kártya)
  • OTP2
    (kétszereplős)
  • OTPay
  • OTPayMP
  • OTPMultipont
  • OTPSimple
  • OTPSimpleWire
  • PayPal
  • PayU2
  • PSC
    (Paysafecard)
  • QPAY
  • Saferpay
  • SMS
  • Sofort
  • UniCredit
Ez a paraméter határozza meg a választott fizetési szolgáltatót.
 
StoreName Kötelező Nincs Szöveges (max. 20 karakter) Szerződéskötéskor kerül meghatározásra
A kereskedő egyedi azonosítója a Payment Gateway-ben.
 
ResponseUrl Opcionális vagy Kötelező Beállítástól függ Szöveges (max. 255 karakter) Szabadon választott
Az az URL cím, ahová a Payment Gateway visszaküldi a vásárlót a tranzakciót követően. Lehetőség van beállítani az alapértelmezett válaszcímet a Payment Gateway adminisztrátori felületén, ha be van állítva, nem szükséges minden tranzakció indításnál kitölteni.
 
Amount Kötelező Nincs Pozitív valós szám Szabadon választott
A vásárló által fizetendő bruttó végösszeg.
 
OrderId Opcionális Nincs Szöveges max. 255 karakter) Szabadon választott
A megrendelés kereskedőnél lévő sorszáma, használata erősen javasolot a tranzakciók több szempont szerinti visszakeresése miatt.
 
UserId Opcionális Nincs Szöveges (max. 255 karakter) Szabadon választott
A vásárló kereskedőnél lévő azonosítója, használata erősen javasolot a tranzakciók több szempont szerinti visszakeresése miatt.
 
Currency Opcionális HUF Szöveges (3 karakter)
  • HUF
  • EUR
  • USD
Valutanem (fizetési szolgáltatónként eltérő lehet az értékkészlet).
 
Language Opcionális HU Szöveges (2 karakter)
  • HU
  • EN
  • DE
A fizető felület nyelvét határozza meg.
 
NotificationUrl Opcionális Nincs Szöveges (max. 255 karakter) Szabadon választott
Az az URL cím, ahová a Payment Gateway visszaküldi a notification üzenetet.
 
AutoCommit Opcionális true Logikai
  • true
  • false
Meghatározza, hogy a tranzakciót rögtön végrehajtsa-e a bank, vagy először csak zárolja az összeget és egy későbbi időpontban hagyjuk jóvá, vagy vonjuk vissza a tranzakciót a Close funkció segítségével.
 
MppPhoneNumber Opcionális Nincs Szöveges (max. 32 karakter) Szabadon választott (pl.: 36201114567)
A MobilFizetésnél előre átadható a felhasználó telefonszáma.
 
OtpCardNumber Opcionális Nincs Szöveges (16 karakter) Kártyaszám (pl.: 4908366099900425)
Az OTP kétszereplős fizetés esetén megadandó kártyaszám.
 
OtpExpiration Opcionális Nincs Szöveges (4 karakter) Kártyalejárat dátuma (pl.: 1014)
Az OTP kétszereplős fizetés esetén megadandó kártyalejárat dátuma.
 
OtpCvc Opcionális Nincs Szöveges (3 karakter) CVC/CVV kód (pl.: 823)
Az OTP kétszereplős fizetés esetén megadandó CVC/CVV ellenőrző kód.
 
OtpCardPocketId Opcionális Nincs Szöveges (2 karakter)
  • 07
    (vendéglátás)
  • 08
    (szabadidő)
  • 09
    (szálláshely)
Az OTP SZÉP Kártyás fizetés esetén megadandó zseb azonosító.
 
OtpConsumerRegistrationId Opcionális Nincs Szöveges Szabadon választott
Az OTP ismétlődő fizetéshez szükséges vásárló azonosító.
 
OneClickPayment Opcionális false Logikai
  • true
  • false
A One Click Payment típusú fizetések engedélyezéséhez használt paraméter (Escalion, PayU).
 
MkbSzepCafeteriaId Opcionális Nincs Szöveges (4 karakter)
  • 1111
    (szálláshely)
  • 2222
    (vendéglátás)
  • 3333
    (szabadidő)
Az MKB SZÉP Kártyás fizetés esetén megadandó zseb azonosító.
 
MkbSzepCardNumber Opcionális Nincs Szöveges Kártyaszám
Az MKB SZÉP Kártyás fizetés esetén használt kártyaszám.
 
MkbSzepCardCvv Opcionális Nincs Szöveges (3 karakter) CVV kód
Az MKB SZÉP Kártyás fizetés esetén használt CVV ellenőrző kód.
 
GatewayPaymentPage Opcionális false Logikai
  • true
  • false
Az MKB SZÉP Kártyás fizetés esetén használható paraméter. Segítségével beállítható, hogy a kártyaadatok bekérése a kereskedő, vagy a Payment Gateway oldalán történjen-e meg.

1.4. A Payment Gateway-től kapott válasz

Paraméter Típus Értékkészlet Példa
TransactionId Szöveges (32 karekter hosszú md5 hash) Változó 0a62408585bdfbb54851fd454078641d
Sikeresség esetén a Payment Gateway által generált tranzakció azonosító.
 
ResultCode Szöveges
  • SUCCESSFUL
  • MissingParameter
  • WrongParameter
  • UnknownStore
  • UnknownProvider
  • UnknownProviderForStore
  • WrongProviderSettings
UnknownProvider
Az eredménykód a tranzakció inicializálás sikerességét jelzi. Ha az eredménykód eltér a 'SUCCESSFUL'-tól, sikertelen volt az inicializálás.
 
ResultMessage Szöveges Változó Ismeretlen fizetési szolgáltató
A fenti eredménykódhoz tartozó szöveges magyarázat (a tranzakció inicilaizálásakor megadott nyelven). Igény esetén megjeleníthető a vásáró számára.

2. Start

A Start funkció segítségével küldheti át a Webáruház a vásárlót a Payment Gateway-hez a fizetés végrehajtása miatt (HTTP Redirect).

2.1. Példa a Start funkció hívásra (PHP SDK)

if ($response->ResultCode == "SUCCESSFUL" && $response->TransactionId) {
	\BigFish\PaymentGateway::start(new \BigFish\PaymentGateway\Request\Start($response->TransactionId));
} else {
	// Hiba megjelenítése a vásárlónak
}
	

2.2. Példa az URL hívásra (HTTP Redirect)

https://test.paymentgateway.hu/Start?TransactionId=0a62408585bdfbb54851fd454078641d

2.3. A paraméterek magyarázata

Paraméter Kötelező? Alapértelmezett érték Típus Értékkészlet
TransactionId Kötelező Nincs Szöveges (32 karekter hosszú md5 hash) Változó
Az inicializáláskor kapott tranzakció azonosító.

2.4. A Payment Gateway-től kapott válasz

A tranzakció végrehajtását követően a Payment Gateway visszaküldi a vásárlót a Webáruház által adott válasz URL-re, például:
http://www.webaruhaz.hu/payment_gateway_valasz_url.php?TransactionId=0a62408585bdfbb54851fd454078641d

3. Result

A Result funkció segítségével a Webáruház lekérdezi a tranzakció eredményét a Payment Gateway-től. A Webáruház és a Payment Gateway közötti kommunikáció a háttérben, azaz a vásárló elől rejtve zajlik.

3.1. Példa a Result funkció hívásra (PHP SDK)

$response = \BigFish\PaymentGateway::result(new \BigFish\PaymentGateway\Request\Result($_GET["TransactionId"]));

3.2. REST hívás (HTTP POST)

method=Result&json={"TransactionId":"0a62408585bdfbb54851fd454078641d"}

3.3. A paraméterek magyarázata

Paraméter Kötelező? Alapértelmezett érték Típus Értékkészlet
TransactionId Kötelező Nincs Szöveges (32 karekter hosszú md5 hash) Változó
Az válasz URL-ben kapott tranzakció azonosító.

3.4. A Payment Gateway-től kapott válasz

Paraméter Típus Értékkészlet Példa
TransactionId Szöveges (32 karekter hosszú md5 hash) Változó 0a62408585bdfbb54851fd454078641d
Payment Gateway-ben nyilvántartott tranzakció azonosító.
 
ResultCode Szöveges
  • SUCCESSFUL
  • PENDING
  • ERROR
  • CANCELED
SUCCESSFUL
A SUCCESSFUL eredménykód a tranzakció sikerességét jelzi. PENDING státusz esetén a fizetés még nem lett befejezve, vagy a szolgáltató által elfogadva/elutasítva, tehát folyamatban lévő tranzakciót jelez.
 
ResultMessage Szöveges Változó Sikeres tranzakció
A fenti eredménykódhoz tartozó szöveges magyarázat (a tranzakció inicilaizálásakor megadott nyelven). Igény esetén megjeleníthető a vásáró számára.
 
Anum Szöveges (max. 100 karakter) Változó AN123456
A fizetési szolgáltatótól kapott authorizációs kód vagy engedélyszám (opcionális).
 
OrderId Szöveges (max. 255 karakter) Változó 12345
A megrendelés kereskedőnél lévő sorszáma. A tranzakciók visszakeresését segítheti.
 
UserId Szöveges (max. 255 karakter) Változó 123
A vásárló kereskedőnél lévő azonosítója. A tranzakciók visszakeresését segítheti.
 
ProviderTransactionId Szöveges (max. 255 karakter) Változó 5467429862223832
Fizetési szolgáltató specifikus tranzakció azonosító. A tranzakciók visszakeresését segítheti.
 
AutoCommit Szöveges
  • true
  • false
true
Amennyiben a tranzakció azonnal lezárult pénzügyileg, az érték true. Ha egy későbbi időpontban véglegesíteni kell - a Close funkció segítségével - akkor az értéke false.
 
CommitState Szöveges
  • PENDING
  • APPROVED
  • DECLINED
APPROVED
Ha a Close funkció segítségével engedélyeztük a terhelést, akkor APPROVED, ha elutasítottuk, akkor DECLINED.

4. Close

A Close funkció segítségével lehetséges véglegesíteni a függőben lévő tranzakciókat, azaz a zárolást felszabadítani, vagy terhelni a vásárló bankszámláját.

4.1. Példa a Close funkció hívásra (PHP SDK)

$response = \BigFish\PaymentGateway::close(new \BigFish\PaymentGateway\Request\Close($transactionId, true));

4.2. REST hívás (HTTP POST)

method=Close&json={"TransactionId":"0a62408585bdfbb54851fd454078641d","Approved":"true"}

4.3. A paraméterek magyarázata

Paraméter Kötelező? Alapértelmezett érték Típus Értékkészlet
TransactionId Kötelező Nincs Szöveges (32 karekter hosszú md5 hash) Változó
Payment Gateway-ben nyilvántartott tranzakció azonosító.
 
Approved Opcionális true Szöveges
  • true
  • false
A true megterheli a felhasználó számláját, a false felszabadítja a zárolást.

4.4. A Payment Gateway-től kapott válasz

Paraméter Típus Értékkészlet Példa
TransactionId Szöveges (32 karekter hosszú md5 hash) Változó 0a62408585bdfbb54851fd454078641d
Payment Gateway-ben nyilvántartott tranzakció azonosító.
 
ResultCode Szöveges
  • SUCCESSFUL
  • ERROR
SUCCESSFUL
Az eredménykód a lezárás sikerességét jelzi.

5. Refund

A Refund funkció segítségével lehetőség van egyes szolgáltatók esetében pénzvisszatérítést kezdeményezni.

5.1. Példa a Refund funkció hívásra (PHP SDK)

$response = \BigFish\PaymentGateway::refund(new \BigFish\PaymentGateway\Request\Refund($ransactionId, $amount));

5.2. REST hívás (HTTP POST)

method=Refund&json={"TransactionId":"0a62408585bdfbb54851fd454078641d","Amount":"100.00"}

5.3. A paraméterek magyarázata

Paraméter Kötelező? Alapértelmezett érték Típus Értékkészlet
TransactionId Kötelező Nincs Szöveges (32 karekter hosszú md5 hash) Változó
Payment Gateway-ben nyilvántartott tranzakció azonosító.
 
Amount Kötelező Nincs float Nullánál nagyobb szám
A visszatérítés összege.

5.4. A Payment Gateway-től kapott válasz

Paraméter Típus Értékkészlet Példa
TransactionId Szöveges (32 karekter hosszú md5 hash) Változó 0a62408585bdfbb54851fd454078641d
Payment Gateway-ben nyilvántartott tranzakció azonosító.
 
ResultCode Szöveges
  • SUCCESSFUL
  • ERROR
SUCCESSFUL
Az eredménykód a visszatérítés indításának sikerességét jelzi.