Capacités et tâches

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

​

Découvrir les capacités prises en charge

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

​

Types de comptes mutualisés vs nominatifs

• pooled : compte bancaire Swipelux partagé. Chaque encaissement utilise une référence unique pour acheminer les fonds. Choisissez ceci pour les transferts ponctuels.
• named : coordonnées bancaires dédiées au client (IBAN virtuel, compte ACH dédié). Réutilisables et partageables avec n’importe quel payeur. Requis pour les comptes bancaires émis.

​

Demander la capacité

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

​

Applications partagées par banque

• Une seule approbation peut couvrir plusieurs capacités. Par exemple, un dossier approuvé auprès d’une banque peut rendre ready à la fois une capacité ACH et une capacité Wire.
• Une demande ultérieure qui correspond à un dossier existant le réutilise. Swipelux n’ouvre pas de deuxième application et n’ajoute aucune tâche en double.
• Les dossiers auprès de banques différentes sont indépendants. Un rejet auprès d’une banque n’affecte pas un dossier auprès d’une autre banque.

• 201 signifie que la demande a ouvert un nouveau dossier d’application.
• 200 signifie que la demande a abouti à un dossier d’application que le client possédait déjà, par exemple une demande répétée pour une capacité bancaire que le client détient déjà, ou une demande pour une capacité annulée. Une demande répétée pour card ou stablecoin_transfers renvoie toujours 409 capability_already_exists.
• selectedApplicationId est un champ de premier niveau à côté de data qui contient l’ID du dossier que la demande a sélectionné ou ouvert. Swipelux l’omet lorsque la demande n’a sélectionné aucun dossier. Une relecture idempotente renvoie la même valeur.

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

​

Lister les applications du client

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

• scope : named pour un dossier auprès d’une seule banque, provider_pooled ou platform pour les dossiers sans banque, ou null pour un dossier historique non classé. institution est absent pour les dossiers provider_pooled et platform.
• requestedScope[] : les clés de capacité demandées pour le dossier, chacune avec son premier requestedAt. Les entrées ne sont jamais supprimées.
• coverage[] : les clés de capacité couvertes par l’approbation du dossier, chacune avec grantedAt et source. La couverture enregistre une portée, pas une autorisation. Lisez la capacité pour connaître son statut actuel.
• probes[] : les vérifications de méthode pour les clés de capacité pooled couvertes par le dossier, chacune avec capabilityKey, status et reason. Les clés named ne nécessitent jamais de vérification.
• generation, predecessorApplicationId et supersededByApplicationId : liens de succession. Lorsque supersededByApplicationId est défini, le dossier a été remplacé. Suivez cet ID jusqu’au dossier actuel. La liste applications[] d’une capacité ne contient que les dossiers actuels, donc un dossier remplacé n’apparaît que dans cette liste.

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

​

Compléter les tâches actuelles

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

​

Preuves de profil réutilisées

​

Afficher les exigences

• allowedValues : les valeurs autorisées pour un champ scalaire, ou pour chaque élément d’un champ de type tableau. Soumettez ces valeurs, pas des libellés d’affichage traduits.
• valueSchema : un document JSON Schema Draft 7 autonome qui décrit la forme de la saisie, les propriétés imbriquées, les champs obligatoires et les contraintes structurelles. Les enums sur les objets apparaissent sur la propriété concernée, par exemple valueSchema.items.properties.type.enum pour les identifiants fiscaux. Swipelux applique toujours une validation inter-champs et de revue après la soumission, donc une valeur conforme au schéma peut tout de même être rejetée.
• valueType: "country", ou itemValueType: "country" pour les tableaux : le champ accepte des codes ISO 3166-1 alpha-2 en majuscules. Les propriétés de pays imbriquées dans valueSchema utilisent format: "iso-3166-1-alpha-2". Utilisez une liste de pays standard pour les libellés localisés.

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

​

Actions hébergées

• action.kind: "available" inclut action.url et action.expiresAt (actuellement toujours null). Enregistrez action.url, envoyez-y le client, puis relisez la tâche. Les champs url et expiresAt au niveau de la session contiennent les mêmes valeurs.
• action.kind: "unavailable" signifie qu’aucun lien ne doit être présenté. Les champs url et expiresAt au niveau de la session sont absents. Le status d’une session ne détermine pas à lui seul le type d’action reçu.

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

​

Téléverser des 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}"

​

Réponses 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

​

Prérequis de bénéficiaire effectif pour les entreprises

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

• Créer ou mettre à jour une partie liée qualifiée satisfait l’exigence lors de la même réévaluation et ouvre le travail de profil et de documents propre à ce propriétaire. Consultez Ajouter des parties liées professionnelles.
• Vous pouvez aussi référencer explicitement une partie qualifiée avec une réponse resource_reference portant son relatedPartyId.
• L’exigence reste listée dans la tâche actuelle après avoir été satisfaite. Lorsqu’aucune autre obligation ne reste ouverte, la tâche devient satisfied.
• Archiver la dernière partie qualifiée, ou supprimer les faits qui la qualifiaient, rouvre l’exigence, même après que la tâche est passée à satisfied.

​

Continuer lorsque la capacité est prête

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