NETOPIA

Bucharest, Romania
www.mobilPay.ro

Documentatie tehnica de
implementare mobilPay

Dezvoltat de NETOPIA
2007-2014

Acest document este clasificat drept CONFIDENTIAL

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

Istoric modificari
Versiunea
3.2

Data
2014-07

Revizuire
5

Acest document a fost creat si se afla in proprietatea

Proprietar
NETOPIA

Autor
Claudiu Tudose
claudiu.tudose@netopiasystem.com

Data crearii
2009-03

Lista de distributie
Recipient
Persoana

Data distributiei
Companie

Acest document a fost revizuit de

Versiune

Revizuit de
Andrei Panait
Andrei Panait

4
5

La data
06-2012
07-2014

Acest document a fost aprobat de

Versiune

Nume

Semnatura

La data

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

CUPRINS
1. Introducere
1.1 Scopul si obiectivele mobilPay
1.2 Scopul si obiectivele acestui document
1.3 Documente si resurse suplimentare
2. Crearea unui cont de comerciant mobilPay
3. Implementarea serviciului mobilPay in website
3.1 Descrierea fluxului informational
3.2 Descrierea efectuarii platii
3.3 Descrierea modalitatii de initiere a platii
3.4 Descrierea modalitatii de confirmare a platii

1
2
2
3
3
5

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

1.Introducere
1.1 Scopul si obiectivele mobilPay
mobilPay este un serviciu web securizat ce permite proprietarilor de
site-uri sa accepte plati cu costuri de implementare si operationale aproape
nule. mobilPay se comporta ca un portal de plati. Cand clientul trebuie sa
plateasca un anumit serviciu sau produs, va fi redirectionat de catre
comerciant catre portalul securizat mobilPay. Pentru plata prin SMS, clientul
va primi instructiuni cu privire la procedura de plata folosind telefonul mobil.
Cand procedura de plata este finalizata clientul este redirectionat catre
pagina web a comerciantului cu o confirmare a platii. Toate datele transmise
si primite intre comerciant si mobilPay sunt criptate, astfel incat nimeni nu
poate vedea detaliile tranzactiei. Avantajul platii prin SMS folosind mobilPay
este numarul mare de posesori de telefoane mobile (18 milioane), viteza,
simplitatea implementarii si costurile operationale.
1.2 Scopul si obiectivele acestui document
Acest document este destinat folosirii de catre dezvoltatori pentru
implementarea metodei de plata prin SMS online mobilPay intr-un site web.
Va explica modalitatea in care este deschis un cont de comerciant si cum
poate interactiona un site web cu mobilPay. Acest document explica de
asemenea si documentele si resursele necesare pentru simplificarea
integrarii serviciului.
1.3 Documente si resurse suplimentare
Impreuna cu acest document vei primi si urmatoarele informatii
suplimentare:
Nume
Tip
Numele fisierului
Detalii
Utile

Fisier xml

Exemple Fisier zip

Sms.xml

Samples.zip

Structura fisierului XML

ce trebuie trimis catre
mobilpay la initierea
platii
Exemplifica
modalitatea de
implementare

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

2. Crearea unui cont de comerciant mobilPay

Crearea unui cont mobilPay este si va ramane gratuita. Impreuna cu noul
cont creat vei primi:
signature un ID unic care ajuta in identificarea ta si a contului tau de
comerciant; Formatul va fi XXXX-XXXX-XXXX-XXXX-XXXX unde X poate
fi o majuscula sau o cifra. Semnatura va fi folosita in toate requesturile catre mobilPay. Semnatura trebuie pastrata in siguranta. Nu
permite accesul personalului neautorizat la aceasta!
Certificat public X509 serviciul mobilPay va genera un certificat
public X509 pentru fiecare cont de comerciant creat. Va trebui sa
folosesti acest certificat pentru criptarea datelor ori de cate ori initiezi
o plata prin mobilPay. Nu poate fi folosit pentru decriptarea datelor,
NETOPIA Sistem va folosi cheia privata pentru decriptare.
Cheia privata serviciul mobilPay va genera o cheie privata pentru
fiecare cont de comerciant creat. Vei folosi cheia privata pentru a
decripta datele sosite de la serviciul mobilPay catre site-ul tau (de
exemplu confirmarea platii). Pastreaza cheia privata intr-un loc sigur.
Nu permite accesul personalului neautorizat la aceasta!
Nume de utilizator si parola necesare pentru autentificarea in
panoul de administrare mobilPay (parola ar trebui schimbata la prima
autentificare).

3. Implementarea serviciului in site-ul tau

