Plăți PayPal

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.

PayPal (NVP) este acceptat începând din API versiunea 11 până la versiunea 49.

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

PayPal prin Hosted Checkout

Dacă aveți deja o integrare Hosted Checkout, PayPal va fi automat disponibil din momentul în care furnizorul dvs. de servicii de plată configurează cu succes legătura achizitor pentru PayPal.

Pentru detalii, consultați Plățile prin browser în integrarea Hosted Checkout.

PayPal prin Direct Payment

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.

Alegerea unui proces de validare

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.

Selectarea momentului confirmării plății

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.

Selectarea modului de colectare a adresei de livrare

Î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. Implicit, PayPal colectează adresa de livrare de la plătitor pe site-ul web PayPal, iar 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.

Exemplu de proces de validare

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 lucru PayPal

Procesul de validare este după cum urmează:

  1. Un plătitor vizitează site-ul magazinului dvs., selectează un produs și apasă Validare cu PayPal în cadrul paginii de validare.
  2. Când plătitorul face clic pe butonul Validare cu PayPal, veți efectua un apel Initiate Browser Payment către gateway și veți redirecționa plătitorul către adresa URL returnată în răspuns.
  3. Gateway-ul redirecționează plătitorul către site-ul web PayPal.
  4. Plătitorul se conectează la contul personal PayPal cu ajutorul paginii de conectare PayPal.
  5. Plătitorul precizează adresa de livrare. Plătitorul poate selecta o adresă de livrare stocată anterior de PayPal sau poate introduce o adresă nouă.
  6. Plătitorul selectează o sursă de finanțare și continua plata apăsând butonul "Continue" (Continuare) din cadrul site-ului web PayPal.
  7. 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.
  8. 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 Payment către gateway.
  9. 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]

Referință API Retrieve Transaction [REST][NVP]

Referință API Confirm 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
  • browserPayment.operation=Authorize sau Pay

    Î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.

    Referință API câmp operațiune [REST][NVP]

  • browserPayment.paypal.paymentConfirmation

    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 Transaction că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 Transaction pentru 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 apel Confirm Browser Payment pentru a confirma plata cu PayPal. Răspunsul la Confirm Browser Payment va 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 a plătitorului
    • numele posesorului de cont pentru contul PayPal al plătitorului
    • detaliile adresei de livrare
  • [Opțional] Afișare/Modificare adresă 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.

      Referință API afișare câmp adresă de livrare [REST][NVP]

    • browserPayment.paypal.overrideShippingAddress — când are valoarea true (implicită), plătitorul poate modifica adresa de livrare pe site-ul web PayPal.

      Referință API modificare câmp adresă de livrare [REST][NVP]

    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.displayShippingAddress cu 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 Transaction dacă adresa de livrare a fost furnizată în solicitarea Initiate Browser Payment sau dacă câmpul browserPayment.paypal.displayShippingAddress are 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 livrare? Este validă Adresa de livrare? Este afișată pentru plătitor Adresa de livrare? Sursa Adresei de livrare afișate Poate plătitorul modifica Adresa de livrare?
    true (implicit) true (implicit) opțional nu NA da PayPal colectează adresa de livrare. 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 livrare 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.
  • [Opțional] Detalii pentru articol de linie

    Puteți să specificați detaliile pentru articolele-rând în solicitarea Initiate Browser Payment pentru 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=SUBMITTED
result=SUCCESS		 Redirecționați plătitorul la adresa URL inclusă în răspuns.
response.gatewayCode=SUBMITTED
result=FAILURE or PENDING or UNKNOWN		 Trimiteți o altă solicitare INITIATE_BROWSER_PAYMENT.
Răspunsul la Retrieve Transaction/Retrieve Order
Ce înseamnă...
response.gatewayCode=APPROVED
result=SUCCESS
 Plata a fost realizată cu succes.
response.gatewayCode=PENDING
result=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=CANCELLED
result=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_SUPPORTED
result=FAILURE		 Plata a fost respinsă de PayPal.
response.gatewayCode=ACQUIRER_SYSTEM_ERROR
result=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_ERROR
result=FAILURE		 Gateway-ul nu a putut procesa tranzacția.
response.gatewayCode=TIMED_OUT
result=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=UNKNOWN
result=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ă.

Pentru a rambursa în exces cu succes, trebuie să aveți configurate rambursări excesive prin intermediul:

  • 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:

  1. Conectați-vă la contul dvs. PayPal (la https://www.paypal.com).
  2. 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:
      1. Apăsați Profile (Profil).
      2. Î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:
      1. În cadrul Profile (Profil), apăsați My Selling Tools (Instrumentele mele de vânzări).
      2. În cadrul Selling online (Vânzări online), apăsați legătura Update (Actualizare) din dreapta Custom payment pages (Pagini de plată personalizate).

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.

Configurarea contului dvs.

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:

  1. Conectați-vă la contul dvs. PayPal de companie (la https://www.paypal.com).
  2. 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:
      1. Apăsați Profile (Profil).
      2. În cadrul Account information (Informații cont), apăsați Request API credentials (Solicitare acreditări API).
      3. 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:
      1. În cadrul Profile (Profil), apăsați My Selling Tools (Instrumentele mele de vânzări).
      2. În cadrul Selling online (Vânzări online), apăsați legătura Update (Actualizare) din dreapta API access (Acces API).
  3. Î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).
  4. Î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 mesajul e-mail de configurare comerciant trimis de UniCredit Bank.
  5. Î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)
  6. Faceți clic pe Add (Adăugare).
După configurarea contului dvs.

Trebuie să transmiteți furnizorului dvs. de servicii de plată adresa de e-mail a contului dvs. PayPal de companie.

Utilizând aceste detalii, furnizorul dvs. de servicii de plată 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.

Copyright © 2023 UniCredit Bank