PHP biblioteka

Bibliotekos API

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.

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

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

    }
}

Metaduomenų siuntimas

Siekiant užtikrinti programinės įrangos kokybę, naujausias ir saugiausias technologijas bei kokybišką partnerių palaikymą, kartu su mokėjimo pranešimu yra siunčiami meta duomenys:

• naudojamos Gateway PHP bibliotekos versija (pvz., 1.3.0);
• partnerio pusėje naudojamos PHP programinės įrangos versija (pvz., 8.1.10);
• naudojant įskiepį, papildoma įskiepio informacija:
  • platforma (pvz., OpenCart);
  • platformos versija (pvz., 4.0.1.1);
  • OPAY įskiepio versija (pvz. 1.2.0).

Ši informacija yra reikalinga tam, kad galėtume laiku atnaujinti programinės įrangos versiją. Pavyzdžiui, jeigu žemiausia partnerių naudojama PHP versija yra 7.1, mes atnaujinsime OPAY biblioteką ir įskiepius iki šios versijos, kad užtikrintumėme aukštesnį kokybės, greičio ir saugumo lygį.

Meta duomenys yra siunčiami automatiškai visose Gateway bibliotekos versijose, pradedant nuo 1.3.0 versijos. Jei pageidaujate, kad šie nebūtų siunčiami jūsų naudojamos programinės įrangos versijos, kreipdamiesi į metodą signArrayOfParameters() antru parametru pridėkite false reikšmę, pavyzdžiui, $opay➝signArrayOfParameters($data, false);.

Atkreipiame dėmesį, kad, jeigu nesiunčiate meta duomenų, rekomenduojame naudoti PHP ir prekybos platformų versijas ne vėlesnes nei 2 metų. Remdamiesi turimais statistiniais duomenimis, mes ruošiame ir atnaujiname programinės įrangos versijas. Neturint statistinių duomenų apie jūsų naudojamas programinės įrangos versijas, yra tikimybė išleisti programinę įrangą, kuri nebus suderinama su jūsų aplikacija.