Tovább a tartalomhoz

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.

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.
  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.

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.
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',
),

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' );

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.

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 );

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 ú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.

Készült:

Tiszteletben tartjuk a magánszférádat

Sütiket használunk a böngészési élmény javítására és a forgalom elemzésére. Az analitika csak akkor indul, ha engeded. Adatvédelmi irányelvek, Sütitájékoztató.

Sütibeállítások