Migreren naar v3

• Deel 1, het concept. Lees dit eerst. v3 is een herontwerp, geen hernoeming: als u oude endpoints één-op-één in kaart brengt, werkt u tegen de API in. Tien minuten hier bespaart u later dagen.
• Deel 2, de API. Endpoint-voor-endpoint mapping, voorbeeldverzoeken, toestandsmachines en een migratiechecklist.

​

Deel 1, het concept

​

1.1 Waarom v3 bestaat

​

1.2 Het objectmodel

1. Capabilities sturen alles. Accounts worden ingericht onder een ready capability; quotes worden geprijsd tegen een capability. Onboarding komt neer op de benodigde capabilities naar ready brengen.
2. Tasks kunnen overal aan hangen. Een capability, een account of een lopende transfer kan openTaskIds dragen. Waar u ze ook ziet, de loop is hetzelfde: task lezen, antwoorden indienen, wachten op beoordeling, het bovenliggende object opnieuw lezen.

​

1.3 Gereedheid is per capability, niet per klant

• “Kan hij transacties doen op X?” wordt capability X status == "ready".
• “Moet hij iets doen?” wordt een task met status action_required (de capability toont doorgaans restricted met statusReason.resolution: "complete_tasks").
• “Wachten wij op Swipelux?” wordt tasks in in_review, capability pending.

​

1.4 De taakloop

• Een task bevat requirements[], de afzonderlijke vragen. Elk heeft een taakspecifieke requirementId, een stabiele key die de vraag benoemt (bijvoorbeeld adresbewijs, dedupliceer uw UI hierop) en een getypeerd request dat exact beschrijft welke invoer wordt gevraagd (tekst, datum, keuze, document, verklaring, enzovoort).
• Indienen is beoordeling-gestuurd: het muteert nooit direct de status van een capability of account, dat doet acceptatie. Eén uitzondering: profile-antwoorden schrijven bij indienen door naar het klantprofiel (2.3). Poll na indienen de task of de bovenliggende resource.
• taskRevision (echo van de revision van de task) is een concurrency-beveiliging: is de task gewijzigd sinds u hem las, lees dan opnieuw en bouw uw antwoorden opnieuw op.
• absence is een volwaardig antwoord (“Ik heb dit niet omdat …”), gebruik het in plaats van vereisten open te laten.

​

1.5 Geldbewegingen

​

1.6 Eén toestandsmachine per resource

​

1.7 Conventies

• Een sleutel hergebruiken met een andere body geeft 409 idempotency_conflict zolang de sleutel wordt bewaard (ten minste 7 dagen), plan dus nooit hergebruik van een sleutel. Genereer per logische bewerking een verse UUID en bewaar die bij uw job.
• De replay dekt ook fouten: eindigde de oorspronkelijke aanvraag in een terminale 4xx, dan levert dezelfde sleutel plus body dezelfde probleemantwoord opnieuw op.
• Twee gelijktijdige aanvragen met dezelfde sleutel: één wint, de ander krijgt 409. Doe de verliezer opnieuw nadat de winnaar is afgehandeld; de replay geeft het oorspronkelijke antwoord terug.

​

1.8 Het gouden pad

​

Deel 2, de API

​

2.1 Klanten

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

• Aanmaken is progressief: { "type": "individual" } op zichzelf is een geldige create. Ontbrekende feiten maken de klant nooit ongeldig, ze duiken later op als intake-tasks op de capabilities die ze nodig hebben.
• Bedrijven dragen business plus registratiegegevens. Het shareholder-CRUD van v1 wordt gemapt op related parties, verbreed om directors, officers en owners te omvatten: maak ze inline bij het aanmaken van de klant (elk krijgt een stabiele rp_-id) of beheer ze via de dedicated related-parties-endpoints.
• Geen klant-status-veld, zie 1.3.
• Bestaande klanten worden overgenomen: klanten die op v1 of v2 zijn aangemaakt, zijn met dezelfde id adresseerbaar via v3-endpoints. Het v3-lezen is een gesaneerde weergave, legacy-waarden die de v3-validatie niet halen, komen als afwezig terug. Na uw eerste v3-write wordt die weergave permanent: afwezige waarden komen niet vanzelf terug. Verrijk dus vroeg, plan een eenmalige pass die het volledige profiel uit uw eigen records via PATCH inzet voordat u op v3-reads vertrouwt. v1-metadata is een aparte namespace en wordt niet overgenomen, zet het opnieuw op v3.
• externalId is eersteklas en uniek over al uw klanten op v3, per omgeving (409 duplicate_external_id). Het archiveren van een klant geeft zijn externalId niet vrij, wis het via PATCH voor DELETE als u het wilt hergebruiken.
• DELETE is een archiveringscascade (geen herstel; ids worden nooit hergebruikt). Deze wordt geblokkeerd met 409 customer_has_active_resources plus blockingResources[] zolang er een niet-gearchiveerd account of lopende transfer bestaat.
• PATCH-mergeregels: expliciete null wist een nullable veld, arrays vervangen volledig (behalve inline related parties, die per id worden ge-upsert), metadata-sleutels worden samengevoegd. Volledige schema’s en lijstfilters staan in de OpenAPI-specificatie.

​

2.2 /rails, /banks, applications worden Capabilities

• Een capability is method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers, enzovoort) plus accountType (pooled of named, null voor niet-bankmethoden) plus directions (payin of payout). De publieke capabilityId is het gekwalificeerde paar (sepa_pooled, ach_named) of enkel de methode voor card en stablecoin_transfers.
• Elke capability-aanvraag genereert een application, het record per poging onder .../capabilities/{capabilityId}/applications (plus /{applicationId}/history), met eigen statussen (1.6) en statusReason. Het is het audit-spoor van een aanvraag; dagelijks poll u de capability zelf.
• capabilities/supported geeft beschikbaarheid (available, beta of disabled), geschiktheid en aangeboden instellingen terug. Bankselectie gebeurt bij aanvragen via de optionele institutions-array, er is geen aparte /banks-resource. Weglaten (of [] sturen) selecteert alle standaardinstellingen; isDefault: true is een klant- en capability-specifieke vlag, geen globale. Een niet-lege lijst overschrijft de standaarden, en een bank-gebaseerde capability zonder toepasselijke standaard geeft 422 capability_institutions_required. Instelling-ids zijn opaak, tolereer nieuwe.
• stablecoin_transfers wordt automatisch toegekend bij het aanmaken van de klant en wordt geboren als ready (wordt dus nooit aangevraagd en is niet annuleerbaar). card is enkel voor individuen.
• openTaskIds op de capability is uw “wat moet ik nu doen”-wijzer. Open betekent action_required of in_review, en de rollup omvat gedeelde tasks op klantniveau die via actieve afhankelijkheden bereikbaar zijn.
• cancel werkt alleen vanuit pending of restricted en zonder blokkerende resources, anders 409 capability_not_cancelable, waarvan de probleembody blockingResources opsomt. Opnieuw aanvragen na annuleren is een nieuwe create met een nieuwe idempotency-key.
• Poll de GET. Capability-status verversts wanneer u leest; poll GET .../capabilities/{capabilityId} of abonneer u op capability.status_changed, cache niet.
• Één methode aanvragen kan gerelateerde methoden meteen beschikbaar maken, behandel capabilities als een set die u opnieuw leest, niet als één rij die u volgt.
• Gebruik tasks-preview om onboarding-vragen te tonen voor u een aanvraag definitief indient.
• Verificatie is niet eenmalig: nieuwe tasks kunnen verschijnen op een reeds ready capability (periodieke of event-gedreven herverificatie). Houd de taakloop actief gedurende de hele levensduur van de klant, niet alleen tijdens onboarding.

​

2.3 Documenten en KYC worden Tasks en Submissions

