Hopp til hovedinnhold
En capability forteller deg om en kunde kan bruke et bestemt utfall, betalingsmetode og retning. Åpne oppgaver forteller deg hva som må skje før capability-en eller en relatert ressurs kan gå videre.
Environment variables

Oppdag støttede capabilities

Les kundens gjeldende valg med GET /v3/customers/{customerId}/capabilities/supported:
List supported capabilities
Velg en responsoppføring som samsvarer med tiltenkt directions, method og accountType. Fortsett kun når availability er available eller beta og eligibility.eligible er true. Hvis institutions returneres, velg kun én ID fra den responsen. Hver institusjonsoppføring inneholder en logoUrl og et isDefault-flagg. Bruk logoUrl til å vise bankens logo i et grensesnitt for bankvalg, og vis ditt eget generiske bankikon når den er null. isDefault gjelder kun for denne kunden og capability-en, ikke for institusjonen globalt. GET /v3/institutions returnerer den samme logoUrl, som kan være null. Institusjons-ID-er er ugjennomsiktige, så håndter nye ID-er uten kodeendringer.
Institution entry
Lagre den valgte data[].id som CAPABILITY_ID. Kopier aldri en capability-ID fra en annen kunde eller et annet miljø.

Pooled vs named kontotyper

Bankcapabilities finnes i to varianter, kodet som accountType-feltet og suffiks i capability-ID-en (for eksempel ach_pooled, wire_named):
  • pooled: delt Swipelux-bankkonto. Hver pay-in bruker en unik referanse for å rute midler. Velg denne for engangsoverføringer.
  • named: dedikerte bankopplysninger for kunden (virtuell IBAN, dedikert ACH-konto). Gjenbrukbare og delbare med hvilken som helst betaler. Kreves for utstedte bankkontoer.
Bruk pooled som standard. Bruk named kun når kunden trenger gjenbrukbare bankopplysninger. Sjekk supported-responsen for hvilke varianter som er tilgjengelige. Bruk swift_named for å motta SWIFT-innskudd eller utstede SWIFT-bankopplysninger. swift_pooled støtter kun utbetalinger, så sjekk directions for hvert alternativ i responsen for støttede capabilities. En named SWIFT-konto returnerer gjenbrukbare mottaksopplysninger, inkludert bankens BIC, en referanse når det kreves, og mottakerens adresse når banken oppgir den. For utstedte ACH-, Wire- og SWIFT-kontoer kan du velge en bestemt bank med institution og lagre kontoforespørselen før banken godkjenner kunden. Se Utsted en bankkonto.

Be om capability-en

Be om det valgte alternativet med POST /v3/customers/{customerId}/capabilities/{capabilityId}:
Request capability
Bruk en eksplisitt institutions-liste kun når du må velge fra ID-er returnert av responsen for støttede capabilities. Lagre data.status som CAPABILITY_STATUS, data.accountProvisioning som ACCOUNT_PROVISIONING_STATUS, data.openTaskIds som OPEN_TASK_IDS, og hver data.applications[].id i APPLICATION_IDS.

Delte søknader per bank

For named bankcapabilities har hver kunde én søknadssak per bank. Pooled- og plattform-capabilities bruker saker uten bank. Swipelux deler en sak på tvers av alle kompatible capabilities du ber om:
  • Én godkjenning kan dekke flere capabilities. For eksempel kan en godkjent sak hos én bank gjøre både en ACH- og en wire-capability ready.
  • En senere forespørsel som samsvarer med en eksisterende sak, gjenbruker den. Swipelux åpner ingen ny søknad og legger ikke til dupliserte oppgaver.
  • Saker hos forskjellige banker er uavhengige. Et avslag hos én bank påvirker ikke en sak hos en annen bank.
Responsen på forespørselen forteller deg hvilken sak Swipelux brukte:
  • 201 betyr at forespørselen åpnet en ny søknadssak.
  • 200 betyr at forespørselen ble løst til en søknadssak kunden allerede hadde, for eksempel en gjentatt forespørsel om en bankcapability kunden allerede har, eller en forespørsel om en kansellert capability. En gjentatt forespørsel om card eller stablecoin_transfers returnerer fortsatt 409 capability_already_exists.
  • selectedApplicationId er et felt på toppnivå ved siden av data med ID-en til saken som forespørselen valgte eller åpnet. Swipelux utelater feltet når forespørselen ikke valgte noen sak. En idempotent gjentakelse returnerer samme verdi.
Forkortet respons:
Response (abbreviated)
For named capabilities sender du den samme institutions-listen på nytt for å velge den samme saken, eller én institusjons-ID for å målrette den banken. En bank som endelig har avslått kunden, hoppes over. Når du bare angir den banken, eller alle kvalifiserte banker har avslått kunden, returnerer forespørselen 409 capability_terminally_rejected. For å prøve en annen bank etter et avslag, be om capability-en på nytt med den bankens institusjons-ID. Statusen til en capability gjenspeiler alle kundens relaterte saker. For en named capability er én ready-sak med en godkjenning som dekker den, nok til å gjøre den ready, uansett hva andre banker rapporterer. En pooled capability venter også på metodesjekken sin, som rapporteres i probes i kundens søknadsliste.

