Environment variables
Objevte podporované capabilities
Přečtěte aktuální možnosti zákazníka pomocíGET /v3/customers/{customerId}/capabilities/supported:
List supported capabilities
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.
Každá položka instituce obsahuje logoUrl a příznak isDefault. Pomocí logoUrl zobrazte logo banky v rozhraní pro výběr banky, a když je null, vykreslete vlastní obecnou ikonu banky. isDefault platí pouze pro tohoto zákazníka a tuto capability, nikoli pro instituci globálně. GET /v3/institutions vrací stejné logoUrl, které může být null. ID institucí jsou neprůhledná, proto nová ID zpracovávejte bez změn kódu.
Institution entry
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 poleaccountType 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.
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.
Chcete-li přijímat vklady SWIFT nebo vydávat bankovní údaje SWIFT, použijte swift_named. swift_pooled podporuje pouze výplaty, proto u každé možnosti zkontrolujte directions v odpovědi na podporované capabilities. Pojmenovaný účet SWIFT vrací opakovaně použitelné údaje pro příjem plateb, včetně BIC banky, reference, pokud je vyžadována, a adresy příjemce, pokud ji banka poskytne.
U vydaných účtů ACH, Wire a SWIFT můžete pomocí institution vybrat konkrétní banku a uložit požadavek na účet ještě předtím, než banka zákazníka schválí. Viz Vydat bankovní účet.
Požádejte o capability
Požádejte o vybranou možnost pomocíPOST /v3/customers/{customerId}/capabilities/{capabilityId}:
Request capability
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.accountProvisioning jako ACCOUNT_PROVISIONING_STATUS, data.openTaskIds jako OPEN_TASK_IDS a každé data.applications[].id do APPLICATION_IDS.
Sdílené aplikace pro každou banku
U pojmenovaných bankovních capabilities má každý zákazník jeden případ aplikace pro každou banku. Sdružené a platformní capabilities používají případy bez banky. Swipelux sdílí případ napříč všemi kompatibilními capabilities, o které požádáte:- Jedno schválení může pokrýt několik capabilities. Například schválený případ u jedné banky může převést capability ACH i wire do stavu
ready. - Pozdější požadavek, který odpovídá existujícímu případu, jej znovu použije. Swipelux neotevře druhou aplikaci a nepřidá duplicitní úkoly.
- Případy u různých bank jsou nezávislé. Zamítnutí u jedné banky neovlivní případ u jiné banky.
201znamená, že požadavek otevřel nový případ aplikace.200znamená, že požadavek byl přiřazen k případu aplikace, který zákazník již měl, například při opakovaném požadavku na bankovní capability, kterou zákazník již má, nebo při požadavku na zrušenou capability. Opakovaný požadavek nacardnebostablecoin_transfersstále vrací409 capability_already_exists.selectedApplicationIdje pole nejvyšší úrovně vedledatas ID případu, který požadavek vybral nebo otevřel. Swipelux jej vynechá, když požadavek žádný případ nevybral. Idempotentní opakování vrací stejnou hodnotu.
Response (abbreviated)
institutions, abyste vybrali stejný případ, nebo pošlete jedno ID instituce, abyste cílili na danou banku. Banka, která zákazníka definitivně zamítla, se přeskočí. Když uvedete pouze tuto banku, nebo když zákazníka zamítly všechny způsobilé banky, požadavek vrátí 409 capability_terminally_rejected. Chcete-li po zamítnutí zkusit jinou banku, požádejte o capability znovu s ID instituce této banky.
Stav capability odráží všechny související případy zákazníka. U pojmenované capability stačí k tomu, aby byla ready, jeden případ ve stavu ready, jehož schválení ji pokrývá, bez ohledu na to, co hlásí ostatní banky. Sdružená capability navíc čeká na kontrolu své metody, která je uvedena v probes v seznamu aplikací zákazníka.
Zobrazte aplikace zákazníka
Vypište všechny případy aplikací zákazníka pomocíGET /v3/customers/{customerId}/applications. Výsledky jsou stránkované pomocí nextCursor a hasMore a přijímají updatedAfter:
List applications
applications[] capability, a navíc:
scope:namedpro případ u jedné banky,provider_pooledneboplatformpro případy bez banky, nebonullpro nezařazený historický případ. U případůprovider_pooledaplatformpoleinstitutionchybí.requestedScope[]: klíče capabilities, o které bylo v rámci případu požádáno, každý s prvnímrequestedAt. Položky se nikdy neodstraňují.coverage[]: klíče capabilities, které schválení případu pokrývá, každý sgrantedAtasource. Pokrytí zaznamenává rozsah, nikoli autorizaci. Aktuální stav zjistěte přečtením capability.probes[]: kontroly metod pro klíče sdružených capabilities, které případ pokrývá, každá scapabilityKey,statusareason. Pojmenované klíče kontrolu nikdy nevyžadují.generation,predecessorApplicationIdasupersededByApplicationId: odkazy na posloupnost případů. Když je nastavenosupersededByApplicationId, případ byl nahrazen. Pokračujte podle tohoto ID k aktuálnímu případu. Seznamapplications[]capability obsahuje pouze aktuální případy, takže nahrazený případ se objeví pouze v tomto seznamu.
Response (abbreviated)
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}:
List open tasks
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.
Znovu použité důkazy z profilu
U úkolů příjmu aplikace, které přijímají přímé odeslání přes API, Swipelux znovu používá informace, které zákazník již poskytl. Když je takový úkol vytvořen nebo sladěn, Swipelux zkontroluje profil zákazníka a dokumenty, které zákazník sám nahrál. Způsobilé požadavky, které již podkládá použitelná hodnota profilu nebo dokument, přejdou doin_review, místo aby zůstaly akční. Aktualizace profilu a nahrání nových dokumentů spouštějí stejnou kontrolu u existujících úkolů.
Akční zůstávají pouze chybějící nebo nekompatibilní hodnoty. Opětovné použití důkazy neschvaluje. Swipelux je stále posuzuje. Explicitní žádosti o opravu a dříve zodpovězené požadavky zůstávají akční. Dokumenty vlastníků a propojených stran se znovu nepoužívají a požadavky shromažďované pouze prostřednictvím hostované relace si zachovávají svůj běžný postup.
Vykreslete požadavky
Formuláře sestavujte z metadat, která vrací každý požadavek, nikoli z klíčů požadavků. Požadavek může obsahovat volitelný krátkýtitle a každý request obsahuje prompt, který se zobrazí pod nadpisem.
Požadavky s request.type: "profile" identifikují pole profilu pomocí profilePointer a přidávají metadata vstupu:
allowedValues: povolené hodnoty skalárního pole nebo každé položky pole typu array. Odesílejte tyto hodnoty, nikoli přeložené zobrazované popisky.valueSchema: samostatný dokument JSON Schema Draft 7, který popisuje tvar vstupu, vnořené vlastnosti, povinná pole a strukturální omezení. Výčty u objektů se objevují u příslušné vlastnosti, napříkladvalueSchema.items.properties.type.enumu daňových identifikátorů. Swipelux po odeslání stále provádí validaci napříč poli a validaci v rámci posouzení, takže hodnota, která projde schématem, může být přesto zamítnuta.valueType: "country", neboitemValueType: "country"u polí typu array: pole přijímá kódy ISO 3166-1 alpha-2 velkými písmeny. Vnořené vlastnosti země vevalueSchemapoužívajíformat: "iso-3166-1-alpha-2". Pro lokalizované popisky použijte standardní seznam zemí.
Requirement
valueSchema a allowedValues. Ty vykreslete z prompt a valueType.
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 vverificationSessions 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"obsahujeaction.urlaaction.expiresAt(aktuálně vždynull). Uložteaction.url, odešlete na něj zákazníka a poté úkol znovu načtěte. PoleurlaexpiresAtna úrovni relace obsahují stejné hodnoty.action.kind: "unavailable"znamená, že se nemá zobrazit žádný odkaz. PoleurlaexpiresAtna úrovni relace chybí. Samotnýstatusrelace neurčuje, který druh akce obdržíte.
Verification session
action_required, nese reviewFeedback.code: hosted_profile_direct_submission_required. Získejte tuto hodnotu od zákazníka a odešlete ji jako API odpověď.
Nahrání dokumentů
Když požadavek vyžaduje dokument, nahrajte jej pomocíPOST /v3/customers/{customerId}/documents:
Upload document
data.id jako DOCUMENT_ID předtím, než odešlete odpověď, která na něj odkazuje.
Pro pozdější načtení uloženého souboru zavolejte GET /v3/customers/{customerId}/documents/{documentId}/download. Swipelux vrátí url, která stáhne soubor jako přílohu a vyprší po jedné hodině. Archivované dokumenty vracejí 404.
API odpovědi
Odešlete jednu kompletní sadu odpovědí pro aktuální revizi pomocíPOST /v3/customers/{customerId}/tasks/{taskId}/submissions:
Submit task answers
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ří jakorestricted 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":
Beneficial owner requirement
person téhož zákazníka s poskytnutým procentem vlastnictví alespoň 25, nebo s ownership.declared: true bez uvedeného procenta.
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}:
Refetch capability
status capability oznamuje, zda je oprávnění schváleno. U capability, která vydává účet, accountProvisioning samostatně oznamuje, zda je daný účet not_started, in_progress, issued nebo failed; capability, která účet nevydává, vrací not_applicable.
Dokud je capability ve stavu pending, dvě z hodnot statusReason.code, které může hlásit, ukazují, zda probíhá kontrola. preparing_submission znamená, že Swipelux stále připravuje žádost k odeslání a neprobíhá žádná kontrola, a to i v případě, že žádost u jiné banky je rejected nebo vyžaduje pozornost. review_in_progress znamená, že kontrola probíhá, například když je žádost ve stavu in_review nebo je otevřené hostované ověření. Oba používají resolution: wait. Změna mezi těmito kódy ponechá stav pending, takže se neodešle žádná událost capability.status_changed. Aktuální kód zjistíte načtením capability.
Pokračujte jen tehdy, když aktuální stav capability umožňuje účet, quote nebo převod, který zamýšlíte vytvořit. Když tok potřebuje vydaný účet, počkejte také, až se accountProvisioning změní na issued.
Dále vyberte odpovídající cestu v Běžných tocích.