OPAY / Techninė informacija / PHP biblioteka

PHP biblioteka

Parsisiųskite naujausią bibliotekos versiją (v1.2.9)

Bibliotekos žemiausia palaikoma PHP versija - 5.0.1

Parsisiųsti (.zip)


Bibliotekos failų struktūra

Biblioteką sudaro keli failai, kuriuos visada reikia laikyti vieną šalia kito. Į programinį kodą reikia įtraukti failą opay_8.1.gateway.inc.php, po ko Jums bus pasiekiama klasė OpayGateway.

require_once 'opay_8.1.gateway.inc.php';

Failas opay_8.1.gateway.class.<versijos_numeris>.php yra komunikavimą su OPAY, pagal standartą "OPAY_8.1", valdančios klasės OpayGateway failas. Kai OPAY atnaujina šį failą, pasikeičia failo versijos numeris. Tokiu būdu OPAY pasilieka galimybę ateityje atlikti tam tikrų algoritmų patobulinimus, galimų klaidų ištaisymus.

Failuose, kurių pavadinimai baigiasi .interface.php, aprašyti pagrindiniai metodai (funkcijos), skirti jūsų naudojimui.
Interfeisus naudojame tam, kad jūs, keisdamas OPAY bibliotekos failą (opay_8.1.gateway.class.v<klasės_versija>.php) į naujesnę jo versiją, būtumėt užtikrinti, jog jūsų programiniuose scenarijuose naudojami metodai, kurie aprašyti interfeisuose, nesikeičia.


Bibliotekos API

Metodai, skirti pasirašymo būdui nustatyti siunčiant ir gaunant duomenis iš/į OPAY.

Visų pirma yra tikrinama ar nustatytas privatus raktas su sertifikatu, jei ne, tada tikrinama ar nustatytas pasirašymo slaptažodis. Todėl jei nustatysite ir tą, ir tą, bus naudojamas asimetrinis pasirašymas/parašo tikrinimas su privačiu raktu ir sertifikatu.

void setMerchantRsaPrivateKey(string $merchantRsaPrivateKey)

Metodas, skirtas prekybininko privačiam raktui nustatyti.  Naudojamas kartu su metodu setOpayCertificate.

void setOpayCertificate(string $opayCertificate)

Metodas, skirtas OPAY sertifikatui nustatyti. Naudojamas kartu su metodu setMerchantRsaPrivateKey.

void setSignaturePassword(string $signaturePassword)

Metodas, skirtas OPAY išduotam pasirašymo slaptažodžiui nustatyti. Naudojamas vietoje setMerchantRsaPrivateKey ir setOpayCertificate.

int getTypeOfSignatureIsUsed()

Metodas grąžina koks parašo algoritmas bus naudojamas siunčiant duomenis į OPAY.
Galimos  grąžinamos reikšmės: OpayGateway::SIGNATURE_TYPE_PASSWORD arba OpayGateway::SIGNATURE_TYPE_RSA

Metodai, naudojami siunčiant užklausą apmokėjimui.

array signArrayOfParameters(array $parametersArray)

Prie asociatyvaus parametrų masyvo $parametersArray metodas prideda dar vieną masyvo narį indekso pavadinimu "rsa_signature" arba "password_signature" (priklausomai nuo jūsų nustatyto pasirašymo būdo), kurio reikšmė yra šio masyvo struktūrą užtvirtinantis skaitmeninis parašas.

string generateAutoSubmitForm(string $url, array $parametersArray[, boolean $sendEncoded = true])

Metodas, skirtas HTML dokumentui, su jame esančia forma (<form>), sugeneruoti. Forma sudaryta iš parametrų, kuriuos ruošiamasi siųsti POST metodu į $url parametru pateiktą adresą. HTML dokumentas taip pat turi JavaScript fragmentą, kuris automatiškai patvirtitna (angl. submit) formą. Todėl išvedant šį HTML dokumentą  į naršyklę, įvyksta vartotojo nukreipimas į pateiktą adresą kartu su duomenimis, siunčiamais POST metodu.
  • $url - Pilnas HTTPS adresas kartu su nurodytu protokolu. Pvz.: https://gateway.opay.lt/pay/
  • $parametersArray - Masyvas parametrų, kurie bus siunčiami. Masyvo asociatyvus indeksas atspindi parametro pavadinimą, o reikšmė - parametro reikšmę.
  • $sendEncoded - Jei nurodyta reikšmė TRUE, tada visi parametrai bus suspausti ir siunčiami kaip vienas parametras pavadinimu "encoded".

