Implementacija plačilnega sistema

Plačilni sistem omogoča izvedbo plačila iz zunanjih in notranjih aplikacij
Za dostop do njega iz lokalnih aplikacij uporabimo interne sistemske klice, iz zunanjih (oddaljeni strežniki) pa to storimo s pomočjo RPC XML vmesnika.
Navodila za implementacijo komunikacije z RPC XML vmesnikom se nahajajo v sklopu „Uporaba v zunanjih aplikacijah“.

Metode plačilnega sistema

Metoda	Opis	Vhodni parametri	Odgovor
authorizationRequest	Inicializacija zahtevka v sistem	(array) Aplikacija, interni id naročila v aplikaciji, znesek, dodatni podatki	(string) ID avtorizacije
show	Podaja povezavo za procesiranje naročila, kamor preusmerimo uporabnika.	(string) ID avtorizacije	(string) URL za procesiranje
getAuthorization	Vrne osnovne informacije o avtorizaciji.	(string) ID avtorizacije	(array) osnovni podatki uporabnika (brez osebnih)
getMethods	Vrne možne načine prcoesiranja.	(array) Aplikacija, vrednost	(array) ključi/imena možnih načinov procesiranja
getStatuses	vrne možne ključe in imena statusov	(nima parametrov)	(array) Ključi/imena statusov, ki jih avtorizacija posreduje naprej.
voidRequest	razveljavi avtorizacijo	(array) ID avtorizacije, znesek za razveljaviti	(boolean) true/false

authorizationRequest

Določeni plačilni sistemi zahtevajo dodatne informacije o kupcu ali naročilu. Na primer, sistem za plačevanje preko predračuna, zahteva dodatne podatke za izpis virmana, Moneta pa zahteva posredovanje celotne košarice z artikli. Zato ima metoda authorizationRequest kot zadnji parameter array v katerega lahko vnesemo dodatne parametre o kupcu ali košarici. Ti dodatni podatki se prenesejo v trenutno sejo uporabnika. Shranjevanje dodatnih podatkov je prepuščeno izbranemu načinom plačevanja, ki shrani le kar potrebuje. Če potrebnih podatkov ni, in jih lahko posreduje kupec (primer Mobitel kraj prebivališča), ga plačilni sistem sam vpraša po njih v sklopu plačevanja.

Vhodni parametri

array (
[0] => (string) ime aplikacije, doloci ponudnik
[1] => (string) edinstven ID narocila iz zunanje aplikacije
[2] => (float) skupen znesek
[4] => array parametri (
        ... (Array s parametri za plačilo)
    )
)

Vsebuje 2 ključa:
* billing - osebni podatki za plačilo
* items - artikli

billing zahteva naslednja polja:

array (
    [first_name] => (string) ime
    [last_name] => (string) priimek
    [address] => (string) ulica, hisna stevilka
    [country] => (string) drzava
    [zip] => (string) postna stevilka
    [town] => (string) kraj
    [email] => (string) email
)    

V items lahko damo več artiklov, za vsako skupino moramo dolociti naziv, ceno, davek, kolicino in skupno ceno.
Trenutno items potrebuje le Moneta.

array (
[0] => array (
    [name] => (string) naziv artikla
    [id] => (string) id artikla
    [model] => (string) id modela
    [price] => (float) cena artikla/modela
    [tax] => (float) davek
    [quantity] => (int) kolicina
    [discount] => (float) popust v %
    [total] => (float) skupna cena teh artiklov
)
[1] => ...
[2] => ...
)

Odgovor
Vrne string z ID avtentikacije, ki ga uporabimo v show.

show

Vhodni parametri
(string) ID avtorizacije, ki smo ga dobili iz authorizationRequest.
Odgovor
URL kamor moramo preusmeriti uporabnika.

getAuthorization

Vhodni parametri
(string) ID avtorizacije
Odgovor
Vrne podatke od uporabnika v obliki array-a. Ta array ne vsebuje večine osebnih podadtkov.

getMethods

Vhodni parametri

array(
    [0] => ime aplikacije, ki jo doloci ponudnik
    [1] => vrednost, ki jo zelimo sprocesirati
)

Vrednost je pomemben podatek, ker so določena plačila dostopna samo za do ali od določene vsote. Naprimer z Moneto plačamo do 50 eur, zato pri vrednosti 120 eur ta način plačila ni dostopen.

Odgovor
Vrne array s ključi in imeni vseh načinov procesiranja, ki so za nas dostopni za to vsoto.

getStatuses

Vhodni parametri
Nima vhodnih parametrov.
Odgovor
Array možnih statusov (odobreno, preklicano, prekinjeno itd.).

voidRequest

Vhodni parametri

array (
    [0] => (string) ID avtorizacije
    [1] => (float) cena, ki bi jo radi odbili (optional)
)

Odgovor
Uspelo (true)/neuspelo (false).

Noben od trenutno dostopnih načinov plačila ne omogoča storniranje že izvedenega plačila na daljavo in ima za to izveden poseben ureniški vmesnik. Tako je ta sistem trenutno uporaben le za storniranje plačila, ki še ni bilo izvedeno. Če je naprimer uporabnik zapustil plačilni sistem (zaprl brskalnik, šel na drugo spletno stran) in tako onemogočimo ponovno uporabo te avtentikacije, pri sebi pa "prenehamo čakati" na uporabnika.

Povratne informacije o stanju procesiranja

