Capabilities en tasks

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

​

Ontdek ondersteunde capabilities

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

{
  "institutions": [
    {
      "id": "jpmorgan",
      "name": "JPMorgan Chase",
      "bic": "CHASUS33",
      "logoUrl": "https://wallet.swipelux.com/bank-logos/jpmorgan.png",
      "countries": ["US"],
      "isDefault": true
    }
  ]
}

​

Pooled vs named accounttypes

• 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.

​

Vraag de capability aan

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 '{}'

​

Gedeelde applications per bank

• Eén goedkeuring kan meerdere capabilities dekken. Een goedgekeurde case bij één bank kan bijvoorbeeld zowel een ACH- als een wire-capability ready maken.
• Een later verzoek dat overeenkomt met een bestaande case, hergebruikt die. Swipelux opent geen tweede application en voegt geen dubbele taken toe.
• Cases bij verschillende banken zijn onafhankelijk. Een afwijzing bij één bank heeft geen invloed op een case bij een andere bank.

• 201 betekent dat het verzoek een nieuwe application-case heeft geopend.
• 200 betekent dat het verzoek is uitgekomen bij een application-case die de klant al had, bijvoorbeeld een herhaald verzoek voor een bank-capability die de klant al heeft, of een verzoek voor een geannuleerde capability. Een herhaald verzoek voor card of stablecoin_transfers retourneert nog steeds 409 capability_already_exists.
• selectedApplicationId is een top-level veld naast data met de ID van de case die het verzoek heeft geselecteerd of geopend. Swipelux laat het weg wanneer het verzoek geen case heeft geselecteerd. Een idempotente replay retourneert dezelfde waarde.

{
  "data": {
    "id": "ach_named",
    "status": "pending",
    "openTaskIds": ["tsk_000000000000000002"],
    "applications": [{ "id": "apl_000000000000000005", "status": "in_review" }]
  },
  "selectedApplicationId": "apl_000000000000000005"
}

​

Bekijk de applications van de klant

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

• scope: named voor een case bij één bank, provider_pooled of platform voor cases zonder bank, of null voor een niet-geclassificeerde historische case. institution ontbreekt bij provider_pooled- en platform-cases.
• requestedScope[]: de capability-keys die voor de case zijn aangevraagd, elk met de eerste requestedAt. Entries worden nooit verwijderd.
• coverage[]: de capability-keys die de goedkeuring van de case dekt, elk met grantedAt en source. Coverage legt scope vast, geen autorisatie. Lees de capability voor de huidige status.
• probes[]: methodecontroles voor de pooled capability-keys die de case dekt, elk met capabilityKey, status en reason. Named keys vereisen nooit een probe.
• generation, predecessorApplicationId en supersededByApplicationId: opvolgingslinks. Wanneer supersededByApplicationId is ingesteld, is de case vervangen. Volg die ID naar de huidige case. De applications[] van een capability bevat alleen huidige cases, dus een vervangen case verschijnt alleen in deze lijst.

{
  "data": [
    {
      "id": "apl_000000000000000005",
      "status": "ready",
      "scope": "named",
      "institution": { "id": "jpmorgan", "name": "JPMorgan Chase", "bic": "CHASUS33" },
      "requestedScope": [
        { "capabilityKey": "ach_named", "requestedAt": "2026-09-20T10:00:00.000Z" }
      ],
      "coverage": [
        { "capabilityKey": "ach_named", "grantedAt": "2026-09-22T12:00:00.000Z", "source": "approval" },
        { "capabilityKey": "wire_named", "grantedAt": "2026-09-22T12:00:00.000Z", "source": "approval" }
      ],
      "probes": [],
      "generation": 1,
      "predecessorApplicationId": null,
      "supersededByApplicationId": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

​

Voltooi huidige taken

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

​

Hergebruikt profielbewijs

​

Vereisten renderen

• allowedValues: de toegestane waarden voor een scalair veld, of voor elk item van een arrayveld. Dien deze waarden in, niet vertaalde weergavelabels.
• valueSchema: een zelfstandig JSON Schema Draft 7-document dat de invoervorm, geneste properties, verplichte velden en structurele beperkingen beschrijft. Enums op objecten staan op de relevante property, bijvoorbeeld valueSchema.items.properties.type.enum voor fiscale identificatiecodes. Swipelux past na indiening nog steeds veldoverschrijdende validatie en reviewvalidatie toe, dus een waarde die het schema doorstaat, kan nog steeds worden afgewezen.
• valueType: "country", of itemValueType: "country" voor arrays: het veld accepteert ISO 3166-1 alpha-2-codes in hoofdletters. Geneste landproperties in valueSchema gebruiken format: "iso-3166-1-alpha-2". Gebruik een standaard landenlijst voor gelokaliseerde labels.

{
  "id": "req_000000000000000010",
  "key": "account_purposes",
  "title": "Account purpose",
  "status": "action_required",
  "request": {
    "type": "profile",
    "prompt": "Select every purpose that applies.",
    "required": true,
    "profilePointer": "/financialProfile/accountPurposes",
    "valueType": "array",
    "itemValueType": "string",
    "allowedValues": ["business_expenses", "ecommerce", "payroll"],
    "valueSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "array",
      "items": { "enum": ["business_expenses", "ecommerce", "payroll"] }
    }
  }
}

​

Gehoste acties

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

​

Documenten uploaden

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

​

API-antwoorden

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

​

UBO-voorwaarde voor bedrijven

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

• 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

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