API-Referenz
Die Wallee-Join-APIs sind Teil der Web-Service-API v2.0. Sie decken zwei Bereiche ab:
- Partnerschaften – Richten Sie die Verknüpfung zwischen Ihrem Partnerkonto und den Konten Ihrer Händler ein und verwalten Sie diese.
- Händleranträge – Erstellen, füllen Sie die KYC-Anträge der von Ihnen neu gewonnenen Händler vorab aus und verfolgen Sie deren Bearbeitung.
Basis-URL
https://app-wallee.com/api/v2.0
Authentifizierung und Header
Alle Anfragen werden mit einem JSON-Web-Token authentifiziert und im Kontext Ihres Partnerkontos ausgeführt:
| Überschrift | Wert | Beschreibung |
|---|---|---|
| Autorisierung | Bearer <JWT> | Für Ihren Anwendungsbenutzer ausgestelltes JWT |
| Konto | <YOUR_ACCOUNT_ID> | Das Partnerkonto, unter dem die Anfrage ausgeführt wird |
| Content-Type | application/json | Für Anfragen mit einem Body |
Sie benötigen einen Anwendungsbenutzer mit einem Authentifizierungsschlüssel und der Berechtigung „JOIN_PROGRAM_ACCESS“. Informationen zum Erstellen des JWT finden Sie in der Einführung in die Web-Service-API und Informationen zur Rollenverwaltung im Berechtigungskonzept.
SDKs
Alle „Join“-Endpunkte sind Teil der wallee-Webservice-API, sodass Sie den Onboarding-Prozess mithilfe der offiziellen wallee-SDKs integrieren oder die REST-API direkt aus jeder beliebigen Programmiersprache aufrufen können. Alle SDKs sind Open Source und auf GitHub verfügbar:
| Sprache | Repository | Paketmanager |
|---|---|---|
| PHP | wallee-payment/php-sdk | Composer |
| Java | wallee-payment/java-sdk | Maven |
| TypeScript / JS | wallee-payment/typescript-sdk | npm |
| Python | wallee-payment/python-sdk | pip |
| C# / .NET | wallee-payment/csharp-sdk | NuGet |
| Ruby | wallee-payment/ruby-sdk | RubyGems |
Tipp: Die SDKs übernehmen für Sie die JWT-Authentifizierung, die Signierung von Anfragen sowie die (De-)Serialisierung der Datenmodelle. Informationen zur Installation und einen Schnellstart finden Sie in der README-Datei des jeweiligen Repositorys.
Testen Ihrer Integration
- Nutzen Sie den interaktiven API-Client, um Anfragen und Antworten für Ihr Konto zu erkunden, bevor Sie Code schreiben – suchen Sie nach „partnership“ oder „application“, um die Endpunkte für die Anmeldung zu finden, die vollständigen Anfrage-/Antwortschemas einzusehen und Code-Schnipsel zu generieren. Vom Client gesendete Anfragen sind Live-Anfragen.
- Richten Sie Webhook-Listener ein, um Änderungen des Onboarding- und Transaktionsstatus in Ihrer Plattform zu empfangen.
Fehlerbehandlung
Die APIs verwenden Standard-HTTP-Statuscodes:
| Code | Bedeutung |
|---|---|
| 200 | Anfrage erfolgreich |
| 201 | Ressource erstellt |
| 204 | Ressource gelöscht (kein Inhalt) |
| 400 | Ungültige Anfrage – fehlende oder ungültige Felder, ungültige Konfiguration |
| 401 | Authentifizierung fehlgeschlagen – JWT und Anwendungsbenutzer überprüfen |
| 403 | Fehlende Berechtigung (JOIN_PROGRAM_ACCESS) |
| 404 | Ressource nicht gefunden |
| 409 | Konflikt – z. B. die Ressource existiert bereits |
| 500 | Unerwarteter Serverfehler |
Fehlerantworten enthalten einen maschinenlesbaren Fehlertyp und eine für Menschen lesbare Meldung, in der das ungültige Feld oder die ungültige Bedingung angegeben ist.
Webhooks
Bei ereignisgesteuerten Integrationen sollten Sie sich für Webhooks anmelden, anstatt regelmässig Abfragen durchzuführen – z. B., um benachrichtigt zu werden, wenn sich der Status einer Händleranwendung ändert oder eine Partnerschaft aktiv wird.
Ressourcen für Entwickler
- Entwicklerdokumentation – Space-Konzept, Berechtigungskonzept, Integrationsmodi
- Webservice-API-Referenz
- Datenmodelle
- SDK-Übersicht auf GitHub