List kundens søknader

List alle søknadssaker for kunden med GET /v3/customers/{customerId}/applications. Resultatene pagineres med nextCursor og hasMore, og godtar updatedAfter:
List applications
Hver oppføring inneholder søknadsfeltene som returneres i en capabilitys applications[], samt:
  • scope: named for en sak hos én bank, provider_pooled eller platform for saker uten bank, eller null for en uklassifisert historisk sak. institution er fraværende for provider_pooled- og platform-saker.
  • requestedScope[]: capability-nøklene som er forespurt mot saken, hver med sin første requestedAt. Oppføringer fjernes aldri.
  • coverage[]: capability-nøklene som sakens godkjenning dekker, hver med grantedAt og source. Dekningen registrerer omfang, ikke autorisasjon. Les capability-en for å se gjeldende status.
  • probes[]: metodesjekker for de pooled capability-nøklene saken dekker, hver med capabilityKey, status og reason. Named nøkler krever aldri en probe.
  • generation, predecessorApplicationId og supersededByApplicationId: etterfølgerlenker. Når supersededByApplicationId er satt, er saken erstattet. Følg den ID-en til den gjeldende saken. En capabilitys applications[] viser bare gjeldende saker, så en erstattet sak vises bare i denne listen.
Forkortet respons:
Response (abbreviated)

Fullfør gjeldende oppgaver

List oppgaver med GET /v3/customers/{customerId}/tasks, velg ID-er fra OPEN_TASK_IDS, og les så hver gjeldende oppgave med GET /v3/customers/{customerId}/tasks/{taskId}:
List open tasks
Bruk siste data.revision og data.requirements. Hent oppgaven på nytt umiddelbart før innsending hvis noen av delene kan ha endret seg.

Gjenbrukte profilbevis

For intake-oppgaver for søknader som godtar direkte innsending via API, gjenbruker Swipelux informasjon kunden allerede har oppgitt. Når en slik oppgave opprettes eller avstemmes, sjekker Swipelux kundeprofilen og kundens egne opplastede dokumenter. Kvalifiserte krav som allerede støttes av en brukbar profilverdi eller et dokument, flyttes til in_review i stedet for å forbli handlingsklare. Profiloppdateringer og nye dokumentopplastinger utløser den samme sjekken for eksisterende oppgaver. Kun manglende eller inkompatible verdier forblir handlingsklare. Gjenbruk godkjenner ikke beviset. Swipelux gjennomgår det fortsatt. Eksplisitte forespørsler om korrigering og krav som allerede er besvart, forblir handlingsklare. Dokumenter for eiere og nærstående parter gjenbrukes ikke, og krav som kun samles inn gjennom en hosted sesjon, følger sin vanlige flyt.

Gjengi krav

Bygg skjemaer fra metadataene hvert krav returnerer, ikke fra kravnøkler. Et krav kan inneholde en valgfri kort title, og hver request inneholder en prompt som skal vises under overskriften. Krav med request.type: "profile" identifiserer profilfeltet med profilePointer og legger til metadata for inndata:
  • allowedValues: de tillatte verdiene for et skalarfelt, eller for hvert element i et array-felt. Send inn disse verdiene, ikke oversatte visningsetiketter.
  • valueSchema: et selvstendig JSON Schema Draft 7-dokument som beskriver formen på inndataene, nestede egenskaper, påkrevde felt og strukturelle begrensninger. Enums på objekter vises på den aktuelle egenskapen, for eksempel valueSchema.items.properties.type.enum for skatteidentifikatorer. Swipelux utfører fortsatt validering på tvers av felt og ved gjennomgang etter innsending, så en verdi som består skjemaet, kan likevel bli avvist.
  • valueType: "country", eller itemValueType: "country" for arrays: feltet tar ISO 3166-1 alpha-2-koder med store bokstaver. Nestede landegenskaper i valueSchema bruker format: "iso-3166-1-alpha-2". Bruk en standard landliste for lokaliserte etiketter.
Requirement
Dette eksempelet forkorter verdikatalogen. API-et returnerer alle tillatte verdier. Noen profilkrav har ikke noe publisert skjema og utelater valueSchema og allowedValues. Gjengi disse fra prompt og valueType. Hver åpen oppgave inneholder et dueAt-tidsstempel. Når Swipelux oppretter en oppgave uten en eksplisitt forfallsdato, settes dueAt som standard til nøyaktig 31 dager etter oppgavens createdAt. Behandle dueAt som informativt: du kan ikke sette det via API-et, og det utløser ingen automatisk livssyklusovergang. Bare det separate feltet deadline forårsaker en automatisk overgang når det er satt.

Hostede handlinger

