Egyedi fizetési átjáró készítése

Ez az útmutató végigvezet azon, hogyan építhetsz be saját fizetési átjárót a Tutor LMS natív e-kereskedelmébe. A példában az átjáró neve CustomPayment: ez csak helyőrző, a saját átjáród nevére kell cserélned.

Mielőtt belekezdesz

Ismerd meg a beépíteni kívánt átjáró API-ját és dokumentációját. Figyelj ezekre:

• Szükséges mezők: például secret_key, public_key, client_id és az átjáró egyedi mezői.
• Támogatott funkciók: támogatja-e az ismétlődő fizetést, van-e éles és teszt (sandbox) mód, van-e webhook.
• API-végpontok: fizetés létrehozása, visszahívások és webhookok kezelése, tranzakciók ellenőrzése.
• Hitelesítés: milyen típusú (API-kulcsok, tokenek, OAuth).

1. lépés: a mintabővítmény

Töltsd le a CustomPayment mintabővítményt, amely referenciaszerkezetként szolgál, és alakítsd át a saját átjárődhoz. A custompayment mappa fájljait fogod módosítani. A mintában a következő fájlok vannak:

Fájl	Szerepe
CustomPaymentConfig.php	Az átjáró konfigurációja (kulcsok, környezet).
CustomPaymentGateway.php	A fizetések feldolgozásának belépési osztálya.
Init.php	Az átjáró regisztrálása a Tutor LMS-ben.
Custompayment.php	A fizetés logikája.
custompayment.php	A bővítmény főfájlja.
composer.json	Az automatikus osztálybetöltés beállítása.

2. lépés: CustomPaymentConfig.php

Ez a fájl az átjáró konfigurációját kezeli. Az osztály a CustomPayment névtérben van, a BaseConfig osztályból származik, és megvalósítja a ConfigContract felületet.

namespace CustomPayment;
use Tutor\Ecommerce\Settings;
use Ollyo\PaymentHub\Core\Payment\BaseConfig;
use Tutor\PaymentGateways\Configs\PaymentUrlsTrait;
use Ollyo\PaymentHub\Contracts\Payment\ConfigContract;

• A BaseConfig az alapvető konfigurációs funkciókat kezelő osztály.
• A ConfigContract felület biztosítja, hogy az osztály megvalósítsa a szükséges metódusokat.

A konfigurációs adatok privát tulajdonságok. Itt add meg az átjáród szükséges mezőit. Ezeket az értékeket a felhasználó a WordPress admin felületén tölti ki (a Tutor LMS fizetési beállításain át).

private $environment;
private $public_key;
private $secret_key;
private $client_id;
protected $name = 'custompayment';

Mit kell módosítanod:

1. Az osztály neve és névtere: igazítsd az új átjáróhoz.

2. A konfigurációs mezők: ha az átjáródnak más mezők kellenek (például kereskedői azonosító vagy pénznem), vedd fel őket privát tulajdonságként:

   private $merchant_id;
   private $currency_type;

   Majd frissítsd a get_custompayment_config_keys() metódust az új mezőkkel:

   private function get_custompayment_config_keys() {
       return array(
           'environment' => 'environment',
           'secret_key'  => 'secret_key',
           'public_key'  => 'secret_key',
           'client_id'   => 'secret_key',
           'merchant_id' => 'secret_key', // új mező
       );
   }

3. Lekérdező (getter) metódusok minden új beállításhoz:

   private function getMerchantID(): string {
       return $this->merchant_id;
   }

4. A konfiguráció ellenőrzése: az is_configured() metódus azt vizsgálja, hogy minden szükséges mező ki van-e töltve. Az új mezőket is vedd bele. Előtte gondoskodj róla, hogy a merchant_id (és minden új mező) inicializálva legyen a createConfig() metódusban:

   public function createConfig(): void {
       parent::createConfig();
       $config = array( 'merchant_id' => $this->getMerchantID() );
       $this->updateConfig( $config );
   }
   
   public function is_configured() {
       return $this->secret_key && $this->public_key && $this->merchant_id;
   }

Összefoglalva: nevezd át az osztályt és a névteret, vedd fel az új mezőket, gondoskodj arról, hogy a konstruktor betöltse őket, add hozzá a lekérdező metódusokat, és vedd bele őket az is_configured ellenőrzésbe.

3. lépés: CustomPaymentGateway.php

Ez a fájl a fizetések feldolgozását végzi a beállított átjárón át: kapcsolatot tart a fizetésfeldolgozóval, kezeli a fizetési kéréseket és a válaszokat. Az osztály a GatewayBase osztályból származik, amely az általános átjáró-funkciókat tartalmazza, így csak az átjáród sajátosságaival kell foglalkoznod.

Fő tulajdonságok:

• $dir_name: az átjáró fájljait tartalmazó gyökérmappa neve.
• $config_class: a konfigurációs osztály (itt a CustomPaymentConfig::class).
• $payment_class: a tranzakciókat feldolgozó osztály (itt a Custompayment::class).

Metódusok:

• get_root_dir_name(): a gyökérmappa neve.
• get_payment_class(): a fizetést feldolgozó osztály.
• get_config_class(): a konfigurációs osztály.
• get_autoload_file(): az automatikus betöltő fájl útvonala, amely az átjáró függőségeit tölti be.

Mit kell módosítanod:

1. A $payment_class és a $config_class az átjárót és a konfigurációt kezelő osztályokra mutasson.

2. A $dir_name alapértéke 'Custompayment'. Ha átnevezed a mappát, ezt is írd át.

3. Ha az átjáródhoz Composer-függőségek tartoznak, a get_autoload_file() adja vissza a megfelelő útvonalat. Ha nincs szükség automatikus betöltőre, hagyd az alapértéken (üres szöveg):

   public static function get_autoload_file() {
       return '/path/to/vendor/autoload.php';
   }

