Migrace na v3

• Část 1, koncept. Přečtěte si nejprve. v3 je přepracování, nikoli přejmenování: pokud budete staré endpointy mapovat jeden ku jednomu, budete s API bojovat. Deset minut zde vám ušetří dny později.
• Část 2, API. Mapování endpoint po endpointu, ukázky požadavků, stavové automaty a kontrolní seznam migrace.

​

Část 1, koncept

​

1.1 Proč existuje v3

​

1.2 Objektový model

1. Capabilities řídí vše. Accounts se poskytují pod ready capability; quotes se cení proti capability. Onboarding se rovná získání capabilities, které potřebujete, do stavu ready.
2. Tasks se připojují kdekoli. Capability, account nebo probíhající transfer mohou nést openTaskIds. Kdekoli je uvidíte, smyčka je stejná: přečíst task, odeslat odpovědi, počkat na kontrolu, znovu přečíst rodiče.

​

1.3 Připravenost je per capability, ne per customer

• „Mohou obchodovat na X?” se stává capability X status == "ready".
• „Musí něco udělat?” se stává jakýkoli task se stavem action_required (capability typicky ukazuje restricted s statusReason.resolution: "complete_tasks").
• „Čekáme na Swipelux?” se stává tasks in_review, capability pending.

​

1.4 Task smyčka

• Task nese requirements[], jednotlivé požadavky. Každý má requirementId v rámci tasku, stabilní key pojmenovávající požadavek (například doklad o adrese, deduplikujte podle něj své UI) a typované request popisující přesně, jaký vstup se očekává (text, date, select, document, attestation atd.).
• Odesílání je řízené kontrolou: nikdy přímo nemění stav capability ani accountu, to dělá až akceptace. Jedna výjimka: odpovědi typu profile se při odeslání propisují do profilu customera (2.3). Po odeslání polluj task nebo rodičovský zdroj.
• taskRevision (ozvěna hodnoty revision u tasku) je ochrana konkurence: pokud se task od doby, co jste jej četli, změnil, přečtěte jej znovu a znovu sestavte své odpovědi.
• absence je plnohodnotná odpověď („Toto nemám, protože…”), použijte ji místo ponechávání požadavků nevyřešených.

​

1.5 Pohyb peněz

​

1.6 Jeden stavový automat na zdroj

​

1.7 Konvence

• Použití klíče s jiným body je 409 idempotency_conflict, dokud je klíč uchováván (nejméně 7 dní), takže nikdy neplánujte znovu použití klíče. Generujte čerstvý UUID na logickou operaci a uchovávejte jej se svou úlohou.
• Přehrání pokrývá i chyby: pokud původní požadavek skončil terminálním 4xx, stejný klíč plus body vrátí znovu stejnou problem odpověď.
• Dva souběžné požadavky se stejným klíčem: jeden vyhraje, druhý dostane 409. Poražený zkuste znovu po tom, co se vítěz usadí; přehrání vrátí původní odpověď.

​

1.8 Zlatá cesta

​

Část 2, API

​

2.1 Customers

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

• Vytváření je progresivní: samotné { "type": "individual" } je platné vytvoření. Chybějící fakta customera nikdy neznehodnotí, později se objeví jako intake tasks na capabilities, které je potřebují.
• Podniky nesou business plus registrační data. CRUD nad shareholdery ve v1 se mapuje na related parties, rozšířeno tak, aby pokrývalo directors, officers a owners: vytvořte je inline při vytváření customera (každý dostane stabilní rp_ id) nebo je spravujte přes dedikované related-parties endpointy.
• Neexistuje pole status na customerovi, viz 1.3.
• Stávající customers přecházejí: customers vytvoření na v1 nebo v2 jsou adresovatelní stejným id na v3 endpointech. v3 čtení je sanitizovaný pohled, legacy hodnoty, které selžou validací v3, přijdou nazpět chybějící. Po vašem prvním v3 zápisu se ten pohled stane trvalým: chybějící hodnoty se samy nevrátí. Proto obohaťte data brzy, naplánujte jednorázový průchod, který PATCHne plný profil ze svých vlastních záznamů předtím, než se začnete spoléhat na v3 čtení. metadata z v1 je oddělený namespace a není přeneseno, znovu jej nastavte ve v3.
• externalId je prvotřídní pole a unikátní napříč vašimi customers na v3, per prostředí (409 duplicate_external_id). Archivace customera neuvolní jeho externalId, vymažte jej pomocí PATCH před DELETE, pokud jej hodláte znovu použít.
• DELETE je archivační kaskáda (žádné obnovení; id se nikdy nepoužijí znovu). Blokuje se s 409 customer_has_active_resources plus blockingResources[], dokud existuje jakýkoli nearchivovaný account nebo probíhající transfer.
• Pravidla slučování PATCH: explicitní null vymaže nullable pole, pole se nahrazují celá (kromě inline related parties, které se upsertují podle id), klíče metadata se slučují. Kompletní schémata a filtry seznamů jsou v OpenAPI specifikaci.

