# Sikertelen fizetések újrapróbálása fejlesztőknek

> Az újrapróbálási rendszer osztályai, folyamata, szabályai, testreszabása, tesztelése és az adatok migrálása.

Ez a fejezet a sikertelen ismétlődő fizetések automatikus újrapróbálásának technikai leírása azoknak, akik testre szabnák vagy bővítenék a rendszert. A nem technikai bemutatót a [Sikertelen fizetések újrapróbálása](https://hub.hellowp.io/hu/plugins/woocommerce-subscriptions/megujitas-ujraprobalas/) fejezetben találod.

## Az alkatrészek

| Osztály | Szerepe |
|---|---|
| `WCS_Retry_Manager` | Az egész rendszert kezeli: betölti az alkatrészeket, a sikertelen fizetés szokásos folyamatába kapcsolódik, ellenőrzi a szabályokat, és szabályt alkalmaz a sikertelen megújítás újrapróbálására. |
| `WCS_Retry_Rules` | Az alapértelmezett, áruház szintű szabályokat állítja be, és metódusokat ad a szabályokkal való munkához (például `get_rule()`). |
| `WCS_Retry_Rule` | Egy szabály példánya, metódusokkal a tulajdonságok lekérdezéséhez és ellenőrzéséhez. |
| `WCS_Retry` | Egy újrapróbálás példánya (például `get_order_id()`, `get_rule()`). |
| `WCS_Retry_Store` | Bővíthető felület az újrapróbálás adatbázisban tárolásához. |
| `WCS_Retry_Post_Store` | A `WCS_Retry_Store` megvalósítása egyéni bejegyzéstípussal, a WordPress bejegyzés-táblákban. |
| `WCS_Retry_Database_Store` | A `WCS_Retry_Store` megvalósítása a `wcs_payment_retries` egyéni táblában. |
| `WCS_Retry_Hybrid_Store` | Híd a két alapértelmezett tár között: ha egy újrapróbálást a bejegyzéstárból kér le a kód, áttelepíti az adatbázistárba. |
| `WCS_Retry_Background_Migrator` | A `WCS_Background_Upgrader` leszármazottja, az áttelepítést végzi a háttérben, Action Scheduler akcióval, a `WCS_Retry_Migrator` segítségével. |
| `WCS_Retry_Migrator` | A bejegyzéstárból az adatbázistárba áttelepítés logikája. |
| `WCS_Retry_Stores` | A két alapértelmezett tár kezelője: `WCS_Retry_Stores::get_post_store()` és `WCS_Retry_Stores::get_database_store()`. |
| `WCS_Retry_Email` | Az újrapróbálás e-mailjeit kezeli: regisztrálja az egyedi e-mail osztályokat, és a megfelelő akcióknál küldi az üzeneteket. |
| `WCS_Email_Payment_Retry` | Az áruház tulajdonosának küldött e-mail sablonja, ha az automatikus megújítási fizetés meghiúsult, és szabály szerint később újra próbálja a rendszer. |
| `WCS_Email_Customer_Payment_Retry` | Az előfizetőnek küldött e-mail sablonja ugyanebben a helyzetben. |
| `WCS_Retry_Admin` | A felületi elemeket állítja be: az automatikus újrapróbálásokat mutató meta dobozt és az újrapróbálási rendszer engedélyezésének beállítását. |
| `WCS_Retry_Table_Maker` | A `WCS_Table_Maker` leszármazottja, megadja az újrapróbálási tábla verzióját és definícióját. |

## A folyamat

1. Egy megújítási fizetés sikertelen, és a `WC_Subscription->payment_failed()` elindítja a `woocommerce_subscription_renewal_payment_failed` akciót.
2. Ehhez kapcsolódik a `WCS_Renewal_Retry_Manager::maybe_apply_retry_rule()`, és ellenőrzi:
   - az előfizetés automatikus-e (nem kézi): `$subscription->is_manual()`;
   - a fizetési mód támogatja-e az automatikus újrapróbálást: `$subscription->payment_method_supports( 'gateway_scheduled_payments' )`;
   - az utolsó rendelés megújítási rendelés-e: `wcs_order_contains_renewal( $last_order )`;
   - van-e szabály az újrapróbálás ezen szakaszára és erre a rendelésre: `WCS_Renewal_Retry_Manager::rules()->has_rule( WCS_Renewal_Retry_Manager::store()->get_retry_count_for_order( $renewal_order->id ), $renewal_order->id )`.
3. Ha minden feltétel teljesül:
   - új, függő újrapróbálás kerül mentésre a szabály szerint: `WCS_Renewal_Retry_Manager::store()->save( $retry )`;
   - a megújítási rendelés státusza a szabály szerint változik: `$order->update_status( $new_status )`;
   - az előfizetés státusza a szabály szerint változik: `$subscription->update_status( $new_status )`;
   - a szabály intervalluma alapján beállítódik az újrapróbálás időpontja: `$subscription->update_dates( array( 'payment_retry' => gmdate( 'Y-m-d H:i:s', gmdate( 'U' ) + $retry_rule->get_retry_interval( $retry_count ) ) ) )`.
4. Amikor eljön az időpont, a `woocommerce_scheduled_subscription_payment_retry` akció lefut, a megújítási rendelés azonosítójával.
5. Ehhez kapcsolódik a `WCS_Renewal_Retry_Manager::maybe_retry_payment()`, és ellenőrzi, hogy az újrapróbálás még függő státuszú-e, és az utolsó rendelésért még fizetni kell-e (`$last_order->needs_payment()`). Ha nem, az újrapróbálás `cancelled` (törölt) státuszú lesz.
6. Ha megfelel, az újrapróbálás `processing` (feldolgozás alatt) státuszba lép, és újra ellenőrzi, hogy az utolsó rendelés és az előfizetés még azt a státuszt viseli-e, amelyet a szabály beállított (`$last_order->has_status( $last_retry->get_rule()->get_status_to_apply( 'order' ) )`, illetve `$subscription->has_status( $last_retry->get_rule()->get_status_to_apply( 'subscription' ) )`). Ha nem, az újrapróbálás `cancelled`.
7. Ha megfelel, az előfizetés a fizetés előkészítéseként `on-hold` státuszba kerül (a bővítmény a szabályban megadott státusztól függetlenül mindig ezt használja közvetlenül a fizetés előtt, mert a fizetési átjárók ezt várják a szokásos ismétlődő fizetésnél): `$subscription->update_status( 'on-hold' )`. Ezután a fizetési átjáró feldolgozza az utolsó rendelés fizetését: `WC_Subscriptions_Payment_Gateways::gateway_scheduled_subscription_payment( $subscription )`.
8. Ha a rendelésért már nem kell fizetni, az újrapróbálás `complete` (kész) státuszba kerül. Ha még kell, `failed` (sikertelen) lesz.
9. Sikertelen fizetésnél a `WC_Subscription->payment_failed()` újra elindítja a `woocommerce_subscription_renewal_payment_failed` akciót, és a folyamat az 1. lépéstől ismétlődik.

## Szabályok

Az újrapróbálás szabályokon alapul. Testreszabható az áruház alapértelmezett szabálykészlete és egy adott rendelésre vonatkozó egyedi szabály is.

**Figyelem:** ne adj olyan szabályt, amely sok (tucatnyi vagy több) újrapróbálást végez, vagy nagyon sűrűn (naponta többször, vagy hetekig minden nap). Egyes fizetési átjárók megjelölhetik a fiókodat, és a vásárló bankjánál is ronthatja a hírnevedet. Az automatikus újrapróbálást mértékkel használd, és a legtöbb (vagy minden) próbálkozásról értesítsd a vásárlót.

A szabály adata kétféle lehet:

- **nyers szabály**: tömb. Így tárolódik az alapértelmezett szabálykészlet a védett `WCS_Retry_Rules->default_retry_rules` tulajdonságban, és az adatbázisban az adott újrapróbáláshoz alkalmazott szabály is;
- a **`WCS_Retry_Rule` példánya** (vagy leszármazottja): ezzel dolgozol egy konkrét szabályon.

### A nyers szabály felépítése

| Kulcs | Jelentése |
|---|---|
| `retry_after_interval` | A szabály alkalmazása és az újrapróbálás közötti idő másodpercben. Az időtartamok halmozódnak: ha az első szabály 24 óra, a második 48 óra, akkor az első újrapróbálás sikertelensége után a második 48 órával később fut, vagyis az első fizetési hibától számítva 72 óra múlva. |
| `email_template_customer` | A vásárlónak küldendő e-mail sablon osztályneve, ha a szabály érvényesül (vagyis a fizetés sikertelen). Üresen nem megy e-mail. |
| `email_template_admin` | Az áruház tulajdonosának küldendő e-mail sablon osztályneve. Üresen nem megy e-mail. |
| `status_to_apply_to_order` | A megújítási rendelés státusza a sikertelen fizetés és az újabb próbálkozás között. Nem a következő próbálkozás sikertelensége utáni státusz, hanem az, amelyet a szabály alkalmazásakor kap, vagyis az előző próbálkozás meghiúsulásakor. Lehet teljes (`wc-pending`) vagy rövid (`pending`) név. |
| `status_to_apply_to_subscription` | Ugyanez az előfizetésre (például `wc-on-hold` vagy `on-hold`). |

```php
array(
    'retry_after_interval'            => DAY_IN_SECONDS,
    'email_template_customer'         => 'WCS_Email_Customer_Payment_Retry',
    'email_template_admin'            => 'WCS_Email_Payment_Retry',
    'status_to_apply_to_order'        => 'pending',
    'status_to_apply_to_subscription' => 'on-hold',
),
```

### Egyedi szabályosztály

A szabályadatból alapból `WCS_Retry_Rule` példány lesz a `WCS_Retry_Manager`-ben és másutt. A `wcs_retry_rule_class` szűrővel lecserélhető az osztály, de ez általában nem szükséges, csak akkor, ha olyan viselkedés kell, amit az alábbi szűrők nem tudnak. Egyedi osztálynál a `WCS_Retry_Rule`-t kell bővíteni, vagy a metódusait mind megvalósítani, különben hiba keletkezik.

```php
function eg_my_custom_retry_rule_class( $default_retry_class ) {
    return 'EG_Retry_Rule';
}
add_filter( 'wcs_retry_rule_class', 'eg_my_custom_retry_rule_class' );
```

### Az alapértelmezett szabályok módosítása

Az alapszabályokat a `WCS_Retry_Rules::__construct()` adja meg, és a `WCS_Retry_Rules::get_rule()` éri el. Egyedi alapszabályokkal az áruházad igényeihez igazíthatod a folyamatot. Például ha csak éves előfizetéseket árulsz, a szabályok a sikertelen fizetéstől számított 30 napig is próbálkozhatnak, nem csak a rövid alapértelmezett ideig.

A `wcs_default_retry_rules` szűrő a nyers szabály-tömböt kapja és adja vissza. Az `add_filter()` hívásnak azelőtt kell megtörténnie, hogy a `WCS_Retry_Rules` először példányosul (ez a `woocommerce_subscription_renewal_payment_failed` és a `woocommerce_scheduled_subscription_payment_retry` akcióhoz kötött).

Példa: 5 újrapróbálás egy hónap alatt (az alapértelmezett 7 nap helyett), három különböző e-mail a vásárlónak, az áruház tulajdonosa csak az első és az utolsó próbálkozásról kap e-mailt, és az előfizetés az első 7 napban aktív marad (türelmi idő a hozzákötött digitális tartalom elérésére):

```php
function eg_my_custom_retry_rules( $default_retry_rules_array ) {
    return array(
        array(
            'retry_after_interval'            => 3 * DAY_IN_SECONDS,
            'email_template_customer'         => '',
            'email_template_admin'            => 'WCS_Email_Payment_Retry',
            'status_to_apply_to_order'        => 'pending',
            'status_to_apply_to_subscription' => 'active',
        ),
        array(
            'retry_after_interval'            => 4 * DAY_IN_SECONDS,
            'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_First_Nag', // egyedi e-mail
            'email_template_admin'            => '',
            'status_to_apply_to_order'        => 'pending',
            'status_to_apply_to_subscription' => 'active',
        ),
        array(
            'retry_after_interval'            => WEEK_IN_SECONDS,
            'email_template_customer'         => '', // a vásárlót nem zaklatjuk újabb e-maillel
            'email_template_admin'            => '',
            'status_to_apply_to_order'        => 'pending',
            'status_to_apply_to_subscription' => 'on-hold',
        ),
        array(
            'retry_after_interval'            => WEEK_IN_SECONDS,
            'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_Second_Nag', // egyedi e-mail
            'email_template_admin'            => '',
            'status_to_apply_to_order'        => 'pending',
            'status_to_apply_to_subscription' => 'on-hold',
        ),
        array(
            'retry_after_interval'            => WEEK_IN_SECONDS,
            'email_template_customer'         => 'EG_Email_Customer_Payment_Retry_Final_Nag', // egyedi e-mail
            'email_template_admin'            => 'WCS_Email_Payment_Retry',
            'status_to_apply_to_order'        => 'pending',
            'status_to_apply_to_subscription' => 'on-hold',
        ),
    );
}
add_filter( 'wcs_default_retry_rules', 'eg_my_custom_retry_rules' );
```

### Egyedi szabály egy rendelésre

Termékenként, számlázási ütemezésenként, fizetési összegenként vagy más feltétel szerint más szabály is alkalmazható: a rendelés azonosítója és az újrapróbálás sorszáma alapján. A nyers (tömb) szabályt a `wcs_get_retry_rule_raw`, a példányosított szabályobjektumot a `wcs_get_retry_rule` szűrővel módosítod. Mindkettő három paramétert kap:

1. `$rule`: a `wcs_get_retry_rule_raw`-nál a fenti kulcsú tömb, a `wcs_get_retry_rule`-nál `WCS_Retry_Rule` példány, `null`, ha az adott `$retry_number` és `$order_id` mellett nincs szabály.
2. `$retry_number`: a sorszám az újrapróbálási sorban, 0-tól. Az első fizetési hiba után még nem volt újrapróbálás, ezért ekkor 0. Ha az első szabály utáni újrapróbálás is sikertelen, a másodiknál már 1.
3. `$order_id`: a rendelés azonosítója.

Példa nyers szabályra: a 30-as azonosítójú termék vásárlóinak más e-mail sablon megy.

```php
function eg_my_custom_retry_rule( $rule_raw, $retry_number, $order_id ) {
    $order       = wc_get_order( $order_id );
    $has_product = false;

    foreach ( $order->get_items() as $line_item ) {
        if ( $line_item['product_id'] == 30 ) {
            $has_product = true;
            break;
        }
    }

    if ( $has_product && ! empty( $rule_raw['email_template_customer'] ) ) {
        $rule_raw['email_template_customer'] = 'EG_Email_Customer_Payment_Retry_Product_Thirty';
    }

    return $rule_raw;
}
add_filter( 'wcs_get_retry_rule_raw', 'eg_my_custom_retry_rule', 10, 3 );
```

Példa szabályobjektumra: egyedi szabályosztály és intervallum az éves előfizetésekhez.

```php
function eg_my_custom_retry_rule( $rule, $retry_number, $order_id ) {
    $subscription = wcs_get_subscriptions_for_order( $order, array( 'order_type' => 'renewal' ) );

    if ( ! empty( $subscription ) && 'year' === $subscription->billing_period ) {
        $existing_rule_raw = $rule->get_raw_data();

        if ( ! empty( $existing_rule_raw['retry_after_interval'] ) ) {
            $existing_rule_raw['retry_after_interval'] = WEEK_IN_SECONDS;
            $rule = new EG_Retry_Rule( $rule->get_rule_raw() );
        }
    }

    return $rule;
}
add_filter( 'wcs_get_retry_rule', 'eg_my_custom_retry_rule', 10, 3 );
```

## Tesztelés

Egyedi szabályok megírása után, vagy hogy kipróbáld, kompatibilis-e a fizetési átjáród az újrapróbálási rendszerrel, így tesztelhetsz. Előtte kapcsold be az újrapróbálási rendszert az áruházban.

A sikertelen ismétlődő fizetést az átjárótól függően máshogy lehet előidézni. Stripe-pal és más, az előfizetés fizetési módjának adminisztrátori módosítását támogató átjárókkal:

1. Vásárolj előfizetést olyan fizetési móddal, amely támogatja a fizetési dátum módosítását.
2. Nyisd meg az előfizetés szerkesztőjét.
3. Kattints a ceruza ikonra a számlázási adatoknál.
4. Add meg álfizetési token adatokat, hogy a fizetés sikertelen legyen.
5. Mentsd az előfizetést.
6. Az oldal újratöltése után nyisd le a **Rendelés műveletek** doboz legördülőjét.
7. Válaszd a **Megújítás feldolgozása** műveletet.
8. Kattints újra a mentésre.

Ez megújítási rendelést hoz létre, rögzíti rajta a sikertelen fizetést, és az első újrapróbálási szabályt alkalmazza. Ekkor látszik a függő újrapróbálás a megújítás újrapróbálásának dátumával az előfizetés szerkesztőjében, és a **Függő** újrapróbálás az automatikus újrapróbálásokat mutató dobozban.

Ha nem akarod megvárni az automatikus indulást, azonnal lefuttathatod az ütemezett újrapróbálást:

1. Kapcsold be a hibakeresési módot a `WP_DEBUG` konstanssal.
2. Nyisd meg a **WooCommerce → Állapot → Időzített műveletek** oldalt.
3. A keresőbe írd be a tesztrendelés azonosítóját.
4. Keresd meg a `scheduled_subscription_payment_retry` hook sorát függő státusszal.
5. Húzd rá az egeret a sorra, és kattints a **Futtatás** műveletre.

Ez azonnal elindítja a `scheduled_subscription_payment_retry` hookot. Az újrapróbálás időpontjait az Action Scheduler kezeli.

## Az adatok migrálása

Az újrapróbálások eredetileg egyéni bejegyzéstípusként a WordPress bejegyzés- és meta-tábláiban tároltak. A teljesítmény javítására később egyéni adatbázis-tábla (`wcs_payment_retries`) került be, a meglévő adatokat át kellett telepíteni. Ez kétféleképpen történik:

1. **Menet közben:** amíg újrapróbálások vannak a bejegyzés-táblákban, a `WCS_Retry_Hybrid_Store` híd a két tár között. Ha egy újrapróbálást lekérdez a kód (például `WCS_Retry_Manager::store()->get_retry( $retry_id )`), a hibrid tár először a bejegyzés-táblában keresi, és ha ott van, az adatokat az új táblába telepíti át, mielőtt visszaadná az objektumot.
2. **A háttérben:** frissítéskor a bővítmény ütemez egy áttelepítési akciót az Action Schedulerrel. Ezt a `WCS_Retry_Background_Migrator` osztály kötegekben dolgozza fel, és alapból 60 másodpercenként újraütemezi magát, amíg minden újrapróbálás átkerül. Az osztályt a `WCS_Retry_Manager` hozza létre, és védett változóban tárolja.

Az áttelepítés állapota az Állapot oldalon látszik:

1. Nyisd meg a **WooCommerce → Állapot** oldalt.
2. Görgess az újrapróbálások áttelepítési állapotának blokkjához.

Hogy hány újrapróbálás van még a bejegyzés-táblákban: ugyanezen az oldalon a bejegyzéstípusok számait mutató részben a `payment_retry` sor értéke az át nem telepített újrapróbálások száma. Ha nincs `payment_retry` sor, nincs több ilyen adat.
