Notificări Webhook
Un Webhook permite unei aplicații să trimită notificări către alte aplicații. Când gateway-ul creează sau actualizează o tranzacție pentru o comandă, acesta trimite o notificare către URL-ul specificat de dumneavoastră. Abonându-vă la notificările Webhook, vă puteți asigura că sistemul magazinului dvs. online este la curent cu cele mai recente informații despre comenzi.
Notificarea Webhook:
- Folosește protocolul API pentru servicii web (REST-JSON sau NVP) configurat pentru comerciant.
- Conține secretul configurat de comerciant, pe care sistemul îl transmite cu fiecare notificare către o adresă URL securizată, în câmpul antet personalizat X-Notification-Secret.
Notificările webhook nu sunt recomandate pentru proiectarea sistemelor critice sau care necesită răspuns rapid, deoarece nu garantează livrarea promptă. Ca alternativă, puteți utiliza API-ul Retrieve Transaction. Evitați utilizarea Webhook în sisteme importante, cum ar fi decontare și reconcilierea sau fluxul de tranzacţie în timp real, deoarece este un serviciu de notificare offline.
Notificare Webhook pentru operațiunile API Serviciile Web
Primiți notificări Webhook pentru următoarele operațiuni API:
- Initiate Authentication: solicitare care returnează mecanismul de autentificare a plătitorului (de exemplu, Autentificare 3-D Secure versiunea 2, Autentificare 3-D Secure versiunea 1, RuPay PaySecure) pe care gateway-ul vă recomandă să îl utilizați pentru această comandă.
- Authenticate Payer: Sistemul trimite această notificare după finalizarea operațiunii Authenticate Payer. Conține numai detalii despre operațiunea de autentificare și nu oferă informații despre rezultatul tranzacției financiare. Authentication Payer nu acceptă order.notificationUrl în sarcina utilă JSON, dar sistemul trimite un Webhook pe adresa URL pe care ați configurat-o în solicitarea Initiate Authentication.
- Authorization sau Pay: Sistemul trimite o notificare după finalizarea operațiunii de tranzacţie Authorization sau a operațiunii de tranzacţie Pay. Conține rezultatul procesării tranzacției financiare.
- Capture: Sistemul trimite o notificare după finalizarea operațiunii de tranzacție Capture. Conține rezultatul procesării tranzacției financiare. De asemenea, Standalone Capture este suportată.
- Refund: Sistemul trimite o notificare după finalizarea operațiunii de tranzacţie Refund. Conține rezultatul procesării tranzacției financiare. Este suportată și Standalone Refund.
- Update Authorization: Sistemul trimite o notificare după finalizarea operațiunii de tranzacție Update Authorization. Conține rezultatul procesării tranzacției financiare.
- Void: Sistemul trimite o notificare după finalizarea operațiunii de tranzacţie Void. Conține rezultatul procesării tranzacției financiare.
- Verify: Sistemul trimite o notificare după finalizarea operațiunii de tranzacție Verify. Conține rezultatul procesării tranzacției financiare.
- Referral: Sistemul trimite o notificare după finalizarea operațiunii de tranzacție Referral. Conține rezultatul procesării tranzacției financiare.
- Disbursement: Sistemul trimite o notificare după finalizarea operațiunii de tranzacție Referral. Conține rezultatul procesării tranzacției financiare.
- Initiate Browser Payment: Sistemul trimite o notificare după finalizarea operațiunii de tranzacţie IBP. Conține rezultatul procesării tranzacției financiare.
- Confirm Browser Payment: Sistemul trimite o notificare după finalizarea tranzacţiei CBP. Conține rezultatul procesării tranzacției financiare.
Configurați notificările Webhook în Merchant Administration
Pentru a configura notificările Webhook:
- Autentificați-vă în portal Merchant Administration și accesați Admin>Notificări Webhook.
- Configurați următorii parametri pentru notificările Webhook:
- URL global de notificare: Configurați un URL global de notificare pentru a primi actualizări pentru toate tranzacțiile. URL-ul pe care îl furnizați trebuie să fie conform standardului IETF pentru URL-uri. În caz contrar, sistemul respinge solicitarea.
Pentru a suprascrie această adresă URL globală pentru o anumită tranzacție, includeți adresa URL în câmpul order.notificationUrl al solicitării tranzacției. Pentru tranzacțiile ulterioare, notificările sunt trimise la adresa URL specificată în tranzacție (dacă este furnizată) sau la ultima adresă URL utilizată pentru comandă.
Conform noului standard IETF, formatul username:password@host.com nu mai este aplicabil. Dacă utilizați acest format, webhook-urile sunt trimise, dar numele de utilizator și parola sunt ignorate. Utilizați un secret de notificare în scopuri de autentificare.
- Formatul API: Mastercard Gateway transmite notificările Webhook în formatul (REST-JSON sau NVP) pe care îl configurați în Merchant Administration. Sistemul trimite notificarea în versiunea care a fost utilizată pentru a trimite solicitarea de tranzacție.
- Verificați secretul de notificare: Secretul de notificare este un șir aleatoriu de 32 de caractere generat de gateway. Vedeți acest secret în portalul Merchant Administration atunci când configurați notificările Webhook. Pentru adrese URL securizate (https://), gateway-ul include secretul în antetul
X-Notification-Secretal mesajului.
- URL global de notificare: Configurați un URL global de notificare pentru a primi actualizări pentru toate tranzacțiile. URL-ul pe care îl furnizați trebuie să fie conform standardului IETF pentru URL-uri. În caz contrar, sistemul respinge solicitarea.
Livrarea cu succes a notificărilor Webhook
Gateway-ul consideră livrarea notificării Webhook ca fiind reușită dacă sistemul dumneavoastră răspunde cu un mesaj de confirmare care conține codul de stare HTTP 200 în cel mult 2 secunde.
Gateway nu așteaptă anteturi specifice de la comercianți, dar în cazul în care un răspuns de la endpoint-ul țintă trimite anteturi, acestea nu trebuie să depășească 32KB. Sistemul încearcă să retrimită notificarea webhook până când primește un răspuns.
Mastercard Gateway impune comercianților să primească notificări webhook exclusiv printr-un endpoint securizat (HTTPS://), asigurând atât securitatea, cât și conformitatea.
Secvența notificărilor Webhook și reexpedierea
- Încercări de livrare: Gateway-ul Mastercard încearcă să livreze notificările Webhook pentru comercianți de maximum 20 de ori într-o perioadă de 3 zile de la apariția evenimentului.
- Intervale de reîncercare: Gateway-ul reexpediază notificarea webhook la următoarele intervale: 10 secunde, 30 secunde, 2 minute, 5 minute, 30 minute, 4 ore (de patru ori), 8 ore, 12 ore (de patru ori).
- Gestionarea timeout-ului: Gateway-ul așteaptă 30 de secunde înainte de a înregistra o excepție de tip timeout pentru notificarea Webhook.
- Livrare reușită: Gateway-ul va considera că livrarea notificării Webhook a avut succes dacă sistemul dumneavoastră răspunde cu un cod de stare HTTP 200 în intervalul de 3 zile.
- Oprirea încercărilor: Toate încercările de livrare a unei notificări webhook se opresc după 20 de încercări în decurs de 3 zile.
Gestionarea notificărilor retrimise
Puteți utiliza următoarele câmpuri din notificarea Webhook pentru a gestiona notificările retrimise:
- X-Notification-ID: Acest antet identifică în mod unic notificarea și este identic pentru tranzacțiile duplicate.
- X-Notification-Attempt: Acest antet indică numărul de încercări efectuate pentru trimiterea notificării.