Capabilities en tasks

Een capability geeft aan of een klant een specifieke uitkomst, betaalmethode en richting kan gebruiken. Open taken vertellen je wat er moet gebeuren voordat die capability of een gerelateerde resource verder kan.

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

Ontdek ondersteunde capabilities

Lees de huidige opties van de klant met GET /v3/customers/{customerId}/capabilities/supported:

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

Kies een response-entry die overeenkomt met de beoogde directions, method en accountType. Ga alleen verder wanneer availability gelijk is aan available of beta en eligibility.eligible gelijk is aan true. Als er institutions worden geretourneerd, selecteer je alleen een ID uit die respons. Bewaar de geselecteerde data[].id als CAPABILITY_ID. Kopieer nooit een capability-ID van een andere klant of omgeving.

Pooled vs named accounttypes

Bank-capabilities komen in twee varianten, gecodeerd in het accountType-veld en de capability-ID-suffix (bijvoorbeeld ach_pooled, wire_named):

pooled: gedeelde Swipelux-bankrekening. Elke pay-in gebruikt een unieke referentie om geld te routeren. Kies dit voor eenmalige transfers.
named: dedicated bankgegevens voor de klant (virtueel IBAN, dedicated ACH-rekening). Herbruikbaar en te delen met elke betaler. Vereist voor uitgegeven bankrekeningen.

Standaard pooled. Gebruik named alleen wanneer de klant herbruikbare bankgegevens nodig heeft. Controleer de supported-response voor welke varianten beschikbaar zijn.

Vraag de capability aan

Vraag de geselecteerde optie aan met 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 '{}'

Gebruik alleen een expliciete institutions-array wanneer je moet kiezen uit ID’s die de supported-capability-respons heeft geretourneerd. Bewaar data.status als CAPABILITY_STATUS, data.openTaskIds als OPEN_TASK_IDS en elke data.applications[].id in APPLICATION_IDS.

Voltooi huidige taken

Bekijk taken met GET /v3/customers/{customerId}/tasks, selecteer ID’s uit OPEN_TASK_IDS en lees elke huidige taak met 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}"

Gebruik de nieuwste data.revision en data.requirements. Refetch de taak direct vóór indiening als een van beide kan zijn gewijzigd. Elke open taak bevat een dueAt-tijdstempel. Wanneer Swipelux een taak aanmaakt zonder expliciete vervaldatum, staat dueAt standaard op precies 31 dagen na de createdAt van de taak. Behandel dueAt als informatief: je kunt het niet via de API instellen en het activeert geen automatische levenscyclusovergang. Alleen het aparte veld deadline veroorzaakt, indien aanwezig, een automatische overgang.

Gehoste acties

In het taakdetailantwoord bevat elke entry in verificationSessions en tosSessions een action-object. Antwoorden met een takenlijst bevatten deze actielinks niet. Sla de id van elke sessie op en lees vervolgens action.kind voordat je de klant doorstuurt; leid de beschikbaarheid van een link niet af uit de status van de sessie.

action.kind: "available" bevat action.url en action.expiresAt (momenteel altijd null). Sla action.url op, stuur de klant ernaartoe en lees de taak daarna opnieuw. De velden url en expiresAt op sessieniveau bevatten dezelfde waarden.
action.kind: "unavailable" betekent dat er geen link mag worden getoond. De velden url en expiresAt op sessieniveau ontbreken. Alleen de status van een sessie bepaalt niet welk actietype je ontvangt.

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

Dit zijn task-scoped acties, geen aparte lifecycle voor klantverificatie.

Documenten uploaden

Wanneer een vereiste om een document vraagt, upload je het met 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}"

Bewaar de geretourneerde data.id als DOCUMENT_ID voordat je het antwoord indient dat ernaar verwijst.

API-antwoorden

Dien één volledige antwoordset in voor de huidige revisie met 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

Neem elke requirement-ID en elk antwoordtype uit de nieuwste taak. Als de API meldt dat de taak is gewijzigd, refetch je hem en bouw je de submission opnieuw op vanuit de nieuwe revisie.

UBO-voorwaarde voor bedrijven

Het aanvragen van een zakelijke capability die UBO-bewijs nodig heeft, slaagt ook wanneer de klant nog geen kwalificerende eigenaar heeft. De capability wordt aangemaakt als restricted met statusReason.code: tasks_due, en de zakelijke intake-taak vraagt de ontbrekende ownership facts op, inclusief de eigendomsstructuur. Dezelfde taak bevat een resource_reference vereiste waarvan het verzoek qualification: "beneficial_owner" bevat:

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

Een related party kwalificeert wanneer die een actieve person party van dezelfde klant is met ownership.declared: true of een opgegeven eigendomspercentage van ten minste 25. De vereiste wordt afgeleid uit het huidige related-party bestand, dus je beantwoordt hem meestal niet direct:

Het aanmaken of bijwerken van een kwalificerende related party voldoet aan de vereiste in dezelfde herevaluatie en opent het eigen profiel- en documentwerk van die eigenaar. Zie Voeg zakelijke related parties toe.
Je kunt ook expliciet naar een kwalificerende party verwijzen met een resource_reference antwoord dat de bijbehorende relatedPartyId bevat.
De vereiste blijft in de huidige taak vermeld nadat eraan is voldaan. Wanneer geen andere verplichting meer openstaat, wordt de taak satisfied.
Het archiveren van de laatste kwalificerende party, of het verwijderen van de facts die hem kwalificeerden, heropent de vereiste, zelfs nadat de taak satisfied was.

Ga verder wanneer de capability ready is

Lees de capability opnieuw met 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}"

Vervang de opgeslagen status en task-ID’s door de nieuwste respons. Ga alleen verder wanneer de huidige capability-status het account, de quote of de transfer die je wilt aanmaken toestaat. Kies vervolgens de bijpassende journey in Common flows.

Aan de slag

Klanten onboarden

Geldstromen bouwen

Live gaan

Capabilities en tasks

Ontdek ondersteunde capabilities

Pooled vs named accounttypes

Vraag de capability aan

Voltooi huidige taken

Gehoste acties

Documenten uploaden

API-antwoorden

UBO-voorwaarde voor bedrijven

Ga verder wanneer de capability ready is

​Ontdek ondersteunde capabilities

​Pooled vs named accounttypes

​Vraag de capability aan

​Voltooi huidige taken

​Gehoste acties

​Documenten uploaden

​API-antwoorden

​UBO-voorwaarde voor bedrijven

​Ga verder wanneer de capability ready is

Ontdek ondersteunde capabilities

Pooled vs named accounttypes

Vraag de capability aan

Voltooi huidige taken

Gehoste acties

Documenten uploaden

API-antwoorden

UBO-voorwaarde voor bedrijven

Ga verder wanneer de capability ready is