Migrere til v3

• Del 1, konseptet. Les dette først. v3 er en omforming, ikke en omdøping: hvis du mapper gamle endepunkter én-til-én, kjemper du mot API-et. Ti minutter her sparer deg for dager senere.
• Del 2, API-et. Endepunkt-for-endepunkt-mapping, forespørselseksempler, tilstandsmaskiner og en migreringssjekkliste.

​

Del 1, konseptet

​

1.1 Hvorfor v3 finnes

​

1.2 Objektmodellen

1. Capabilities styrer alt. Kontoer opprettes under en ready capability; quotes prises mot en capability. Onboarding betyr å få de nødvendige capabilities til ready.
2. Tasks kan henge hvor som helst. En capability, en konto eller en pågående transfer kan bære openTaskIds. Uansett hvor du ser dem, er løkken den samme: les task, send inn svar, vent på gjennomgang, les foreldreobjektet på nytt.

​

1.3 Klarhet er per capability, ikke per kunde

• “Kan de transactere på X?” blir capability X status == "ready".
• “Må de gjøre noe?” blir en task med status action_required (capabilityen viser typisk restricted med statusReason.resolution: "complete_tasks").
• “Venter vi på Swipelux?” blir tasks i in_review, capability pending.

​

1.4 Task-løkken

• En task bærer requirements[], de enkelte forespørslene. Hver har en task-spesifikk requirementId, en stabil key som navngir forespørselen (for eksempel adressebekreftelse, dedupliser UI-en din på denne) og et typet request som beskriver nøyaktig hva slags inndata som kreves (tekst, dato, valg, dokument, attestasjon og så videre).
• Innsending er gjennomgangs-styrt: den endrer aldri capability- eller kontostatus direkte, det gjør aksept. Ett unntak: profile-svar skrives direkte inn i kundeprofilen ved innsending (2.3). Etter innsending poller du tasken eller foreldreressursen.
• taskRevision (ekko av taskens revision) er en samtidighetsvakt: har tasken endret seg siden du leste, må du lese på nytt og bygge svarene på nytt.
• absence er et fullverdig svar (“Jeg har ikke dette fordi …”), bruk det i stedet for å la krav henge.

​

1.5 Pengeflytting

​

1.6 Én tilstandsmaskin per ressurs

​

1.7 Konvensjoner

• Å gjenbruke en nøkkel med en annerledes body gir 409 idempotency_conflict så lenge nøkkelen oppbevares (minst 7 dager), så planlegg aldri å gjenbruke en nøkkel. Generer en ny UUID per logisk operasjon og lagre den sammen med jobben din.
• Replay dekker også feil: hvis den opprinnelige forespørselen endte i en terminal 4xx, gir samme nøkkel pluss body samme problemsvar igjen.
• To samtidige forespørsler med samme nøkkel: én vinner, den andre får 409. Prøv taperen på nytt etter at vinneren er ferdig; replayen returnerer det opprinnelige svaret.

​

1.8 Den gyldne veien

​

Del 2, API-et

​

2.1 Kunder

// POST /v3/customers        Idempotency-Key: <fresh uuid>
{
  "type": "individual",
  "externalId": "user-1042",
  "individual": {
    "firstName": "Maria",
    "lastName": "Silva",
    "birthDate": "1990-04-12",
    "nationalities": ["BR"],
    "residenceCountry": "BR",
    "email": "maria@example.com",
    "residentialAddress": {
      "streetLine1": "Av. Paulista 1000",
      "city": "Sao Paulo",
      "postalCode": "01310-100",
      "country": "BR"
    }
  },
  "financialProfile": {
    "accountPurposes": ["cross_border_remittance"],
    "sourcesOfFunds": ["salary"]
  }
}