string convertArrayOfParametersToEncodedString(code $parametersArray)

Metodas konvertuoja parametrų masyvą į užkoduotą eilutę. Kurią galima siųsti į OPAY kaip POST/GET parametrą pavadinimų "encoded". Jeigu naudojate funkciją generateAutoSubmitForm su parametro $sendEncoded reikšme TRUE, tai funkcijos convertArrayOfParametersToEncodedString papildomai naudoti nebereikia.

Metodai, naudojami priimant iš OPAY užklausą (pranešimą) apie apmokėjimą.

array convertEncodedStringToArrayOfParameters(string $encodedString)

Metodas konvertuoja užkoduotą eilutę (kuri ateina parametru "encoded") į parametrų masyvą.

boolean verifySignature(array $parametersArray)

Funkcija patikrina ar pasirašyto $parametersArray masyvo informacija yra autentiška ir ar panaudotas teisingas raktas tai informacijai pasirašyti. $parametersArray masyvas laikomas pasirašytu kai turi narį indekso pavadinimu "rsa_signature" arba "password_signature".

Metodai, naudojamis komunikacijai su OPAY web servisais

array webServiceRequest(string $url, array $parametersArray[, boolean $sendEncoded = true])

Metodas skirtas komunikuosi su OPAY web servisais ir grąžinti web servisų atsakymus
  • $url - Pilnas HTTPS adresas kartu su nurodytu protokolu. Pvz.: https://gateway.opay.lt/pay/
  • $parametersArray - Masyvas parametrų, kurie bus siunčiami. Masyvo asociatyvus indeksas atspindi parametro pavadinimą, o reikšmė - parametro reikšmę.
  • $sendEncoded - Jei nurodyta reikšmė TRUE, tada visi parametrai bus suspausti ir siunčiami kaip vienas parametras pavadinimu "encoded".

Bendri naudojimosi biblioteka principai

Prieš pradėdami naudotis OpayGateway klasės objekto metodais, skirtais komunikuoti su OPAY, turite nustatyti kokiu būdu visos užklausos bus pasirašomos