​

2.2 Z /rails, /banks, applications se stanou Capabilities

• Capability se rovná method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers atd.) plus accountType (pooled nebo named, null pro nebankovní metody) plus directions (payin nebo payout). Veřejné capabilityId je kvalifikovaná dvojice (sepa_pooled, ach_named) nebo prostá metoda pro card a stablecoin_transfers.
• Každý požadavek na capability zplodí application, záznam za pokus pod .../capabilities/{capabilityId}/applications (plus /{applicationId}/history), s vlastními stavy (1.6) a statusReason. Je to audit trail požadavku; každodenně polluj samotnou capability.
• capabilities/supported vrací dostupnost (available, beta nebo disabled), způsobilost a nabízené instituce. Výběr banky probíhá při žádosti prostřednictvím volitelného pole institutions, neexistuje samostatný zdroj /banks. Vynechání (nebo poslání []) vybere všechny výchozí instituce; isDefault: true je příznak specifický pro customera a capability, nikoli globální. Neprázdný seznam přepíše výchozí a bankovní capability bez použitelné výchozí instituce vrátí 422 capability_institutions_required. Id institucí jsou neprůhledná, tolerujte nová.
• stablecoin_transfers je automaticky udělena při vytvoření customera a rodí se ready (proto se o ni nikdy nežádá a nelze ji zrušit). card je jen pro individual.
• openTaskIds na capability je váš ukazatel „co dělat dál”. Otevřený se rovná action_required nebo in_review, a souhrn zahrnuje sdílené tasky na úrovni customera dosažené přes aktivní závislosti.
• cancel funguje pouze z pending nebo restricted a bez blokujících zdrojů, jinak 409 capability_not_cancelable, jehož problem body uvádí blockingResources. Nové vyžádání po zrušení je čerstvé vytvoření s novým idempotency klíčem.
• Polluj GET. Stav capability se obnovuje při čtení; polluj GET .../capabilities/{capabilityId} nebo se přihlaste k odběru capability.status_changed, neukládejte do cache.
• Vyžádání jedné metody může naráz zpřístupnit související metody, ke capabilities přistupujte jako k množině, kterou znovu čtete, nikoli k jednomu řádku, který sledujete.
• Použijte tasks-preview, abyste ukázali onboarding požadavky před podáním žádosti.
• Verifikace není jednorázová: nové tasky se mohou objevit na už ready capability (periodická nebo událostmi řízená reverifikace). Držte task smyčku zapojenou po celou dobu života customera, ne jen během onboardingu.

​

2.3 Z Documents a KYC se stanou Tasks a Submissions

• Úložiště surových souborů: POST/GET/DELETE /v3/customers/{customerId}/documents (plus /{documentId}), nahrajte jednou se svým API klíčem, poté odkazujte na document ids v odpovědích submission. Toto nahrazuje každý upload-token a direct-upload intake.
• Zcela nová čtení: GET /v3/tasks (merchant-wide schránka), 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" } }
  ]
}

• Typy odpovědí: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. Objekt request každého požadavku vám řekne, jaký typ očekává.
• Submission musí odpovědět na každý akční požadavek v aktuálním kole, s přesnou hodnotou taskRevision, kterou jste přečetli. Částečná submissiona jsou odmítána.
• Odpovědi typu profile propisují: aktualizují profil customera přes běžnou validační cestu a okamžitě přehodnotí každou capability odkazující na stejnou intake práci. Sourozenecké intake tasky, jejichž požadavky jsou všechny splněny, se automaticky uzavírají.
• Požadavky mohou tvořit alternativní skupiny (alternativeKey): odešlete přesně jeden ze skupiny.
• changes_requested inkrementuje remediationRound a nese reviewFeedback. Přečtěte task znovu, znovu odešlete s čerstvým idempotency klíčem.
• URL hostované verifikace se objevují jen v detailu tasku scoped na customera (GET /v3/customers/{customerId}/tasks/{taskId}) a jen dokud je session akční; seznamy a GET /v3/tasks/{taskId} jsou záměrně bez URL.
• Podmínky služby jsou také task: openTaskIds může obsahovat task s category: "terms_of_service", jehož hostovaná stránka akceptace je odkazována stejně (jen v detailu scoped na customera). Obecná submissiona nemohou akceptovat podmínky a schválení KYC nikdy neimplikuje akceptaci podmínek.
• Tasks jsou scoped per capability, takže „stejný” požadavek (například doklad o adrese) se může objevit jednou per capability. Deduplikujte ve svém UI podle key požadavku.
• Žádná vrstva překladu: postování na /v1/documents neodblokuje v3 capabilities. Jakmile je customer na v3, veškeré požadavky žeňte přes tasky.