Ob vsaki spremembi statusa avtorizacije plačilni sistem pokliče nazaj prodajno aplikacijo. Ta mora imeti prijavljeno metodo authorizationResponse. Klic posreduje dva parametra. Prvi ja ID internega zahtevka prodajne aplikacije, drugi pa array z kjučema „status_id“ in status „status_name“. Prvi je interni ID statusa, drugi pa je prevod imena statusa v trenutno uporabljen jezik.

Možni statusi avtorizacije

2	Na čakanju
4	Preklicano
6	Uspešno
8	Razveljavljeno

Primer uporabe

Primer pošiljanja zahtevka v plačilni sistem

$app = 'merk'; // Aplkacija za trgovino
$total = 100; // 100 EUR
$order_id = 333; // Interni ID naročila v naši aplikaciji

// Preverimo če je plačilni sistem na voljo
if (!$registry->hasMethod('payment/authorizationRequest')) {
    die("ni plačilnega sistema");
}

// Pogledamo če sploh obstaja kakšen možen način plačila za izbrano vrednost 
// S tem preverimo tudi če se vsi plačilni sistemi prav naložijo  (če so prav nastavljeni etc)
$authorization_methods = $registry->call('payment/getMethods', array($app, $total));
if (is_a($authorization_methods, 'PEAR_Error')) {
    die($authorization_methods->getMessage());
}

// Vnesemo zahtevek v plačilni sistem
$authorizationID = $registry->call('payment/authorizationRequest', array($app, $order_id, $total));
if (is_a($authorizationID, 'PEAR_Error')) {
    die($authorization_methods->getMessage());
}

// Vprašamo plačilni sisetm za naslov kamor preusmerimo kupca za procesiranje
$authorization_url = $registry->link('payment/show', array('id' => $authorizationID));
header('Location: ' . $authorization_url);
exit;

Primer sprejemanja statusov naročil v prodajni aplikaciji

/**
 * Do authorization response.
 *
 * @param string $invoice_id Invoice identification number
 * @param string $params     Additional parameters
 */
function _merk_authorizationResponse($invoice_id, $params)
{
   switch ($params['status_id']) {

        case PAYMENT_STATUS_SUCCESSFUL:
            // avtorizacija uspela.... gremo naprej
            header('Location: hvala.php');
            exit;
        break;

        case PAYMENT_STATUS_PENDING:
            // na čakanju..... tačas mi bomo poslali mail
            $kupec = najdi_mail_kupca($invoice_id);
            mail($kupec, 'hvala za vašo izbiro', 'artikle vam bomo poslali takoj ko prejememo vašo plačilo');
            return true;
        break;

        case PAYMENT_STATUS_REVOKED:
            // kupec je preklical naročilo
            zbri_narocilo($invoice_id);
            header('Location: skoda.php');
            exit;
        break;

        case PAYMENT_STATUS_VOID:
            // administrator je preklical naročilo
            zbri_narocilo($invoice_id);
            return true;
        break;

        default:
            error_log('prišlo je do napake. klicano je s: ' $params['status_name'], 3, '/tmp/napke');
            return true;
        break;
    }
}

Primer vnosa preko RPC z uporabo PHP5 in XML_RPC2

// Namestitev
$app = 'schedul'; // aplikacija za katero dodajemo zahtevo
$id = time(); // interna indentifikacija v aplikaciji
$amount = 100; // vrednost
$params = array(); // dodatni parametri
$options = array('prefix' => 'payment.'); // aplikacija, ki bomo klicali
$dsn = 'http://ime:geslo@demo.drugapisarna.si/rpc.php'; // pot do strežnika

// Priprava clienta
require_once 'XML/RPC2/Client.php';
$client = XML_RPC2_Client::create($dsn, $options);

try {
    $id = $client->authorizationRequest($app, $id, $amount, $params);
    $url = $client->show($id);
    header('Location: '. $url);
    exit;
} catch (XML_RPC2_FaultException $e) {
    die('Request error: ' . $e->getFaultString());
} catch (Exception $e) {
    die('Unkown error: ' . $e->getMessage());
}

Oddaljeno spremljanje statusov

Plačilni sistem posredovanje rezultatov na daljavo ne pozna, saj ne hrani nobenih podatkov o tipu, načinu ali nastavitvah nekega oddaljenega sprejemnika. Zato moramo na stražniku pripraviti mini aplikacijo, ki vsebuje vsaj metodo authenticationResponse. Kar naredimo v njej (GET, RPC, SOAP itd) pa je stvar implementatorja in je seveda lahko za vsako uporabo čisto drugačna.

Glave klicev

/**
 * Get authorization methods linked to an application
 *
 * @param string $app     The Horde application that is doing the authorization
 * @param float  $amount  Amount to process
 */
function _Horde_Payment_getMethods($app, $amount = 0)
{
    ...
}

/**
 * Get available statuses
 */
function _Horde_Payment_getStatuses()
{
    ...
}

/**
 * Add a request to authorization mechanism
 *
 * @param string $app     The Horde application that is doing the authorization
 * @param string $id      Horde appliaction internal id
 * @param float  $amount  Amount for atuherisation request
 * @param array  $params  Addition data passed by selling app
 *                        avaiable to the selling app in the current session.
 */
function _Horde_Payment_authorizationRequest($app, $id, $amount, $params = array())
{
    ...
}

/**
 * Get basic authorization data
 *
 * @param string $id      Authorization id
 */
function _Horde_Payment_getAuthorization($id)
{
    ...
}

/**
 * Void an original authorization or order
 *
 * @param string $id      Authorization id
 * @param float  $amount  Amount for atuherisation request
 */
function _Horde_Payment_voidRequest($id, $amount = 0)
{
    ...
}