4. lépés: Init.php

Az Init.php az átjárót inicializálja a Tutor LMS-ben: regisztrálja a hookokat, amelyek révén a rendszer felismeri az egyedi fizetési módot és a konfigurációját.

Mit kell módosítanod:

• Az átjáró neve: a kódban 'custompayment' szerepel, cseréld a sajátodra.

• Az átjáró osztályai: a payment_gateways_with_ref és a filter_payment_gateways függvényekben a CustomPaymentGateway::class és a CustomPaymentConfig::class az új osztályaidra mutasson.

• Címke: a $custom_payment_method tömbben a 'Custom Payment' felirat az átjáród megjelenő neve.

• Mezők: a fields tömb tartalmazza az admin beállításoknál megjelenő mezőket. Új mezőt azonos formátumban vehetsz fel, például:

  array(
      'name'  => 'merchant_id',
      'type'  => 'secret_key',
      'label' => 'Merchant ID',
      'value' => '',
  ),

• Ikon: az 'icon' mezőben megadhatod az átjáró ikonjának URL-jét (egy általad tárolt képre mutathat).

• Előfizetés-támogatás: a 'support_subscription' => false érték azt jelzi, hogy az átjáró nem támogatja az előfizetést. Ha támogatja, állítsd true-ra.

5. lépés: Custompayment.php (a fizetés logikája)

Ez a fájl a fizetés feldolgozásának magja. A BasePayment osztályból származik, és az átjáródra jellemző műveleteket felülírja.

• Névtér: igazítsd a bővítményed nevéhez (a Payments\Custom helyett a saját névteredet használd).
• check() metódus: itt adod meg az átjáró konfigurációs kulcsait, például secret_key, public_key és mode. Ha az átjárónak más értékek is kellenek (API-hitelesítő adatok, környezeti beállítások), vedd fel őket a $configKeys tömbbe.
• setup() metódus: az API-hívásokhoz szükséges beállításokat végzi, például az API-fejléceket, amelyeket a további kérések használnak.
• createPayment() metódus: a Tutor LMS fizetési adatait elküldi az átjárónak. Fizetési kérést generál: az átjáró integrációs módjától függően átirányítja a felhasználót egy megadott URL-re, vagy iframe-et használ. A minta egy helyőrző címre irányít, ezt cseréld az átjáród tényleges tranzakciós URL-jére, és igazítsd a logikát az átjáró API-jához (fizetési adatok küldése, válaszok kezelése). A szükséges értékeket (például secret_key, public_key, mode) a $this->config->get('tulajdonsag_neve') hívással kapod meg a beállítások közül.
• verifyAndCreateOrderData() metódus: az átjáróból a Tutor LMS felé érkező adatot fogadja. Ellenőrzi a webhook aláírását, és feldolgozza a rendelési adatot. A $get_data, $post_data, $server_variables és $stream értékeket az átjáród webhookjának formátumához igazítsd. A rendelési adatban a payment_status, transaction_id és fees mezőket az átjáró válasza alapján töltsd ki, és az eredményt a $returnData változóban add vissza.
• Adatok a Tutor LMS-től: a Tutor LMS által küldött fizetési adatokat a getData() metódussal olvashatod ki, amely a setData($data) híváskor átadott adatokat adja vissza. A setData($data) egy objektumot kap (object $data), és Throwable kivételt dob, ha hiba történik az adat beállításakor.
• További metódusok: ha az átjárónak visszatérítés, lemondás vagy fizetési állapot lekérdezés is kell, vedd fel őket ebbe az osztályba a meglévő metódusok mintájára.

6. lépés: custompayment.php (a bővítmény főfájlja)

Ez a bővítmény belépési pontja: regisztrálja a bővítményt, betölti a szükséges fájlokat és elindítja az integrációt.

• A bővítmény adatai: írd át a nevet, az URI-t, a leírást, a szerzőt és a verziót.

• Útvonalak és mappák: ellenőrizd, hogy a konstansok megfelelnek-e a bővítményed szerkezetének:

  define( 'CUSTOM_PAYMENT_VERSION', '1.0.0' );
  define( 'CUSTOM_PAYMENT_URL', plugin_dir_url( __FILE__ ) );
  define( 'CUSTOM_PAYMENT_PATH', plugin_dir_path( __FILE__ ) );
  define( 'CUSTOM_PAYMENT_PAYMENTS_DIR', trailingslashit( CUSTOM_PAYMENT_PATH . 'src/Payments' ) );

• Automatikus betöltő: a fájl beilleszti a Composer betöltőjét, így a Composerrel telepített függőségek automatikusan betöltődnek. Győződj meg arról, hogy a vendor mappa létezik és tartalmazza a függőségeket.

• Inicializálás: a CustomPayment\Init osztály példányosodik, ha a feltételek teljesülnek, és regisztrálja a szükséges hookokat és szűrőket. Ha további beállítás kell, itt módosíthatod.

7. lépés: composer.json

• name: a csomag neve themeum/csomag-neve formátumban.
• description: rövid leírás a bővítményről (például hogy egyedi fizetési átjárót integrál a Tutor LMS-be).
• autoload: a névterek és a mappaszerkezet megfeleltetése:

"autoload": {
    "psr-4": {
        "Ollyo\\PaymentHub\\": "../tutor/ecommerce/PaymentGateways/Paypal/src",
        "Payments\\Custom\\": "payments",
        "CustomPayment\\": "integration"
    }
}

Az Ollyo\\PaymentHub\\ névtér rögzített, nem változtatható. A másik két névteret és mappát a saját szerkezetedhez igazíthatod.