# Fizetési átjáró integrálása

> Hogyan adhatsz előfizetés-támogatást egy fizetési átjáró bővítményhez: támogatási jelzők, feliratkozás, kezelés, sikertelen fizetések és fizetésimód-váltás.

Ez a fejezet azt a hat lépést írja le, amellyel egy meglévő fizetési átjáró bővítmény előfizetés-támogatást kap. A bővítmény teljes API-t ad, és az előfizetések kezelésének nagy részét magától elvégzi: neked csak a fizetés feldolgozását kell hozzáadnod.

A lépések:

1. a támogatás regisztrálása;
2. az előfizetésre való feliratkozás feldolgozása;
3. az előfizetések kezelése;
4. a sikertelen fizetések feldolgozása;
5. az ismétlődő fizetési mód változásának kezelése;
6. a támogatás jelzése.

Előfeltétel a [Fejlesztői áttekintés](https://hub.hellowp.io/hu/plugins/woocommerce-subscriptions/fejlesztoknek-attekintes/) ismerete és a WooCommerce fizetési átjáró API-jának alapos ismerete. Az egyedi kódokra nem vonatkozik terméktámogatás.

## 1. A támogatás regisztrálása

Ha egy rendelés előfizetéses terméket tartalmaz, a bővítmény a fizetési átjárók közül csak azokat mutatja, amelyek támogatják az ismétlődő fizetést. Az átjárónak a `WC_Payment_Gateway::supports()` API-n át jeleznie kell az előfizetés-támogatást: a `supports` tulajdonságát olyan tömbre kell állítani, amely tartalmazza a `subscriptions` elemet (és a `products` elemet is, ha az átjáró terméket is tud árusítani).

```php
class WC_Awesome_Gateway extends WC_Payment_Gateway {
     function __construct() {
          // ...
          $this->supports = array( 'subscriptions', 'products' );
          // ...
     }
}
```

Ezután, ha egy rendelés előfizetést tartalmaz és az átjáró be van kapcsolva, az átjáró megjelenik fizetési lehetőségként a pénztárban.

### Az előfizetés-kezelő funkciók jelzése

Ha az átjáró kezelni tudja az előfizetések lemondását, felfüggesztését és hasonlókat, ezt is jelezni kell. A bővítmény ezeket a funkciókat valósítja meg, ha az átjáró támogatja őket:

- előfizetés lemondása (`subscription_cancellation`),
- előfizetés felfüggesztése (`subscription_suspension`),
- előfizetés újraaktiválása felfüggesztés után (`subscription_reactivation`),
- az ismétlődő összeg módosítása (`subscription_amount_changes`),
- a következő fizetés dátumának módosítása (`subscription_date_changes`).

Példa egy olyan átjáróra, amely minden funkciót támogat:

```php
class WC_Awesome_Gateway extends WC_Payment_Gateway {
     function __construct() {
          // ...
          $this->supports = array(
               'products',
               'subscriptions',
               'subscription_cancellation',
               'subscription_suspension',
               'subscription_reactivation',
               'subscription_amount_changes',
               'subscription_date_changes',
               'subscription_payment_method_change',
               'subscription_payment_method_change_customer',
               'subscription_payment_method_change_admin',
               'multiple_subscriptions',
          );
          // ...
     }
}
```

Ha az átjáró tokenalapú számlázást használ, és az ismétlődő fizetéshez a bővítmény ütemezett fizetési horgait használja, minden funkciót támogathat, ezért mindegyik jelzőt add hozzá.

## 2. Az előfizetésre való feliratkozás feldolgozása

Az előfizetés indítását, a termékvásárláshoz hasonlóan, az átjáró `process_payment()` függvényében kell feldolgozni. Attól függően, hogyan kezeli az átjáró az előfizetéseket, szükséged lehet a kezdeti összegre, a feliratkozási díjra, az időszakonkénti árra, a számlázási időszakra és az előfizetés hosszára. Ezeket egy előfizetést tartalmazó rendelésnél a `WC_Subscriptions_Order` osztály metódusaival kérheted le:

| Metódus | Mit ad vissza |
|---|---|
| `WC_Subscriptions_Order::get_total_initial_payment( $order )` | Az előfizetés kezdetén egy összegben fizetendő összeg (ha az átjárónak egyetlen kezdő összeg kell). |
| `WC_Subscriptions_Order::get_price_per_period( $order )` | Az egyes számlázási időszakokban felszámítandó összeg. |
| `WC_Subscriptions_Order::get_sign_up_fee( $order )` | A rendelés külön feliratkozási díja. |
| `WC_Subscriptions_Order::get_subscription_period( $order )` | A rendelés előfizetésének számlázási időszaka. |
| `WC_Subscriptions_Order::get_subscription_length( $order )` | Az előfizetés időtartama. |

Az `$order` mindegyiknél `WC_Order` objektum.

### Ingyenes próbaidő

Az átjárók általában kétféleképpen állítják be az ingyenes próbaidőt:

1. átadják a próbaidő időszakát és hosszát (például PayPal), vagy
2. megadják az előfizetés kezdődátumát (például WorldPay).

Az első módszerhez a próbaidő adatait ezzel a két függvénnyel kérheted le:

```php
WC_Subscriptions_Order::get_subscription_trial_period( $order );
WC_Subscriptions_Order::get_subscription_trial_length( $order );
```

A másodikhoz, a kezdődátum beállításához:

```php
WC_Subscriptions_Product::get_trial_expiration_date( $product_id, $order_start_date );
```

### Példa: a beépített PayPal Standard integráció

A bővítménnyel szállított `WC_PayPal_Standard_Subscriptions` osztály `paypal_standard_subscription_args()` függvénye mutatja meg, hogyan lehet az előfizetés adatait lekérni és egy átjáró kérésévé alakítani. A lényege:

- az előfizetéses rendelést a PayPal `_xclick-subscriptions` parancsával küldi el;
- az elemnevet a termék címéből adja meg, több tételnél a „Rendelés <szám>” szövegből;
- a számlázási időszakot és a próbaidő időszakát a PayPal formátumába alakítja (`D` nap, `W` hét, `M` hónap, `Y` év);
- lekéri a feliratkozási díjat, a kezdő összeget, az időszakonkénti árat, az időközt, a hosszt és a próbaidő hosszát;
- az időszakok számát (részletek) a hossz és az időköz hányadosából számolja;
- ha van próbaidő, annak paramétereit (`a1`, `p1`, `t1`) állítja be, a feliratkozási díjat a próbaidőszak összegébe teszi;
- ha nincs próbaidő, de van feliratkozási díj, az első időszakot a kezdő összeggel számlázza;
- az ismétlődő fizetés paramétereit (`a3`, `p3`, `t3`) állítja be;
- az `src` paraméterrel kapcsolja be az ismétlődést (vagy ki, ha csak egy részlet van), az `srt` paraméterrel adja meg a részletek számát;
- a visszatérési URL-t kényszeríti (`rm = 2`), hogy a rendelés leírása és útmutatója megjelenjen.

## 3. Az előfizetések kezelése

Az előfizetés vásárlása után egyes dolgokat a bővítmény magától kezel, másokat az átjárónak kell. Az előfizetés státusza a rendelés státuszához kötődik: ha a WooCommerce fizetési átjáró API-jával állítod a rendelés státuszát, az előfizetés státusza magától változik. Amikor a rendelés **Feldolgozás alatt** vagy **Teljesítve** állapotba kerül, az abban vásárolt előfizetés magától aktiválódik. Ha a rendelést lemondják, visszatérítik vagy sikertelennek jelölik, az előfizetés státusza is lemondottra vagy sikertelenre változik. A minimum tehát a rendelés státuszának helyes kezelése.

Az ismétlődő fizetéseket nem kezeli a bővítmény: ezt az átjárónak vagy a bővítményednek kell elvégeznie.

### Az átjáró dolgozza fel az ismétlődő fizetést

Ha az átjáró maga tud ismétlődő fizetést terhelni (például PayPal), a bővítményed beállíthatja az előfizetést az átjárónál, majd a `WC_Subscriptions_Manager::process_subscription_payments_on_order()` függvénnyel rögzítheti az egyes fizetéseket, miután az átjáró feldolgozta őket.

Ha az átjáró a számlázási ütemezést is kezeli, a támogatás regisztrálásakor add hozzá a `gateway_scheduled_payments` jelzőt is. Enélkül előfordulhat, hogy az előfizetések tévesen felfüggesztődnek, ha az átjáró ütemezése nem előzi meg a WooCommerce ütemezését.

### A bővítményed dolgozza fel az ismétlődő fizetést

Egyes átjárók alig vagy egyáltalán nem támogatják az ismétlődő fizetést, de eltárolt bankkártyát terhelni tudnak. Ezek is kínálhatnak automatikus ismétlődő számlázást a bővítménnyel. A Stripe bővítmény is így támogatja az előfizetéseket.

Minden előfizetésnél, amikor egy adott átjáróra fizetés esedékes, a bővítmény elsüti a `woocommerce_scheduled_subscription_payment_{payment_gateway_id}` horgot. Ez megkapja az esedékes összeget és a megújítási rendelést, és ezzel dolgozhatod fel a fizetést. A Stripe bővítmény például a `scheduled_subscription_payment()` függvényét köti a `woocommerce_scheduled_subscription_payment_stripe` horogra:

```php
function scheduled_subscription_payment( $amount_to_charge, $renewal_order ) {

    $result = $this->process_subscription_payment( $amount_to_charge, $renewal_order );

    if ( is_wp_error( $result ) ) {
        WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $renewal_order );
    } else {
        WC_Subscriptions_Manager::process_subscription_payments_on_order( $renewal_order );
    }
}
```

A fizetés terhelése ezen a horgon csak akkor kötelező, ha az átjáró nem terhel automatikusan ismétlődő fizetést. De akkor is használható az átjáró saját ismétlődő számlázása helyett, mert:

1. kevesebb kód kell az előfizetési fizetések és funkciók (például a következő fizetési dátum módosítása) támogatásához, mert a bővítmény magja mindezt elvégzi, neked csak a horogra kell kötnöd;
2. teljes rugalmasságot ad a számlázási időközben és időszakban (például az Authorize.net ARB csak a számlázási időszakkal megegyező időszakú próbaidőt enged, így egy havonta számlázott előfizetéshez nem adható 2 hetes próbaidő);
3. minden előfizetési funkciót támogathatsz, függetlenül attól, mit nyújt az átjáró saját ismétlődő számlázása.

### Aktiválás

```php
WC_Subscriptions_Manager::activate_subscriptions_for_order( $order );
```

A függvény a rendelés összes előfizetését aktívra állítja. Magától lefut, amikor a rendelés státusza **Teljesítve** vagy **Feldolgozás alatt** lesz, tehát ha helyesen frissíted a rendelés státuszát, nem kell meghívnod. Az előfizetés-tételenként a `WC_Subscriptions_Manager::activate_subscription()` függvényt hívja.

### Lemondás

Ha az átjáró API-t ad az előfizetés lemondásához (vagy te kézzel terheled az ismétlődő fizetést), támogathatod, hogy az előfizetés az áruházban is lemondható legyen. Ezt is jelzővel kell jelezni:

```php
function __construct() {
    // ...
    $this->supports = array( 'products', 'subscriptions', 'subscription_cancellation' );
    // ...
}
```

A `subscription_cancellation` jelző hatására a **Lemondás** művelet megjelenik az átjáróval vásárolt előfizetésen az áruházkezelőnek és az előfizetőnek is. Ha rákattintanak, a bővítmény lemondja az előfizetést az áruházban, az átjárónál viszont neked kell lemondanod.

A bővítmény a `cancelled_subscription` horgot süti el minden lemondáskor, de jobb a `woocommerce_subscription_cancelled_{payment_gateway_id}` akciót használni. Ez megkapja a `WC_Order` objektumot és a lemondott előfizetéses termék `WC_Product` azonosítóját, ezekkel mondhatod le az előfizetést az átjárónál.

#### Lemondás az átjárónál

Ha a felhasználó közvetlenül az átjárónál is lemondhatja az előfizetést, ezt az áruházban is át kell vezetni:

```php
WC_Subscriptions_Manager::cancel_subscriptions_for_order( $order );
```

Ez a függvény magától lefut, amikor a rendelés státusza lemondott, sikertelen vagy visszatérített lesz. Belül a `WC_Subscriptions_Manager::cancel_subscription()` függvény kényelmi burkolója. Ha csak egy előfizetést kell lemondani, a hozzá tartozó rendelés nélkül, hívd közvetlenül a lemondó függvényt:

```php
WC_Subscriptions_Order::cancel_subscription( $user_id, $subscription_key );
```

A `$subscription_key` a rendelés azonosítójából, egy aláhúzásból és az előfizetéses termék azonosítójából áll, például `153_12` a 153-as rendelésen vásárolt, 12-es azonosítójú termékhez.

### Lejárat

A bővítmény ütemezett műveletet állít be, amely az előfizetést lejárttá teszi, amikor eléri a lejárati dátumot, ezért nem kell kézzel lejáratni. Ha az átjáró lejárati értesítést küld, és biztosra mennél, közvetlenül is hívhatod a `WC_Subscriptions_Manager` függvényeit.

A rendelés összes előfizetésének lejárata:

```php
WC_Subscriptions_Manager::expire_subscriptions_for_order( $order );
```

Egy előfizetés lejárata:

```php
WC_Subscriptions_Manager::expire_subscription( $user_id, $subscription_key );
```

Ha az ismétlődő fizetést kézzel terheled, nem kell lejáratni az előfizetést, mert az ütemezett fizetési horgok már nem sülnek el, ha az előfizetést lemondták.

### Fizetések rögzítése

Az előfizetés státusza nem változik minden egyes beérkezett fizetésnél (az elsőt esetleg kivéve), de a bővítmény API-t ad a fizetések rögzítésére. Ha az átjáró értesítési rendszert használ (például PayPal IPN), érdemes a `process_subscription_payments_on_order()` függvényt hívni, hogy a fizetés nyoma megmaradjon a rendelésen:

```php
WC_Subscriptions_Manager::process_subscription_payments_on_order( $order );
```

### Sikertelen fizetések rögzítése

Az előfizetés státusza nem változik sikertelen fizetésnél (kivéve, ha a sikertelen fizetések száma meghaladja az áruházban beállított értéket), de a sikertelen fizetéseket is rögzíteni kell. Értesítési rendszer esetén hívd a `process_subscription_payment_failure_on_order()` függvényt:

```php
WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order );
```

A bővítmény függvényei egyaránt léteznek rendelésre és egyedi előfizetésre. Többnyire egyszerűbb és kevesebb kódot igényel a rendelésre működő változat használata.

### Példa: a PayPal IPN kezelése

A bővítménnyel szállított `WC_PayPal_Standard_Subscriptions` osztály `process_paypal_ipn_request()` függvénye azt mutatja, hogyan hívhatók kézzel, redundánsan az előfizetés-kezelő függvények. A függvény a PayPal IPN-kérésekhez van kötve, megnézi, hogy a kérés előfizetéshez tartozik-e, és a tranzakció típusa szerint kezeli:

| IPN tranzakciótípus | Mit csinál a kód |
|---|---|
| `subscr_signup` | Eltárolja a PayPal adatait (fizető címe, neve, előfizetőazonosító) a rendelésen, és megjegyzést fűz hozzá, hogy a feliratkozás befejeződött. |
| `subscr_payment` | Ha a fizetés **completed** állapotú: eltárolja a tranzakció adatait, megjegyzést ír. Ha ez az előfizetés első fizetése, `payment_complete()` és `activate_subscriptions_for_order()` fut, egyébként `process_subscription_payments_on_order()`. Ha a fizetés **failed**: megjegyzést ír, és a `process_subscription_payment_failure_on_order()` fut. Más státusznál csak naplóz. |
| `subscr_cancel` | Megjegyzést ír, és a `cancel_subscriptions_for_order()` fut. |
| `subscr_eot` | Az előfizetés véget ért (sikertelen fizetések vagy lejárat miatt). A PayPal egyetlen időszakos előfizetésnél azonnal elküldi, ezért ha a hossz 1, a kérést figyelmen kívül hagyja. Ha a lejárati dátum még nem telt el, `cancel_subscriptions_for_order()` fut, egyébként `expire_subscriptions_for_order()`. |
| `subscr_failed` | A feliratkozás nem sikerült: megjegyzést ír, és a `failed_subscription_sign_ups_for_order()` fut. |

## 4. A sikertelen fizetések feldolgozása

A bővítmény API-t ad a sikertelen fizetésekhez is. Szükséged lehet rá, ha az átjáró nem maga kezeli a sikertelen fizetéseket. Két függvény van:

```php
WC_Subscriptions_Manager::process_subscription_payment_failure_on_order( $order, $product_id );
```

A rendelés azonosítóját vagy objektumát (az előfizetést megvásárló, szülő rendelést) kell átadni. Ennek a rendelésnek a státusza nem változik: a függvény ennek alapján keresi meg az előfizetést, és „sikertelen” státuszú megújítási rendelést hoz létre.

```php
WC_Subscriptions_Manager::process_subscription_payment_failure( $user_id, $subscription_key );
```

Az első ennek a másodiknak a kényelmi burkolója: bármelyiket használhatod, de egyszerre csak az egyiket.

Sikertelen fizetésnél a bővítmény az előfizetést **Felfüggesztve** állapotba teszi, amíg a vásárló be nem jelentkezik, és kézzel ki nem egyenlíti a megújítási időszak díját. A kifizetéshez használt fizetési mód lesz a későbbi ismétlődő fizetések módja is, ha az átjáró kezeli az ismétlődő fizetési mód változását (lásd a következő pontot). Ha az átjáró nem kezeli maga a sikertelen fizetéseket, ezek közül valamelyik függvényt használnod kell.

## 5. Az ismétlődő fizetési mód változásának kezelése

A vásárlók megváltoztathatják a jövőbeli fizetésekhez használt fizetési módot az előfizetésükön. A bővítmény ezt az eljárást használja akkor is, ha egy sikertelen ismétlődő fizetés után frissíteni kell a fizetési módot. Az átjárónak két dolgot kell tennie:

1. Hozzá kell adnia a `subscription_payment_method_change` jelzőt, hogy az átjáró a fizetési mód módosításakor választható legyen.
2. Rá kell kötnie a `woocommerce_subscription_failing_payment_method_updated_{az-átjáród}` akcióra, hogy frissítse a fizetési módot, amikor a vásárló egy korábban sikertelen automatikus megújítás helyett fizet.

### A vásárló által indított módosítás

A vásárló kezdeményezte fizetésimód-váltáshoz az átjárónak csak a 0 összegű kezdő rendelést kell tudnia feldolgozni. A bővítmény az eredeti rendelés adataiból „álpénztárat” készít, az összeget 0-ra állítva. Ha az átjáró helyesen kezeli a 0 összegű kezdő rendelést (ami az ingyenes próbaidő helyes kezeléséhez is kell), általában nem kell több kód.

További kódra akkor van szükség, ha a számlázási ütemezést az átjáró kezeli, nem a bővítmény. Ilyenkor a helyes első fizetési dátumot is be kell állítanod, hasonlóan az ingyenes próbaidő beállításához egy szokásos feliratkozásnál.

Ilyen esetben a `wcs_is_subscription( $order_id )` függvénnyel ellenőrizheted, hogy az átjáró `process_payment()` metódusának átadott `$order_id` előfizetés-e. Ha igen, a kérés az előfizetés fizetési módjának módosítására vonatkozik.

### Sikertelen automatikus fizetés utáni módosítás

Ha az előfizető automatikus fizetése nem sikerül, az előfizetés **Felfüggesztve** állapotba kerül, amíg a vásárló be nem jelentkezik és ki nem fizeti. A jövőbeli ismétlődő fizetésekhez az a fizetési mód lesz használatos, amellyel ezt a fizetést teljesítette. Ezért frissítened kell az eredeti előfizetés minden olyan meta-adatát, amelyet az átjáró a jövőbeli automatikus fizetésekhez használ. A meta-adatot a `woocommerce_subscriptions_changed_failing_payment_method_{az-átjáród}` horgon kell frissíteni, különben minden további automatikus fizetés sikertelen marad.

Az eredeti rendelésen a fizetési módot vagy bármi mást nem kell frissítened, azt a bővítmény megteszi. Csak arról gondoskodj, hogy az eredeti rendelésen legyen minden szükséges meta-adat a jövőbeli fizetések helyes kezeléséhez.

A Stripe és az Authorize.net CIM kódjához hasonló példa: az új megújítási rendelésről az ügyféltoken azonosítóját átmásolja az eredeti előfizetési rendelésre.

```php
/**
 * Frissíti az előfizetés ügyféltoken-azonosítóit, miután a vásárló az átjáróval
 * sikeresen kifizette a korábban sikertelen automatikus megújítást.
 *
 * @param WC_Order $original_order Az eredeti rendelés, amelyben az előfizetést megvásárolták.
 * @param WC_Order $new_renewal_order A rendelés, amely a sikeres fizetést rögzítette.
 * @return void
 */
function yg_update_failing_payment_method( $original_order, $new_renewal_order ) {
    update_post_meta( $original_order->id, '_your_gateway_customer_token_id', get_post_meta( $new_renewal_order->id, '_your_gateway_customer_token_id', true ) );
}
add_action( 'woocommerce_subscriptions_changed_failing_payment_method_your_gateway', 'yg_update_failing_payment_method', 10, 2 );
```

Az átjáró fizetésimód-váltása csak akkor működik, ha az átjáró a 0 összegű kezdő rendelést is fel tudja dolgozni.

## 6. A támogatás jelzése

Ha minden működik, érdemes tesztelned az ismétlődő fizetést. A megújítások kézi elindításához lásd a [Megújítások tesztelése](https://hub.hellowp.io/hu/plugins/woocommerce-subscriptions/megujitas-tesztelese/) fejezetet.

A sikertelen fizetést is kipróbálhatod: töröld vagy módosítsd azt a meta-adatot, amellyel a fizetést feldolgozod. Például a Stripe `_stripe_customer_id` meta-adatát vagy az Authorize.net CIM `_wc_authorize_net_cim_payment_profile_id` meta-adatát az eredeti előfizetési rendelés meta-táblájában. A fizetés feldolgozásakor az érvénytelen ügyféltoken miatt sikertelen lesz, és elindul a sikertelen megújítás folyamata.

## Hibaelhárítás: a megújítás az átjárónál sikeres, de a rendelés státusza nem változik

Ha az átjárónál a megújítási fizetés rendben lefut, de a megújítási rendelés státusza nem lesz **Feldolgozás alatt** vagy **Teljesítve**, valószínűleg PHP végzetes hiba történik a megújítás közben. Okozhatja egyedi kód, bővítményütközés vagy a szerver beállítása.

A diagnózishoz a webhely PHP hibanaplóját kell megnézni. A napló helye nem szabványos, tárhelyenként más lehet. Így találhatod meg:

1. Hozz létre egy `phpinfo.php` nevű fájlt a WordPress gyökérkönyvtárában.
2. Nyisd meg szövegszerkesztőben.
3. Írd bele: `<?php phpinfo(); ?>`
4. Nyisd meg az oldalon, például `https://pelda.hu/phpinfo.php` címen.
5. Keresd meg az oldalon az `error_log` értéket. Az itt szereplő abszolút fájlútvonal a PHP hibanaplója. Ha az érték üres, be kell állítanod a hibák naplózását.

Ha megvan a napló, keresd a megújítás idejére eső `PHP Fatal error` kezdetű sorokat: ezek a hiba okát mutatják. A teszt végén töröld a `phpinfo.php` fájlt a szerverről.
