Integrarea Leanpay pentru Shopify este compusă din două aplicații separate, pe care le instalezi și le configurezi independent. Metoda de plată permite clienților să aleagă plata în rate Leanpay la finalizarea comenzii, iar modulul pentru prețuri divizate afișează informații despre rata lunară și calculatorul de rate în diferite locuri din magazin.
Metoda de plată
Adaugă Leanpay ca opțiune de plată la finalizarea comenzii. Clientul poate alege plata în rate în locul plății cu card de credit sau cu alte metode.
Modul pentru prețuri divizate
Afișează prețul pe rată și calculatorul de rate cu trei widget-uri (Product, Horizontal, Vertical), pe care le poți insera în diferite locuri în tema Shopify.
Cerințe preliminare
- ✓Magazin Shopify activ
- ✓Acces de administrator la Shopify Admin
- ✓Cont Leanpay activ pentru mediul ales (de test sau de producție)
- ✓API Key și Secret Word (le obții în aplicația Vendor, în secțiunea Companie > Development)
ℹ
Pentru testare creează un cont de test gratuit aici. Cheia API și Secret Word le găsești în secțiunea Companie > Development.
1
Configurează webhook-ul în aplicația Leanpay
În aplicația Leanpay Vendor, în secțiunea Companie > Development configurează:
API URL:
https://extapp.leanpay.ro/callback/webhook
Secret Word: alege o valoare arbitrară și notează-o — vei avea nevoie de ea la pasul 4.
⚠
API URL este esențial pentru sincronizarea actualizărilor de stare a comenzilor și a plăților între Leanpay și Shopify. O configurare incorectă poate face ca unele comenzi să rămână într-o stare nerezolvată.
2
Introdu domeniul magazinului Shopify
Deschide https://extapp.leanpay.ro, introdu domeniul magazinului (de ex.
your-store.myshopify.com) și apasă Install/Configure Leanpay.
3
Confirmă instalarea în Shopify
Vei fi redirecționat către ecranul de instalare Shopify. Verifică permisiunile solicitate și apasă Install.
4
Configurează aplicația
După instalare se deschide Configuration view. Introdu:
- API Key — din panoul Leanpay, sub
Company → Development. - API Secret — corespunde valorii Secret Word de la pasul 1.
- Default Environment — folosit atunci când țara de destinație nu are un mediu corespunzător.
- Mode — determină ce endpoint Leanpay API va fi folosit (Sandbox / Production).
⚠
Nu folosi modul Sandbox în mediul de producție, decât dacă este absolut necesar. În acest caz, asigură-te că pentru metoda de plată este activat Test Mode (vezi pasul 7).
5
Salvează configurația
După salvarea reușită apare o notificare de succes. Metoda de plată Leanpay este pregătită pentru activare.
6
Deschide Shopify Payment Settings
În Shopify Admin mergi la
Settings → Payments → Add payment method, sau apasă butonul Shopify Payment Settings din colțul din dreapta sus al vizualizării de configurare.
7
Activează Leanpay
La Leanpay, în lista metodelor de plată, apasă Activate.
⚠
Setarea Test Mode nu determină dacă aplicația comunică cu mediul de producție sau cu mediul Sandbox al Leanpay. Este destinată exclusiv vizibilității și procesării din interiorul Shopify. Pentru utilizarea în producție dezactivează Test Mode.
8
Verifică afișarea la checkout
După finalizarea configurării, Leanpay apare ca opțiune de plată în checkout-ul Shopify.
Note importante
⚠
Secret Word se folosește pentru autentificarea cererilor webhook primite de la Leanpay Gateway. Valoarea trebuie să corespundă exact cu cea din configurația panoului Leanpay Gateway, altfel actualizările de stare a comenzilor și a plăților nu vor funcționa.
⚠
Toate mediile configurate trebuie să corespundă Mode-ului selectat — fie toate în producție, fie toate în Sandbox. Credențialele mixte (de ex. chei API de producție împreună cu modul Sandbox activat) fac ca metoda de plată să nu funcționeze pentru destinațiile aferente.
ℹ
Mediul Leanpay se determină în funcție de delivery address a clientului. Serviciul și endpoint-ul Leanpay sloven se folosesc doar dacă adresa de livrare este în Slovenia și există o configurație corespunzătoare. Dacă configurația endpoint-ului (API Key și Secret) nu este setată sau a fost ștearsă, pentru apelurile API se folosește fallback environment-ul configurat.
ℹ
Aplicația Leanpay efectuează automat conversia valutară atunci când valuta magazinului Shopify nu corespunde valutei așteptate de mediul de destinație (de ex. Slovenia și Croația necesită EUR, România RON). Conversia folosește cele mai recente cursuri de schimb disponibile, ceea ce poate cauza diferențe vizibile de preț pentru client. Pentru a evita neconcordanțele, setează magazinul Shopify la valuta corectă în funcție de shipping destination.
ℹ
Pentru dezactivarea temporară a metodei de plată, șterge API Key și Secret din configurație și salvează modificările. Astfel se păstrează funcționarea webhook-urilor, iar Leanpay nu se afișează la checkout.
ℹ
Un singur mediu Leanpay nu acceptă momentan trimiterea de webhook-uri către mai multe magazine simultan (de ex. Magento + Shopify pe același mediu). Pentru configurări cu mai multe magazine, contactează suportul Leanpay.
Înainte de instalare pregătește-ți API Key și Pre-qualify URL din aplicația Leanpay Vendor, din secțiunea Companie > Development.
1
Introdu domeniul magazinului Shopify
Deschide https://installmentapp.leanpay.ro/, introdu domeniul magazinului (de ex.
your-store.myshopify.com) și apasă Install/Configure Leanpay Storefront Tools.
2
Confirmă instalarea în Shopify
Vei fi redirecționat către ecranul de instalare Shopify. Verifică permisiunile solicitate și apasă Install.
3
Configurează aplicația
După instalare se deschide Configuration view. Introdu:
- API Key și Pre-qualify URL — valorile din
Company → Development. - API Environment și API Mode — alege mediul corespunzător pentru API Key-ul selectat.
- Payment Information URL (opțional) — dacă setezi URL-ul paginii cu explicația metodei de plată, acesta se folosește în butonul “More information” din interiorul widget-urilor.
4
Sincronizează planurile de rate
Apasă Save & Sync Plans. După salvare, lista de selecție Installment Group se completează automat cu grupurile disponibile pentru contul tău.
5
Activează Installment Group
În lista Default Group alege grupul dorit și apasă Activate Group. Aplicația este acum configurată și pregătită pentru afișarea widget-urilor.
Configurarea widget-urilor
În Shopify Admin mergi la Online Store → Themes → Customize al temei active. În căutarea de secțiuni sunt disponibile trei widget-uri noi, pe care le poți insera în secțiunile dorite ale paginii.
Integrarea în temă
Product Widget nu acceptă în mod implicit evenimentele de modificare a prețului la schimbarea variantei produsului (de ex. mărime, culoare), deoarece fiecare temă Shopify gestionează diferit actualizările de preț și nu există o modalitate standardizată de a detecta aceste evenimente.
Pentru a depăși această limitare și a asigura compatibilitatea cu aplicațiile terțe, Leanpay Marketing Tools oferă o modalitate programatică de a declanșa actualizările de preț — prin CustomEvent-ul leanpay:priceChange.
Exemplu de implementare:
// Exemplu: la schimbarea variantei function onVariantChange(variant) { // Logica ta existentă pentru schimbarea variantei... // Notifică widget-ul Leanpay despre modificarea prețului if (variant && variant.price) { window.dispatchEvent(new CustomEvent('leanpay:priceChange', { detail: { price: variant.price / 100 // Convertește cenții în unități valutare } })); } } // Exemplu: la schimbarea cantității function onQuantityChange(quantity) { const basePrice = 99.99; const newPrice = basePrice * quantity; window.dispatchEvent(new CustomEvent('leanpay:priceChange', { detail: { price: newPrice } })); }
Note importante
ℹ
Planurile de rate (Installment plans) le poți reîmprospăta manual selectând Save & Sync Plans în vizualizarea de configurare. Altfel, planurile se actualizează automat în fiecare zi la miezul nopții.
ℹ
Dacă valuta magazinului diferă de valuta mediului API de destinație, calculatorul convertește automat valorile afișate în valuta de destinație folosind cele mai recente cursuri de schimb disponibile.
ℹ
Toate widget-urile sunt traduse automat în limba, respectiv locale-ul magazinului. Momentan sunt acceptate: English (limba de rezervă implicită), slovenă, română și croată.
Returnări și reclamații Shopify
Pentru informații detaliate despre soluționarea disputelor, consultă documentația oficială Leanpay.
Dacă suma returnării nu corespunde exact cu suma totală plătită (inclusiv toate produsele și costurile de livrare), cererea va fi respinsă cu o eroare.
Pentru o procesare reușită selectează întotdeauna toate produsele comenzii și costurile de livrare aferente la trimiterea returnării.