• Ruwe bestandsopslag: POST/GET/DELETE /v3/customers/{customerId}/documents (plus /{documentId}), upload één keer met uw API-sleutel en verwijs dan naar document-ids in submission-antwoorden. Dit vervangt elke upload-token- en direct-upload-intake.
• Geheel nieuw: GET /v3/tasks (merchant-brede inbox), GET /v3/transfers/{transferId}/tasks, GET .../tasks/{taskId}/history, GET .../tasks/{taskId}/submissions (plus /{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" } }
  ]
}

• Antwoordtypes: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. Het request-object van elke requirement zegt welk type wordt verwacht.
• Een submission moet elke actionable requirement in de huidige ronde beantwoorden, met exact de taskRevision die u hebt gelezen. Deelsubmissions worden afgewezen.
• profile-antwoorden schrijven door: ze werken het klantprofiel bij via het normale validatiepad en evalueren onmiddellijk elke capability opnieuw die naar hetzelfde intake-werk verwijst. Broer-en-zus intake-tasks waarvan alle requirements zijn voldaan, sluiten automatisch.
• Requirements kunnen alternatieve groepen vormen (alternativeKey): dien er precies één van de groep in.
• changes_requested verhoogt remediationRound en draagt reviewFeedback. Lees de task opnieuw en dien opnieuw in met een nieuwe idempotency-key.
• Gehoste verificatie-URL’s verschijnen enkel in klantgeschopte task-details (GET /v3/customers/{customerId}/tasks/{taskId}) en alleen zolang de sessie actionable is; lijsten en GET /v3/tasks/{taskId} zijn bewust URL-vrij.
• De gebruiksvoorwaarden zijn ook een task: openTaskIds kan een task met category: "terms_of_service" bevatten waarvan de gehoste acceptatiepagina op dezelfde manier is gekoppeld (alleen klantgeschopte detail). Generieke submissions kunnen geen voorwaarden accepteren, en KYC-goedkeuring impliceert nooit acceptatie van voorwaarden.
• Tasks zijn per capability afgebakend, dus dezelfde vraag (bijvoorbeeld adresbewijs) kan eenmaal per capability verschijnen. Dedupliceer in uw UI op de requirement key.
• Geen vertaallaag: posten naar /v1/documents deblokkeert geen v3-capabilities. Zodra een klant op v3 is, drijf u alle vragen via tasks.

​

2.4 Accounts en 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 op uitgegeven bankrekeningen is optioneel (standaard per methode); op externe bankrekeningen geeft u het expliciet op. Walletrekeningen hebben helemaal geen land.
• settlement.accountId is verplicht op uitgegeven bankrekeningen: het benoemt de uitgegeven walletrekening die verrekende gelden uit stortingen op de bankrekening ontvangt.
• Uitgegeven accounts stellen details (IBAN of routing plus account of adres) bloot, geversioneerd routing (stortingscoördinaten kunnen roteren, render altijd de nieuwste lees), fees, balances.
• Netwerken: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• De capability-poort geldt alleen voor uitgegeven accounts: er een maken tegen een niet-ready capability mislukt met een capability-gecodeerde fout, vraag eerst de capability aan (2.2). Externe accounts hebben geen capability nodig (en geen klantgoedkeuring); ze krijgen alleen validatie van het request-schema en de bankgegevens.
• Uitgegeven bankrekeningen worden provisioning geboren met details: null. Poll de rekening of let op account.status_changed tot ready.
• DELETE archiveert, verwijdert nooit hard. Rekeningen waarnaar lopende transfers verwijzen, geven 409 account_has_active_transfers. Doe het opnieuw nadat die transfers een terminale toestand hebben bereikt.
• Nieuw in v3: Rules, doorlopende instructies op een uitgegeven walletrekening (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}) die inkomende gelden automatisch doorsluizen naar een andere rekening of een wallet-destination. Geen v1- of v2-equivalent.

