WEB api

OPAY sistemos techninė specifikacija (standartas OPAY_8.1).

Lentelėse Nr. 1 ir Nr. 2 pateikti Pardavėjo siunčiamiems ir gaunamiems duomenims taikomi reikalavimai. Kiekvienas duomuo vadinamas Parametru.

Šios API dokumentacijos aptarnavimas nutrauktas nuo 2023-11-30. Dokumentacija skirta integracijoms, atliktoms iki nurodytos datos.
Naujoms integracijoms rekomenduojame naudoti naujausią Public API v1 dokumentaciją.

Naudojamos sąvokos

Pirkėjo nukreipimas ir Pranešimai tarp serverių

Duomenys, keliaujantys tarp OPAY sistemos ir Pardavėjo tinklalapio gali keliauti dviem būdais:

  1. Pirkėjui keliaujant iš Pardavėjo tinklalapio į OPAY ir iš OPAY į Pardavėjo tinklalapį, kartu keliauja ir tam tikri duomenys, skirti tinklalapiui, į kurį yra keliaujama. Šį duomenų perdavimo būdą vadinsime Pirkėjo nukreipimu, kadangi Pirkėjas yra nukreipiamas iš vieno puslapio į kitą (kuriam perduodami duomenys HTTP POST arba GET metodu).
  2. Du serveriai tiesiogiai vienas su kitu apsikeičia informacija, t. y., vienas serveris išsiunčia tam tikrą pranešimą su duomenimis, o kitas jį priima (HTTP POST metodu). Šį būdą vadinsime Pranešimais tarp serverių.

Sisteminiai atsiskaitymo būdų pavadinimai

Kai programavimo pavyzdžiuose ar kitoje techninėje specifikacijoje prašome pateikti atsiskaitymo būdo (arba mokėjimo būdo) pavadinimą, žinokite, kad prašome jūsų pateikti sisteminį atsiskaitymo būdo pavadinimą.

Atsiskaitymo būdai yra suskirstyti į grupes. Atsiskaitymo būdo sisteminiame pavadinime atsispindi ir grupės pavadinimas. Jei specifikacija leidžia nurodyti daugiau nei vieną atsiskaitymo būdą, vietoj vardinant visus grupės mokėjimo būdus galite nurodyti tik grupės sisteminį pavadinimą. Kai nurodomas grupės pavadinimas, sistema identifikuoja jį taip, lyg būtų išvardinti visi nurodytos grupės atsiskaitymo būdai.

Žemiau esančiame sąraše pateiktos atsiskaitymo būdų grupės su joms priklausančiais atsiskaitymo būdais. Sisteminiai mokėjimo būdų pavadinimai pateikti skliausteliuose šalia pavadinimo.

  1. Internetinė bankininkystė, Lietuva (banklink)
    1. Swedbank bankas (banklink_swedbank)
    2. SEB bankas (banklink_seb)
    3. Luminor bankas (banklink_dnb)
    4. Citadele bankas (banklink_citadele)
    5. Šiaulių bankas (banklink_sb)
    6. Medicinos bankas (banklink_medbank)
  2. Mokėjimas inicijavimo paslauga, Lietuva (pis)
    1. Swedbank bankas (pis_swedbank)
    2. SEB bankas (pis_seb)
    3. Luminor bankas (pis_dnb)
    4. Citadele bankas (pis_citadele)
    5. Šiaulių bankas (pis_sb)
    6. Medicinos bankas (pis_medbank)
    7. Revolut (pis_revolut)
    8. Paysera (pis_paysera)
    9. LKU (pis_lku)
    10. N26 (pis_n26)
    11. Wise (pis_wise)
  3. Mokėjimas inicijavimo paslauga, Latvija (pis)
    1. Swedbank bankas (pis_swedbank.lv)
    2. SEB bankas (pis_seb.lv)
    3. Luminor bankas (pis_luminor.lv)
    4. Citadele bankas (pis_citadele.lv)
    5. Rietumu bankas (pis_rietumu.lv)
    6. Revolut (pis_revolut)
    7. Paysera (pis_paysera)
    8. LPB (pis_lpb.lv)
    9. N26 (pis_n26.lv)
    10. Wise (pis_wise.lv)
  4. Mokėjimas inicijavimo paslauga, Estija (pis)
    1. Swedbank bankas (pis_swedbank.ee)
    2. SEB bankas (pis_seb.ee)
    3. Luminor bankas (pis_luminor.ee)
    4. Citadele bankas (pis_citadele.ee)
    5. LHV bankas (pis_lhv.ee)
    6. Revolut (pis_revolut)
    7. Paysera (pis_paysera)
    8. Coop (pis_coop.ee)
    9. LHV (pis_lhv.ee)
    10. N26 (pis_n26.ee)
    11. Wise (pis_wise.ee)
  5. Mokėjimo kortelė (card)
  6. Pavedimas banke (banktransfer)
  7. Grynieji kasose, Lietuva (cash)
    1. Perlo terminalas (cash_perlas)
  8. Išsimokėtinai, Lietuva (financing)
    1. General Financing (financing_gf)

 


Bendra taisyklė neprivalomais pažymėtiems parametrams

Kai neprivalomas parametras nepateikiamas arba pateikiamas su tuščia reikšme, tai:

  • jei parametras turi lentelėje nurodytą standartinę (angl. default) reikšmę, tada laikoma, kad parametras pateiktas su standartine reikšme.

Kai neprivalomas parametras pateikiamas su reikšme (netuščias), tai:

  • neprivalomų parametrų reikšmės privalo atitikti galimas reikšmes (jei tokios nurodytos lentelėje), reikšmių tipus, maksimalaus reikšmės ilgio reikalavimus. Priešingu atveju bus laikoma, kad įvyko klaida ir parametro reikšmė nustatoma į standartinę.
  • neprivalomų parametrų, kuriems įvyko klaida, reikšmės nustatomos į standartines nestabdant mokėjimo vykdymo. Pirkėjas nėra informuojamas apie klaidą, o Pardavėjas apie šias klaidas informuojamas el. paštu.

Bendra taisyklė privalomais pažymėtiems parametrams

  • Privalomų parametrų reikšmės privalo atitikti galimas reikšmes (jei tokios nurodytos lentelėje), reikšmių tipus ir maksimalaus reikšmės ilgio reikalavimus. Priešingu atveju įvyks klaida.
  • Privalomų parametrų klaidos išjungia atsiskaitymo būdo (-ų), kuriam (-iems) reikalingas šis parametras, rodymą.
  • Jei neužtenka nei vieno privalomo parametro, kad patenkinti nors vieno atsiskaitymo būdo reikalavimus, tuomet tolesnis vykdymas yra stabdomas. Pirkėjui atvaizduojamas puslapis su informacija apie klaidą, Pardavėjas informuojamas apie ją el. paštu.

Pardavėjo siunčiami duomenys

