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 fejezetben találod.
Az alkatrészek
Szekció neve “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
Szekció neve “A folyamat”- Egy megújítási fizetés sikertelen, és a
WC_Subscription->payment_failed()elindítja awoocommerce_subscription_renewal_payment_failedakciót. - 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 ).
- az előfizetés automatikus-e (nem kézi):
- 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 ) ) ) ).
- új, függő újrapróbálás kerül mentésre a szabály szerint:
- Amikor eljön az időpont, a
woocommerce_scheduled_subscription_payment_retryakció lefut, a megújítási rendelés azonosítójával. - 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áscancelled(törölt) státuszú lesz. - 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áscancelled. - Ha megfelel, az előfizetés a fizetés előkészítéseként
on-holdstá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 ). - 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. - Sikertelen fizetésnél a
WC_Subscription->payment_failed()újra elindítja awoocommerce_subscription_renewal_payment_failedakciót, és a folyamat az 1. lépéstől ismétlődik.
Szabályok
Szekció neve “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_rulestulajdonságban, és az adatbázisban az adott újrapróbáláshoz alkalmazott szabály is; - a
WCS_Retry_Rulepéldánya (vagy leszármazottja): ezzel dolgozol egy konkrét szabályon.
A nyers szabály felépítése
Szekció neve “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). |
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
Szekció neve “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.
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
Szekció neve “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):
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
Szekció neve “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:
$rule: awcs_get_retry_rule_raw-nál a fenti kulcsú tömb, awcs_get_retry_rule-nálWCS_Retry_Rulepéldány,null, ha az adott$retry_numberés$order_idmellett nincs szabály.$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.$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.
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.
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
Szekció neve “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:
- Vásárolj előfizetést olyan fizetési móddal, amely támogatja a fizetési dátum módosítását.
- Nyisd meg az előfizetés szerkesztőjét.
- Kattints a ceruza ikonra a számlázási adatoknál.
- Add meg álfizetési token adatokat, hogy a fizetés sikertelen legyen.
- Mentsd az előfizetést.
- Az oldal újratöltése után nyisd le a Rendelés műveletek doboz legördülőjét.
- Válaszd a Megújítás feldolgozása műveletet.
- 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:
- Kapcsold be a hibakeresési módot a
WP_DEBUGkonstanssal. - Nyisd meg a WooCommerce → Állapot → Időzített műveletek oldalt.
- A keresőbe írd be a tesztrendelés azonosítóját.
- Keresd meg a
scheduled_subscription_payment_retryhook sorát függő státusszal. - 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
Szekció neve “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:
- Menet közben: amíg újrapróbálások vannak a bejegyzés-táblákban, a
WCS_Retry_Hybrid_Storehíd a két tár között. Ha egy újrapróbálást lekérdez a kód (példáulWCS_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. - 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_Migratorosztá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 aWCS_Retry_Managerhozza létre, és védett változóban tárolja.
Az áttelepítés állapota az Állapot oldalon látszik:
- Nyisd meg a WooCommerce → Állapot oldalt.
- 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.
Készült: