- Ghid de integrare
- Caracteristici acceptate (Metode de plată)
- Implementarea unei integrări pentru plată prin browser
- Plățile PayPal NVP
PayPal NVP
PayPal este o metodă de plată prin browser acceptată în eGenius Platform. Această pagină descrie detaliile de integrare specifice pentru API-ul NVP PayPal, inclusiv modul de configurare a contului de companie PayPal pentru a accepta plăți prin gateway, cerințele de branding etc. Este recomandat să citiți ghidul de integrare pentru plățile prin browser înainte de a construi o integrare PayPal.
Cerințe preliminare
Pentru a utiliza PayPal ca metodă de plată pe gateway, trebuie să aveți un cont de companie PayPal configurat pentru gateway. Pentru detalii, consultați secțiunea Configurarea contului dvs. PayPal de companie.
Pentru a vă înregistra pentru un cont PayPal de companie, apăsați aici.
Integrarea PayPal
Dacă aveți o integrare Hosted Checkout existentă, PayPal va fi disponibil automat după ce your payment service provider a configurat cu succes legătura achizitor pentru PayPal.
Pentru detalii, consultați Plățile prin browser în integrarea Hosted Checkout.
Alegeți integrarea Direct Payment dacă doriți să oferiți metoda de plată PayPal pe propria dvs. pagină de validare.
Procesul de validare PayPal
Puteți alege procesul de validare adecvat pentru site-ul magazinului dvs.
PayPal permite plătitorilor dvs. să realizeze rapid și în siguranță validarea pe site-ul magazinului dvs., permițându-le să utilizeze contul personal PayPal pentru plată și opțional să furnizeze informații de livrare site-ului de comerț. Cu PayPal, plătitorii încep și finalizează procesul de validare pe site-ul magazinului dvs.. Plătitorii trebuie doar să se conecteze la contul personal PayPal și să confirme adresa de livrare și metoda de plată. Site-ul de comerț poate apoi să primească informațiile de livrare.
Gateway-ul acceptă două tipuri de procese de validare PayPal — Comandă rapidă și Marcare.
Procesul Comandă rapidă vă permite să redirecționați plătitorul de pe site-ul magazinului dvs. pe site-ul PayPal, folosind butonul “Validare cu PayPal afișat pe pagina de verificare a cardului de pe site-ul magazinului. Plătitorul evită procesul normal de validare și realizează validarea folosind informațiile stocate în contul propriu PayPal. PayPal furnizează site-ului magazinului numele, adresa e-mail și adresa de livrare din contul plătitorului, permițând o validare mai rapidă prin evitarea introducerii acestor informații pe site-ul magazinului.
Procesul Marcare permite plătitorului să continue procesul normal de validare, introducând informațiile de facturare și livrare pe site-ul magazinului. Când plătitorului îi este solicitat să selecteze metoda de plată, plătitorul selectează opțiunea PayPal aflată pe pagina de facturare a site-ului de comerț alături de alte opțiuni de plată. Spre deosebire de o tranzacție de tip comandă rapidă, site-ul de comerț furnizează serviciului PayPal adresa de livrare a plătitorului.
Atât în procesul de validare Comandă rapidă, cât și în cel de Marcare, puteți alege să afișați butonul "Plătiți acum" sau un buton "Continuare" pe site-ul PayPal.
Butonul "Plătiți acum" permite plătitorului să confirme plata pe site-ul web PayPal înainte de a fi redirecționat înapoi către site-ul magazinului dvs. Această opțiune vă permite să oferiți plătitorului o experiență de validare mai rapidă, deoarece plătitorul finalizează plata pe site-ul web PayPal.
Butonul "Continuare" permite redirecționarea plătitorului către site-ul magazinului dvs. pentru confirmarea plății după vizualizarea tuturor detaliilor comenzii. Această opțiune vă permite să modificați, dacă este necesar, comanda, înainte de a accepta plata (de exemplu, adăugând taxele de livrare și manipulare pe baza adresei returnate de la PayPal). Ca alternativă, puteți include alți pași de validare, cum ar fi ofertele de produse similare sau conexe pe pagina dvs. de confirmare a comenzii.
Consultați secțiunea Confirmare plată de mai jos, pentru detalii privind implementarea acestei opțiuni în cadrul integrării dvs. PayPal.
În funcție de procesul de validare, Marcare sau Comandă rapidă, puteți alege să colectați adresa de livrare a plătitorului pe site-ul magazinului dvs., respectiv pe site-ul web PayPal. În mod implicit, PayPal colectează adresa de expediere de la plătitor pe site-ul PayPal, pe care plătitorul o poate adăuga sau edita, dacă este necesar. Puteți opta să nu afișați adresa de livrare și/sau să dezactivați posibilitatea editării. Consultați secțiunea Afișare/Înlocuire adresă de livrare de mai jos, pentru informații privind implementarea acestei opțiuni în cadrul integrării dvs. PayPal.
Exemplul de mai jos descrie procesul Comandă rapidă, unde plătitorul utilizează adresa de livrare așa cum este stocată de PayPal. Plătitorul revizuiește și confirmă plata pe site-ul de comerț al comerciantului.
Procesul de validare este după cum urmează:
- Un plătitor vizitează site-ul magazinului dvs., selectează un produs și apasă Validare cu PayPal în cadrul paginii de validare.
- Când plătitorul face clic pe butonul Validare cu PayPal, veți efectua un apel
Initiate Browser Paymentcătre gateway și veți redirecționa plătitorul către adresa URL returnată în răspuns. - Gateway-ul redirecționează plătitorul către site-ul web PayPal.
- Plătitorul se conectează la contul personal PayPal cu ajutorul paginii de conectare PayPal.
- Plătitorul precizează adresa de expediere. Plătitorul poate selecta o adresă de expediere stocată anterior de PayPal sau poate introduce o adresă nouă.
- Plătitorul selectează o sursă de finanțare și continua plata apăsând butonul "Continue" (Continuare) din cadrul site-ului web PayPal.
- Plătitorul este redirecționat de pe site-ul PayPal înapoi pe site-ul magazinului dvs., prin intermediul gateway-ului. Veți apela detaliile tranzacției, inclusiv adresa de e-mail și adresa de livrare din contul plătitorului, cu ajutorul operațiunii
Retrieve Transaction. - Pe baza acestor informații prezentați o pagină de revizuire pentru plătitor (de exemplu, este posibil să doriți să adăugați taxele de transport și manipulare). Când plătitorul face clic pe butonul "Plătiți acum" pentru a procesa plata, veți efectua un apel
Confirm Browser Paymentcătre gateway. - Gateway-ul trimite un răspuns cu detaliile tranzacției, care indică succesul sau altă stare a plății, pentru ca dvs. să puteți prezenta această stare plătitorului.
Referință API Initiate Browser Payment [REST][NVP]
Integrarea Direct Payment
Integrarea Direct Payment vă permite să oferiți metoda de plată PayPal pe propria dvs. pagină de validare.
Următoarele câmpuri din solicitarea Initiate Browser Payment sunt fie specifice PayPal, fie au o utilizare specifică în cadrul integrării PayPal. Pentru alte detalii, consultați Plățile prin browser în integrarea Direct Payment.
sourceOfFunds.type = PAYPAL-
În cazul PayPal, autorizarea expiră în 3 zile de la momentul realizării autorizării. Dacă încă doriți să decontați fondurile după expirarea autorizării, puteți utiliza operațiunea Update Authorization.
În mod implicit, contul dvs. de comerciant PayPal este configurat doar pentru decontări unice. Dacă doriți să modificați configurația pentru a accepta decontări multiple, vă rugăm să contactați PayPal. -
La inițierea unei plăți PayPal, trebuie să specificați dacă doriți ca plătitorul să confirme plata pe site-ul web PayPal sau pe site-ul magazinului dvs..
Referință API câmp confirmare plată [REST][NVP]
În cazul confirmării la furnizor (PayPal), site-ul web PayPal afișează un buton "Plătiți acum", care permite plătitorului să confirme plata pe site-ul web PayPal înainte de a fi redirecționat către site-ul magazinului dvs. Trebuie să trimiteți o solicitare
Retrieve Transactioncătre gateway pentru a determina succesul sau altă stare a plății.Dacă confirmarea are loc pe site-ul magazinului dvs., site-ul web PayPal afișează un buton "Continue" (Continuare), care permite plătitorului să fie redirecționat către site-ul magazinului dvs., unde plătitorul poate confirma plata. Trebuie să trimiteți o solicitare către
Retrieve Transactionpentru a apela detalii privind continuarea sau necontinuarea plății de plătitor. Dacă plătitorul continuă cu plata pe site-ul magazinului dvs., trebuie să trimiteți un apelConfirm Browser Paymentpentru a confirma plata cu PayPal. Răspunsul laConfirm Browser Paymentva conține informații referitoare la succesul sau altă stare a plății.Referință API Confirm Browser Payment [REST][NVP]
În ambele cazuri, dacă plata are succes, funcția Retrieve Transaction returnează:
- adresa de e-mail a contului PayPal al plătitorului
- numele posesorului de cont pentru contul PayPal al plătitorului
- detaliile adresei de livrare
-
Puteți să administrați modul în care plătitorul vă furnizează o adresă de livrare utilizând două câmpuri:
browserPayment.paypal.displayShippingAddress— când are valoarea true (implicită), adresa de livrare este afișată pe site-ul web PayPal.browserPayment.paypal.overrideShippingAddress— când are valoarea true (implicită), plătitorul poate modifica adresa de livrare pe site-ul web PayPal.
Implicit, PayPal colectează pentru dvs. adresa de livrare de la plătitor pe site-ul web PayPal. Dacă optați să colectați adresa de livrare de la plătitor pe site-ul magazinului dvs. și nu doriți ca PayPal să afișeze adresa de livrare pentru plătitor, trebuie să setați câmpul
browserPayment.paypal.displayShippingAddresscu valoarea „false”. Aceasta situație este aplicabilă și pentru cazul în care adresa de livrare nu este necesară pentru o comandă (de exemplu, pentru produse exclusiv digitale).Gateway-ul va returna întotdeauna adresa de livrare în cadrul răspunsului
Retrieve Transactiondacă adresa de livrare a fost furnizată în solicitareaInitiate Browser Paymentsau dacă câmpulbrowserPayment.paypal.displayShippingAddressare valoarea true.Consultați tabelul de mai jos pentru diferitele scenarii care ar putea fi aplicabile integrării dvs. Puteți selecta un scenariu diferit pentru fiecare plată.
Initiate Browser Payment Site web PayPal Afișare Adresă de livrare Modificare Adresă de livrare Este necesară Adresa de livrare? Este furnizată Adresa de expediere? Este validă Adresa de expediere? Este afișată pentru plătitor Adresa de livrare? Sursa Adresei de livrare afișate Poate plătitorul modifica Adresa de expediere? true (implicit) true (implicit) opțional nu Neaplicabil da PayPal colectează adresa de expediere. da true (implicit) true (implicit) opțional da da da PayPal afișează adresa de livrare furnizată de dvs. în solicitarea către site-ul web PayPal. da true (implicit) true (implicit) opțional da nu da PayPal ignoră adresa de livrare furnizată de dvs. în solicitare și în locul acesteia colectează adresa de livrare pe site-ul web PayPal. da true (implicit) false obligatoriu da da da PayPal afișează adresa de livrare furnizată de dvs. în solicitarea către site-ul web PayPal. nu true (implicit) false obligatoriu da nu nu PayPal respinge solicitarea. Neaplicabil false Neaplicabil Neaplicabil da da nu PayPal ignoră adresa de expediere furnizată de dvs. în solicitare. nu false Neaplicabil Neaplicabil Neaplicabil Neaplicabil nu PayPal nu dispune de o adresă de livrare pentru a fi afișată. Neaplicabil Pentru toate scenariile, trebuie să utilizați adresa de livrare returnată în răspunsul de tranzacție în cazul în care adresa de livrare a fost modificată de către plătitor pe site-ul web PayPal. Vă rugăm să rețineți faptul că PayPal validează combinațiile de oraș, stat și cod zip pentru adresele de livrare din SUA. -
Puteți să specificați detaliile pentru articolele-rând în solicitarea
Initiate Browser Paymentpentru a furniza plătitorului toate detaliile comenzii înainte ca acesta să confirme plata. Studiile efectuate în rândul consumatorilor arată ca un procent mai mare finalizează achizițiile în cazul în care văd articolele individuale și detaliile comenzii în decursul validării PayPal. Prin urmare, este recomandat să furnizați informațiile referitoare la comandă când inițiați o validare PayPal, pentru a încuraja plătitorii să continue plata mai curând decât să renunțe la aceasta.Articolele de linie sunt considerate furnizate, dacă numele articolului și prețul unitar sunt specificate.
Pentru mai multe informații referitoare la detaliile pentru articolele de linie, consultați Date articol de linie.
Interpretarea rezultatului tranzacției
Tabelul următor prezintă codurile de răspuns la tranzacții pentru scenariile posibile care pot apărea după inițierea unei plăți prin browser.
Răspunsul la Initiate Browser Payment |
Ce înseamnă... |
|---|---|
response.gatewayCode=SUBMITTEDresult=SUCCESS |
Redirecționați plătitorul la adresa URL inclusă în răspuns. |
response.gatewayCode=SUBMITTEDresult=FAILURE or PENDING or UNKNOWN |
Trimiteți o altă solicitare INITIATE_BROWSER_PAYMENT. |
Răspunsul la Retrieve Transaction/Retrieve Order |
Ce înseamnă... |
response.gatewayCode=APPROVEDresult=SUCCESS |
Plata a fost realizată cu succes. |
response.gatewayCode=PENDINGresult=PENDING |
Plata se află în așteptarea examinării în sistemul PayPal. Starea plății va fi actualizată de către gateway imediat ce sistemul PayPal informează gateway-ul în privința rezultatului examinării. Consultați Plăți în așteptare. |
response.gatewayCode=CANCELLEDresult=FAILURE |
Plătitorul a revocat interacțiunea pentru plata respectivă. Oferiți plătitorului opțiunea de a încerca o altă metodă de plată. |
response.gatewayCode=DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTEDresult=FAILURE |
Plata a fost respinsă de PayPal. |
response.gatewayCode=ACQUIRER_SYSTEM_ERRORresult=FAILURE |
Achizitorul nu a putut procesa tranzacția. Poate fi util să solicitați achizitorului motivul pentru eșecul plății sau puteți încerca RETRIEVE_TRANSACTION din nou. De asemenea, puteți oferi plătitorului opțiunea de a încerca o altă metodă de plată. |
response.gatewayCode=SYSTEM_ERRORresult=FAILURE |
Gateway-ul nu a putut procesa tranzacția. |
response.gatewayCode=TIMED_OUTresult=FAILURE |
Interacțiunea dintre plătitor și sistemul PayPal nu a fost finalizată cu succes; de exemplu, gateway-ul nu a primit o redirecționare a browserului plătitorului de l a comerciant în interval de 24 de ore sau gateway-ul nu a putut apela detaliile interacțiunii dintre plătitor și sistemul PayPal, iar plata a rămas nefinalizată. |
response.gatewayCode=UNKNOWNresult=UNKNOWN |
Gateway-ul nu a putut determina dacă plata a avut succes sau nu. |
Plăți în așteptare
În anumite cazuri, gateway-ul poate returna starea PENDING în cadrul răspunsului la tranzacție. De exemplu, dacă tranzacția este în curs de evaluare a riscului de către PayPal. Dacă starea este în așteptare și dvs. aveți configurate propriile dvs. filtre de management al fraudelor, trebuie să vă conectați la contul dvs. PayPal de companie și să revizuiți plata.
PayPal va notifica gateway-ul când starea unei tranzacții în așteptare este actualizată de PayPal. Puteți colecta rezultatul tranzacției actualizate cu ajutorul operațiunii Retrieve Transaction.
Gateway-ul consideră o tranzacție PENDING ca tranzacție desfășurată cu succes, până la recepționarea unei notificări referitoare la succesul sau altă stare a tranzacției. Sumele totale ale comenzilor (sumă totală autorizată/decontată/rambursată) sunt actualizate luând în considerare tranzacțiile în așteptare. Dacă tranzacția este refuzată, actualizările sunt refăcute.
Rambursarea plăților PayPal
Puteți rambursa plăți procesate prin intermediul PayPal, parțial, total sau în exces; totuși, vă rugăm să rețineți faptul că suma rambursată este aplicabilă doar anumitei tranzacții Capture pe care doriți să o rambursați, și nu sumei totale autorizate. De exemplu, dacă o autorizare pentru 100 USD este urmată de două decontări parțiale de 30 USD (Capture 1) și 70 USD (Capture 2) atunci, orice sumă rambursată pentru această comandă, parțială, totală sau în exces, este aplicabilă individual pentru Capture 1 sau Capture 2 și nu întregii sume a comenzii, de 100 USD. Astfel, o rambursare de 50 USD pentru Capture 1 și Capture 2 este considerată în exces și respectiv parțială.
- API și suma rambursată (inclusiv tentativa de rambursare) nu trebuie să depășească suma decontată cu mai mult decât suma maximă de rambursare excesivă permisă.
- PayPal, dacă nu achizitorul PayPal respinge solicitarea.
Cerințe de branding pentru site-ul magazinului dvs.
Această secțiune vă ajută să configurați paginile dvs. de validare, pentru a vă conforma cerințelor de branding PayPal.
Când oferiți plătitorilor dvs. ca opțiune de plată PayPal, este important să vă asigurați că experiența de validare a plătitorului întrunește sau depășește standardele de bune practici pentru implementare a validării formulate de PayPal.
Pentru a oferi plătitorilor dvs. o experiență fluidizată, gateway-ul recomandă personalizarea paginilor dvs. de plată PayPal. În acest scop:
- Conectați-vă la contul dvs. PayPal (la https://www.paypal.com).
- Stabiliți dacă utilizați Administrator comercianți PayPal. Pentru a stabili aceasta, verificați adresa URL din bara de adresă a browserului dvs. Dacă adresa URL începe cu https://paypalmanager.paypal.com/, înseamnă că utilizați Administrator comercianți PayPal.
- Dacă utilizați Administrator comercianți PayPal:
- Apăsați Profile (Profil).
- În cadrul Hosted payment settings (Setări plată găzduită), apăsați Custom page styles (Stiluri de pagini personalizate).
- Dacă nu utilizați Administrator comercianți PayPal:
- În cadrul Profile (Profil), apăsați My Selling Tools (Instrumentele mele de vânzări).
- În cadrul Selling online (Vânzări online), apăsați legătura Update (Actualizare) din dreapta Custom payment pages (Pagini de plată personalizate).
- Dacă utilizați Administrator comercianți PayPal:
Pentru indicații despre modul de prezentare a elementelor de interfață utilizator în cadrul paginilor dvs. de validare, consultați Express Checkout User Interface Standards Guide (Ghid de standarde pentru interfața utilizator de validare rapidă) de pe site-ul web PayPal.
Configurarea contului dvs. PayPal de companie
Această secțiune descrie modul de configurare a contului dvs. de companie PayPal pentru a funcționa cu integrarea pe gateway.
Pentru a procesa tranzacții prin intermediul PayPal, trebuie să oferiți gateway-ului drepturi pentru apelurile specifice API pe care acesta trebuie să le realizeze pentru dvs.
În acest scop:
- Conectați-vă la contul dvs. PayPal de companie (la https://www.paypal.com).
- Stabiliți dacă utilizați Administrator comercianți PayPal. Pentru a stabili aceasta, verificați adresa URL din bara de adresă a browserului dvs. Dacă adresa URL începe cu https://paypalmanager.paypal.com/, înseamnă că utilizați Administrator comercianți PayPal.
- Dacă utilizați Administrator comercianți PayPal:
- Apăsați Profile (Profil).
- În cadrul Account information (Informații cont), apăsați Request API credentials (Solicitare acreditări API).
- Apăsați Set up PayPal API credentials and permissions (Configurare acreditări și drepturi API PayPal).
- Dacă nu utilizați Administrator comercianți PayPal:
- În cadrul Profile (Profil), apăsați My Selling Tools (Instrumentele mele de vânzări).
- În cadrul Selling online (Vânzări online), apăsați legătura Update (Actualizare) din dreapta API access (Acces API).
- În caseta Option 1 (Opțiune 1), va exista o legătură denumită Grant API permission (Oferire drept API) sau Add or edit API permissions (Adăugare sau editare drepturi API).
- Dacă legătura este denumită Grant API permission (Oferire drept API), apăsați-o.
- Dacă legătura este denumită Add or edit API permissions (Adăugare sau editare drepturi API), apăsați-o și apoi apăsați Add New Third Party (Adăugare terț nou).
- În caseta Third Party Permission Username (Nume utilizator drept terț), introduceți numele de utilizator API furnizat de UniCredit Bank și apăsați Lookup (Căutare). Numele de utilizator API va fi furnizat în e-mailul de configurare al comerciantului trimis de UniCredit Bank.
- În secțiunea Available Permissions (Drepturi disponibile), apăsați pe următoarele casete de selectare:
- Use Express Checkout to process payments. (Utilizare validare rapidă pentru procesarea plăților)
- Issue a refund for a specific transaction. (Emitere rambursare pentru o tranzacție specifică)
- Authorize and capture your PayPal transactions. (Autorizare și decontare tranzacții PayPal)
- Faceți clic pe Add (Adăugare).
Trebuie să furnizați your payment service provider cu adresa de e-mail a contului dvs. de companie PayPal.
Folosind aceste detalii, your payment service provider va finaliza configurarea. În momentul în care integrarea dvs. pe gateway pentru PayPal este finalizată, puteți iniția o plată prin browser cu PAYPAL ca tip de plată. În funcție de integrarea dvs., puteți furniza unele câmpuri specifice PayPal, care sunt prezentate în secțiunea care urmează.
Testarea integrării
Gateway-ul furnizează un emulator PayPal care vă permite să vă testați integrarea pentru utilizarea funcțiilor PayPal pe gateway.