• Opprettelse er progressiv: { "type": "individual" } alene er en gyldig opprettelse. Manglende opplysninger gjør aldri kunden ugyldig, de dukker opp senere som intake-tasks på capabilities-ene som trenger dem.
• Virksomheter bærer business pluss registreringsdata. v1s shareholder-CRUD mappes til related parties, utvidet til å dekke direktører, ledere og eiere: opprett dem inline ved kundeopprettelse (hver får en stabil rp_-id) eller administrer dem via de dedikerte related-parties-endepunktene.
• Ingen kunde-status-felt, se 1.3.
• Eksisterende kunder overføres: kunder opprettet på v1 eller v2 er adresserbare med samme id på v3-endepunktene. v3-lesningen er en renset visning, eldre verdier som ikke består v3-validering kommer tilbake som fraværende. Etter din første v3-write blir visningen permanent: fraværende verdier kommer ikke tilbake av seg selv. Berik derfor tidlig, sett av en engangs-runde som PATCH-er den fulle profilen fra dine egne poster før du stoler på v3-lesninger. v1-metadata er et separat navneområde og overføres ikke, sett det på nytt på v3.
• externalId er førsteklasses og unik på tvers av alle kundene dine i v3, per miljø (409 duplicate_external_id). Arkivering av en kunde frigjør ikke externalId, tøm den via PATCH før DELETE hvis du vil gjenbruke den.
• DELETE er en arkiveringskaskade (ingen gjenoppretting; ids gjenbrukes aldri). Den blokkeres med 409 customer_has_active_resources pluss blockingResources[] så lenge det finnes en ikke-arkivert konto eller pågående transfer.
• PATCH-mergeregler: eksplisitt null tømmer et nullbart felt, arrayer erstattes fullstendig (unntatt inline related parties, som upsertes etter id), metadata-nøkler slås sammen. Fulle skjemaer og listefiltre finnes i OpenAPI-spesifikasjonen.

​

2.2 /rails, /banks, applications blir Capabilities

• En capability er method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers og så videre) pluss accountType (pooled eller named, null for ikke-bankmetoder) pluss directions (payin eller payout). Den offentlige capabilityId er det kvalifiserte paret (sepa_pooled, ach_named) eller kun metoden for card og stablecoin_transfers.
• Hver capability-forespørsel genererer en application, posten per forsøk under .../capabilities/{capabilityId}/applications (pluss /{applicationId}/history), med egne statuser (1.6) og statusReason. Den er revisjonsloggen for en forespørsel; i det daglige poller du selve capabilityen.
• capabilities/supported returnerer tilgjengelighet (available, beta eller disabled), kvalifisering og institusjoner som tilbys. Bankvalg skjer ved forespørselstidspunktet via det valgfrie institutions-arrayet, det finnes ingen separat /banks-ressurs. Utelatelse (eller å sende []) velger alle standardinstitusjoner; isDefault: true er et kunde- og capability-spesifikt flagg, ikke et globalt. En ikke-tom liste overstyrer standardene, og en bankstøttet capability uten anvendbar standard returnerer 422 capability_institutions_required. Institusjons-ids er ugjennomsiktige, tolerer nye.
• stablecoin_transfers tildeles automatisk ved kundeopprettelse og fødes som ready (bes altså aldri om og kan ikke kanselleres). card er kun for individer.
• openTaskIds på capabilityen er “hva gjør jeg neste”-pekeren. Åpen betyr action_required eller in_review, og oppsummeringen inkluderer delte tasks på kundenivå som nås gjennom aktive avhengigheter.
• cancel fungerer kun fra pending eller restricted og uten blokkerende ressurser, ellers 409 capability_not_cancelable, hvis problem-body lister blockingResources. Å be på nytt etter kansellering er en fersk opprettelse med en ny idempotency-nøkkel.
• Poll GET-en. Capability-status oppdateres når du leser; poll GET .../capabilities/{capabilityId} eller abonner på capability.status_changed, ikke cache.
• Å be om én metode kan gjøre relaterte metoder tilgjengelige med en gang, behandle capabilities som et sett du leser på nytt, ikke som én rad du sporer.
• Bruk tasks-preview for å vise onboarding-forespørsler før du forplikter deg til en forespørsel.
• Verifikasjon er ikke engangs: nye tasks kan dukke opp på en allerede ready capability (periodisk eller hendelsesdrevet re-verifikasjon). Hold task-løkken koblet gjennom hele kundens levetid, ikke bare ved onboarding.

​

2.3 Dokumenter og KYC blir Tasks og Submissions