Galimi du pasirašymo principai (arba vienas, arba kitas):

  • Sitmetrinio pasirašymo. Kai abi šalys tiek pasirašymui, tiek parašo tikrinimui naudoja tą patį OPAY suteiktą pasirašymo slaptažodį.
    require_once('opay_8.1.gateway.inc.php');
    $opay = new OpayGateway();
    
    // Nustatome pasirašymo slaptažodį. 
    // Čia naudojamas pavyzdinis pasirašymo slaptažodis, 
    // jūsiškį jums suteiks OPAY.
    $opay->setSignaturePassword("05be076d3f9c0b6f6f2c26542e9b66a6");
  • Asimetrinio pasirašymo. Kai šalys susigeneruoja privačius raktus, pagal juos susigeneruoja SSL sertifikatus ir tais sertifikatais apsikeičia. Duomenų pasirašymui abi šalys naudoja privačius raktus, o parašo tikrinimui (gavus duomenis iš partnerio) naudoja partnerio sertifikatą.
    // Nustatome savo privatų raktą.
    // Čia naudojamas pavyzdinis privatus raktas, 
    // jūsiškį turėtumėte susigeneruoti patys
    $opay->setMerchantRsaPrivateKey("
    -----BEGIN RSA PRIVATE KEY-----
    MIIEowIBAAKCAQEA2koP8ib2OmCfyH18a229DOH8456J4wKsksEtBiMNdeuMdqaW
    r946tqelc8/urcfhrDysfA/+Z4RmmIadBMUMiyL1tl2MJAlY8klj9dhNpGFM4t2k
    WY5msp6hUI1WFFdfFKLSndJsTjVcTYJ8+zJQD2Zssx8zNC8EZqotH0JUotXHKMA3
    qKPp+wlTcXV4vSf4fIK9OmzO4T9fbyf1wwRdDt3JoRzjpfC33DZ5I/QwpmlQ4ktN
    POLeklbrR3VDb2jOkI+FHvHjDcMcp9aGKNrIAt3WnybFBAhJ+yx4NxNSThdH6I/e
    OA/op4E9AYciu6nVzRUwYczrGAunqcy1ZBv4ewIDAQABAoIBAHLa80bzby1KN+hy
    9mtEI2vK4JgXi++xMYJKOFl5ShTYqmCnyLOil3wR+8FTD//KIxjQF+VzOOXYyW7J
    rYab87yl2WlqEVnIvU9GhF0PwdKTC7R28InannivdKuAomEzk6i0/2LhG/GOrBFw
    bjhxwaRIvTsGWJfFgWhPdEx1Rzkhj43039ISmv3M4qxmtsduuYdUruOn+pYBlTpd
    2LFUUdH55J6dyta1U6vln7gmjsqwxI1DMUqhZK8Pf86C6eZFm+p6fIe5q7+yjN5y
    7fudEBA2cMJad/G7leXVOKZCjudCq9uB67AGzPeOJptCWXGQqY88Uf3Ro6+ldvIR
    fuAYD4kCgYEA97wPF1DhUA8aFpdalhHqSMRwyEP7CCs2FegwlFq5NziPL+5RAspQ
    PROjJMSEhZImO0CJGkpIBinh6k093A6oAfyd7tF3aPIdddt5CFql/KNqqbO3c6g+
    KuJFqSuYG9gqicM4VQt7RIwIqHe2PwFniL2nLvk3B3ybX9irDIH3xO8CgYEA4ZKB
    nV6yyatgdPH4WvVC66rAAJYH1a2I28039gLh4AcOB6aWn3yAqkmlZRfcIAqmu/6x
    hzQQbGp5maiCsceE4Qmj1gc7Rf04tVWbFbAhqGs6XDY1B7nxi54QZs03ES3N5Td+
    wU6X8dsNc5KuNQNVBfY9u7nwmyHqNQITBSTQ/TUCgYBG0sy9rbG8YZTjwIF1Rcnk
    48QafNTXkQL1YFwDDazFzLWizk76rTwjOen6KPR5+z5S0jBgA7xzhqW/hjWZI9eE
    OeQs0lWA+zbQ6t2/NaseftmPioF33zFmsSmZI41o6HPAzr7cEVw8TIxtHUxM1uny
    fcW9+CFzUnxY+mhsOvvKoQKBgFqRIRtXLz+LYHHzyPx0JsdKSkax9jlTsHRX5BUR
    OTFig76Mo0MrkNlOMmrxdn8i56jpbMvVGpb89Q+9uaO5cN+NqEtBognKzp733QmL
    KyhczRTC6u3MOXAOKZWs5WQvWNCkRG9Gp/kCM1do2CsOyG9ZW5Xo5PLUXh2kVJCn
    JIXVAoGBAIkieYMAFZXxpELlGM3hBcuY+6ooNjT8ALUoPghJsXVfU1vOZva0lV6W
    icph3FT8lsCPhMm5pSfRKCrveq/qTHYRi+r8q7m0siE2fzBmz8BnsIqqMtQKON+o
    wrtPvaNdQh9lIOWWwY3NI/7Gf+UHXZHavcuSOy3/kWRvaQJ5OzPP
    -----END RSA PRIVATE KEY-----
    ");
    
    // Nustatome OPAY jums suteiktą sertifikatą.
    // Čia naudojamas pavyzdinis sertifikatas. 
    // Kiekvienam tinklalapiui OPAY išduoda specialiai jam sugeneruotą sertifikatą.
    $opay->setOpayCertificate("
    -----BEGIN CERTIFICATE-----
    MIIDEzCCAfugAwIBAgIJAKyrfrqvHyLyMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV
    BAMMFXBhdnl6ZGluaXNwdXNsYXBpcy5sdDAeFw0xNTA5MjUxMzE5MzFaFw0yNTA5
    MjIxMzE5MzFaMCAxHjAcBgNVBAMMFXBhdnl6ZGluaXNwdXNsYXBpcy5sdDCCASIw
    DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANpKD/Im9jpgn8h9fGttvQzh/OOe
    ieMCrJLBLQYjDXXrjHamlq/eOranpXPP7q3H4aw8rHwP/meEZpiGnQTFDIsi9bZd
    jCQJWPJJY/XYTaRhTOLdpFmOZrKeoVCNVhRXXxSi0p3SbE41XE2CfPsyUA9mbLMf
    MzQvBGaqLR9CVKLVxyjAN6ij6fsJU3F1eL0n+HyCvTpszuE/X28n9cMEXQ7dyaEc
    46Xwt9w2eSP0MKZpUOJLTTzi3pJW60d1Q29ozpCPhR7x4w3DHKfWhijayALd1p8m
    xQQISfsseDcTUk4XR+iP3jgP6KeBPQGHIrup1c0VMGHM6xgLp6nMtWQb+HsCAwEA
    AaNQME4wHQYDVR0OBBYEFAzT0uGzL0gckDno42TiUF0/M9lTMB8GA1UdIwQYMBaA
    FAzT0uGzL0gckDno42TiUF0/M9lTMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEF
    BQADggEBADEC5/qo00tK7tmXiqFS29Dbob+2HFItZJtL2wdg9DM0IIhqRnp37gPs
    vUfJ+JVZgiBeNNw9PdVP+G3MCBU1u2qUiGBU1iMS/UV8yl5sDa/fyerclNc6bppE
    7YxqjV5Khe/QgILKMttU9eSX175vBBJ/RUKE+I4mvBMwBD/5+PGBYBtT0FhYDimR
    0jO96XvZt9VWq9GpNm+F9fIK/Qx78C/iwFmpao/OxqVYHuq6CxLchhBL2ej/3gHx
    focG9NjTAJsM3Ld3xz06uhCoD0tJ814exjb8IWsHf2e55Ktl9V4TQiJrveIxHP6w
    i0dFumPRZjPmM/iJwpOkjyWMqe8fLA8=
    -----END CERTIFICATE-----
    ");

 


Pirkėjo nukreipimas į OPAY atsiskaitymo puslapį

Šis pavyzdys parodo kaip su minimaliu kiekiu parametrų nukreipti pirkėją į OPAY atsiskaitymo puslapį. Pavyzdį reikia užsipildyti savo duomenimis.

$opay = new OpayGateway();
$opay->setSignaturePassword("...įveskite savo pasirašymo slaptažodį...");

$paramsArray = array(
  'website_id'            => '8W11U8Y8JF', // OPAY jums suteiktas tinklalapio atpažinimo numeris
  'order_nr'              => '300', // užsakymo numeris jūsų sistmeoje
  'redirect_url'          => 'http://jusu-tinklalapis.lt/sssss', // Čia OPAY nukreips pirkėją po apmokėjimo
  'web_service_url'       => 'http://jusu-tinklalapis.lt/aaaaa', // Čia OPAY siųs pranešimą apie apmokėjimo būseną 
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000, // suma centais
  'currency'              => 'EUR', // valiuta
  'test'                  => '8U11Z8SK8H', // Kad įjungtumėte testavimo režimą, turite pateikti parametrą 'test', kurio reikšmė turi būti jūsų vartotojo atpažinimo numeris OPAY sistemoje (Vartotojo ID). 
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);
echo $opay->generatetAutoSubmitForm('https://gateway.opay.lt/pay/', $paramsArray);

Jei turite pirkėjo el. pašto adresą, pateikite jį parametru 'c_email', ir pirkėjui nereikės jo dar kartą įvesti OPAY atsiskaitymo puslapyje.
Jei turite pirkėjo mobilaus telefono numerį, pateikite jį parametru 'c_mobile_nr'. Tuomet, pirkėjui, atsiskaitančiam mobiliąją pinigine, nereikės jo dar kartą įvesti.


Pirkėjo nukreipimas tiesiai į banką

Pirkėjo nukreipimas tiesiai į banką ar kitą mokėjimo būdą yra lygiai toks pat, kaip Pirkėjo nukreipimas į OPAY atsiskaitymo puslapį, tik reikia pateikti papildomą parametrą 'pass_through_channel_name' ir taip pat pateikti pirkėjo el. pašto adresą parametru 'c_email'.

$opay = new OpayGateway();
$opay->setSignaturePassword("...");
$paramsArray = array(
  'website_id'            => '8W11U8Y8JF', 
  'order_nr'              => '300', 
  'redirect_url'          => 'http://jusu-tinklalapis.lt/sssss', 
  'web_service_url'       => 'http://jusu-tinklalapis.lt/aaaaa', 
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000, 
  'currency'              => 'EUR',
 
  'pass_through_channel_name' => 'banklink_swedbank', // pateikiamas sisteminis mokėjimo būdo pavadinimas, į kurį reikia nukreipti pirkėją
  'c_email'               => 'pirkejo@elpastas.lt' 
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);
echo $opay->generatetAutoSubmitForm('https://gateway.opay.lt/pay/', $paramsArray)

 


Leidžiamų mokėjimo būdų gavimas prieš nukreipiant į banką

Kai nukreipiate pirkėjus tiesiai į banką ar kitą mokėjimo būdą, jums reikia atvaizduoti mokėjimo būdų parinktis, kad pirkėjas galėtų pasirinkti vieną iš jų. Priklausomai nuo pirkinio kainos dydžio ar nuo to, kokie jums mokėjimo būdai  yra aktyvuoti, kai kuriais mokėjimo būdais atsiskaityti gali būti neleidžiama, taigi pirkėjui jie neturi būti matomi. Todėl visada naudokitės OPAY web servisu, kuris grąžins informaciją kokiais mokėjimo būdais yra leidžiama apmokėti šį pirkinį. Taip pat jums nebereikės rūpintis jei norėsite aktyvuoti naujų mokėjimo būdų. Jūsų tinklalapyje jie atsiras automatiškai, po to, kai bus aktyvuoti OPAY pusėje.

Web servisui turite pateikti tą patį parametrų masyvą, kurį vėliau pateiksite metodui generatetAutoSubmitForm, kaip aprašyta skiltyje Pirkėjo nukreipimas tiesiai į banką

$opay = new OpayGateway();
$opay->setSignaturePassword("...");
$paramsArray = array(
  'website_id'            => '8W11U8Y8JF', 
  'order_nr'              => '300', 
  'redirect_url'          => 'http://jusu-tinklalapis.lt/sssss', 
  'web_service_url'       => 'http://jusu-tinklalapis.lt/aaaaa', 
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000, 
  'currency'              => 'EUR',
  'pass_through_channel_name' => 'banklink_swedbank',
  'c_email'               => 'pirkejo@elpastas.lt' 
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);

$array = $opay->webServiceRequest('https://gateway.opay.lt/api/listchannels/', $paramsArray);

echo '<pre>';
print_r($array); 
echo '</pre>';

Žemiau pateikiamas $array rezultato fragmentas.

Spalvomis pažymėtos vietų reikšmės:

  • # - Sisteminis mokėjimo būdų grupės pavadinimas
  • # - Sisteminis mokėjimo būdo pavadinimas
  • # - Mokėjimo būdų grupės pavadinimas
  • # - Mokėjimo būdo pavadinimas

Rezultato fragmentas

Masyve prie kiekvieno mokėjimo būdo pateikiami ir paveikslėlių adresai, kuriuos prašome naudoti, kad paveikslėliai būtų užkraunami iš mūsų. To reikia, kad galėtume suvaldyti bankų logotipų keitimąsi, kai to reikalauja bankai ir k.t. mokėjimo įstaigos. Paveikslėlių adresai gali keistis, bet bet indeksai 'color_33px', 'color_49px' nesikeis (nebent atsiras daugiau indeksų), todėl kreipiantis į juos, visada gausite tuo metu pasiekiamo paveisklėlio adresą.


Atsakymo iš OPAY apie apmokėjimą priėmimas

Atsakymą apie apmokėjimą OPAY siunčia HTTP POST metodu jūsų nurodytu adresu (kurį nurodėte parametru 'web_service_url'). Taip pat lygiai tokį patį duomenų paketą OPAY siunčia HTTP GET metodu kai nukreipia pirkėją po apmokėjimo į kitą jūsų nurodytą adresą (kurį nurodėte parametru 'redirect_url'). Abiem atvejais gautus duomenis reikia išpakuoti ir patikrinti jų autentiškumą. Abiem atvejais tai daroma vienodai.

$opay = new OpayGateway();
$opay->setSignaturePassword("...įveskite savo pasirašymo slaptažodį...");

if (isset($_POST['encoded'])) {

    $parametersArray = $opay->convertEncodedStringToArrayOfParameters($_POST['encoded']);

} elseif (isset($_GET['encoded'])) {

    $parametersArray = $opay->convertEncodedStringToArrayOfParameters($_GET['encoded']);

}

if (isset($parametersArray)) {

    if ($opay->verifySignature($parametersArray)) {

        echo '<pre>';
        print_r($parametersArray); // Čia turite OPAY atsakymo parametrų masyvą
        echo '</pre>';

    } else {

        echo 'Klaida'; // Arba panaudotas neteisingas pasirašymo slaptažodis, arba duomenys buvo pakeisti po jų pasirašymo

    }
}