Capacitats i tasques

Una capacitat t’indica si un client pot utilitzar un resultat, mètode de pagament i direcció específics. Les tasques obertes t’indiquen què ha de passar abans que aquesta capacitat o un recurs relacionat puguin avançar.

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

Descobreix les capacitats suportades

Llegeix les opcions actuals del client amb GET /v3/customers/{customerId}/capabilities/supported:

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

Escull una entrada de resposta que coincideixi amb els directions, method i accountType previstos. Continua només quan availability sigui available o beta i eligibility.eligible sigui true. Si es retornen institutions, selecciona només un ID d’aquesta resposta. Emmagatzema el data[].id seleccionat com a CAPABILITY_ID. No copiïs mai un ID de capacitat d’un altre client o entorn.

Tipus de comptes agrupats vs nominatius

Les capacitats bancàries venen en dues variants, codificades al camp accountType i al sufix de l’ID de capacitat (per exemple ach_pooled, wire_named):

pooled: compte bancari compartit de Swipelux. Cada cobrament utilitza una referència única per encaminar els fons. Escull aquest per a transferències d’un sol ús.
named: dades bancàries dedicades per al client (IBAN virtual, compte ACH dedicat). Reutilitzables i compartibles amb qualsevol pagador. Necessari per als comptes bancaris emesos.

Per defecte, utilitza pooled. Utilitza named només quan el client necessiti dades bancàries reutilitzables. Consulta la resposta supported per veure quines variants estan disponibles.

Sol·licita la capacitat

Sol·licita l’opció seleccionada amb 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 '{}'

Utilitza una matriu institutions explícita només quan necessitis seleccionar entre els IDs retornats per la resposta de capacitats suportades. Emmagatzema data.status com a CAPABILITY_STATUS, data.openTaskIds com a OPEN_TASK_IDS i cada data.applications[].id a APPLICATION_IDS.

Completa les tasques actuals

Llista les tasques amb GET /v3/customers/{customerId}/tasks, selecciona els IDs de OPEN_TASK_IDS i, a continuació, llegeix cada tasca actual amb 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}"

Utilitza els data.revision i data.requirements més recents. Torna a obtenir la tasca immediatament abans d’enviar-la si qualsevol dels dos pot haver canviat. Cada tasca oberta inclou una marca de temps dueAt. Quan Swipelux crea una tasca sense una data de venciment explícita, dueAt és per defecte exactament 31 dies després del createdAt de la tasca. Tracta dueAt com a informatiu: no el pots definir mitjançant l’API i no provoca cap transició automàtica del cicle de vida. Només el camp separat deadline, quan és present, provoca una transició automàtica.

Accions allotjades

A la resposta de detall de la tasca, cada entrada de verificationSessions i tosSessions inclou un objecte action. Les respostes de la llista de tasques no inclouen aquests enllaços d’acció. Desa l’id de cada sessió i llegeix action.kind abans d’enviar el client; no dedueixis la disponibilitat de l’enllaç a partir del status de la sessió.

action.kind: "available" inclou action.url i action.expiresAt (actualment sempre null). Desa action.url, envia-hi el client i torna a llegir la tasca. Els camps url i expiresAt de la sessió contenen els mateixos valors.
action.kind: "unavailable" significa que no s’ha de presentar cap enllaç. Els camps url i expiresAt de la sessió no hi són. El status d’una sessió, per si sol, no determina quin tipus d’acció rebràs.

{
  "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" }
      }
    ]
  }
}

Aquestes són accions amb àmbit de tasca, no un cicle de vida separat de verificació del client.

Puja documents

Quan un requisit sol·licita un document, puja’l amb 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}"

Emmagatzema el data.id retornat com a DOCUMENT_ID abans d’enviar la resposta que hi fa referència.

Respostes via API

Envia un conjunt complet de respostes per a la revisió actual amb 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

Extreu cada ID de requisit i tipus de resposta de la tasca més recent. Si l’API informa que la tasca ha canviat, torna a obtenir-la i reconstrueix l’enviament a partir de la nova revisió.

Prerequisit de propietari beneficiari per a negocis

Sol·licitar una capacitat de negoci que necessita proves de propietari beneficiari té èxit encara que el client encara no tingui cap propietari qualificat. La capacitat es crea com a restricted amb statusReason.code: tasks_due, i la tasca d’admissió del negoci sol·licita els fets de propietat que falten, inclosa l’estructura de propietat. La mateixa tasca conté un requisit resource_reference la sol·licitud del qual inclou qualification: "beneficial_owner":

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

Una part relacionada es qualifica quan és una part person activa del mateix client amb ownership.declared: true o un percentatge de propietat proporcionat d’almenys 25. El requisit es deriva de la llista actual de parts relacionades, per la qual cosa normalment no el respons directament:

Crear o actualitzar una part relacionada qualificada satisfà el requisit en la mateixa reavaluació i obre el treball de perfil i documents propi d’aquest propietari. Consulta Afegeix parts relacionades del negoci.
També pots fer referència explícita a una part qualificada amb una resposta resource_reference que porti el seu relatedPartyId.
El requisit continua llistat a la tasca actual després de complir-se. Quan no queda cap altra obligació oberta, la tasca esdevé satisfied.
Arxivar l’última part qualificada, o eliminar els fets que la qualificaven, torna a obrir el requisit, fins i tot després que la tasca hagi estat satisfied.

Continua quan la capacitat estigui preparada

Torna a llegir la capacitat amb 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}"

Reemplaça l’estat emmagatzemat i els IDs de tasques amb la resposta més recent. Continua només quan l’estat actual de la capacitat permeti el compte, la cotització o la transferència que vulguis crear. A continuació, escull el recorregut corresponent a Fluxos comuns.

Comença aquí

Incorpora clients

Construeix fluxos de diners

Llança

Capacitats i tasques

Descobreix les capacitats suportades

Tipus de comptes agrupats vs nominatius

Sol·licita la capacitat

Completa les tasques actuals

Accions allotjades

Puja documents

Respostes via API

Prerequisit de propietari beneficiari per a negocis

Continua quan la capacitat estigui preparada

​Descobreix les capacitats suportades

​Tipus de comptes agrupats vs nominatius

​Sol·licita la capacitat

​Completa les tasques actuals

​Accions allotjades

​Puja documents

​Respostes via API

​Prerequisit de propietari beneficiari per a negocis

​Continua quan la capacitat estigui preparada

Descobreix les capacitats suportades

Tipus de comptes agrupats vs nominatius

Sol·licita la capacitat

Completa les tasques actuals

Accions allotjades

Puja documents

Respostes via API

Prerequisit de propietari beneficiari per a negocis

Continua quan la capacitat estigui preparada