Clienti

Crea il cliente prima di costruire un pay-in, un payout o un conto bancario emesso. Capability, conti e transfer hanno come scope quel cliente. Usa externalId come mapping stabile verso il record corrispondente nel tuo sistema.

Environment variables

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

Clienti individuali

Un individuo richiede solo type. Includi i campi del profilo che già conosci e aggiungine altri solo quando la capability o il task corrente ne ha bisogno. Crea il cliente con POST /v3/customers:

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

Salva il data.id restituito come CUSTOMER_ID. Consulta Onboarding individuale per il contesto di policy.

Clienti business

Un business richiede business.legalName. Crea il business con la stessa operazione:

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

Salva il data.id restituito come CUSTOMER_ID. Consulta Onboarding business per il contesto di policy e documenti. Aggiungi director, owner e altri partecipanti aziendali quando sono noti o richiesti. Questo esempio crea un director con POST /v3/customers/{customerId}/related-parties:

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

Salva il data.id restituito come RELATED_PARTY_ID. Se devi esportare un cliente, usa POST /v3/customers/{customerId}/export e segui lo schema della richiesta. Il formato json_basic_data restituisce la risorsa cliente v3 pubblica corrente come allegato JSON; ogni chiamata ricalcola i dati correnti ed esclude i documenti e i metadati dei documenti. Per un formato con token di portabilità, invia il client ID del progetto KYC ricevente come forClientId, non il customerId Swipelux. Usa il data.token restituito prima di data.expiresAt. Riutilizzare la stessa Idempotency-Key e lo stesso body ripropone quel risultato di token; usa una nuova chiave per emettere un altro token.

Leggi la readiness dalle capability

Un cliente non ha uno stato di verifica o di readiness nell’API. Leggi il cliente con GET /v3/customers/{customerId} per ottenere i dati di profilo correnti, quindi usa le capability e i loro openTaskIds per decidere cosa il cliente può fare successivamente.

Get customer

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

Trovare i clienti con documenti in sospeso

Per sapere quali clienti di una pagina devono ancora fornire documenti obbligatori, passa include=documentRequirements a GET /v3/customers. Puoi combinarlo con i riepiloghi delle capability come include=capabilities,documentRequirements. Le chiavi API richiedono accounts:read per l’espansione documentRequirements. Ogni riepilogo cliente include quindi un oggetto documentRequirements:

Document requirement summary

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

count è il numero di requisiti documentali obbligatori in action_required su task anch’essi in action_required. Copre ogni ambito di task, inclusi i task a livello di account, e non dipende dalla readiness delle capability.
required è true quando count è maggiore di 0.
Un insieme di alternative conta una sola volta, e solo quando ogni alternativa richiede un documento.

Il riepilogo è prudente. Esclude i documenti facoltativi, i documenti obbligatori in base a condizioni e le alternative che combinano percorsi con e senza documenti. Esclude anche i requisiti che il cliente può completare tramite la verifica ospitata. Di conseguenza, required: false non dimostra che non si applichi alcun task documentale. Usalo per dare priorità ai clienti, quindi leggi i loro task per l’elenco autorevole di ciò che devi raccogliere. Senza l’espansione, la risposta omette documentRequirements. Successivamente, prosegui su Capability e task per scoprire e attivare il risultato di prodotto di cui hai bisogno.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

Clienti individuali

Clienti business

Leggi la readiness dalle capability

Trovare i clienti con documenti in sospeso

​Clienti individuali

​Clienti business

​Aggiungi related party del business

​Leggi la readiness dalle capability

​Trovare i clienti con documenti in sospeso

Clienti individuali

Clienti business

Aggiungi related party del business

Leggi la readiness dalle capability

Trovare i clienti con documenti in sospeso