Pardavėjo siunčiamų duomenų (parametrų) kiekis vykdant Pirkėjo nukreipimą į OPAY skiriasi priklausomai nuo to, kokiomis mokėjimo paslaugomis Pardavėjas naudojasi, remiantis Sutartimi sudaryta tarp OPAY ir Pardavėjo.Pardavėjas, kiekvieną kartą siųsdamas užklausą, gali nurodyti tam apmokėjimui norimus atsiskaitymo būdus (norimą Mokėjimo paslaugą), Sutartyje apibrėžtųMokėjimo paslaugų ribose. Dalis siunčiamų parametrų sutampa visiems atsiskaitymo būdams. Atkreipkite dėmesį į kiekvienam atsiskaitymo būdui (Mokėjimo paslaugai) reikalingus ir privalomais pažymėtus parametrus.

Pardavėjas, pateikdamas mažesnį kiekį privalomų parametrų ir norėdamas tikslingai atsisakyti kai kurių atsiskaitymo būdų (Mokėjimo paslaugų), turi tai pranešti parametrais show_channels ir/arba hide_channels, atsisakant tų atsiskaitymo būdų, kurie ir taip Pirkėjui būtų nerodomi dėl neužtenkamų privalomų parametrų. Jei to Pardavėjas nepadarys, OPAY sistema kas kartą informuos Pardavėją el. paštu apie dėl per mažai pateiktų privalomų parametrų, galimai per klaidą nerodomus atsiskaitymo būdus.

Sistemai siunčiami duomenys privalo būti UTF-8 koduotės. Duomenys siunčiami HTTP POST arba GET metodu, adresu https://gateway.opay.lt/pay/.

Lentelės Nr. 1 stulpelių paaiškinimas:

  • Parametras. Parametro pavadinimas.
  • Maksimalus reikšmės ilgis. Parametrui priskirtos reikšmės simbolių kiekis negali būti didesnis nei šiame stulpelyje nurodyta reikšmė.
  • Reikšmės tipas. str – tekstas (galimos raidės, skaičiai ir kiti UTF-8 koduotės simboliai, jei prie parametro aprašymo nėra tiksliai nurodytos galimos reikšmės), int – sveikas skaičius (galimi tik skaičiai, be kablelių ar taškų).
  • Standartinė reikšmė (angl. default). Nepateikus parametro ar pateikus su neteisingais duomenimis, bus taikoma šiame stulpelyje nurodyta standartinė reikšmė (jei tokia pateikta).
  • Banklink, Card, Financing, Mobilewallet. Šioms grupėms priklausantiems atsiskaitymo būdams reikalingi parametrai.
  • Banktransfer, Cash. Šioms grupėms priklausantiems atsiskaitymo būdams reikalingi parametrai.
  • Privalomas. Jei parametras, pažymėtas privalomu, bus pateiktas su neteisingais duomenimis ar nepateiktas iš viso, tai atsiskaitymo būdas, kuriam šis parametras yra reikalingas, bus Pirkėjui neatvaizduojamas. Atkreipkite dėmesį kaip sutampa ar nesutampa (pvz., Banklink ir Banktransfer) stulpeliuose pažymėti laukai su privalomais pažymėtais laukais. Gali būti, kad dėl klaidos neužteks privalomų parametrų pateikti Banklink atsiskaitymo būdą, bet Banktransfer atsiskaitymo būdui reikalingų privalomų parametrų užteks.
  • Aprašymas. Šiame stulpelyje pateikiamas detalus parametro paaiškinimas ar komentaras.

Duomenys gali būti siunčiami kaip vienas parametras. Siunčiant duomenis šiuo būdu, duomenys turi būti sudedami į vieną eilutę, kuri yra paverčiama į base64 koduotę ir siunčiama vieninteliu parametru pavadinimu encoded. Plačiau apie tai skaitykite skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų..

Lentelė Nr. 1

Pardavėjo siunčiamų duomenų aprašymas (HTTP POST arba GET parametrai).

  pažymėta.
  nepažymėta.
Parametras
tipas(maks. ilgis)
Galimos reikšmės,
standartinė reikšmė
Banklink, Card, Financing, Mobilewallet Banktransfer, Cash Privalomas Rodyti aprašymus Slėpti aprašymus
website_id
str(10)
        Rodyti aprašymą Slėpti aprašymą
Pardavėjo interneto Parduotuvės unikalus kodas, kurį OPAY suteikia ir nurodo Pardavėjo ir OPAY pasirašytoje Sutartyje.
order_nr
str(40)
        Rodyti aprašymą Slėpti aprašymą
Parduotuvės sugeneruotas užsakymo numeris. Pardavėjas jį pateikia tam, kad OPAY atsakyme matydamas šį numerį Pardavėjas žinotų kurio tai užsakymo mokėjimo patvirtinimas ar pranešimas apie nepavykusį mokėjimą.

a – ž A-Ž (lietuviškos mažosios ir didžiosios raidės), 0 – 9, (kablelis), . (taškas),  (tarpas),  ( ) (lenktiniai skliaustai),  ; (kabliataškis), - (trumpas brūkšnelis).

Leidžiamų simbolių Regex atrodytų taip: a-zA-Z0-9ąčęėįšųūžĄČĘĖĮŠŲŪŽ,\.\s();\-
redirect_url
str(255)
        Rodyti aprašymą Slėpti aprašymą