3.1 Descrierea fluxului informational
Cand un utilizator viziteaza pagina ta de internet si isi doreste
achizitionarea unui produs sau serviciu, el/ea incarca ceea ce doreste sa
cumpere in cosul de cumparaturi si trebuie sa aleaga metoda de plata. Va trebui
sa plasezi un link catre portalul de plati securizate mobilPay si sa redirectezi
clientul. Vom oferi clientului instructiuni cu privire la modalitatea de plata.
Imediat ce plata s-a efectuat redirectam clientul spre site-ul tau impreuna cu o
confirmare a platii. Legatura catre portalul nostru se va face printr-o conexiune
criptata SSL. Mai mult decat atat, toate datele manipulate intre site-ul tau si
portaul nostru vor fi criptate si semnate pentru a ne asigura ca nu exista cereri
neautorizate si ca nimeni nu a modificat datele schimbate intre portaluri.

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

3.2 Descrierea efectuarii platii

Cand un client este redirectat catre portalul nostru pentru a efectua o
plata, va primi informatii complete cu privire la ce, cat si catre cine plateste.
Clientul va trebui sa trimita un mesaj text (SMS) care va contine un cod de 6
(sase) cifre catre un anumit numar scurt de tip VAS (Value Added SMS). Numarul
scurt depinde de suma pe care clientul trebuie sa o plateasca. Codul unic este
generat de mobilPay pentru fiecare tranzactie initiata. Trimiterea SMS-ului la
numarul scurt va taxa clientul (depinzand aici de procedura specifica fiecarui
operator de telefonie mobila). Pe telefon se va primi un mesaj de raspuns care
va contine un cod de validare. Clientul trebuie sa introduca acest cod de
validare in interfata de plati si sa valideze plata. Daca a fost introdus codul de
validare corect, clientul va fi redirectat catre site-ul tau web impreuna cu o
confirmare a platii. Imediat ce ai primit confirmarea platii nu trebuie decat sa
finalizezi comanda respectiva si sa livrezi serviciul sau produsul pentru care s-a
platit.
3.3 Descrierea modalitatii de initiere a platii
mobilPay te ajuta sa implementezi platile mobile in site-ul web
punandu-ti la dispozitie clase utilitare si exemplificari despre modalitatea de
folosire a acestora. Pentru orice situatie iti punem la dispozitie si o descriere
detaliata asupra modului in care initierea platii trebuie realizata in paragraful ce
urmeaza.
Reguli pentru o initiere corecta a platii:
1.Redirecteaza intotdeauna clientul la plata catre https://secure.mobilpay.ro (sau
http://sandboxsecure.mobilpay.ro pentru teste)
2.Foloseste intotdeauna POST ca metoda de initiere a platii in interfata mobilPay
3.Parametrii POST ce vor trebui trimisi intotdeauna sunt data si env_key;
3.1.data un parametru ce contine date criptate pe care va trebui sa le trimiti
cand initiezi o plata. Datele vor fi mereu semnate cu un certificat public X509 pe
care il primesti de la mobilPay atunci cand creezi un cont de comerciant.
3.2.env_key este plicul asociat cu cheia publica generat in momentul
impachetarii datelor.
Parametrul data este compus dintr-o lista de informatii necesare
mobilPay pentru procesarea platii, in format XML. O descriere completa
structurii XML se regaseste in fisierul sms.payment.request.xml, parte
integranta a acestui document. Campurile din acest fisier au urmatoarea
semnificatie:

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

1
1

type atribut obligatoriu va avea valoarea sms pentru ca tranzactia sa

fie initiata si finalizata printr-un SMS cu valoare adaugata
id atribut obligatoriu identificator al tranzactiei generat de aplicatia ta
(stocheaza acest identificator pentru a-l folosi cand primesti confirmarea
platii); trebuie sa aiba maxim 64 de caractere; acest parametru trebuie sa
fie unic pe cont de comerciant.
timestamp atribut care ia ca valoare ora serverului tau in format
YYYYMMDDhhmmss (de ex 20070925020304 reprezinta 25 Septembrie 2007
ora 02:03:04)
signature element obligatoriu semnatura contului tau de
comerciantprimita de la mobilPay in momentul crearii contului; acest
parametru are mereu lungimea de 24 de caractere si il gasesti in Admin ->
Conturi de comerciant -> Detalii -> Setari securitate
service element obligatoriu identificatorul produsului sau serviciului pe
care doresti sa il comercializezi. Platforma de administrare iti permite sa
definesti oricate servicii sau produse doresti. Cand adaugi un produs nou
acestuia i se va genera automat un identificator unic. Este disponibil in
Admin -> Conturi de comerciant -> Produse si servicii -> Semnul plus
confirm element optional un URL din site-ul tau care va fi apelat pentru
confirmarea platii; trebuie sa aiba maxim 255 de caractere. Acest parametru
poate fi configurat cand creezi produsul/serviciul. Trebuie sa setezi confirm
numai daca vrei sa il suprascrii pe cel definit in platforma.
return element optional un URL din site-ul tau in care clientul va fi
redirectionat dupa ce plata a fost finalizata cu succes. Acest parametru
poate fi configurat cand creezi produsul/serviciul. Trebuie sa setezi return
numai daca vrei sa il suprascrii pe cel definit in platforma.
msisdn element optional in cazul in care ii soliciti clientului numarul de
telefon si doresti prepopularea campului de verificare a telefonului mobil din
pagina de plata, poti trimite acest element
params element optional poti adauga oricat de multi parametri doresti
pentru a avea un numar suficient de mare de detalii cu privire la clientul
platitor si/sau la produsul tranzactionat (nume, prenume, adresa, email, etc.)

