Tehniline dokumentatsioon

Dokumentatsioon kirjeldab, kuidas integreerida Styx makset oma kodulehele või infosüsteemi.

Päring

Päringu all on mõeldud HTTP POST päringut kindlate parameetritega.

  • Dokumentatsioonile mittevastavatele ja vigastele päringutele vastatakse veateatega ning teavitatakse kaupmeest e-posti teel automaatselt.

Päringuid on kahte tüüpi - kaupmehe päringud ja Styx päringud.

Kaupmehe päring

Kaupmees saadab Styxi tellimuse andmed HTTP POST meetodiga aadressile https://api.styx.ee/

Parameetrid

Parameeter Nimi Tüüp Näide Nõutud
kaupmehe autoriseerimiskood nm_key STRING xxxx Jah
tehingu tunnus nm_order STRING T-1 Jah
tehingu summa nm_amount DOUBLE 120.00 Jah
kliendi e-posti aadress nm_email EMAIL klient@gmail.com Jah
päringu URL nm_returnurl STRING http://styx.ee/return.php Ei
tellimuse tarneaeg päevades nm_delivery INTEGER 3 Ei
kasutaja genereeritud hash nm_userhash STRING XXXXXXXXXXXX Ei

* kui tarneaeg on määramata, arvestatakse tarneajaks 3 päeva (miinimum väärtus on 3)

Näidis päring:
nm_key=7F2AB11457213977BD7125492BD4CF27&nm_amount=120.00&nm_order=T-1&nm_email=klient@gmail.com

7F2AB11457213977BD7125492BD4CF27 on MD5-ga arvutatud autoriseerimiskood. Tehingu summa on 120 eurot ja 0 senti. Tellimuse number sinu süsteemis on T-1 ning kliendi (tellija) e-posti aadress on klient@gmail.com.

Autoriseerimiskoodi arvutamine

Autoriseerimiskood arvutatakse järgnevate väljade liitmise teel:

SINUTUNNUS + nm_order + nm_amount + nm_email = SINUTUNNUST-1120.00klient@gmail.com

seejärel arvutatakse MD5-sum

MD5(SINUTUNNUST-1120.00klient@gmail.com) = 7f2ab11457213977bd7125492bd4cf27

ning teisendatakse väikesed tähed suurteks

7f2ab11457213977bd7125492bd4cf27 = 7F2AB11457213977BD7125492BD4CF27

Näide autoriseerimiskoodi arvutamisest PHP-s

<?php
$myKey = 'SINUTUNNUS';
$nmOrder = 'T-1';
$nmAmount = '120.00';
$nmEmail = 'klient@gmail.com';

$authKey = strtoupper(MD5($myKey.$nmOrder.$nmAmount.$nmEmail));
?>

Näidis vorm kaupmehe kodulehel

<form action="https://api.styx.ee/" method="post"> <input name="nm_key" value="7F2AB11457213977BD7125492BD4CF27" type="hidden"> <input name="nm_order" value="T-1" type="hidden"> <input name="nm_amount" value="120.00" type="hidden"> <input name="nm_email" value="klient@gmail.com" type="hidden"> <input value="submit" src="styx_makse.jpg" alt="Maksa" name="image" border="0" type="image"> </form>

Styx päring

Styx saadab kaupmehe määratud aadressile makseinfo HTTP POST meetodiga pärast kliendi pangast lahkumist.

Parameetrid

Parameeter Nimi Tüüp Nõutud
tehingu summa nm_amount DOUBLE Jah
tehingu tunnus nm_order STRING Jah
kliendi e-posti aadress nm_email EMAIL Jah
tehingu staatus nm_status CHAR Jah
kasutaja genereeritud hash nm_userhash STRING Ei

Näidis päring:
nm_amount=120.00&nm_order=T-1&nm_email=klient@gmail.com&nm_status=B &nm_userhash=XXXXXXXXX

Tehingu staatuste selgitused

P (ootel) - klient on sisenenud panka, kuid makset ei sooritanud või puudub info makse edukuse kohta
B (pangamakse) - pangamakse on edukalt sooritatud
E (vigane pangamakse) - klient sisenes panka kuid katkestas tehingu või puudub info makse edukuse kohta
S (tehing peatatud) - klient on peatanud tehingu täitmise kuna tal on pretensioone
F (tehing lõpetatud) - tehingu eest saadav summa on kantud kaupmehe pangaarvele

Kasutaja genereeritud hash

Styx jätab kasutajale võimaluse genereerida endale sobiv algoritm, kontrollimaks tehingu staatuse õigsust. Selle rakendamiseks on võimalik maksepäringuga kaasa anda parameeter nm_userhash, mille väärtuseks võib olla suvaliselt genereeritud kirje.

Näiteks anname maksepäringuga kaasa parameetri nm_userhash koos väärtusega MD5(nm_order.'B'.nm_amount) ehk MD5 krüpteeritud kirje, mis on saadud tehingutunnuse, eduka pangamakse ja tehingu summa liitmise teel. Styx päringu vastuses saab samal meetodil kontrollida vastuse õigsust (vt näide all).

NB! Toodud näide on lihtsaim algoritm, võid seda oma vajadustele vastavalt kohandada või muuta.

Näide Styx päringu lugemisest kaupmehe serveris ja päringu kontroll PHP-ga

<?php
$myKey = $_POST['nm_key'];
$nmOrder = $_POST['nm_order'];
$nmAmount = $_POST['nm_amount'];
$nmEmail = $_POST['nm_email'];
$nmStatus = $_POST['nm_status'];
$nmHash = $_POST['nm_userhash'];

if ($nmHash == MD5($nmOrder.$nmStatus.$nmAmount)) {
  echo "Tehing õnnestus";
}
else
{
  echo "Tehing ebaõnnestus";
}
?>

Kasutatav sümboolika

Styx ei esita kindlat nõuet, millist sümboolikat oma kodulehel kasutada. On lubatud ja aktsepteerime ka teie disainerite loomingut.


Aadress: http://www.styx.ee/images/logos/styx-logo-3.png


Aadress: http://www.styx.ee/images/logos/styx-logo-1.png


Aadress: http://www.styx.ee/images/logos/styx-logo-2.png