Tovább a tartalomhoz

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 ismerete és a WooCommerce fizetési átjáró API-jának alapos ismerete. Az egyedi kódokra nem vonatkozik terméktámogatás.

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

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

Szekció neve “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:

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

Szekció neve “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.

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:

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:

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

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

Szekció neve “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.

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

Szekció neve “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

Szekció neve “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:

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

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:

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.

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:

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:

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.

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:

WC_Subscriptions_Manager::expire_subscriptions_for_order( $order );

Egy előfizetés lejárata:

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.

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:

WC_Subscriptions_Manager::process_subscription_payments_on_order( $order );

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:

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.

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

Szekció neve “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:

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.

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

Szekció neve “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

Szekció neve “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

Szekció neve “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.

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

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

Szekció neve “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.

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