PHP biblioteka


puzzle icon

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

Bibliotekos žemiausia palaikoma PHP versija - 5.0.1


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 Pardavėjo 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
  • 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 Pirkėjo nukreipimas į pateiktą adresą kartu su duomenimis, siunčiamais POST metodu.
  • $url - pilnas HTTPS adresas kartu su nurodytu protokolu.
    Pavyzdžiui: 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, naudojami komunikacijai su OPAY web servisais

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

Metodas skirtas komunikacijai su OPAY web servisais ir grąžinti web servisų atsakymus:
  • $url - pilnas HTTPS adresas kartu su nurodytu protokolu.
    Pavyzdžiui: 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.

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 bus pasiekiama klasė OpayGateway.

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, keisdami 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į.
  • 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ą.

 


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.

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.

 


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

Kai nukreipiate Pirkėją 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ą

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

 


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.