Fizetési események

A SimplePay fizetési folyamat kardinális pontjaira rákapcsolódás WordPress hooks-ok használatával lehetséges.

Tranzakció indítása

A SimplePay saját terminilógiájában a start hívás. Az átadott adattömbnek jelenleg egy eleme módósítható filter hookkal: az orderRef paraméter, mely a weboldalon belüli egyedi tranzakció azonosító.

$sps_data = array(
    'base'    => array(
        'currency'      => $currency,
        'total'         => $total,
        'language'      => 'HU',
        'timeout'       => $timeout,
        'methods'       => array( 'CARD' ),
        'url'           => add_query_arg( array(
            'action'    => 'SimplePay_BACK',
            'nf_resume' => $form_id
        ), get_site_url() ),
        'orderRef'      => apply_filters( 'ninja_forms_simplepay_order_ref', $order_ref, $form_data ),
        'customerEmail' => $action_settings['simplepay_billing_email'],
    ),
    'invoice' => array(
        'name'    => $action_settings['simplepay_billing_name'] ?: '',
        'company' => $action_settings['simplepay_billing_company'] ?: '',
        'email'   => $action_settings['simplepay_billing_email'] ?: '',
        'city'    => $action_settings['simplepay_billing_city'] ?: '',
        'zip'     => $action_settings['simplepay_billing_zip'] ?: '',
        'address' => $action_settings['simplepay_billing_address'] ?: '',
    ),
);

A filter 2 paramétert kap:

• order_ref: az orderRef alapértelmezett értékét
• $form_data: a Ninja Forms űrlap teljes adattartalma

A fenti kódrészletben látható az is, hogy az invoice tömbben a Simplepay Action beállításai közül a billing data mezők értéke kerül behívásra.

Tranzakció visszatérés

A SimplePay terminológiában a back művelet során a fizető fél a SimplePay fizetőoldalról visszairányításra kerül arra az URL-re, ami a start hívásban lett átadva.

Ezen oldalakon kötelezően tájékoztatni kell a fizető felet a tranzakció eredményéről. Ezt előkészítendő a SimplePay back válaszhívásban GET paraméterként érkező adattömbből összeállításra kerül a megjelenítendő üzenet, mely a simplepay-transaction-result GET paraméterként kerül hozzáfűzésre az Action beállításoknál megadott sikeres / sikertelen URL végére. Ami innentől tetszőleges módon jeleníthető meg a céloldalakon - pl.: shortcode, Elementor Dynamic tag -> request parameter, stb.

Ezen eseményhez tartozó action hook: ninja_forms_simplepay_back, melynek 2 paramétere:

• a SimplePay adattömb
• sikeres, vagy sikertelen volt a tranzakció: ‘success’ / ‘failure’

do_action( 'ninja_forms_simplepay_back', $result, 'success' );

do_action( 'ninja_forms_simplepay_back', $result, 'failure' );

A SimplePay által küldött back válasz struktúrájára példa. Az “o” az orderRef értéke.

{
    "r":0,
    "t":99844942,
    "e":"SUCCESS",
    "m":"PUBLICTESTHUF",
    "o":"101010515680292482600"
}

IPN: jóváhagyott tranzakció

Az Instant Payment Notification (IPN) során a fizetési tranzakció végstátuszáról tájékoztatja a kereskedői rendszert a SimplePay. Ez a fizető fél böngészőjétől függetlenül, POST hívással érkezik a SimplePay fiókban megadott URL-re.

Note

Ugyan a back válaszban előzetes tájékoztatásként szerepel hogy sikeres, vagy sikertelen volt a tranzakció, az csak a SimplePay fizetési felületen végrehajtott műveletre igaz. Az IPN ellenben már a banki csalásvizsgálat eredményét és így a végleges eredményt tartalmazza. Emiatt ha a back hívás értéke success, attól még csak az IPN megérkezte és megfelelő státusza esetén tekinthető lezártnak kereskedői oldalról a tranzakció. Ha a back értéke failure, az egyből végleges eredménynek tekinthető, hiszen már a SimplePay fizetési felületen sem jutott át a folyamat - és alapértelmezett fiók beállítások szerint IPN sem érkezik róla.

A SimplePay által küldött IPN adattömböt kapja meg az ninja_forms_simplepay_ipn action hook:

do_action( 'ninja_forms_simplepay_ipn', json_decode( $json, true ), 'ipn' );

Az IPN hívásban átadott adatokra egy példa:

{
    "salt":"223G0O18VAqdLhQYbJz73adT36YzLtak",
    "orderRef":"101010515680292482600",
    "method":"CARD",
    "merchant":"PUBLICTESTHUF",
    "finishDate":"2019-09-09T14:46:18+0200",
    "paymentDate":"2019-09-09T14:41:13+0200",
    "transactionId":99844942,
    "status":"FINISHED"
}

Ahol az orderRef természetesen a start hívásban átadott egyedi azonosító, mely így alkalmas arra, hogy az oldal értesüljön arról, hogy az adott traznakció sikeresen átment a banki csalásvizsgálaton is.

Alapértelmezetten csak a jóváhagyott, csalásvizsgálaton átment tranzakciókról küld IPN üzenetet a SimplePay, de ez a SimplePay fiókon belül állítható, más kifutásokról is kérhető IPN hívás. Ezeknél természetesen más lesz a status értéke. Erről bővebben az áttekintőben linkelt SimplePay fejlesztői dokumentációban lehet olvasni az IPN fejezetben.