Pilnas HTTP internetinis adresas su nurodytu protokolu (pvz.: https://puslapis.lt/failas.jsp). Tai adresas, kur nukreipiamas Pirkėjas po apmokėjimo.
redirect_on_success
int(1)
0, 1       Rodyti aprašymą Slėpti aprašymą
Kai kuriais atvejais grįžtantis Pirkėjas į Pardavėjo puslapį (į redirect_url) negali kartu atsinešti OPAY pasirašyto duomenų paketo, kuris sakytų jog mokėjimas įvykęs. Tai sąlygoja kai kurių OPAY Partnerių (pvz., kai kurių bankų) negalėjimas iš karto po atlikto mokėjimo suteikti OPAY informaciją ar mokėjimas yra pavykęs.
Parametro galimos reikšmės:
  • 1. Jeigu nurodysite 1, tai tokiu atveju Pirkėjui OPAY atvaizduos langą „Mokėjimas apdorojamas“ iki tol, kol OPAY gaus informaciją apie mokėjimo būseną. Po to, pavykusio mokėjimo atveju, Pirkėjas iškarto bus nukreiptas į Pardavėjo puslapį (redirect_url) su duomenų paketu (pranešimu) patvirtinančiu sėkmingą mokėjimą (status = 1) arba, nepavykusio mokėjimo atveju, grąžintas į OPAY atsiskaitymo būdų pasirinkimo langą su prašymu pasirinkti kitą atsiskaitymo būdą.
  • 0. Jeigu nurodysite 0, tai, jei Pirkėjo grąžininimo į Pardavėjo puslapį (redirect_url) metu OPAY neturės informacijos apie mokėjimo būseną, Pirkėjas bus grąžintas su duomenų paketu (pranešimu) „Mokėjimo nurodymas priimtas“ (status = 2), o jei OPAY informaciją turės, tada grąžins įprastai su duomenų paketu „Mokėjimas įvykdytas sėkmingai“ (status = 1).
    Reikšmė 0 nurodo OPAY nenaudoti laukimo lango Mokėjimas apdorojamas, o iškarto nukreipti Pirkėją kartu perduodant informaciją apie mokėjimą tokią, kokią OPAY turi.
Naudojant laukimo langą „Mokėjimas apdorojamas“, į Pardavėjo puslapį bus grąžinami tik Pirkėjai sėkmingai atlikę mokėjimą. Šiuo atveju Pardavėjo sistema gali atlikti reikiamus veiksmus, t.y. iškarto suteikti paslaugą ar bent jau padėkoti už sėkmingai atliktą mokėjimą.
web_service_url
str(255)
        Rodyti aprašymą Slėpti aprašymą
HTTP adresas su nurodytu protokolu (pvz.: https://puslapis.lt/failas.jsp), kuriuo bus siunčiamas OPAY serverio atsakymas apie mokėjimą.
back_url
str(255)
        Rodyti aprašymą Slėpti aprašymą
Pilnas HTTP adresas su nurodytu protokolu (pvz.: https://puslapis.lt/failas.jsp). Jeigu pateiktas šis adresas, tai OPAY, atsiskaitymo puslapyje Pirkėjui paspaudus „Grįžti į pardavėjo tinklalapį“, nukreips Pirkėją nurodytu adresu kartu su HTTP GET metodu perduodamu parametrais (Lentelė Nr. 2, Stulpelis „Kai atsakymo parametras status = 5“).
Verta paminėti porą grąžinamų parametrų:
  • transaction_id, kurio reikšmė yra operacijos, kuri buvo sukurta šiam mokėjimui, unikalus kodas;
  • language, kurio reikšmė yra trijų raidžių kalbos kodas (ISO 639-3), viena iš OPAY palaikomų kalbų. Kalba siunčiama tam, kad jei Pirkėjas OPAY tinklalapyje pakeistų kalbą, tai Pardavėjas grįžusiam Pirkėjui informaciją galėtų atvaizduoti ta pačia kalba.

Nuorodos https://gateway.opay.lt/?tid=<transakcijos kodas> pagalba galėsite grąžinti Pirkėją tiesiai į tą patį atsiskaitymo puslapį, jei Pirkėjas nieko nekeičia pirkinių krepšelyje, o tiesiog naviguoja tarp Pardavėjo ir OPAY atsiskaitymo puslapių.

Atkreipkite dėmesį, kad tai nėra mokėjimo nutraukimo nuoroda, o tiesiog galimybė Pardavėjui leisti laisvai naviguoti tarp OPAY mokėjimui skirto puslapio ir parduotuvės. Šią nuorodą gali paspausti asmuo, kuris nėra pradinis Pirkėjas (ne tas asmuo, kurio prisijungimo sesija galioja Pardavėjo svetainėje), nes mokėjimui skirtą puslapio nuorodą Pirkėjas gali persiųsti apmokėti kitam asmeniui.

Pagal poreikius galite back_url nuorodoje naudoti pirkinių krepšelį ar pan. identifikuojančius parametrus.

Pastaba. Šis parametras skirtas tik labai individualius porekius turintiems Pardavėjams ir jų nestandartinėms sistemoms, kurioms yra būtina navigavimo tarp OPAY ir Pardavėjo tinklalapių galimybė.

standard
str(9)
opay_8.1       Rodyti aprašymą Slėpti aprašymą
Duomenų mainų specifikacijos versija. Pardavėjo ir OPAY sistemos turi žinoti kurios specifikacijos pagrindu pateikiami/gaumami duomenys.
language
str(3)
LIT, ENG, LAV, EST, RUS       Rodyti aprašymą Slėpti aprašymą
Kokia kalba rodyti Opay mokėjimo puslapį.
amount
int(10)
        Rodyti aprašymą Slėpti aprašymą
Kokia sumą Pirkėjas turi apmokėti. Suma pateikiama centais.
currency
str(3)
EUR       Rodyti aprašymą Slėpti aprašymą
Kokia valiuta pateikiama suma apmokėjimui.
show_channels
str(1000)
Skaityti aprašymą       Rodyti aprašymą Slėpti aprašymą
Čia galite nurodyti šiam mokėjimui pageidaujamus atsiskaitymo būdus. Žiūrėti “Parametrai show_channels ir hide_channels.
hide_channels
str(1000)
Skaityti aprašymą       Rodyti aprašymą Slėpti aprašymą
Čia galite nurodyti šiame mokėjime nepageidaujamus atsiskaitymo būdus. Žiūrėti “Parametrai show_channels ir hide_channels.
country
str(2)
LT, LV, EE       Rodyti aprašymą Slėpti aprašymą
Remiantis nurodyta šalimi, Pirkėjui pateikiami toje šalyje galimi atsiskaitymo būdai (ISO 3166-1 alpha-2).
payment_description
str(128)
Skaityti aprašymą       Rodyti aprašymą Slėpti aprašymą

Pirkėjui atliekant mokėjimą, šis tekstas nurodomas mokėjimo paskirtyje. Tekstą galite sukurti savo nuožiūra, bet tekste turite naudoti žymes:

  • {order_nr} – Užsakymo numeris Pardavėjo sistemoje
  • {website} – tinklalapio (Parduotuvės) adresas
  • {merchant} – Pardavėjo pavadinimas.

Vietoje žymės OPAY sistema į tekstą įterps jos reikšmę
Privaloma žymė yra {order_nr}, taip pat privaloma bent viena iš žymių {website} arba {merchant}.

Pardavėjo sukurtame tekste gali būti naudojami tik šie simboliai:
a – ž A-Ž (lietuviškos mažosios ir didžiosios raidės), 0 – 9, (kablelis), . (taškas),  (tarpas),  ( ) (lenktiniai skliaustai),  ; (kabliataškis), - (trumpas brūkšnelis).

Leidžiamų simbolių Regex atrodytų taip: a-zA-Z0-9ąčęėįšųūžĄČĘĖĮŠŲŪŽ,\.\s();\-

Standartinė reikšmė: Apmokėjimas pagal užsakymą Nr. {order_nr}, tinklalapyje {website}

time_limit
int(7)
        Rodyti aprašymą Slėpti aprašymą
Minutės, per kiek laiko turi būti atliktas mokėjimas. Plačiau apie šį parametrą skaitykite skiltyje Parametras time_limit
test
str(10)
Skaityti aprašymą       Rodyti aprašymą Slėpti aprašymą
Šiuo parametru reikia pateikti vartotojo, kuriam suteikta teisė testuoti duotąjį tinklalapį, atpažinimo numerį (Vartotojo ID OPAY sistemoje). Nurodę šį parametrą galėsite testuoti duomenų mainus su OPAY. Realūs mokėjimai nebus vykdomi.
c_email
str(100)
        Rodyti aprašymą Slėpti aprašymą
Pirkėjo el. pašto adresas. Jei jį nurodysite, Pirkėjui nebereikės įvedinėti savo el. pašto adreso OPAY mokėjimo puslapyje.
c_mobile_nr
str(30)
        Rodyti aprašymą Slėpti aprašymą
Pirkėjo mobilaus telefono numeris. Pateikiamas su tarptautiniu kodu. Pvz.: +37065912387. Jei nurodysite,Pirkėjui, atsiskaitančiam mobiliąja pinigine, nebereikės įvedinėti savo mobilaus telefono numerio OPAY mokėjimo puslapyje.
pass_through_channel_name
str(30)
        Rodyti aprašymą Slėpti aprašymą

Tai nurodymas OPAY sistemai nerodyti mokėjimų pasirinkimo lango, o iškarto nukreipti Pirkėją į norimą atsiskaitymo būdą, pvz.: banklink_swedbank.

Tam, kad šis funkcionalumas suveiktų, parametras c_email negali būti tuščias.

pass_through_only
int(1)
0, 1       Rodyti aprašymą Slėpti aprašymą

Šis parametras gali būti naudojamas tik su parametru pass_through_channel_name.

Standartiškai OPAY sistema veikia taip, kad nepavykus mokėjimui kuriame nors iš mokėjimo būdų, pirkėjas yra grąžinamas į OPAY mokėjimo būdų pasirinkimo langą, o ne atgal į pardavėjo tinklalapį. Taip pirkėjui suteikiama galimybė pasirinkti kitą mokėjimo būdą ar išsiųsti mokėjimą kitam žmogui.

Naudodami parametrą pass_through_only su reikšme 1 (pass_through_only = 1), Jūs nurodote OPAY sistemai, kad sistema naudotų tik mokėjimo būdą, nurodytą parametru pass_through_channel_name. Nepavykus mokėjimui, pirkėjas nebebus grąžinamas į OPAY mokėjimo būdų pasirinkimo puslapį, o bus grąžinamas atgal pas pardavėją, parametre redirect_url nurodytu adresu. Pirkėjas grąžinamas į el. parduotuvę su pranešimu "Atšauktas mokėjimas" (status = 3).

rsa_signature
str(700)
        Rodyti aprašymą Slėpti aprašymą
Parašas, gautas RSA privačiu raktu pasirašius visus siunčiamus duomenis. Tai OPAY rekomenduojamas pasirašymo būdas. Pasirašymo būdai sutariami Sutartyje.
password_signature
str(32)
        Rodyti aprašymą Slėpti aprašymą
Parašas, gautas slaptažodžiu pasirašius visus siunčiamus duomenis. Slaptažodis yra OPAY suteiktas ir Sutartyje nurodytas unikalus simbolių darinys, žinomas tik OPAY ir Pardavėjui, kuris naudojamas tiek Pardavėjui pasirašant, tiek OPAY tikrinant Pardavėjo parašą ir atvirkščiai, - OPAY pasirašant ir Pardavėjui tikrinant.
Pasirašymo būdai sutariami Sutartyje.

Pardavėjo gaunami duomenys

Parametrų duomenys yra UTF-8 koduotės.

Dėmesio! Pardavėjo serveris iš OPAY serverio, pranešimų tarp serverių metu, duomenis gaus tik HTTP POST metodu.Pirkėjo nukreipimo į pardavėjo tinklalapį metu, tinklalapiui duomenys gali būti perduodami tiek GET, tiek POST metodu. Standartiškai duomenys bus perduodami GET metodu. Norėdami duomenis gauti POST metodu, kreipkitės į OPAY.

Pardavėjui siunčiami parametrai yra siunčiami kaip vienas parametras pavadinimu encoded. Visi parametrai sudedami į vieną eilutę, kuri yra paverčiama į base64 koduotę. Plačiau apie tai skaitykite skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų.

OPAY serveris tokį patį pranešimą gali išsiųsti pakartotinai, todėl Pardavėjas, priimdamas pranešimą, visada turi patikrinti ar jau nėra prieš tai tokio gavęs.

Sėkmingo mokėjimo atveju (status = 1), tai rodys parametras p_token.

Jei Pardavėjas gavo pakartotiną pranešimą apie sėkmingą apmokėjimą (status = 1), kur parametro order_nr reikšmė sutampa su prieš tai gautu (-ais) pranešimu (-ais), bet parametro p_token reikšmės skiriasi, tai reiškia, kad tai atlikti skirtingi mokėjimai už tą patį prekių krepšelį (parametru order_nr grąžinamas Pardavėjo pateiktas užsakymo / krepšelio numeris Pardavėjo sistemoje).

Pardavėjas turi tikrinti parametro status reikšmę. Ateityje pranešimų tipų (status reikšmių) gali atsirasti daugiau, todėl Pardavėjo serveris turi reaguoti tik į pranešimus su jam žinomomis parametro status reikšmėmis.

Pardavėjui yra būtina patikrinti ar sutampa suma ir valiuta, kuria gaunamas mokėjimas, su suma ir valiuta, kurios buvo nurodytos siunčiant užklausą į OPAY. Priežastis – atsiskaitant kai kurias mokėjimo būdais (pvz.: Pavedimu banke) Pirkėjas gali klaidingai nurodyti sumą ar valiutą.

Pardavėjui siunčiamame pranešime apie sėkmingą mokėjimą pateikiama valiuta (parametras currency), suma (parametras amount), kurias Pardavėjas siuntė į OPAY, ir valiuta (parametras p_currency), suma (parametras p_amount), kurias Pirkėjas sumokėjo. Nesutampant šiems parametrams, OPAY papildomai informuos Pardavėją el. paštu, tačiau yra svarbu, kad Pardavėjo sistema pati atrastų nesutapimus ir atliktų teisingus Pardavėjo nurodytus tolimesnius veiksmus.

OPAY sistemai siunčiant atsakymą į Pardavėjo pateiktą interneto adresą, skirtą komunikacijai tarp serverių (parametras web_service_url), Pardavėjo serveris turi atsakyti OPAY sistemai, kad Pardavėjo sistema duomenis priėmė. Pardavėjo sistema turi grąžinti tekstą OK. OPAY sistema nekreipia dėmesio į HTTP antraštėje (angl. header) pateiktus įrašus (pvz.: Status ar Content-Type), ji tikrina teksto dalį, kur laukia atsakymo OK. OPAY serveris, išsiuntęs užklausą su pranešimu, laukia atsakymo 3 sekundes.

OPAY sistema, nesulaukusi atsakymo ar negavusi OK, laiko, kad pranešimas buvo negautas, todėl pakartotinai jį siųs vėliau. Po pirmojo nesėkmingo bandymo, OPAY sistema bandys išsiųsti pakartotinai duomenis dar 3 kartus. Pirmą kartą – po 1 min., antrą – po 5 min., o trečią – po 1 val.

Jei ir po trečiojo (iš viso ketvirtojo) bandymo OPAY sistema nesulaukia teisingo atsakymo, šis pranešimas daugiau automatiškai siunčiamas nebebus.

Lentelė Nr. 2 Gaunamų parametrų aprašymas.

  siunčiamas visada.
  siunčiamas priklausomai nuo Pardavėjo siųstų duomenų arba informacijos, kurią pateikia OPAY mokėjimų Partneris.
  nesiunčiamas.
Parametras
tipas(maks. ilgis)
Galimos reikšmės Kai atsakymo parametras status = 1 Kai atsakymo parametras status = 0 Kai atsakymo parametras status = 2, status = 3 Kai atsakymo parametras status = 5 Rodyti aprašymus Slėpti aprašymus
status
int(1)
0, 1, 2, 3, 5         Rodyti aprašymą Slėpti aprašymą

Šis parametras apibrėžia pranešimo tipą.

0 – Mokėjimas (Operacija) neįvyko per nurodytą (parametru time_limit) laiką. Pranešimas siunčiamas tik į parametere web_service_url (Lentelė Nr. 1) nurodytą adresą ir tik tuo atveju, kai pardavėjui siunčiant užklausą į OPAY buvo nurodytas time_limit parametras.

1 – Mokėjimas (Operacija) įvykdytas sėkmingai. Naudojantis sandartiniu OPAY funkcionalumu, „status = 1“ yra vienintėlis OPAY pranešimo tipas. Visi kiti pranešimai aktyvuojasi papildomai, parametrais, aprašytais lentelėje Nr. 1.

Pranešimas yra siunčiamas kai pirkėjas nukreipiamas į redirect_url (Lentelė Nr. 1) nurodytą adresą, kartu su HTTP GET metodu perduodamais duomenimis. Pranešimas pakartotinai siunčiamas į parametre web_service_url (Lentelė Nr. 1) nurodytą adresą, kartu su HTTP POST metodu perduodamais duomenis.

Pranešimas, ateinantis kartu su pirkėjuredirect_url) ir pranešimas, siunčiamas tiesiai į serverį (įweb_service_url) vienas kito atžvilgiu yra asinchroniški. Tai yra, pirma gali ateiti vienas, arba pirma kitas. Vartotojas su pranešimu iš viso gali neateiti (į redirect_url), jei uždarytų naršyklę. Bet pranešimas į serverį (web_service_url) siunčiamas visada.

2 – Mokėjimo nurodymas priimtas. Jei Pardavėjas, siųsdamas užklausą mokėjimui, nurodė parametro redirect_on_success reikšmę „0“, tai grįžtantis po mokėjimo Pirkėjas (Pirkėjas visada nukreipiamas į redirect_url nurodytą adresą) gali grįžti su šio tipo pranešimu. Pardavėjui pateikus redirect_on_success = 0, OPAY iš karto, nelaukiant mokėjimo būsenos iš Partnerio, Pirkėją grąžina į Pardavėjo nurodytą parametre redirect_url adresą. Šis pranešimo tipas yra todėl, kad kai kurie OPAY Partneriai (pvz.: kai kurie bankai) negali iš karto po atlikto mokėjimo pranešti OPAY sistemai ar mokėjimas yra pavykęs

3 – Mokėjimas atšauktas Jei Pardavėjas, siųsdamas užklausą mokėjimui, nurodė parametro pass_through_only reikšmę „1“ ir kitos šiam parametrui reikiamos sąlygos buvo įvykdytos (teisingai nurodytas pass_through_channel_name ir c_email), tai nepavykus ar atšaukus mokėjimą viename iš mokėjimo būdų, Pirkėjas bus grąžintas pas Pardavėją (Pirkėjas visada nukreipiamas į redirect_url nurodytą adresą) su šio tipo pranešimu.

5 – Pirkėjas paspaudė mygtuką „grįžti į pardavėjo tinklalapį“ (Lentelė Nr. 1, parametras back_url). Pirkėjas nukreipiamas į parametre back_url nurodytą adresą kartu su pranešimu, siunčiamu HTTP GET metodu.

website_id
str(10)
          Rodyti aprašymą Slėpti aprašymą
Pardavėjo interneto Parduotuvės unikalus kodas, kurį OPAY suteikia ir nurodo Pardavėjo ir OPAY pasirašytoje Sutartyje.
transaction_id
str(10)
          Rodyti aprašymą Slėpti aprašymą
OPAY suteiktas Operacijos unikalus numeris, kuris identifikuoja Pardavėjo suformuotą transakciją OPAY sistemoje. Naudojant šį numerį galima atsidaryti konkrečiam atsiskaitymui skirtą puslapį.
order_nr
str(40)
          Rodyti aprašymą Slėpti aprašymą
Parduotuvės sugeneruotas užsakymo numeris. Pardavėjas jį pateikia tam, kad OPAY atsakyme matydamas šį numerį Pardavėjas žinotų kurio tai užsakymo mokėjimo patvirtinimas ar pranešimas apie nepavykusį mokėjimą.
standard
str(9)
opay_8.1         Rodyti aprašymą Slėpti aprašymą
Duomenų mainų specifikacijos versija. Pardavėjo ir OPAY sistemos turi žinoti kurios specifikacijos pagrindu pateikiami / gaunami duomenys.
language
str(3)
LIT         Rodyti aprašymą Slėpti aprašymą
Kokia kalba buvo rodytas OPAY mokėjimo puslapis.
amount
int(10)
          Rodyti aprašymą Slėpti aprašymą
Parametro reikšmė atitinka Pardavėjo siųstą į OPAY reikšmę.
currency
str(3)
EUR         Rodyti aprašymą Slėpti aprašymą
Parametro reikšmė atitinka Pardavėjo siųstą į OPAY reikšmę.
test
str(10)
          Rodyti aprašymą Slėpti aprašymą
Jei šis parametras yra pateiktas, reiškia, kad tai testinis pranešimas. Tikras mokėjimas nebuvo atliktas. Parametro reikšmė atitinka Pardavėjo siųstą į OPAY reikšmę
p_token
str(100)
          Rodyti aprašymą Slėpti aprašymą
Mokėjimui skirtas unikalus kodas. Jei tas pats žmogus tą patį mokėjimą atliktų daugiau nei vieną kartą, visų parametrų reikšmės sutaptų, bet šio parametro reikšmė būtų kita. Jei šio parametro reikšmė kartojasi, reiškia, kad tai pakartotinas pranešimas apie tą patį mokėjimą (Operaciją).
p_amount
int(10)
          Rodyti aprašymą Slėpti aprašymą
Suma centais, kuria Pirkėjas atliko mokėjimą (Operaciją).
p_currency
str(3)
EUR         Rodyti aprašymą Slėpti aprašymą
Valiuta, kuria Pirkėjas atliko mokėjimą (Operaciją).
p_channel
str(30)
          Rodyti aprašymą Slėpti aprašymą
Mokėjimo būdas (Mokėjimo paslauga), kuriuo buvo atliktas mokėjimas.
p_bank
str(30)
          Rodyti aprašymą Slėpti aprašymą
OPAY Partnerio, kurio paslaugomis naudojosi Pirkėjas atlikdamas mokėjimą, sisteminis pavadinimas.
p_local_date_time
str(19)
          Rodyti aprašymą Slėpti aprašymą
Vietinis laikas, kada OPAY gavo pranešimą apie mokėjimą. Laiko formatas: YYYY-MM-DD hh:mm:ss
p_gmt_date_time
str(19)
          Rodyti aprašymą Slėpti aprašymą
GMT laiko juostos laikas, kada OPAY gavo pranešimą apie apmokėjimą. Laiko formatas: YYYY-MM-DD hh:mm:ss
c_full_name
str(100)
          Rodyti aprašymą Slėpti aprašymą
Pirkėjo vardas ir pavardė. Pateikiama, jeigu OPAY mokėjimų Partneris (pvz.: bankas) pateikia tokią informaciją OPAY.
c_account_nr
str(50)
          Rodyti aprašymą Slėpti aprašymą
Pirkėjo sąskaitos numeris, iš kurios Pirkėjas atliko mokėjimą. Pateikimas, jeigu OPAY mokėjimų Partneris (pvz.: bankas) pateikia tokią informaciją OPAY.
c_email
str(100)
          Rodyti aprašymą Slėpti aprašymą
Pirkėjo el. pašto adresas. Pastaba: El. pašto adresas gali skirtis nuo to, kurį Pardavėjas pateikė OPAY, kadangi OPAY suteikia galimybę Pirkėjui redaguoti Pardavėjo pateiktą Pirkėjo el. pašto adresą.
c_mobile_nr
str(30)
          Rodyti aprašymą Slėpti aprašymą
Pirkėjo mobilaus telefono numeris. Pastaba: mobilaus telefono numeris gali skirtis nuo to, kurį Pardavėjas pateikė OPAY, kadangi OPAY suteikia galimybę Pirkėjui redaguoti Pardavėjo pateiktą Pirkėjo mobilaus telefono numerį.
rsa_signature
str(700)
          Rodyti aprašymą Slėpti aprašymą
OPAY, siųsdama duomenų paketą, pasirašo jį tuo būdu, kuriuo Pardavėjas pasirašė siųsdamas savo užklausą į OPAY. Pasirašymo būdai sutariami Sutartyje.
password_signature
str(32)
          Rodyti aprašymą Slėpti aprašymą
OPAY, siųsdama duomenų paketą, pasirašo jį tuo būdu, kuriuo Pardavėjas pasirašė siųsdamas savo užklausą į OPAY. Pasirašymo būdai sutariami Sutartyje.

Parametrai show_channels ir hide_channels

Įprastu atveju (nenaudojant šių parametrų) OPAY sistema atvaizduos Pirkėjui visus sutartus OPAY ir Pardavėjo Sutartyje atsiskaitymo būdus.

Parametru show_channels nurodysite kokius tiksliai atsiskaitymo būdus Pirkėjui atvaizduoti OPAY atsiskaitymo puslapyje (atsiskaitymo būdų pavadinimai atskiriami kableliais).

Parametru hide_channels nurodysite kokių atsiskaitymo būdų Pirkėjui neatvaizduoti OPAY atsiskaitymo puslapyje (atsiskaitymo būdų pavadinimai atskiriami kableliais).

OPAY galimi atsiskaitymo būdai yra aprašyti skyriuje Sisteminiai atsiskaitymo būdų pavadinimai. Atsiskaitymo būdai yra suskirstyti į grupes ir atitinkamą atsiskaitymo būdą.

Pavyzdžiui, atsiskaitymo grupė banklink yra skaidoma į bankus, kurių trumpiniai yra šie: banklink_swedbank, banklink_seb, banklink_dnb, banklink_danske, banklink_citadele, banklink_sb, banklink_medbank. Banklink atveju galima nurodyti ne tik atsiskaitymo būdą kaip grupę, bet ir konkrečius bankus. Kiekvienas banklink bankas yra kaip atskiras atsiskaitymo būdas, todėl sistema atsiskaitymo būdus laiko tiek banklink, tiek banklink_seb.

Kad nereiktų išvardinti visų bankų, tiesiog rašome banklink, bet galime išvardinti ir visus smulkius atsiskaitymo būdus rašydami: banklink_ <banko sisteminis pavadinimas>, banklink_<banko sisteminis pavadinimas>...

Parametrų reikšmių nuskaitymo eilės tvarka

OPAY sistema patikrina show_channels reikšmę, pagal tai nustato atvaizduojamus Pirkėjui atsiskaitymo būdus, jei show_channels parametre nenurodoma jokia reikšmė, sistema atvaizduoja visus sutartus OPAY ir Pardavėjo Sutartyje atsiskaitymo būdus. Tuomet sistema patikrina hide_channels parametro reikšmes ir išjungia parametre nurodytų atsiskaitymo būdų atvaizdavimą Pirkėjui.

Pavyzdžiai, kai OPAY ir Pardavėjo Sutartyje sutarti Internetinės bankininkystės (banklink) ir Pavedimu banke (banktransfer) atsiskaitymo būdai:

  • Parametre hide_channels nurodome reikšmes: banklink_swedbank, banklink_seb

    Šiuo atveju OPAY sistema atvaizduos banktransfer atsiskaitymo būdą ir banklink atsiskaitymo būdą su visais bankais, išskyrus SWEDBANK ir SEB.

  • Parametre show_channels nurodome reikšmes: banklink_swedbank, banklink_seb

    Šiuo atveju OPAY sistema atvaizduos tik banklink atsiskaitymo būdą, kuriame bus galima atsiskaityti tik naudojantis SWEDBANK ir SEB bankų paslaugomis.

  • Parametre hide_channels nurodome reikšmę: banklink

    Šiuo atveju bus atvaizduojamas tik banktransfer atsiskaitymo būdas.

  • Parametre hide_channels nurodome reikšmes: banklink, banktransfer

    Šiuo atveju Pardavėjas prašo sistemos nerodyti nei vieno atsiskaitymo būdo, todėl įvyks klaida, apie kurią Pardavėjas bus informuotas el. paštu, o Pirkėjui bus atvaizduojami visi OPAY ir Pardavėjo Sutartyje sutarti atsiskaitymo būdai.


Parametras time_limit

Parametras time_limit skirtas nustatyti laiko apribojimą, per kurį turi būti atliktas atsiskaitymas. Jei per šį laiką atsiskaitymas nebus atliktas, Pardavėjo tinklalapis gaus automatinį pranešimą apie neįvykusį mokėjimą (status = 0).

Skiltyje Minimalaus laiko, skirto mokėjimui atliktilentelė yra nurodyti mažiausi galimi laikai, kurie gali būti nurodyti atitinkamiems atsiskaitymo būdams.

OPAY sistema, atsižvelgdama į Pardavėjo nurodytą laiką, atvaizduos Pirkėjui tik tuos atsiskaitymo būdus, kurių minimalus leidžiamas minučių kiekis yra mažesninis arba lygus Pardavėjo nurodytam laikui.

Pardavėjas, nurodydamas mažesnį laiką ir norėdamas tikslingai atsisakyti kai kurių atsiskaitymo būdų, būtinai turi nurodyti atitinkamas reikšmes parametruose show_channels ir / arba hide_channels, atsisakant tų atsiskaitymo būdų, kurie dėl nurodyto jiems per mažo laiko ir taip nebūtų atvaizduojami Pirkėjui. Kitu atveju, OPAY sistema kas kartą informuos Pardavėją el. paštu apie dėl nurodyto per mažo laiko, galimai per klaidą nerodomus atsiskaitymo būdus.

Jeigu bus nurodytas mažesnis minučių kiekis negu patį mažiausią leidžiamų minučių kiekį turintis atsiskaitymo būdas, tai Pardavėjas bus el. paštu informuotas apie klaidą, o Pirkėjui atvaizduotas atsiskaitymo būdas, kuris turi patį mažiausią leidžiamą laiką (arba keli atsiskaitymo būdai, kurie turi vienodą mažiausią laiką). Parametras time_limit yra labai susijęs su parametrais show_channels ir hide_channels, todėl, šiuo atveju, sistema, ieškodama mažiausią laiką turinčio atsiskaitymo būdo, pirmiausiai tikrins ar Pardavėjas yra nurodęs pageidaujamus atsiskaitymo būdus šiam mokėjimui show_channels ir / arba hide_channels parametruose. Jei Pardavėjas bus tai atlikęs, tai sistema ieškos mažiausią laiką turinčio atsiskaitymo būdo iš Pardavėjo pageidaujamų būdų. Jei Pardavėjas nebus to atlikęs, tai sistema ieškos atsiskaitymo būdo iš visų sutartų OPAY ir Pardavėjo Sutartyje atsiskaitymo būdų.

DĖMESIO!

Jeigu pasibaigus time_limit nurodytam laikui įvyksta mokėjimas (pvz.: pasibaigiant laikui Pirkėjas gali būti banko svetainėje, kurioje jam nėra atvaizduojamas OPAY laikas), tai Pardavėjas, įprastu būdu, gaus pranešimą apie neįvykusį (Lentelė Nr. 2, status = 0) mokėjimą, po kurio seks papildomas pranešimas apie pavykusį mokėjimą (Lentelė Nr. 2, status = 1).

Papildomai Pardavėjas gaus el. laišką, informuojantį apie įvykusį mokėjimą pasibaigus mokėjimui skirtam laikui. Pirkėjas taip pat bus informuotas apie pavėluotą mokėjimą ir jam bus pasiūlyta susisiekti su Pardavėju. Šiuo atveju Pardavėjas pats priima sprendimą dėl tolimesnių veiksmų Pirkėjo atžvilgiu, pvz.: gali pasiūlyti kitą prekę arba grąžinti Pirkėjui pinigus.


Minimalaus laiko, skirto mokėjimui atlikti, lentelė

Šioje lentelėje pateikiami kiekvienam atsiskaitymo būdui nustatyti laikai minutėmis, kurie negali būti mažesni (nurodant parametre time_limit), norint, kad atitinkamas atsiskaitymo būdas būtų vaizduojamas Pirkėjui.

Sisteminis atsiskaitymo būdo pavadinimas Laikas, minutėmis
banklink 20
  banklink_swedbank 10
  banklink_seb 10
  banklink_dnb 10
  banklink_citadele 20
  banklink_sb 10
  banklink_medbank 10
card 10
cash 1440 (24 valandos)
  cash_perlas 1440 (24 valandos)
financing 20
  financing_gf 20
mobilewallet 10
  mobilewallet_moq 10
banktransfer 1440 (24 valandos)

Duomenų kodavimas siekiant išvengti galimų iškraipymų

Kadangi siunčiamuose duomenyse pasitaiko ne tik lotyniškų, bet ir kitų raidžių, kurias ypač svarbu persiųsti teisinga simbolių koduote, tai ar pranešimas pasieks adresatą neiškraipytas, priklausys nuo to ar Pirkėjo interneto naršyklė visus simbolius suinterpretuos teisingai. Atsiranda galimybė atsirasti duomenų iškraipymui, dėl ko visas duomenų paketas gali būti palaikytas neteisingu (neatitinkančiu skaitmeninio parašo). Kuo mažiau išvystyta naršyklė tuo didesnė klaidos tikimybė.

Situaciją sprendžiame šiuo būdu:

Užkoduojame siunčiamus duomenis base64 koduote.

Suformuojame visą duomenų paketą, skirtą siųsti į OPAY. Sakykime, kad tai asociatyvus masyvas, kurio indeksas žymi parametro pavadinimą, o reikšmė – parametro reikšmę. Šį masyvą paverčiame RFC 1738 standartu koduota URL eilute, kurią paverčiame į base64 koduotės eilutę, tada turimos eilutės simbolius pakeičiame:

  • + į -
  • / į _
  • = į
  • PHP
  1. $masyvas['website_id'] = 'W8K5JU89MH';
  2. $masyvas['order_nr'] = 'krepselis_89';
  3. $masyvas['…….'] = '…….'; // kiti parametrai
  4. $eilute = strtr(base64_encode(http_build_query($masyvas)), array('+' => '-', '/' => '_', '=' => ','));
  5. // kintamojo $eilute reišmę siunčiame kaip parametro encoded reikšmę

Iškoduojame gautus duomenis

Iškoduodami parametro encoded reikšmę atliekame veiksmus atvirkščia tvarka nei užkodavimo metu.

  • PHP
  1. $eilute = $_POST['encoded'];
  2. $masyvas = array();
  3. // masyvas, į kurį bus išpakuoti duomenys
  4. parse_str(base64_decode(strtr($eilute, array('-' => '+', '_' => '/', ',' => '='))), $masyvas);

Skaitmeninis duomenų pasirašymas

Apsikeisdami duomenimis naudojame du pasirašymo būdus (arba vieną, arba kitą):

  • sitmetrinio pasirašymo. Kai abi šalys tiek pasirašymui, tiek parašo tikrinimui naudoja tą patį slaptažodį.

    Pasirašymo slaptažodžio pavyzdys:
    33cec89hjab1d77b10d21fba67528g5h

  • asimetrinio pasirašymo. Kai šalys susigeneruoja privačius raktus, pagal juos susigeneruoja SSL sertifikatus ir tais sertifikatais apsikeičia. Duomenų pasirašymui naudoja privačius raktus, o parašo tikrinimui (gavus duomenis iš partnerio) naudoja partnerio sertifikatą.

    SSL sertifikato pavyzdys:

    SSL Sertifikatas

Prieš pasirašant duomenis ar prieš tikrinant pasirašytų duomenų autentiškumą, labai svarbu laikytis vienodos parametrų apjungimo į vientisą eilutę tvarkos.

Parametrų apjungimo į vientisą eilutę tvarka (Pasirašymo / parašo tikrinimo eilutė)

Parametrai (duomenys), kuriuos siųsite į OPAY ar kuriuos iš OPAY gausite, bus išdėstyti eilės tvarka, kurią nustatys siunčiančioji pusė. Pavyzdys PHP kalba, jei ruoštumėtės išsiųsti užklausą iš trijų parametrų:

  • PHP
  1. $arrayOfParameters['paramName1'] = 'Parametras 1';
  2. $arrayOfParameters['paramName2'] = 'Parametras 2';
  3. $arrayOfParameters['paramName3'] = 'Parametras ąč';

Siunčiant šiuos parametrus HTTP POST metodu, jie galėtų būtų sujungti į tokią eilutę (parametrų išdėstymo tvarka nėra svarbi):

  • paramName1=Parametras+1&paramName2=Parametras+2&paramName3=Parametras+%C4%85%C4%8D

Pasirašant parametrus ar tikrinant jų parašą, parametrus taip pat reikia sujungti į vieną eilutę, tik kitaip nei HTTP POST parametrų eilutėje, tarp parametro pavadinimo ir jo reikšmės nededamas lygybės ženklas (=), parametrai neatskiriami ampersando ženklu (&). Parametrų pavadinimai su jų reikšmėmis sujungiami į vieną ilgą žodį - eilutę. Šios eilutės specialieji ir ne ASCII simboliai nekeičiami jų atitikmenimis (angl. url encoding), kaip tai daroma HTTP POST eilutėje.

Eilutės pavyzdys:

  • paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč

DĖMESIO! Pasirašymui ar parašo tikrinimui naudojamos eilutės parametrų eilės tvarka privalo sutapti su siunčiamų parametrų eilės tvarka. Kitaip sakant, kokia tvarka surikiuoti siunčiami ar gaunami parametrai, tokia tvarka turi ir būti suformuota pasirašymui ar parašo tikrinimui skirta eilutė.

Simetrinis pasirašymas ir parašo tikrinimas

Pasirašymas

Pasirašant parametrus, iš visų siuntimui paruoštų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) reikia suformuoti pasirašymo eilutę.

Pasirašymas simetriniu būdu vyksta pasirašymo / parašo tikrinimo eilutę ir pasirašymo slaptažodį sujungiant į vieną eilutę, ir ją išmaišant md5 algoritmu.

  • PHP
  1. $string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
  2. $password = '33cec89hjab1d77b10d21fba67528g5h';
  3. $signature = md5($string . $password);

Gautas simetrinis parašas pridedamas kaip password_signature parametras prie paruoštų siuntimui parametrų, kurie siunčiami į OPAY. Pageidautina, kad prieš siunčiant paruoštus parametrus į OPAY, parametrai dar būtų užkoduoti ir siunčiami kaip vienas parametras enocoded(žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

Parašo tikrinimas

Parašas tikrinamas iš visų gautų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) suformuojant pasirašymui / parašo tikrinimui skirtą eilutę. OPAY siunčia parametrus užkoduotus į vieną parametrą encoded, todėl norimiems parametrams gauti, reikės išsikoduoti encoded parametro reikšmę (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

Pasirašymui / parašo tikrinimui skirtą eilutę pasirašome, o gautą rezultatą palyginame su gauto parametro password_signature reikšme. Jeigu reikšmės sutampa – autentifikacija pavyko.

  • PHP
  1. $string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
  2. $password = '33cec89hjab1d77b10d21fba67528g5h';
  3. $signature = md5($string . $password);
  4. if ($arrayOfParameters['password_signature'] == $signature) {
  5. // Duomenų autentifikacija pavyko - SĖKMĖ
  6. } else {
  7. // Duomenys neatitinka parašo - NESĖKMĖ
  8. }

Asimetrinis pasirašymas ir parašo tikrinimas

Privataus rakto ir SSL sertifikato generavimas

Šiems raktams generuoti OPAY siūlo naudoti OpenSSL programinę įrangą (https://www.openssl.org/).

Privatus raktas generuojamas komandinėje eilutėje įvedant komandą:

  • openssl genrsa -out privkey.pem 2048
openssl genrsa -out privkey.pem 2048

Esamoje direktorijoje jums bus sugeneruotas tekstinis failas pavadinimu privkey.pem, kurio viduje rasite privatų raktą. Skaičius 2048 komandoje reiškia rakto ilgį bitais. Pagal saugumo reikalavimus taikomus šią dieną, tai trumpiausias rekomenduojamas rakto ilgis.

SSL sertifikatas generuojamas komandinėje eilutėje įvedant komandą:

  • openssl req -new -x509 -key privkey.pem -out cacert.pem -days 3650

Komandoje nurodytas privataus rakto failo pavadinimas privkey.pem. Taip pat nurodytas tekstinio failo, kuris turi būti sukurtas ir į jį įrašytas SSL sertifikatas, pavadinimas cacert.pem. Skaičius 3650 nurodo kiek dienų nuo sugeneravimo šis sertifikatas turi galioti. Pasibaigus šiam laikui reikėtų sugeneruoti naują sertifikatą ir jį pateikti OPAY. Pasibaigus sertifikato galiojimui OPAY sistema ir toliau tikrina Pardavėjo siunčiamas užklausas su pasibaigusio galiojimo sertifikatu. Sertifikato galiojimo pasibaigimas technine prasme jokios įtakos neturi. Kokį sertifikato galiojimo laiką nustatyti ir kada atnaujinti sertifikatą sprendžia Pardavėjas.

Įvedus SSL sertifikato generavimo komandą jūsų bus paprašyta suvesti įmonės duomenis, pavyzdžiui:

Įmonės duomenys

Pasirašymas

Pasirašant parametrus, iš visų siuntimui paruoštų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) reikia suformuoti pasirašymo eilutę ir ją pasirašyti.

  • PHP
  1. // Pasirašymo / parašo tikrinimo eilutė
  2. $string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
  3. // Privatus raktas nuskaitomas iš failo ir priskiriamas kintamajam
  4. $privateKey = file_get_contents(‘privkey.pem’);
  5. // sukuriam privataus rakto resursą
  6. $pkeyid = openssl_get_privatekey($privateKey);
  7. if ($pkeyid !== false) {
  8. // pasirašome pasirašymo eilutę
  9. if (openssl_sign($string, $signature, $pkeyid) === true) { // jeigu pasirašyti pavyko
  10. // gautą parašą paverčiame į base64 koduotė eilutę
  11. if (($signature = base64_encode($signature)) !== false) { // jeigu paversti į base64 pavyko
  12. // rezultatą išvalome nuo naujos eilutės simbolių
  13. $signature = preg_replace("/[\r\n\t]*/", "", $signature); // gaunam reikiamą parašą
  14. // atlaisvinam atmintį nuo privataus rakto
  15. openssl_free_key($pkeyid);
  16. } else {
  17. // Klaida: base64 kodavimas nepavyko
  18. }
  19. } else {
  20. // Klaida: pasirašyti nepavyko
  21. }
  22. } else {
  23. // Klaida: neteisingo formato raktas
  24. }

Gautas asimetrinis parašas pridedamas kaip rsa_signature parametras prie paruoštų siuntimui parametrų, kurie siunčiami į OPAY. Pageidautina, kad prieš siunčiant paruoštus parametrus į OPAY, parametrai dar būtų užkoduoti ir siunčiami kaip vienas parametras enocoded (žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

Parašo tikrinimas

Parašas tikrinamas iš visų gautų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) suformuojant pasirašymui / parašo tikrinimui skirtą eilutę. OPAY siunčia parametrus užkoduotus į vieną parametrą encoded, todėl norimiems parametrams gauti, reikės išsikoduoti encoded parametro reikšmę (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

  • PHP
  1. // Pasirašymo / parašo tikrinimo eilutė
  2. $string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
  3. // Gautą parametro rsa_signature priskiriam kintamajam
  4. $signature = $arrayOfParameters['rsa_signature'];
  5. // OPAY sertifikatas nuskaitomas iš failo ir priskiriamas kintamajam
  6. $certificate = file_get_contents('OPAYcert.pem');
  7. // sukuriam viešojo rakto resursą
  8. $pubkeyid = openssl_pkey_get_public($certificate);
  9. if ($pubkeyid !== false) {
  10. // tikriname parašą
  11. $ok = openssl_verify($string, base64_decode($signature), $pubkeyid);
  12. openssl_free_key($pubkeyid); // atlaisvinam atmintį nuo sertifikato
  13. if ($ok === 1) {
  14. // Duomenų autentifikacija pavyko - SĖKMĖ
  15. } else if ($ok === 0) {
  16. // Duomenys neatitinka parašo - NESĖKMĖ
  17. } else {
  18. // Klaida: Parašo tikrinimas nepavyko
  19. }
  20. } else {
  21. // Klaida: neteisingo formato raktas
  22. }