Capability e task

Una capability ti indica se un cliente puo’ usare uno specifico risultato, metodo di pagamento e direzione. I task aperti indicano cosa deve accadere prima che quella capability o una risorsa correlata possa procedere.

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

Scopri le capability supportate

Leggi le opzioni correnti del cliente con GET /v3/customers/{customerId}/capabilities/supported:

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

Scegli una voce della risposta che corrisponda a directions, method e accountType desiderati. Prosegui solo quando availability e’ available o beta e eligibility.eligible e’ true. Se vengono restituite institutions, seleziona solo un ID da quella risposta. Salva il data[].id selezionato come CAPABILITY_ID. Non copiare mai un ID di capability da un altro cliente o ambiente.

Tipi di conto pooled vs named

Le capability bancarie sono disponibili in due varianti, codificate nel campo accountType e nel suffisso dell’ID capability (ad esempio ach_pooled, wire_named):

pooled: conto bancario Swipelux condiviso. Ogni pay-in usa un riferimento univoco per instradare i fondi. Scegli questa opzione per trasferimenti una tantum.
named: coordinate bancarie dedicate al cliente (IBAN virtuale, conto ACH dedicato). Riutilizzabili e condivisibili con qualsiasi pagante. Richieste per i conti bancari emessi.

Predefinito su pooled. Usa named solo quando il cliente ha bisogno di coordinate bancarie riutilizzabili. Controlla la risposta supported per vedere quali varianti sono disponibili.

Richiedi la capability

Richiedi l’opzione selezionata con POST /v3/customers/{customerId}/capabilities/{capabilityId}:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: capability-request-001" \
  --header "Content-Type: application/json" \
  --data '{}'

Usa un array institutions esplicito solo quando devi scegliere tra gli ID restituiti dalla risposta supported-capability. Salva data.status come CAPABILITY_STATUS, data.openTaskIds come OPEN_TASK_IDS e ogni data.applications[].id in APPLICATION_IDS.

Completa i task correnti

Elenca i task con GET /v3/customers/{customerId}/tasks, seleziona gli ID da OPEN_TASK_IDS, quindi leggi ciascun task corrente con GET /v3/customers/{customerId}/tasks/{taskId}:

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

Usa gli ultimi data.revision e data.requirements. Rileggi il task immediatamente prima di inviare se uno dei due potrebbe essere cambiato. Ogni task aperto include un timestamp dueAt. Quando Swipelux crea un task senza una data di scadenza esplicita, dueAt è impostato per impostazione predefinita esattamente a 31 giorni dopo il createdAt del task. Considera dueAt come informativo: non puoi impostarlo tramite l’API e non attiva alcuna transizione automatica del ciclo di vita. Solo il campo separato deadline, quando presente, causa una transizione automatica.

Azioni hosted

Nella risposta di dettaglio del task, ogni voce di verificationSessions e tosSessions include un oggetto action. Le risposte dell’elenco dei task non includono questi link di azione. Memorizza l’id di ogni sessione, quindi leggi action.kind prima di inoltrare il cliente; non dedurre la disponibilità del link dallo status della sessione.

action.kind: "available" include action.url e action.expiresAt (attualmente sempre null). Memorizza action.url, invia lì il cliente e poi rileggi il task. I campi url e expiresAt a livello di sessione contengono gli stessi valori.
action.kind: "unavailable" significa che non deve essere presentato alcun link. I campi url e expiresAt a livello di sessione sono assenti. Lo status di una sessione da solo non determina quale tipo di azione riceverai.

{
  "data": {
    "verificationSessions": [
      {
        "id": "vfy_000000000000000003",
        "key": "identity_verification",
        "type": "identity_verification",
        "status": "action_required",
        "action": {
          "kind": "available",
          "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
          "expiresAt": null
        },
        "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
        "expiresAt": null
      }
    ],
    "tosSessions": [
      {
        "id": "vfy_000000000000000004",
        "key": "terms_of_service",
        "type": "terms_of_service",
        "status": "completed",
        "action": { "kind": "unavailable" }
      }
    ]
  }
}

Queste sono azioni con scope di task, non un ciclo di vita separato di verifica cliente.

Carica documenti

Quando un requisito richiede un documento, caricalo con POST /v3/customers/{customerId}/documents:

export DOCUMENT_PATH='/absolute/path/to/requested-document.pdf'

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/documents" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-document-001" \
  --form "file=@${DOCUMENT_PATH}"

Salva il data.id restituito come DOCUMENT_ID prima di inviare la risposta che lo referenzia.

Risposte via API

Invia un set completo di risposte per la revisione corrente con POST /v3/customers/{customerId}/tasks/{taskId}/submissions:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "taskRevision": 3,
  "answers": [
    {
      "requirementId": "req_from_current_task",
      "answer": {
        "type": "text",
        "value": "Current answer"
      }
    }
  ]
}
JSON

Prendi ogni ID requisito e tipo di risposta dall’ultimo task. Se l’API segnala che il task e’ cambiato, rileggilo e ricostruisci la submission dalla nuova revisione.

Prerequisito del beneficial owner per i business

Richiedere una capability business che necessita di evidenze di beneficial owner riesce anche quando il cliente non ha ancora un proprietario qualificante. La capability viene creata come restricted con statusReason.code: tasks_due, e il task di intake business richiede i fatti di ownership mancanti, inclusa la struttura di ownership. Lo stesso task contiene un requisito resource_reference la cui richiesta include qualification: "beneficial_owner":

{
  "type": "resource_reference",
  "prompt": "Add or select a qualifying beneficial owner.",
  "required": true,
  "resourceType": "related_party",
  "qualification": "beneficial_owner"
}

Un related party si qualifica quando e’ un party person attivo dello stesso cliente con ownership.declared: true o una percentuale di ownership fornita di almeno 25. Il requisito e’ derivato dall’elenco corrente dei related party, quindi di solito non gli rispondi direttamente:

Creare o aggiornare un related party qualificante soddisfa il requisito nella stessa rivalutazione e apre il lavoro su profilo e documenti di quel proprietario. Consulta Aggiungi related party del business.
Puoi anche referenziare esplicitamente un party qualificante con una risposta resource_reference che contiene il suo relatedPartyId.
Il requisito resta elencato nel task corrente dopo essere stato soddisfatto. Quando non resta aperto nessun altro obbligo, il task diventa satisfied.
Archiviare l’ultimo party qualificante, o rimuovere i fatti che lo qualificavano, riapre il requisito, anche dopo che il task era satisfied.

Prosegui quando la capability e’ ready

Rileggi la capability con GET /v3/customers/{customerId}/capabilities/{capabilityId}:

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

Sostituisci lo status e gli ID task memorizzati con l’ultima risposta. Prosegui solo quando lo status corrente della capability consente il conto, quote o transfer che intendi creare. Successivamente, scegli il percorso corrispondente in Flussi comuni.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

Capability e task

Scopri le capability supportate

Tipi di conto pooled vs named

Richiedi la capability

Completa i task correnti

Azioni hosted

Carica documenti

Risposte via API

Prerequisito del beneficial owner per i business

Prosegui quando la capability e’ ready

​Scopri le capability supportate

​Tipi di conto pooled vs named

​Richiedi la capability

​Completa i task correnti

​Azioni hosted

​Carica documenti

​Risposte via API

​Prerequisito del beneficial owner per i business

​Prosegui quando la capability e’ ready

Scopri le capability supportate

Tipi di conto pooled vs named

Richiedi la capability

Completa i task correnti

Azioni hosted

Carica documenti

Risposte via API

Prerequisito del beneficial owner per i business

Prosegui quando la capability e’ ready