Zum Hauptinhalt springen

Onboarding über die API

Der gesamte Onboarding-Prozess für Händler kann über die wallee Web Service API (v2.0) abgewickelt werden – ideal, wenn Sie bereits über die Unternehmensdaten Ihrer Kunden verfügen und den Onboarding-Prozess nahtlos in Ihre Plattform integrieren möchten.

Voraussetzungen: Ein Anwendungsbenutzer mit einem Authentifizierungsschlüssel und der Berechtigung „JOIN_PROGRAM_ACCESS“. Alle Join-Endpunkte erwarten Ihre Konto-ID im Konto-Header. Informationen zur Authentifizierung (JWT), zu Headern und zur Fehlerbehandlung finden Sie in der API-Referenz.

Ablaufübersicht​

  1. Richten Sie eine Partnerschaft für den Händler ein (Affiliate, ISV oder bestehendes Konto).
  2. Erstellen Sie einen Händlerantrag und reichen Sie die Ihnen bereits vorliegenden KYC-Daten ein.
  3. Leiten Sie den Antrag über die Einreichungs-URL an den Händler weiter, damit dieser ihn prüfen und rechtlich bestätigen kann.
  4. Verfolgen Sie den Status des Antrags, bis das Konto aktiv ist.
sequenceDiagram
    autonumber
    participant P as Your platform
    participant W as wallee
    participant M as Merchant

    P->>W: POST /join-program/partnerships/create-…
    W-->>P: Partnership created
    P->>W: POST /onboarding/merchant-applications
    W-->>P: Application created (draft)
    P->>W: PATCH /merchant-applications/{id} (prefill KYC data)
    P->>W: GET /merchant-applications/{id}/submission-url
    W-->>P: Hosted submission URL
    P->>M: Redirect merchant to submission URL
    M->>W: Review & legally confirm application
    Note over W: KYC / AML checks by wallee
    W-->>P: Status update (GET /status or webhook)
    Note over P,W: Merchant account active

1. Eine Partnerschaft aufbauen​

ModellEndpunkt
Konto anlegen (Partner)POST /api/v2.0/join-program/partnerships/create-affiliate
Plattform beitreten (ISV)POST /api/v2.0/join-program/partnerships/create-isv
Bestehendes wallee-KontoPOST /api/v2.0/join-program/partnerships/create-simple

Beispiel – Aufbau einer Affiliate-Partnerschaft:

curl -X POST "https://app-wallee.com/api/v2.0/join-program/partnerships/create-affiliate" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantEmailAddress": "merchant@example.com",
    "pricingProfileSellRateId": 123,
    "subscriptionProductId": 456,
    "emailMessage": "Optional personal message"
  }'

Das Preisprofil und die Abonnement-Produkt-IDs stammen aus Ihrer Partnerkonfiguration. Sie können diesen Endpunkt im interaktiven API-Client ausprobieren.

Was als Nächstes passiert, hängt vom jeweiligen Modell ab:​

  • Affiliate – Der Händler erhält eine E-Mail mit der Schaltfläche „Am Programm teilnehmen“ und durchläuft den wallee-Anmeldevorgang. Die Partnerschaft wird während dieser Anmeldung begründet und nach Abschluss der Anmeldung bestätigt.
  • ISV – Die Partnerschaft und das Unterkonto (mit einem Space) werden sofort angelegt. Der Händler wird als Nutzer des neuen Unterkontos eingeladen und erhält eine Bestätigungs-E-Mail, sobald er die Einladung angenommen hat.

Alle CRUD-Operationen für Partnerschaften (Auflisten, Abrufen, Suchen, Aktualisieren, Löschen) sind in der Partnerschafts-API-Referenz dokumentiert.

2. KYC-Daten übermitteln (Händlerantrag)​

Erstellen Sie einen Händlerantrag – entweder als leeren Entwurf oder direkt mit allen erforderlichen Angaben (Unternehmensdaten, Rechtsform, wirtschaftliche Eigentümer usw.):

curl -X POST "https://app-wallee.com/api/v2.0/onboarding/merchant-applications" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ ...merchant application data... }'

Sie können einen Antrag jederzeit aktualisieren, solange er sich noch im Entwurfsstadium befindet:

curl -X PATCH "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ ...updated fields... }'

Da Sie den Antrag vorab ausfüllen, müssen Ihre Kunden Daten, die Ihnen bereits vorliegen, nicht erneut eingeben. wallee führt im Hintergrund die vollständigen KYC-/AML- und PSD2-Konformitätsprüfungen durch. Die Anträge sind in Schritte unterteilt (Unternehmensdaten, wirtschaftliche Eigentümer usw.), die auch einzeln aktualisiert werden können – siehe die API-Referenz für Händleranträge.

3. Übergabe an den Händler​

Der Händler muss den Antrag selbst prüfen und rechtsgültig bestätigen. Rufen Sie die URL für die gehostete Übermittlung ab und stellen Sie diese Ihrem Kunden zur Verfügung (z. B. per Weiterleitung oder eingebettetem Link):

curl "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}/submission-url" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>"

4. Status verfolgen​

curl "https://app-wallee.com/api/v2.0/onboarding/merchant-applications/{id}/status" \
  -H "Authorization: Bearer <JWT>" \
  -H "account: <YOUR_ACCOUNT_ID>"

Verwenden Sie bei ereignisgesteuerten Integrationen Webhooks, um über Statusänderungen benachrichtigt zu werden, anstatt eine Abfrage durchzuführen.

Literaturverzeichnis​