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

> Saját fizetési átjáró beépítése a Tutor LMS natív e-kereskedelmébe: mintabővítmény, konfigurációs és fizetési osztályok, inicializálás, composer.json.

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.

```php
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).

```php
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:

   ```php
   private $merchant_id;
   private $currency_type;
   ```

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

   ```php
   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:

   ```php
   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:

   ```php
   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):

   ```php
   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:

  ```php
  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:

  ```php
  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:

```json
"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.