Fejlesztőknek

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

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

• Teszt rendszer: https://test.paymentgateway.hu/api/rest/
• Éles rendszer: https://www.paymentgateway.hu/api/rest/

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 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.

1. Init

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)

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

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)

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

3. Result

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)

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 TIMEOUT OPEN	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. Az OPEN eredménykód kizárólag az OTPay MasterPass fizetési szolgáltatás esetén van használatban, speciális esetben.
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

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)

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

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)

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.