I svaret med oppgavedetaljer inneholder hver oppføring i verificationSessions og tosSessions et action-objekt. Svar med oppgavelister inneholder ikke disse handlingslenkene. Lagre id for hver sesjon, og les deretter action.kind før du sender kunden videre. Ikke utled tilgjengeligheten av lenken fra sesjonens status.
  • action.kind: "available" inkluderer action.url og action.expiresAt (for øyeblikket alltid null). Lagre action.url, send kunden dit, og les deretter oppgaven på nytt. Feltene url og expiresAt på sesjonsnivå inneholder de samme verdiene.
  • action.kind: "unavailable" betyr at ingen lenke skal vises. Feltene url og expiresAt på sesjonsnivå er fraværende. Sesjonens status alene avgjør ikke hvilken handlingstype du mottar.
Verification session
Dette er oppgaveavgrensede handlinger, ikke en separat livssyklus for kundeverifisering. Et hostet svar på et profilkrav for en strukturert verdi, for eksempel en adresse eller skatteidentifikatorer, må bestå de samme skjema- og begrensningskontrollene som et direkte svar. Hvis det ikke gjør det, forblir kravet åpent. Et krav som Swipelux returnerer til action_required av denne grunnen, har reviewFeedback.code: hosted_profile_direct_submission_required. Samle inn verdien fra kunden og send den inn som et API-svar.

Last opp dokumenter

Når et krav ber om et dokument, last det opp med POST /v3/customers/{customerId}/documents:
Upload document
Lagre den returnerte data.id som DOCUMENT_ID før du sender inn svaret som refererer til den. For å hente en lagret fil senere, kall GET /v3/customers/{customerId}/documents/{documentId}/download. Swipelux returnerer en url som laster ned filen som et vedlegg og utløper etter én time. Arkiverte dokumenter returnerer 404.

API-svar

Send inn ett komplett svarsett for gjeldende revisjon med POST /v3/customers/{customerId}/tasks/{taskId}/submissions:
Submit task answers
Hent hver krav-ID og svar-type fra siste oppgave. Hvis API-et melder at oppgaven har endret seg, hent den på nytt og bygg innsendingen på nytt fra den nye revisjonen.

UBO-forutsetning for virksomheter

Å be om en virksomhets-capability som trenger UBO-bevis lykkes selv når kunden ennå ikke har en kvalifiserende eier. Capability-en opprettes som restricted med statusReason.code: tasks_due, og intake-oppgaven for virksomheten ber om de manglende eierskapsfaktaene, inkludert eierskapsstrukturen. Den samme oppgaven inneholder et resource_reference-krav der forespørselen inkluderer qualification: "beneficial_owner":
Beneficial owner requirement
En nærstående part kvalifiserer når den er en aktiv person-part hos samme kunde med en oppgitt eierandel på minst 25, eller med ownership.declared: true uten oppgitt eierandel. Kravet utledes fra den gjeldende listen over nærstående parter, så du svarer vanligvis ikke på det direkte:
  • Å opprette eller oppdatere en kvalifiserende nærstående part oppfyller kravet i samme reevaluering og åpner den eierens eget profil- og dokumentarbeid. Se Legg til nærstående parter for virksomheten.
  • Du kan også referere til en kvalifiserende part eksplisitt med et resource_reference-svar som inneholder dens relatedPartyId.
  • Kravet forblir oppført i den gjeldende oppgaven etter at det er oppfylt. Når ingen annen forpliktelse gjenstår som åpen, blir oppgaven satisfied.
  • Å arkivere den siste kvalifiserende parten, eller fjerne faktaene som kvalifiserte den, gjenåpner kravet, selv etter at oppgaven var satisfied.

Fortsett når capability-en er klar

Les capability-en på nytt med GET /v3/customers/{customerId}/capabilities/{capabilityId}:
Refetch capability
Erstatt den lagrede statusen, kontoutstedelsesstatusen og oppgave-ID-ene med siste respons. Capability-ens status viser om rettigheten er godkjent. For en capability som utsteder en konto, rapporterer accountProvisioning separat om den kontoen er not_started, in_progress, issued eller failed; en capability som ikke utsteder en konto, returnerer not_applicable. Mens capability-en er pending, viser to av statusReason.code-verdiene den kan rapportere om en gjennomgang pågår. preparing_submission betyr at Swipelux fortsatt forbereder en søknad for innsending og at ingen gjennomgang pågår, selv om en annen banks søknad er rejected eller trenger oppmerksomhet. review_in_progress betyr at en gjennomgang pågår, for eksempel mens en søknad er in_review eller en hostet verifisering er åpen. Begge bruker resolution: wait. En endring mellom disse kodene beholder statusen pending, så det sendes ingen capability.status_changed-hendelse. Les capability-en for å se gjeldende kode. Fortsett kun når gjeldende capability-status tillater kontoen, tilbudet eller overføringen du har til hensikt å opprette. Når flyten trenger en utstedt konto, vent også til accountProvisioning blir issued. Deretter, velg den samsvarende reisen i Vanlige flyter.