​

2.4 Accounts a 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 u issued bankovních účtů je volitelné (výchozí per metoda); u external bankovních účtů jej uveďte explicitně. Wallet účty nemají zemi vůbec.
• settlement.accountId je povinné u issued bankovních účtů: pojmenovává issued wallet účet, který přijímá vypořádané prostředky z vkladů na bankovní účet.
• Issued účty vystavují details (IBAN nebo routing plus account nebo address), verzované routing (souřadnice pro vklad se mohou rotovat, vždy vykreslete nejnovější čtení), fees, balances.
• Sítě: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• Brána capability platí jen pro issued účty: vytvořit jeden proti neready capability selže s chybou kódovanou capability, nejprve požádejte o capability (2.2). External účty capability nepotřebují (a ani schválení customera); dostanou jen validaci request-schema a bankovních detailů.
• Issued bankovní účty se rodí provisioning s details: null. Polluj účet nebo sleduj account.status_changed, dokud nebude ready.
• DELETE archivuje, nikdy nemaže natvrdo. Účty odkazované probíhajícími transfery vrátí 409 account_has_active_transfers. Opakujte po tom, co ty transfery dosáhnou terminálního stavu.
• Zcela nové ve v3: Rules, trvalé pokyny na issued wallet účtu (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}), které automaticky přesouvají příchozí prostředky na jiný účet nebo wallet destination. Bez ekvivalentu ve v1 nebo v2.

​

2.5 Recipients a destinations

