UNIPaaS/agent-skills

Unipaas

Grundlagen

Unipaas bietet eingebettete Zahlungen für digitale Plattformen und Marktplätze (SaaS, Gig Economy, B2B/B2C-Marktplätze). Sie onboarden Anbieter (Sub-Merchants), akzeptieren Zahlungen, verwalten Konten (Guthaben) und zahlen Gelder aus – während Sie Geldflüsse kontrollieren und PSD2-/PCI-konform bleiben.

Holen Sie sich einen Sandbox-Key. Erstellen Sie ein kostenloses Testkonto unter https://portal.unipaas.com/signup. Das Testkonto ist unbegrenzt und immer verfügbar. Finden Sie Ihren Private Key im Portal unter dem Entwickler-/Schlüsselbereich. Sandbox- und Live-Zugangsdaten sind vollständig getrennt und teilen keine Daten.

Basis-URLs.

• Sandbox: https://sandbox.unipaas.com/platform
• Produktion (Live): https://api.unipaas.com/platform

Zwei Authentifizierungsmodi (Details in references/auth.md).

1. Server-zu-Server: Senden Sie Ihren Private Key als Authorization: Bearer {{PRIVATE_KEY}} direkt bei API-Aufrufen (Checkout-Erstellung, Einzahlungen, Konten, Auszahlungen, Onboarding). Der Private Key muss serverseitig bleiben.
2. Zwei-Schritt /authorize-Flow (für clientseitige Plattform-Einbettungen): Ihr Server POSTt den Private Key an /authorize mit scopes und (normalerweise) einer vendorId, und erhält einen temporären accessToken. Der Client verwendet diesen Access Token – niemals den Private Key.

Idempotenz. Um doppelte Ausführung bei Wiederholungen zu vermeiden, fügen Sie einen requestId: <id>-Header zu POST-Anfragen hinzu. Dieselbe requestId, die mehrmals gesendet wird, führt zu einem einzigen Ergebnis. Request-IDs sind 24 Stunden gültig.

Entscheidungsmatrix

Vier Produkte, drei Integrationsstufen. Wählen Sie die Stufe, die zu Ihrer Entwicklerkapazität und PCI-Position passt.

Produkt	No-Code	Geringer Aufwand	Mittlerer Aufwand
Onboarding	Gehosteter Onboarding-Link	Eingebettete UI (unipaas.components)	Onboarding-API
Zahlungen akzeptieren	Zahlungslink (Portal)	Checkout-Seite / Web SDK	Pay-in-API (Server-zu-Server)
Kontoverwaltung	Portal-Ansicht	Konto-/Guthaben-Komponente	Konto-API
Geld auszahlen	Manuelle/Geplante Auszahlung über Portal	Auszahlungsformular / Konto-Komponente	Auszahlungs-API

Hilfestellung:

• Null Code gewünscht? Verwenden Sie Zahlungslink, gehosteten Onboarding-Link, Portal-Auszahlungen.
• Eigene UI mit geringem Aufwand + reduzierter PCI? Verwenden Sie die Checkout-Seite (Weiterleitung), Web SDK-Sicherheitsfelder oder Buyer-Web-Embeds; verwenden Sie Plattform-Embeds für Onboarding/Guthaben/Portal.
• Volle Kontrolle / White-Label / native App gewünscht? Verwenden Sie die APIs. Pay-in-API (rohe Kartendaten) erfordert PCI SAQ D.

Hinweis: Eine Transaktion, die ohne vendorId gesendet wird, wird gegen das Plattformkonto verbucht.

Clientseitige Checkout-Pfade

Siehe references/web-sdk.md für vollständige Schritte. Zwei Buyer-Zahlungspfade, beide authentifiziert mit dem sessionToken, der von einem serverseitigen POST /pay-ins/checkout zurückgegeben wird – nicht dem /authorize-Access-Token.

1. Secure-Fields SDK – Laden Sie https://cdn.unipaas.com/unipaas.sdk.js (macht das globale Unipaas verfügbar). Erstellen Sie Ihr eigenes Kartenformular, dann new Unipaas().initTokenize(sessionToken, fields, options). Secure Fields sind ein Feature dieses Bundles, kein separates Paket.
2. Buyer-Web-Embeds – Laden Sie https://cdn.unipaas.com/embedded-ui.js, dann unipaas.buyerComponents(sessionToken, config) und .create("checkout"|"card"|"digitalWallet").mount("#id").

Authentifizierungsgrenze (wichtig):

• Buyer-Zahlung (Secure Fields und Buyer-Web-Embeds) → sessionToken von POST /pay-ins/checkout.
• Plattform-Embeds (unipaas.components: Guthaben, Rechnung, Onboarding, payPortal, Benachrichtigung) → der /authorize-Access-Token mit Scopes und vendorId. Buyer-Checkout verwendet nicht den /authorize-Access-Token.

Nach jeder clientseitigen Autorisierung serverseitig verifizieren mit GET /pay-ins/{authorizationId}; Status muss CAPTURED für Erfolg sein.

Referenzen

• references/auth.md – der /authorize-Flow, Scopes, Token-Lebenszyklus, Idempotenz.
• references/accept-payments.md – Das Produkt 'Zahlungen akzeptieren', die drei Stufen, die Checkout-Seite, Zahlungserstellung, Tokenisierung, Webhooks.
• references/web-sdk.md – die zwei clientseitigen Buyer-Zahlungspfade, die vom sessionToken gespeist werden.
• references/security.md – Schlüsselverwaltung, was serverseitig bleibt, die PCI-Oberfläche.