Kunden

Legen Sie den Kunden an, bevor Sie ein Pay-in, einen Payout oder ein ausgegebenes Bankkonto aufbauen. Fähigkeiten, Konten und Transfers sind auf diesen Kunden bezogen. Verwenden Sie externalId als stabile Zuordnung zum entsprechenden Datensatz in Ihrem System.

Environment variables

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

Einzelpersonen-Kunden

Eine Einzelperson benötigt nur type. Fügen Sie Profildaten hinzu, die Sie bereits kennen, und ergänzen Sie weitere nur, wenn die aktuelle Fähigkeit oder Aufgabe sie erfordert. Legen Sie den Kunden mit POST /v3/customers an:

Create individual customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-user-123" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "individual",
  "externalId": "user_123",
  "individual": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

Speichern Sie die zurückgegebene data.id als CUSTOMER_ID. Siehe Onboarding von Einzelpersonen für den Richtlinienkontext.

Unternehmens-Kunden

Ein Unternehmen benötigt business.legalName. Legen Sie das Unternehmen mit derselben Operation an:

Create business customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-company-456" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "business",
  "externalId": "company_456",
  "business": {
    "legalName": "Acme Payments SAS"
  }
}
JSON

Speichern Sie die zurückgegebene data.id als CUSTOMER_ID. Siehe Unternehmens-Onboarding für Richtlinien- und Dokumentenkontext. Fügen Sie Direktoren, Eigentümer und andere Unternehmensbeteiligte hinzu, wenn sie bekannt oder angefordert sind. Dieses Beispiel legt einen Direktor mit POST /v3/customers/{customerId}/related-parties an:

Add related party

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/related-parties" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: related-party-director-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "partyType": "person",
  "roles": ["director"],
  "title": "Chief executive officer",
  "person": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

Speichern Sie die zurückgegebene data.id als RELATED_PARTY_ID. Wenn Sie einen Kunden exportieren müssen, verwenden Sie POST /v3/customers/{customerId}/export und folgen Sie dessen Request-Schema. Das Format json_basic_data gibt die aktuelle öffentliche v3-Kundenressource als JSON-Anhang zurück; jeder Aufruf berechnet die aktuellen Daten neu und schließt Dokumente sowie Dokumentmetadaten aus. Für ein Portabilitäts-Token-Format senden Sie die Client-ID des empfangenden KYC-Projekts als forClientId, nicht die Swipelux-customerId. Verwenden Sie das zurückgegebene data.token vor data.expiresAt. Die Wiederverwendung desselben Idempotency-Key und Bodys spielt dieses Token-Ergebnis erneut ab; verwenden Sie einen neuen Schlüssel, um ein weiteres Token auszustellen.

Bereitschaft aus Fähigkeiten lesen

Ein Kunde hat in der API keinen Verifizierungs- oder Bereitschaftsstatus. Lesen Sie den Kunden mit GET /v3/customers/{customerId} für aktuelle Profildaten und verwenden Sie dann Fähigkeiten und deren openTaskIds, um zu entscheiden, was der Kunde als Nächstes tun kann.

Get customer

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Kunden mit ausstehenden Dokumenten finden

Um herauszufinden, welche Kunden auf einer Seite noch Pflichtdokumente schulden, übergeben Sie include=documentRequirements an GET /v3/customers. Sie können es mit Fähigkeitszusammenfassungen als include=capabilities,documentRequirements kombinieren. API-Schlüssel benötigen accounts:read für die Erweiterung documentRequirements. Jede Kundenzusammenfassung enthält dann ein documentRequirements-Objekt:

Document requirement summary

{
  "documentRequirements": {
    "required": true,
    "count": 2
  }
}

count ist die Anzahl der Pflichtdokumentanforderungen im Status action_required bei Aufgaben, die ebenfalls im Status action_required sind. Sie umfasst alle Aufgabenbereiche, einschließlich kontoweiter Aufgaben, und hängt nicht von der Bereitschaft der Fähigkeiten ab.
required ist true, wenn count größer als 0 ist.
Eine Gruppe von Alternativen zählt einmal, und nur dann, wenn jede Alternative ein Dokument erfordert.

Die Zusammenfassung ist konservativ. Sie schließt optionale Dokumente, bedingt erforderliche Dokumente und Alternativen aus, die Dokument- und Nicht-Dokument-Wege mischen. Sie schließt auch Anforderungen aus, die der Kunde über die gehostete Verifizierung erfüllen kann. Daher beweist required: false nicht, dass keine Dokumentaufgabe zutrifft. Verwenden Sie sie, um Kunden zu priorisieren, und lesen Sie dann deren Aufgaben für die maßgebliche Liste dessen, was zu erfassen ist. Ohne die Erweiterung lässt die Antwort documentRequirements weg. Fahren Sie als Nächstes mit Fähigkeiten und Aufgaben fort, um das benötigte Produktergebnis zu entdecken und zu aktivieren.

Erste Schritte

Kunden onboarden

Geldflüsse aufbauen

Livegang

Einzelpersonen-Kunden

Unternehmens-Kunden

Bereitschaft aus Fähigkeiten lesen

Kunden mit ausstehenden Dokumenten finden

​Einzelpersonen-Kunden

​Unternehmens-Kunden

​Verbundene Parteien für Unternehmen hinzufügen

​Bereitschaft aus Fähigkeiten lesen

​Kunden mit ausstehenden Dokumenten finden

Einzelpersonen-Kunden

Unternehmens-Kunden

Verbundene Parteien für Unternehmen hinzufügen

Bereitschaft aus Fähigkeiten lesen

Kunden mit ausstehenden Dokumenten finden