• Rå fillagring: POST/GET/DELETE /v3/customers/{customerId}/documents (pluss /{documentId}), last opp én gang med API-nøkkelen din, og referer så til dokument-id-er i submission-svar. Dette erstatter alle upload-token- og direct-upload-inntak.
• Helt nye lesninger: GET /v3/tasks (merchant-omfattende innboks), GET /v3/transfers/{transferId}/tasks, GET .../tasks/{taskId}/history, GET .../tasks/{taskId}/submissions (pluss /{submissionId}).

// POST /v3/customers/{cus}/tasks/{task}/submissions   Idempotency-Key: <fresh uuid>
{
  "taskRevision": 3,
  "answers": [
    { "requirementId": "req_a1", "answer": { "type": "document", "documentIds": ["doc_passport1"] } },
    { "requirementId": "req_b2", "answer": { "type": "text", "value": "Import/export business" } },
    { "requirementId": "req_c3", "answer": { "type": "absence", "reason": "not_applicable" } }
  ]
}

• Svartyper: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. Hvert requirements request-objekt sier hvilken type det forventer.
• En submission må besvare hvert handlingskrevende requirement i gjeldende runde, med nøyaktig den taskRevision du leste. Delvise submissions avvises.
• profile-svar skriver gjennom: de oppdaterer kundeprofilen via den vanlige valideringsveien og re-evaluerer umiddelbart hver capability som refererer til det samme intake-arbeidet. Søskenlagerte intake-tasks der alle requirements er oppfylt, lukkes automatisk.
• Requirements kan danne alternative grupper (alternativeKey): send inn nøyaktig én av gruppen.
• changes_requested øker remediationRound og bærer reviewFeedback. Les tasken på nytt og send inn på nytt med en ny idempotency-nøkkel.
• Hostede verifikasjons-URLer vises kun på kundeavgrenset task-detalj (GET /v3/customers/{customerId}/tasks/{taskId}) og bare mens sesjonen er handlingskrevende; lister og GET /v3/tasks/{taskId} er bevisst URL-frie.
• Tjenestevilkår er også en task: openTaskIds kan inkludere en task med category: "terms_of_service" hvis hostede aksepteringside er lenket på samme måte (kun kundeavgrenset detalj). Generiske submissions kan ikke godta vilkår, og KYC-godkjenning innebærer aldri aksept av vilkår.
• Tasks er avgrenset per capability, så det “samme” kravet (for eksempel adressebekreftelse) kan dukke opp én gang per capability. Dedupliser i UI-en på requirement key.
• Ingen oversettelseslag: å poste til /v1/documents låser ikke opp v3-capabilities. Når en kunde først er på v3, driv alle forespørsler gjennom tasks.

​

2.4 Kontoer og wallets

// issued bank account (capability must be ready)
{ "origin": "issued", "type": "bank", "method": "sepa",
  "currency": "EUR", "settlement": { "accountId": "acc_wallet1" } }

// external wallet the customer already owns (replaces /import)
{ "origin": "external", "type": "wallet", "currency": "USDC",
  "network": "polygon", "details": { "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" } }

• country på utstedte bankkontoer er valgfritt (standard per metode); på eksterne bankkontoer oppgir du det eksplisitt. Wallet-kontoer bærer ikke land i det hele tatt.
• settlement.accountId er påkrevd på utstedte bankkontoer: den navngir den utstedte wallet-kontoen som mottar oppgjorte midler fra innskudd til bankkontoen.
• Utstedte kontoer eksponerer details (IBAN eller routing pluss konto eller adresse), versjonert routing (innskuddskoordinater kan roteres, gjengi alltid den nyeste lesningen), fees, balances.
• Nettverk: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• Capability-porten gjelder kun utstedte kontoer: å opprette en mot en ikke-klar capability feiler med en capability-kodet feil, be om capabilityen først (2.2). Eksterne kontoer trenger ingen capability (og ingen kundegodkjenning); de får kun validering av forespørselsskjema og bankdetaljer.
• Utstedte bankkontoer fødes som provisioning med details: null. Poll kontoen eller se på account.status_changed til ready.
• DELETE arkiverer, sletter aldri hardt. Kontoer som refereres av pågående transfers returnerer 409 account_has_active_transfers. Prøv på nytt etter at disse transferene når en terminal tilstand.
• Nytt i v3: Rules, stående instruksjoner på en utstedt wallet-konto (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}) som automatisk feier innkommende midler til en annen konto eller en wallet-destination. Ingen v1- eller v2-ekvivalent.