​

2.5 Recipients en destinations

• Recipient is het wie: individual (voor- en achternaam) of business (bedrijfsnaam), met verplichte relationship (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Recipients en destinations zijn enkel voor derden. Een uitbetaling aan uzelf gebruikt helemaal geen recipient: richt op een van de eigen acc_-rekeningen van de klant als quote destinationId (2.6).
• Destination is het waar: getypeerd per methode, sepa (iban, bic optioneel), ach of wire (routing plus account), swift (volledige coördinaten plus optionele intermediair), spei (clabe), pse, transfers_3_0 (cbu) enzovoort, plus wallet-destinations. Elke destination heeft een eigen status. Let op destination.status_changed.
• Fiat-destinations vereisen het complete address van de recipient (straat, stad, postcode, land) voor het aanmaken. Ontbrekende onderdelen falen met 422 recipient_address_required. Wallet-destinations slaan het adres over, maar vereisen bovenaan ownership (self_custodied, of custodial met een custodian-naam).
• De correctheid van de begunstigde-naam is belangrijk: ontvangende banken vergelijken de wettelijke naam van de rekening. Stuur exacte wettelijke voor- plus achternaam of bedrijfsnaam, geen weergavebijnaam.
• Veldschema’s per methode voor destinations staan in de OpenAPI-specificatie.

​

2.6 Quotes en 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 neemt een acc_-id (rekening van de klant) of een dst_-id (recipient-destination). Fiat-gefinancierde quotes (payins) moeten op een acc_-rekening richten, een dst_-doel betekent altijd een payout (anders 422 quote_direction_invalid).
• externalId op quotes en transfers is een niet-unieke correlatiereferentie (weergegeven bij reads, filterbaar op lijsten). De regel over uniciteit per omgeving (2.1) geldt alleen voor de externalId van de klant.
• Voer een quote precies één keer uit, voor expiresAt. Een vervallen quote faalt met 409 quote_expired, een tweede uitvoering met 409 quote_already_executed (het probleem bevat de bestaande transferId).
• Transfer annuleren wordt nog niet ondersteund: POST .../cancel geeft in elke toestand 409 transfer_not_cancelable. Huidige canceled transfers komen door het verlopen van het financieringsvenster op een ongefinancierde payin, niet door dit endpoint.
• Payins starten in awaiting_funds: render GET .../instructions voor de betaler, bankcoördinaten plus referentie- of memo-code voor fiat, stortingsadres voor crypto. De referentiecode is hoe de storting wordt gematcht. Toon deze altijd.
• state plus stateDetail voor machineleesbare substaten; action_required betekent dat een compliance-task is bijgevoegd (openTaskIds, GET .../tasks), beantwoord via submissions.
• Inkomende stortingen die op uitgegeven rekeningen worden gedetecteerd, verschijnen als transfers met origin: "inbound_deposit" (in plaats van "quoted").
• Betaalnetwerk-referenties zijn geconsolideerd onder references: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Transfers steken niet over tussen versies. Op v1 of v2 aangemaakte transfers zijn niet leesbaar vanuit v3. De lijst laat ze weg en GET /v3/transfers/{transferId} geeft 404. Zet eerst het aanmaken over, houd het v1-leespad tot die transfers terminale toestanden bereiken en laat het dan vallen.
• Geen token-swaps. stablecoin_move vereist dezelfde valuta in en uit: USDC naar USDT faalt met 422 recipient_destination_invalid met een currency_mismatch-veldfout. Zelfde netwerk aan beide kanten, geen bridging, en wallet-naar-wallet-bewegingen ondersteunen momenteel alleen kostenvrije levering: een quote waarvan de platform- of ontwikkelaarsfee niet nul is, faalt met 422 amount_not_deliverable.

​

2.7 Webhooks

• GET /v3/webhooks/portal geeft een gehoste management-portaal-URL terug voor bezorglogs, retries en handmatige replays.
• transfer.created wordt momenteel geleverd in de legacy v1-payloadvorm (de v3-envelop wordt actief wanneer v1-webhooks worden uitgefaseerd). Beschouw het puur als een hint en haal de transfer op via GET; bouw niet op de body ervan.
• Gebeurtenissen zijn hints: haal bij ontvangst de resource op en handel op basis van de read. Bouw nooit toestand op basis van event-payloads of volgorde. Bezorging is at-least-once en kan vertraagd of herordend zijn. Dedupliceer op event-id en herstel gemiste gebeurtenissen met de inclusieve updatedAfter-filter van elke lijst.
• Abonneer u op api.deprecation, het machinale kanaal voor versie-uitfaseringen.
• Vandaag geen task.*-gebeurtenis: poll na indienen de task of zijn bovenliggende object.

​

2.8 Sandbox

​

2.9 Legacy-endpoints zonder v3-vervanging

​

2.10 Voorgestelde migratievolgorde

​

2.11 Valkuilenchecklist

• Verse UUID per logische bewerking, bewaard bij uw job en hergebruikt bij retry; hergebruik een sleutel nooit met een gewijzigde body (409 idempotency_conflict). Sandbox-endpoints zijn vrijgesteld van de header.
• Verrijk bestaande klanten (PATCH het volledige profiel, zet metadata opnieuw, dat wordt niet overgenomen) voor elke andere v3-write, de eerste v3-write maakt de gesaneerde weergave permanent.
• externalId is uniek per omgeving en wordt niet vrijgegeven door archiveren, wis via PATCH voor DELETE als u van plan bent hem opnieuw te gebruiken.
• Er bestaat geen klant-status-veld, leid gereedheid af per capability.
• action_required en in_review betekenen beide een openstaande task.
• Submissions zijn beoordeling-gestuurd (indienen is niet hetzelfde als gedeblokkeerd) en moeten elke actionable requirement met de exacte taskRevision beantwoorden. Bij mismatch opnieuw lezen en opnieuw opbouwen.
• Er bestaat geen task.*-webhook, poll de task (of zijn bovenliggende object) na elk indienen.
• Retry bij changes_requested betekent task opnieuw lezen, nieuwe antwoorden, nieuwe idempotency-key.
• Posten naar /v1/documents deblokkeert nooit een v3-capability, zodra een klant op tasks zit, drijf u elke vraag via tasks.
• Nieuwe tasks kunnen verschijnen op een reeds ready capability, houd de taakloop actief na onboarding, niet alleen tijdens.
• Capability cancel werkt alleen vanuit pending of restricted zonder blokkerende resources (409 capability_not_cancelable); opnieuw aanvragen na annuleren is een nieuwe create met een nieuwe idempotency-key.
• Capability moet ready zijn voor u er accounts onder uitgeeft of ertegen quotes maakt.
• Quote heeft een bedrag aan precies één kant; geen richtingsveld; precies één keer uitvoeren voor expiresAt (409 quote_expired of 409 quote_already_executed).
• Stablecoin-bewegingen zijn alleen dezelfde valuta en hetzelfde netwerk (USDC naar USDT faalt 422); wallet-naar-wallet ondersteunt alleen kostenvrije levering.
• DELETE archiveert, verwijdert nooit hard. Account-delete wordt geblokkeerd door lopende transfers (409 account_has_active_transfers); klant-delete daarnaast door elk niet-gearchiveerd account (409 customer_has_active_resources, blockingResources[] benoemt ze).
• v1- of v2-transfers zijn onzichtbaar voor v3-reads (lijst laat ze weg, GET geeft 404), dubbel-lees tot leeg, en laat dan de oude paden vallen.
• Stort-routing en instructions kunnen roteren, render altijd de laatste GET en toon altijd de referentiecode.
• Webhooks zijn hints; GET is de waarheid, dedupliceer op event-id, herstel gemiste gebeurtenissen met updatedAfter.

​

Volgende stap