YUNIT SL
YUNIT SL
Senior Hands on Delivery
English Deutsch Català Русский

Merchant integration guide

Händlerintegration

Technische Integrationsansicht für Händler, die YUNIT als Identity Provider, Consent Manager und PII Vault für einzelne Kundendatenfreigaben nutzen.

Portal aufrufen Consumer-Überblick

Voraussetzungen für das Händler-Onboarding

  • Jeder Händler wird als YUNIT-Tenant mit einem oder mehreren POS- oder Backend-OAuth-Clients eingerichtet.
  • Jeder OAuth-Client erhält Redirect-URIs, erlaubte Scope-Anfragen und einen Anzeigenamen für die Consent-Seite.
  • Der Händler definiert, welche POS-Prozesse Kundendaten brauchen und welcher Geschäftszweck dem Kunden angezeigt werden soll.
  • Store-Mitarbeiter erhalten klare Anweisungen für Wallet-QR-Scans sowie den Umgang mit abgelehnten oder abgelaufenen Anfragen.

Scope-Katalog und Anfragemodell

  • Händler fordern Felder aus einem vordefinierten YUNIT-Scopeset an, etwa Name, Rechnungsadresse, Steuer- oder NRT-Nummer, E-Mail und Telefon.
  • Jede Consent-Anfrage muss angeforderte Scopes, Händlername und Geschäftszweck enthalten.
  • Die Anfrage ist einmalig und erzeugt keine fortbestehende Berechtigung für spätere Datenabfragen.
  • YUNIT liefert Request-ID, Consent-URL, Callback-Kontext und einen Status-Endpunkt für Polling zurück.

Lifecycle der Consent-Anfrage

  • Das POS oder Händler-Backend erzeugt die Anfrage serverseitig mit den OAuth-Client-Credentials.
  • Der Kunde zeigt seinen Wallet-QR, den das POS scannt, um Lookup und Freigabefluss zu starten.
  • YUNIT zeigt oder versendet den OTP-gestützten Freigabepfad auf dem Gerät des Kunden und protokolliert Erlauben oder Ablehnen.
  • Nach Freigabe tauscht der Händler den Autorisierungscode und liest nur die freigegebenen Felder dieser Anfrage.

Callback-, Polling- und Ablaufverhalten

  • Händlersysteme sollten Redirect- oder Callback-Abschluss und zusätzlich Status-Polling unterstützen, damit das POS robust bleibt.
  • Abgelehnte, abgebrochene oder abgelaufene Requests sind final und dürfen keinen Datenzugriff auf Händlerseite auslösen.
  • Abgelaufene Autorisierungscodes und Tokens verlangen einen Neustart der Anfrage statt Wiederverwendung alter Credentials.
  • POS-Masken sollten die Zustände waiting, approved, denied und expired klar darstellen.

Security- und Audit-Erwartungen

  • Wallet-QRs repräsentieren rotierende Lookup-Tokens, keine stabilen lesbaren Kunden-IDs für den Händler.
  • Händler sollten nur Request-Referenzen, Outcome und minimal notwendige Transaktionsdaten speichern, nicht einen parallelen Vollabzug des YUNIT-Profils.
  • YUNIT bleibt die autoritative Stelle für angeforderte Scopes, freigegebene Scopes, Zwecktext und Release-Ereignisse.
  • Redirect-URI-Registrierung, Token-Laufzeiten und strikte Scope-Nutzung sind Voraussetzung für eine supportbare Integration.

Ablauf der Haendlerintegration

  1. Step 1 Haendler-Tenant bereitstellen, Redirect-URIs registrieren und OAuth-Zugangsdaten fuer das POS-Backend oder Middleware ausgeben.
  2. Step 2 Consent-Anfrage mit benoetigten Scopes, Zweckreferenz und POS-Sitzungskontext erzeugen.
  3. Step 3 Wallet-QR des Kunden scannen, damit YUNIT den Wallet-Token aufloesen und den OTP-gestuetzten Freigabefluss starten kann.
  4. Step 4 Den kurzlebigen Authorization Code nach Freigabe empfangen und gegen ein Access Token tauschen.
  5. Step 5 Nur die freigegebenen Daten abrufen, den Geschaeftsvorgang abschliessen und den Audit-Trail der Anfrage behalten.

Beispiel fuer eine Consent-Anfrage

curl -H "Authorization: Bearer POS_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/consent-requests \
  -d '{
    "merchant_id": "restaurant-abc",
    "terminal_id": "pos-03",
    "purpose": "Invoice #12345",
    "scopes": ["name", "billing_address", "tax_number"],
    "callback_url": "https://merchant.example.com/yunit/callback"
  }'

Authorization-Code-Austausch

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/token \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_req_9f8d",
    "redirect_uri": "https://merchant.example.com/yunit/callback"
  }'

Beispiel fuer den Abruf freigegebener Daten

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET "https://api.yunit.tech/oauth/consent-requests/auth_req_9f8d/data"

Betriebliche Hinweise

  • Callback und Polling gemeinsam nutzen, damit das POS bei Verzoegerungen eines Pfads robust bleibt.
  • Jede Freigabe ist eine einmalige Zustimmung. Eine spaetere Anfrage braucht erneut eine neue Freigabe.
  • Authorization Codes und Access Tokens sollten kurzlebig sein und nur fuer die genehmigte Anfrage gelten.
  • Haendler-Logs sollten Request-IDs, Scopes, Zweckreferenzen und Ergebnisstatus speichern, aber keine unnoetige PII.