​

2.5 Mottakere og destinations

• Recipient er hvem: individual (fornavn og etternavn) eller business (firmanavn), med påkrevd relationship (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Recipients og destinations er kun for tredjeparter. En utbetaling til deg selv bruker ikke recipient i det hele tatt: sikt på en av kundens egne acc_-kontoer som quotens destinationId (2.6).
• Destination er hvor: typet per metode, sepa (iban, bic valgfritt), ach eller wire (routing pluss konto), swift (fulle koordinater pluss valgfri mellombank), spei (clabe), pse, transfers_3_0 (cbu) og så videre, samt wallet-destinations. Hver destination har sin egen status. Følg med på destination.status_changed.
• Fiat-destinations krever mottakerens fullstendige address (gate, by, postnummer, land) før opprettelse. Manglende deler feiler med 422 recipient_address_required. Wallet-destinations hopper over adressen, men krever ownership på toppnivå (self_custodied, eller custodial med et custodian-navn).
• Nøyaktighet i mottakernavnet er viktig: mottakerbanker matcher kontoens juridiske navn. Send eksakt juridisk fornavn pluss etternavn eller firmanavn, ikke et visnings-kallenavn.
• Feltskjemaer per metode for destinations finnes i OpenAPI-spesifikasjonen.

​

2.6 Quotes og transfers

// 1. Quote: amount on exactly one side picks mode (exact_in / exact_out).
// POST /v3/quotes            Idempotency-Key: <fresh uuid>
{
  "customerId": "cus_123",
  "capabilityId": "sepa_named",
  "in":  { "currency": "EUR", "amount": "150.00" },
  "out": { "currency": "USDC" },
  "destinationId": "acc_wallet1",   // fiat-funded: must be a customer-owned acc_ account
  "fees": { "breakdown": { "developer": { "fixed": "1.00", "bips": 50 } } }
}
// -> { mode: "exact_in", direction: "fiat_to_stablecoin", rate, fees[], expiresAt, ... }

// 2. Execute before expiresAt.
// POST /v3/transfers         Idempotency-Key: <fresh uuid>
{ "quoteId": "quo_789", "externalId": "order-991", "memo": "invoice 44" }

• destinationId tar en acc_-id (kundeeid konto) eller en dst_-id (mottakerdestination). Fiat-finansierte quotes (payins) må sikte mot en acc_-konto, et dst_-mål betyr alltid en utbetaling (ellers 422 quote_direction_invalid).
• externalId på quotes og transfers er en ikke-unik korrelasjonsreferanse (gjentas i lesninger, filtrerbar på lister). Regelen om unikhet per miljø (2.1) gjelder kun for kundens externalId.
• Utfør en quote nøyaktig én gang, før expiresAt. En utløpt quote feiler med 409 quote_expired, en andre utførelse med 409 quote_already_executed (problemet inneholder eksisterende transferId).
• Kansellering av transfer støttes ennå ikke: POST .../cancel returnerer 409 transfer_not_cancelable i alle tilstander. Dagens canceled-transfers kommer fra at finansieringsvinduet utløper på en ufinansiert payin, ikke fra dette endepunktet.
• Payins starter i awaiting_funds: gjengi GET .../instructions for betaleren, bankkoordinater pluss referanse- eller memokode for fiat, innskuddsadresse for krypto. Referansekoden er slik innskuddet matches. Vis den alltid.
• state pluss stateDetail for maskinlesbare subtilstander; action_required betyr at en compliance-task er vedlagt (openTaskIds, GET .../tasks), svar via submissions.
• Innkommende innskudd oppdaget på utstedte kontoer vises som transfers med origin: "inbound_deposit" (i stedet for "quoted").
• Referanser til betalingsnettverk er samlet under references: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Transfers krysser ikke versjoner. Transfers opprettet på v1 eller v2 er ikke lesbare fra v3. Listen utelater dem og GET /v3/transfers/{transferId} gir 404. Bytt over oppretting først, behold v1-leseveien til disse transferene når terminale tilstander, og fjern den så.
• Ingen tokenbytter. stablecoin_move krever samme valuta inn og ut: USDC til USDT feiler med 422 recipient_destination_invalid med en currency_mismatch-feltfeil. Samme nettverk på begge sider, ingen bridging, og wallet-til-wallet-flyttinger støtter for øyeblikket kun gebyrfri levering: en quote hvis plattform- eller utviklergebyr er ulik null feiler med 422 amount_not_deliverable.

​

2.7 Webhooks

• GET /v3/webhooks/portal returnerer en hostet administrasjonsportal-URL for leveringslogger, retries og manuell replay.
• transfer.created leveres for øyeblikket i eldre v1-payloadform (v3-konvolutten aktiveres når v1-webhooks utfases). Behandle den kun som et hint og hent transferen via GET; ikke bygg mot bodyen dens.
• Hendelser er hint: ved mottak hent ressursen og handle på lesningen. Bygg aldri tilstand basert på hendelses-payload eller rekkefølge. Levering er minst-én-gang og kan være forsinket eller omordnet. Dedupliser på hendelses-id, og gjenopprett tapte hendelser med hver listes inklusive updatedAfter-filter.
• Abonner på api.deprecation, maskinkanalen for versjonsutfasinger.
• Ingen task.*-hendelse i dag: etter innsending poller du tasken eller foreldreobjektet.

​

2.8 Sandbox

​

2.9 Eldre endepunkter uten v3-erstatning

​

2.10 Foreslått migreringsrekkefølge

​

2.11 Fallgruvesjekkliste

• Ny UUID per logisk operasjon, lagret med jobben din og gjenbrukt ved retry; gjenbruk aldri en nøkkel med endret body (409 idempotency_conflict). Sandbox-endepunkter er unntatt fra headeren.
• Berik eksisterende kunder (PATCH den fulle profilen, sett metadata på nytt, den overføres ikke) før enhver annen v3-write, den første v3-writen gjør den rensede visningen permanent.
• externalId er unik per miljø og frigjøres ikke ved arkivering, tøm den via PATCH før DELETE hvis du planlegger å gjenbruke den.
• Det finnes ikke noe kunde-status-felt, avled klarhet per capability.
• action_required og in_review betyr begge en åpen task.
• Submissions er gjennomgangs-styrt (innsending er ikke det samme som opplåst) og må besvare hvert handlingskrevende requirement med nøyaktig taskRevision. Ved uoverensstemmelse må du lese på nytt og bygge på nytt.
• Det finnes ingen task.*-webhook, poll tasken (eller foreldreobjektet) etter hver innsending.
• Retry ved changes_requested betyr å lese tasken på nytt, nye svar, ny idempotency-nøkkel.
• Å poste til /v1/documents låser aldri opp en v3-capability, når en kunde er på tasks, driv hver forespørsel gjennom tasks.
• Nye tasks kan dukke opp på en allerede ready capability, hold task-løkken koblet etter onboarding, ikke bare under.
• Capability cancel fungerer kun fra pending eller restricted uten blokkerende ressurser (409 capability_not_cancelable); å be på nytt etter kansellering er en fersk opprettelse med en ny idempotency-nøkkel.
• Capability må være ready før du utsteder kontoer under den eller quoter mot den.
• Quote har beløp på nøyaktig én side; ingen retningsfelt; utfør nøyaktig én gang før expiresAt (409 quote_expired eller 409 quote_already_executed).
• Stablecoin-flyttinger er kun samme-valuta og samme-nettverk (USDC til USDT feiler 422); wallet-til-wallet støtter kun gebyrfri levering.
• DELETE arkiverer, sletter aldri hardt. Kontosletting blokkeres av pågående transfers (409 account_has_active_transfers); kundesletting blokkeres i tillegg av enhver ikke-arkivert konto (409 customer_has_active_resources, blockingResources[] navngir dem).
• v1- eller v2-transfers er usynlige for v3-lesninger (listen utelater dem, GET gir 404), dobbeltles til drainert, og fjern så de gamle veiene.
• Innskudds-routing og instructions kan roteres, gjengi alltid den nyeste GET-en, og vis alltid referansekoden.
• Webhooks er hint; GET er sannheten, dedupliser på hendelses-id, gjenopprett tapte hendelser med updatedAfter.

​

Neste steg