Capabilities a úkoly

Capability vám říká, zda zákazník může využívat konkrétní výsledek, platební metodu a směr. Otevřené úkoly vám říkají, co se musí stát, než capability nebo související zdroj může postoupit.

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

Objevte podporované capabilities

Přečtěte aktuální možnosti zákazníka pomocí GET /v3/customers/{customerId}/capabilities/supported:

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

Vyberte položku odpovědi, která odpovídá zamýšleným directions, method a accountType. Pokračujte jen tehdy, když availability je available nebo beta a eligibility.eligible je true. Pokud jsou vráceny institutions, vyberte pouze ID z této odpovědi. Uložte vybrané data[].id jako CAPABILITY_ID. Nikdy nekopírujte ID capability od jiného zákazníka nebo z jiného prostředí.

Sdružené vs. pojmenované typy účtů

Bankovní capabilities přicházejí ve dvou variantách, kódovaných jako pole accountType a přípona ID capability (například ach_pooled, wire_named):

pooled: sdílený bankovní účet Swipelux. Každá příchozí platba používá unikátní referenci ke směrování prostředků. Zvolte pro jednorázové převody.
named: vyhrazené bankovní údaje pro zákazníka (virtuální IBAN, vyhrazený ACH účet). Opakovaně použitelné a sdílitelné s jakýmkoli plátcem. Vyžadováno pro vydané bankovní účty.

Výchozí volba je pooled. Používejte named pouze tehdy, když zákazník potřebuje opakovaně použitelné bankovní údaje. Zkontrolujte odpověď supported, které varianty jsou k dispozici.

Požádejte o capability

Požádejte o vybranou možnost pomocí 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 '{}'

Explicitní pole institutions používejte pouze tehdy, když potřebujete vybrat z ID vrácených v odpovědi na podporované capabilities. Uložte data.status jako CAPABILITY_STATUS, data.openTaskIds jako OPEN_TASK_IDS a každé data.applications[].id do APPLICATION_IDS.

Dokončete aktuální úkoly

Zjistěte úkoly pomocí GET /v3/customers/{customerId}/tasks, vyberte ID z OPEN_TASK_IDS, poté přečtěte každý aktuální úkol pomocí 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}"

Použijte nejnovější data.revision a data.requirements. Znovu načtěte úkol bezprostředně před odesláním, pokud se některé z nich mohlo změnit. Každý otevřený úkol obsahuje časové razítko dueAt. Když Swipelux vytvoří úkol bez explicitního data splatnosti, nastaví se dueAt výchozím způsobem přesně na 31 dní po createdAt úkolu. Berte dueAt jako informativní: nelze jej nastavit přes API a nespouští žádný automatický přechod životního cyklu. Pouze samostatné pole deadline, pokud je nastaveno, způsobí automatický přechod.

Hostované akce

V odpovědi s detailem úkolu obsahuje každá položka v verificationSessions a tosSessions objekt action. Odpovědi se seznamem úkolů tyto odkazy na akce neobsahují. Uložte id každé relace a před odesláním zákazníka přečtěte action.kind; neodvozujte dostupnost odkazu ze status relace.

action.kind: "available" obsahuje action.url a action.expiresAt (aktuálně vždy null). Uložte action.url, odešlete na něj zákazníka a poté úkol znovu načtěte. Pole url a expiresAt na úrovni relace obsahují stejné hodnoty.
action.kind: "unavailable" znamená, že se nemá zobrazit žádný odkaz. Pole url a expiresAt na úrovni relace chybí. Samotný status relace neurčuje, který druh akce obdržíte.

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

Jde o akce v rozsahu úkolu, nikoli o samostatný životní cyklus ověření zákazníka.

Nahrání dokumentů

Když požadavek vyžaduje dokument, nahrajte jej pomocí 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}"

Uložte vrácené data.id jako DOCUMENT_ID předtím, než odešlete odpověď, která na něj odkazuje.

API odpovědi

Odešlete jednu kompletní sadu odpovědí pro aktuální revizi pomocí 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

Každé ID požadavku a typ odpovědi vezměte z nejnovějšího úkolu. Pokud API oznámí, že se úkol změnil, znovu jej načtěte a rebuildujte odeslání z nové revize.

Předpoklad skutečného majitele pro firmy

Žádost o firemní capability, která potřebuje důkazy o skutečném majiteli, uspěje i tehdy, když zákazník zatím nemá žádného kvalifikujícího se vlastníka. Capability se vytvoří jako restricted s statusReason.code: tasks_due a firemní vstupní úkol si vyžádá chybějící fakta o vlastnictví, včetně vlastnické struktury. Tentýž úkol nese požadavek resource_reference, jehož žádost obsahuje qualification: "beneficial_owner":

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

Související strana se kvalifikuje, když je aktivní stranou typu person téhož zákazníka s ownership.declared: true nebo s poskytnutým procentem vlastnictví alespoň 25. Požadavek je odvozen z aktuálního seznamu souvisejících stran, takže na něj obvykle neodpovídáte přímo:

Vytvoření nebo aktualizace kvalifikující se související strany splní požadavek ve stejném přehodnocení a otevře vlastní profilovou a dokumentovou práci tohoto vlastníka. Viz Přidejte propojené strany firmy.
Na kvalifikující se stranu můžete také explicitně odkázat odpovědí resource_reference, která nese její relatedPartyId.
Požadavek zůstává uveden v aktuálním úkolu i po svém splnění. Když nezůstává otevřená žádná jiná povinnost, úkol se stane satisfied.
Archivace poslední kvalifikující se strany, nebo odstranění faktů, které ji kvalifikovaly, požadavek znovu otevře, a to i poté, co byl úkol satisfied.

Pokračujte, když je capability připravena

Přečtěte capability znovu pomocí 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}"

Nahraďte uložený stav a ID úkolů nejnovější odpovědí. Pokračujte jen tehdy, když aktuální stav capability umožňuje účet, quote nebo převod, který zamýšlíte vytvořit. Dále vyberte odpovídající cestu v Běžných tocích.

Začínáme

Onboarding zákazníků

Vytvořte peněžní toky

Spuštění

Capabilities a úkoly

Objevte podporované capabilities

Sdružené vs. pojmenované typy účtů

Požádejte o capability

Dokončete aktuální úkoly

Hostované akce

Nahrání dokumentů

API odpovědi

Předpoklad skutečného majitele pro firmy

Pokračujte, když je capability připravena

​Objevte podporované capabilities

​Sdružené vs. pojmenované typy účtů

​Požádejte o capability

​Dokončete aktuální úkoly

​Hostované akce

​Nahrání dokumentů

​API odpovědi

​Předpoklad skutečného majitele pro firmy

​Pokračujte, když je capability připravena

Objevte podporované capabilities

Sdružené vs. pojmenované typy účtů

Požádejte o capability

Dokončete aktuální úkoly

Hostované akce

Nahrání dokumentů

API odpovědi

Předpoklad skutečného majitele pro firmy

Pokračujte, když je capability připravena