Înregistrare card în sistemul maib ecomm

API endpoint (POST)
https://api.maibmerchants.md/v1/savecard-recurring

Parametri pentru request (body)

Parametru	Obligatoriu	Tip	Descriere
billerExpiry	DA	string(4)	Data (lună/an) pînă la care datele cardului vor fi păstrate în sistemul maib ecomm. Formatul valorii MMYY (de ex. 1225 -> 31 decembrie 2025 / ora 23:59:59). Dacă valabilitatea cardului este mai mică decît valoarea transmisă în acest parametru, atunci datele cardului vor fi păstrate pînă la data valabilității cardului.
clientIp	DA	string(15)	IP Cumpărător
amount	NU*	number(decimal) ≥1	Suma tranzacției în formatul X.XX De exemplu: 10.25 (valuta MDL) -> 10 lei și 25 bani. *Dacă parametrul este transmis va avea loc atît debitarea sumei din contul Cumpărătorului cît și înregistrarea cardului în sistemul maib ecomm. *Dacă parametrul nu este transmis, atunci datele cardului vor fi salvate fără a debita ceva din contul Cumpărătorului.
currency	DA	string(3)	Valuta tranzacției (MDL/EUR/USD)
language	NU	string(2)	Limba în care va fi afișată pagina maib ecomm checkout. Valori posibile: ro/en/ru. Dacă acest parametru nu este transmis, pagina va fi afișată în limba engleză.
description	NU	string(124)	Descrierea plății. Se afișează pe pagina maib ecomm checkout.
clientName	NU	string(128)	Nume Cumpărător
email	DA	string(40)	Email Cumpărător
phone	NU	string(40)	Telefon Cumpărător
orderId	NU	string(36)	Identificatorul comenzii de pe website/app
delivery	NU	number(decimal)	Costul livrării în format X.XX
items	NU	array max. 50 items	Produsele sau serviciile din coșul Cumpărătorului
id	nu	string(36)	ID produs
name	nu	string(128)	Nume produs
price	nu	number(decimal)	Preț produs în format X.XX
quantity	nu	integer(32)	Cantitatea produselor
callbackUrl	NU	string(2048)	Link-ul unde Merchant-ul va primi răspunsul final cu starea și datele tranzacției. Dacă nu se transmite acest parametru valoarea sa va fi preluată din maibmerchants.
okUrl	NU	string(2048)	Link-ul unde Cumpărătorul va fi redirecționat dacă tranzacția este reușită. (GET request: okUrl + payId&orderId&billerId) Dacă nu se transmite acest parametru valoarea sa va fi preluată din maibmerchants.
failUrl	NU	string(2048)	Link-ul unde Cumpărătorul va fi redirecționat dacă tranzacția a eșuat. (GET request: failUrl + payId&orderId) Dacă nu se transmite acest parametru valoarea sa va fi preluată din maibmerchants.

Exemplu

Cu parametrul "amount"

{
"billerExpiry": "1225",
"amount": 6.25,
"currency": "MDL",
"clientIp": "135.250.245.121",
"language": "ro",
"description": "Descriere",
"clientName": "Nume Prenume",
"email": "[e-mail]",
"phone": "069123456",
"orderId": "123",
"delivery": 1.25,
"items": [
{
"id": "10",
"name": "Produs 1",
"price": 2.50,
"quantity": 2
}
],
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}

Fără parametrul "amount"

{
"billerExpiry": "1225",
"clientIp": "135.250.245.121",
"currency": "MDL",
"language": "ro",
"description": "Descriere",
"clientName": "Nume Prenume",
"email": "[e-mail]",
"phone": "069123456",
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}

Parametri răspuns intermediar

Parametru	Tip	Descriere
result	object	Obiect care conține identificatorul tranzacției și link-ul pentru redirecționare Cumpărător
payId	string	Identificatorul tranzacției atribuit de către maib ecomm
orderId	string	Identificatorul comenzii de pe website/app
payUrl	string	Link-ul către pagina de maib ecomm checkout unde Cumpărătorul trebuie să fie redirecționat pentru a introduce datele cardului
ok	boolean	Stare procesare request/tranzacție: true - nu sunt erori; false - sunt erori (detaliile despre erori vor fi în afișate în errors)
errors	array	Erori procesare request/tranzacție. Tabelul cu erori
errorCode	string	Cod eroare
errorMessage	string	Detalii despre eroare
errorArgs	object	Obiectul conține parametri cu detalii despre eroare

Exemplu răspuns intermediar

Fără erori

{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"payUrl": "https://maib.ecommerce.md/ecomm01/ClientHandler?trans_id=rEsfhyIk8s9ypxkcS9fj/3C8FqA="
},
"ok": true
}

Cu erori

{
    "errors": [
        {
            "errorCode": "12034",
            "errorMessage": "Parameter 'billerExpiry' has invalid format. Valid format is 'MMYY'",
            "errorArgs": {
                "parameter": "billerExpiry"
            }
        }
    ],
    "ok": false
}

Parametri răspuns final (pe Callback URL)

Parametru	Tip	Descriere
result	object	Obiect care conține datele tranzacției
payId	string	Identificatorul tranzacției atribuit de către maib ecomm
orderId	string	Identificatorul comenzii de pe website/app
billerId	string	Identificatorul cardului salvat în ecomm maib. Merchant-ul va iniția următoarele plăți recurente cu transmiterea acestui identificator în request (execute-recurring).
billerExpiry	string	Data (lună/an) pînă la care datele cardului vor fi păstrate în sistemul maib ecomm. Formatul valorii MMYY (de ex. 1225 -> 31 decembrie 2025 / ora 23:59:59). Dacă valabilitatea cardului este mai mică decît valoarea transmisă anterior în request, atunci în răspuns veți primi data expirării cardului.
orderId	string	Identificatorul comenzii de pe website/app
status	string	Starea tranzacției OK - Dacă a fost transmis parametrul amount și tranzacția este cu succes (cardul a fost înregistrat). PENDING - Dacă nu a fost transmis parametrul amount (cardul a fost înregistrat).
statusCode	string	Codul stării tranzacției
statusMessage	string	Detalii despre starea tranzacției
threeDs	string	Rezultatul autentificării 3-D Secure
rrn	string	RRN - Identificatorul tranzacției generat de către maib ecomm
approval	string	Approval Code - Identificatorul de aprobare a tranzacției generat de către banca emitentă a cardului.
cardNumber	string	Numărul cardului hașurat
amount	number(decimal)	Suma tranzacției în format X.XX Este prezent doar dacă parametrul amount a fost transmis
currency	string	Valuta tranzacției (MDL/EUR/USD) Este prezent doar dacă parametrul currency a fost transmis
signature	string	Semnătură validare răspuns

Exemplu răspuns final

Cu parametrul "amount"

{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "92f72473-f324-42d7-95fd-9c75c2947408",
"billerExpiry": "1225",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"threeDs": "AUTHENTICATED",
"rrn": "331711380059",
"approval": "327593",
"cardNumber": "510218******1124",
"amount": 6.25,
"currency": "MDL"
},
"signature": "xxxxxxxxxxxxxxxxxxxx"
}

Fără parametrul "amount"

{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"billerExpiry": "1225",
"orderId": "123",
"status": "PENDING",
"threeDs": "AUTHENTICATED",
"cardNumber": "510218******1124",
"amount": 0,
"currency": "MDL"
},
"signature": "xxxxxxxxxxxxxxxxxxxx"
}