ATENTIE! De-a lungul perioadei de testare toate cererile de plata se vor trimite
catre serverul de teste, a carui adresa este http://sandboxsecure.mobilpay.ro,
accesul public la plata prin SMS va fi restrictionat, si nu se vor trimite SMS-uri
de pe telefonul mobil. Se va folosi exclusiv simulatorul de trimitere SMS

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

disponibil in sectiunea Implementare -> Simulator in versiunea sandbox a

mobilpay, numai dupa sincronizarea contului de comerciant (Admin -> Conturi
de comerciant -> Modifica detalii -> Sincronizeaza)
3.4 Descrierea modalitatii de confirmare a platii
In momentul confirmarii platii serviciul mobilPay va apela url-ul
specificat de tine drept confirm. mobilPay va construi parametrii in acelasi mod
in care ai facut-o tu la apelarea paginii de plata. Datele vor fi criptate cu un
certificat public X509 si vei putea folosi cheia ta privata pentru decriptare. Vei
primi inapoi toti parametrii trimisi la apelarea paginii de plata (parametrii vor
avea toti aceleasi valori). Astfel vei putea identifica in mod corespunzator
tranzactia in aplicatia ta. Daca plata a fost finalizata cu succes mobilPay va
adauga un element mobilpay la XML-ul trimis, element cu urmatoarea
structura:
purchase element identificator al tranzactiei mobilPay; numeric
action element ce va avea valoarea confirmed pentru tranzactii
finalizate cu succes, valoarea reversed pentru tranzactii stornate,
valoarea canceled pentru tranzactii anulate, valoarea trial pentru
tranzactii aflate in perioada de incercare. In cazul in care, pe viitor,
vor fi trimise si alte valori, acestea vor fi communicate din timp
timestamp atribut continand data si ora mobilPay la care plata a
fost confirmata de catre client in portal
paid_by_phone element identificator al numarului de telefon
folosit pentru a se efectua plata
validation_code element continand valoarea codului de validare
pe care clientul l-a folosit pentru a finaliza plata
error fara semnificatie pentru platile efectuate prin SMS
URL-ul de confirmare va trebui sa raspunda cu un XML (ContentType: text/xml), care va ajuta mobilPay sa verifice daca ai primit cu succes
confirmarea platii. Formatul XML trebuie sa fie
<?xml version="1.0" encoding="utf-8" ?>
<crc
error_type=1|2
error_code={numeric}>{message}</crc>
Atributele elementului <crc> se folosesc doar in momentul in care
site-ul tau nu a reusit sa inregistreze confirmarea platii si au
urmatoarele semnificatii:

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.

NETOPIA
Bucharest, Romania
www.mobilPay.ro

error_type are valoarea 1 atunci cand s-a inregistrat o eroare

temporara (de exemplu nu s-a realizat conexiunea la baza de date) si
valoarea 2 cand s-a inregistrat o eroare permanenta (de exemplu nu
s-a gasit tranzactia cu parametrii specificati). In functie de valoarea
lui error_type mobilPay va reincerca sau nu procesul de confirmare
a platii. Acest atribut trebuie specificat doar daca a aparut o eroare
in procesul de inregistrare a confirmarii platii.
error_code este o valoare numerica care te va ajuta sa vezi
eroarea generata de site-ul tau. Acest atribut trebuie specificat doar
daca a aparut o eroare in procesul de inregistrare a confirmarii platii.
message daca a aparut o eroare in procesul de inregistrare a
confirmarii platii, valoarea acestui atribut reprezinta un mesaj de
eroare care te va ajuta sa depistezi eroarea generate de site-ul tau.
Daca nu a aparut nicio eroare va trebui sa aiba valoarea
parametrului purchase primita de la mobilPay

This document is confidential.

This document is property of N E T O P I A. Copying or reproducing it, partial or totally, by any means, will be punished according to law.