• Recipient se rovná kdo: individual (křestní a příjmení) nebo business (název společnosti), s povinným relationship (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Recipients a destinations jsou jen pro třetí strany. First-party payout recipienta vůbec nepoužívá: cíluj jeden z customerových vlastních acc_ účtů jako destinationId u quote (2.6).
• Destination se rovná kam: typované per metoda, sepa (iban, bic volitelně), ach nebo wire (routing plus account), swift (plné souřadnice plus volitelně intermediary), spei (clabe), pse, transfers_3_0 (cbu) atd., plus wallet destinations. Každá destination má vlastní stav. Sledujte destination.status_changed.
• Fiat destinations vyžadují úplnou address recipienta (street, city, postal code, country) před vytvořením. Chybějící části selžou s 422 recipient_address_required. Wallet destinations vynechávají adresu, ale vyžadují top-level ownership (self_custodied nebo custodial se jménem custodiana).
• Přesnost jména beneficienta má význam: přijímající banky porovnávají právní jméno účtu. Posílejte přesné právní jméno a příjmení nebo název společnosti, nikoli zobrazovací přezdívku.
• Schémata polí destination per metoda jsou v OpenAPI specifikaci.

​

2.6 Quotes a 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 bere acc_ (customer-owned account) nebo dst_ (recipient destination) id. Fiat-funded quotes (payins) musí cílit acc_ účet, dst_ cíl vždy znamená payout (jinak 422 quote_direction_invalid).
• externalId na quotes a transfers je neunikátní korelační reference (vrácená při čtení, filtrovatelná v seznamech). Pravidlo unikátnosti per prostředí (2.1) platí jen pro customer externalId.
• Quote proveďte přesně jednou, před expiresAt. Vypršelý quote selže s 409 quote_expired, druhé provedení s 409 quote_already_executed (problem nese stávající transferId).
• Zrušení transferu zatím není podporováno: POST .../cancel vrací 409 transfer_not_cancelable v každém stavu. Dnešní canceled transfery přicházejí z vypršení funding okna u nefinancovaného payin, ne z tohoto endpointu.
• Payins začínají awaiting_funds: vykreslete GET .../instructions plátci, souřadnice banky plus referenční nebo memo kód pro fiat, deposit adresa pro krypto. Referenční kód je způsob, jak se vklad páruje. Vždy jej zobrazte.
• state plus stateDetail pro strojově čitelné podstavy; action_required znamená, že je připojen compliance task (openTaskIds, GET .../tasks), odpovídejte přes submissions.
• Příchozí vklady detekované na issued účtech se objevují jako transfery s origin: "inbound_deposit" (oproti "quoted").
• Reference platebních sítí jsou konsolidované pod references: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Transfery nepřecházejí mezi verzemi. Transfery vytvořené na v1 nebo v2 nejsou čitelné z v3. Seznam je vynechá a GET /v3/transfers/{transferId} vrátí 404. Přenechte nejprve vytváření, ponechte v1 čtecí cestu, dokud tyto transfery nedosáhnou terminálních stavů, a pak ji zahoďte.
• Žádné swapy tokenů. stablecoin_move vyžaduje stejnou měnu in a out: USDC na USDT selže s 422 recipient_destination_invalid nesoucí chybu pole currency_mismatch. Stejná síť na obou stranách, žádný bridging, a wallet-to-wallet přesuny aktuálně podporují jen doručení bez poplatku: quote s nenulovým platform nebo developer fee selže s 422 amount_not_deliverable.

​

2.7 Webhooks

• GET /v3/webhooks/portal vrací URL hostovaného management portálu pro delivery logy, opakování a manuální přehrání.
• transfer.created se aktuálně doručuje s legacy tvarem payloadu z v1 (v3 obálka se aktivuje, až v1 webhooks skončí). Berte to čistě jako náznak a GET si transfer; nestavějte proti jeho body.
• Události jsou náznaky: po přijetí GETněte zdroj a jednejte podle čtení. Nikdy nestavějte stav podle payloadu události nebo pořadí. Doručení je at-least-once a může být opožděné nebo přeuspořádané. Deduplikujte podle event id a chybějící události zotavujte pomocí inkluzivního filtru updatedAfter každého seznamu.
• Přihlaste se k odběru api.deprecation, strojového kanálu pro ukončení podpory verzí.
• Dnes žádná událost task.*: po odeslání polluj task nebo jeho rodiče.

​

2.8 Sandbox

​

2.9 Legacy endpointy bez náhrady ve v3

​

2.10 Doporučené pořadí migrace

​

2.11 Checklist záludností

• Čerstvý UUID per logická operace, uchovávaný s vaší úlohou a použitý znovu při opakování; nikdy nepoužívejte klíč znovu se změněným body (409 idempotency_conflict). Sandbox endpointy jsou z hlavičky vyňaty.
• Obohaťte stávající customery (PATCH celý profil, znovu nastavte metadata, nepřenáší se) před jakýmkoli dalším v3 zápisem, první v3 zápis učiní sanitizovaný pohled trvalým.
• externalId je unikátní per prostředí a archivací se neuvolní, vymažte jej přes PATCH před DELETE, pokud jej plánujete znovu použít.
• Neexistuje pole status u customera, připravenost odvozujte per capability.
• action_required i in_review obojí znamenají otevřený task.
• Submissions jsou řízené kontrolou (odeslání není totéž co odblokování) a musí odpovědět na každý akční požadavek s přesným taskRevision. Při neshodě přečtěte znovu a přebudujte.
• Neexistuje webhook task.*, po každém odeslání polluj task (nebo jeho rodiče).
• Opakování při changes_requested se rovná přečtení tasku znovu, čerstvé odpovědi, čerstvý idempotency klíč.
• Postování na /v1/documents nikdy neodblokuje v3 capability, jakmile je customer na tascích, veďte všechny požadavky přes tasky.
• Nové tasky se mohou objevit na už ready capability, držte task smyčku zapojenou i po onboardingu, ne jen během něj.
• cancel capability funguje jen z pending nebo restricted bez blokujících zdrojů (409 capability_not_cancelable); nové vyžádání po zrušení je čerstvé vytvoření s čerstvým idempotency klíčem.
• Capability musí být ready předtím, než pod ní vydáváte účty nebo proti ní quotujete.
• Quote má částku přesně na jedné straně; žádné pole směru; proveďte přesně jednou před expiresAt (409 quote_expired nebo 409 quote_already_executed).
• Stablecoin přesuny jsou pouze same-currency, same-network (USDC na USDT selže 422); wallet-to-wallet podporuje jen doručení bez poplatku.
• DELETE archivuje, nikdy nemaže natvrdo. Smazání účtu je blokováno probíhajícími transfery (409 account_has_active_transfers); smazání customera navíc jakýmkoli nearchivovaným účtem (409 customer_has_active_resources, blockingResources[] je jmenuje).
• Transfery v1 nebo v2 jsou pro čtení z v3 neviditelné (seznam vynechá, GET 404), čtěte duálně, dokud se nevypustí, poté zahoďte staré cesty.
• Deposit routing a instrukce se mohou měnit, vždy vykreslete nejnovější GET a vždy zobrazte referenční kód.
• Webhooks jsou náznaky; GET je pravda, deduplikujte podle event id, chybějící události zotavte pomocí updatedAfter.

​

Další krok