Capacitats i tasques

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

​

Descobreix les capacitats suportades

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

​

Tipus de comptes agrupats vs nominatius

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

​

Sol·licita la capacitat

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

​

Sol·licituds compartides per banc

• Una sola aprovació pot cobrir diverses capacitats. Per exemple, un expedient aprovat en un banc pot fer que tant una capacitat ACH com una de wire passin a ready.
• Una sol·licitud posterior que coincideixi amb un expedient existent el reutilitza. Swipelux no obre una segona sol·licitud ni afegeix tasques duplicades.
• Els expedients de bancs diferents són independents. Un rebuig en un banc no afecta un expedient en un altre banc.

• 201 significa que la petició ha obert un expedient de sol·licitud nou.
• 200 significa que la petició s’ha resolt en un expedient de sol·licitud que el client ja tenia, per exemple una petició repetida d’una capacitat bancària que el client ja té, o una petició d’una capacitat cancel·lada. Una petició repetida de card o stablecoin_transfers continua retornant 409 capability_already_exists.
• selectedApplicationId és un camp de nivell superior al costat de data amb l’ID de l’expedient que la petició ha seleccionat o obert. Swipelux l’omet quan la petició no ha seleccionat cap expedient. Una repetició idempotent retorna el mateix valor.

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

​

Llista les sol·licituds del client

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

• scope: named per a un expedient en un sol banc, provider_pooled o platform per a expedients sense banc, o null per a un expedient històric sense classificar. institution no hi és en els expedients provider_pooled i platform.
• requestedScope[]: les claus de capacitat sol·licitades per a l’expedient, cadascuna amb el seu primer requestedAt. Les entrades no s’eliminen mai.
• coverage[]: les claus de capacitat que cobreix l’aprovació de l’expedient, cadascuna amb grantedAt i source. La cobertura registra l’abast, no l’autorització. Llegeix la capacitat per conèixer-ne l’estat actual.
• probes[]: comprovacions de mètode per a les claus de capacitat agrupades que cobreix l’expedient, cadascuna amb capabilityKey, status i reason. Les claus nominatives no requereixen mai cap comprovació.
• generation, predecessorApplicationId i supersededByApplicationId: enllaços de successió. Quan supersededByApplicationId està definit, l’expedient s’ha substituït. Segueix aquest ID fins a l’expedient actual. La llista applications[] d’una capacitat només inclou els expedients actuals, de manera que un expedient substituït només apareix en aquesta llista.

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

​

Completa les tasques actuals

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

​

Evidències del perfil reutilitzades

​

Mostra els requisits

• allowedValues: els valors permesos per a un camp escalar, o per a cada element d’un camp de matriu. Envia aquests valors, no etiquetes de visualització traduïdes.
• valueSchema: un document JSON Schema Draft 7 autònom que descriu la forma de l’entrada, les propietats niades, els camps obligatoris i les restriccions estructurals. Els enums dels objectes apareixen a la propietat corresponent, per exemple valueSchema.items.properties.type.enum per als identificadors fiscals. Swipelux continua aplicant validacions entre camps i de revisió després de l’enviament, així que un valor que superi l’esquema encara pot ser rebutjat.
• valueType: "country", o itemValueType: "country" per a les matrius: el camp accepta codis ISO 3166-1 alpha-2 en majúscules. Les propietats de país niades a valueSchema utilitzen format: "iso-3166-1-alpha-2". Utilitza una llista de països estàndard per a les etiquetes localitzades.

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

​

Accions allotjades

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

​

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

​

Respostes via API

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

​

Prerequisit de propietari beneficiari per a negocis

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

• 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

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