- Osa 1, konsepti. Lue tämä ensin. v3 on uudelleensuunnittelu, ei uudelleennimeäminen: jos yhdistät vanhat päätepisteet yksi yhteen, taistelet APIa vastaan. Kymmenen minuuttia täällä säästää sinulta päiviä myöhemmin.
- Osa 2, API. Päätepiste kerrallaan -kartoitus, esimerkkipyynnöt, tilakoneet ja migraation tarkistuslista.
api.deprecation saadaksesi käytöstäpoistoilmoitukset.
Sisältö. Osa 1: 1.1 miksi v3 on olemassa, 1.2 objektimalli, 1.3 valmius per capability, 1.4 task-silmukka, 1.5 rahansiirto, 1.6 tilakoneet, 1.7 käytännöt, 1.8 kultainen polku. Osa 2: 2.1 asiakkaat, 2.2 capabilities, 2.3 tasks ja submissions, 2.4 tilit, 2.5 vastaanottajat ja destinations, 2.6 quotes ja transfers, 2.7 webhookit, 2.8 sandbox, 2.9 vanhat päätepisteet, 2.10 migraatiojärjestys, 2.11 sudenkuoppien tarkistuslista.
Osa 1, konsepti
1.1 Miksi v3 on olemassa
v1 ja v2 kasvattivat neljä päällekkäistä tapaa saattaa asiakas maksuvalmiiksi:/rails, /banks, /accounts/applications ja yritysten rail-applications-pinta, kullakin oma tilasanastonsa. Asiakirjankeruu (/documents, KYC-tuonnit, verifiointi-SDK-tokenit) oli irrallaan siitä, minkä sen piti todella avata. v3 tiivistää kaiken tämän kuudeksi resurssiksi, asiakas plus viisi asiaa, jotka se omistaa:
1.2 Objektimalli
Kaksi rakenteellista sääntöä sisäistettäväksi:- Capabilities ohjaavat kaikkea. Tilit alustetaan
ready-tilaisen capabilityn alle; quotet hinnoitellaan capabilitya vasten. Onboarding tarkoittaa tarvittavien capabilityjen saattamistaready-tilaan. - Taskit voivat liittyä mihin tahansa. Capability, tili tai käynnissä oleva transfer voi kantaa
openTaskIds-arvoa. Missä ikinä näetkin niitä, silmukka on sama: lue task, lähetä vastaukset, odota arviointia, lue vanhempi uudelleen.
1.3 Valmius on capability-kohtainen, ei asiakaskohtainen
v1 sekoitti/rails-valmiuden asiakaslaajuiseen KYC-porttiin. v3:ssa ei ole asiakaskohtaista tilaa: asiakas voi olla täysin käyttökelpoinen stablecoin_transfers-toiminnossa, kun taas hänen sepa-capabilityllaan on vielä avoimia taskeja. Yhteispoolattujen tilien capabilityt saavuttavat yleensä ready-tilan nopeammin kuin nimetyt, joten aloita transaktiot sillä, mikä on ready, sen sijaan että odottaisit kaikkea.
Jos v1- tai v2-koodisi ohjaa käyttöliittymämerkkejä asiakkaan verifiointitilan mukaan, kirjoita se uudelleen:
- “Voiko hän tehdä transaktioita X:llä?” muuttuu muotoon capability X
status == "ready". - “Pitääkö hänen tehdä jotain?” muuttuu muotoon mikä tahansa task tilassa
action_required(capability näyttää tyypillisestirestrictedjastatusReason.resolution: "complete_tasks"). - “Odotammeko Swipeluxia?” muuttuu muotoon tasks
in_review, capabilitypending.
1.4 Task-silmukka
Kaikki, mitä vanha asiakirja- ja KYC-pinta teki, on nyt tämä yksi silmukka: Keskeisiä ominaisuuksia:- Task kantaa
requirements[]-taulukon, eli yksittäiset pyynnöt. Kullakin on task-kohtainenrequirementId, vakaakey, joka nimeää pyynnön (esimerkiksi osoitteentodistus, dedupliko käyttöliittymäsi sillä), ja tyypitettyrequest, joka kuvaa täsmälleen millaista syötettä halutaan (teksti, päivämäärä, valinta, asiakirja, vakuutus ja niin edelleen). - Lähettäminen on arviointi-ohjattua: se ei koskaan muuta capabilityn tai tilin tilaa suoraan, hyväksyminen tekee sen. Yksi poikkeus:
profile-vastaukset kirjoittavat lähetyshetkellä läpi asiakasprofiiliin (2.3). Lähettämisen jälkeen pollaa taskia tai vanhempiresurssia. taskRevision(taskinrevision-arvon kaiku) on samanaikaisuuden suoja: jos task on muuttunut sen jälkeen kun luit sen, lue uudelleen ja rakenna vastauksesi uudelleen.absenceon täysivaltainen vastaus (“Minulla ei ole tätä, koska …”), käytä sitä sen sijaan että jättäisit pyynnöt roikkumaan.
1.5 Rahansiirto
Yksi virtaus payineille, payouteille ja stablecoin-siirroille. Suuntaparametria ei ole, et koskaan ilmoita payinia vs. payoutia. Sisään- ja ulostulovaluuttojen muodot johtavat vain luettavandirection-arvon quoteen ja transferiin: fiat_to_stablecoin (payin), stablecoin_to_fiat (payout) tai stablecoin_move.
1.6 Yksi tilakone per resurssi
Jokaisella tilaa kantavalla resurssilla on oma enum, ja jokainen ei-onnellinen tila kantaa jäsenneltyä syytä. Tilit, applicationit ja transferit jakavat muodon{ code, message, actor, retryable }: tilit ja applicationit paljastavat sen nimellä statusReason, transferit nimellä stateDetail. actor kertoo, kenen täytyy toimia (customer, developer, provider, network, swipelux), retryable kertoo, voiko uudelleenyrittäminen auttaa. Capabilities käyttävät muotoa { code, resolution, message }, jossa resolution (complete_tasks, wait, contact_support, none) kertoo, mikä vie capabilitya eteenpäin. code-arvot muodostavat avoimen, vain kasvavan luettelon: haaraudu resolution-arvon (tai actor plus retryable) perusteella ja siedä koodeja, joita et ole koskaan aiemmin nähnyt.
Tilat, joita tämä opas ei käy läpi (
rejected, suspended, disabled, failed, canceled), ovat päättyviä tai tukilähtöisiä; resurssikohtaiset määritelmät ovat spesifikaatiossa.
Transfer, piirrettynä:
1.7 Käytännöt
Idempotenssisääntöjä, jotka kannattaa sisäistää ennen koodin kirjoittamista:
- Avaimen uudelleenkäyttö eri rungolla tuottaa
409 idempotency_conflictniin kauan kuin avain säilytetään (vähintään 7 päivää), joten älä koskaan suunnittele uudelleenkäyttöä. Luo tuore UUID per looginen operaatio ja säilytä se työn kanssa. - Toisto kattaa myös virheet: jos alkuperäinen pyyntö päättyi päättyvään 4xx:ään, sama avain plus runko palauttaa saman virhevastauksen uudelleen.
- Kaksi samanaikaista pyyntöä samalla avaimella: toinen voittaa, toinen saa
409. Yritä häviäjää uudelleen sen jälkeen kun voittaja on ratkennut; toisto palauttaa alkuperäisen vastauksen.
1.8 Kultainen polku
Osa 2, API
2.1 Asiakkaat
Luonti, erotettuna
type-kentän perusteella (havainnollistavat arvot, kenttänimet spesifikaation mukaisia):
- Luonti on progressiivinen:
{ "type": "individual" }yksinään on kelvollinen luonti. Puuttuvat tiedot eivät koskaan tee asiakkaasta virheellistä, ne tulevat myöhemmin esiin intake-taskeina niissä capabilityissa, jotka niitä tarvitsevat. - Yritykset kantavat
business-tiedon plus rekisteröintitiedot. v1:n shareholder-CRUD kuvautuu related parties -kokonaisuuteen, joka on laajennettu kattamaan johtajat, toimihenkilöt ja omistajat: luo ne inline asiakkaan luonnissa (kukin saa vakaanrp_-tunnisteen) tai hallinnoi niitä omistetuilla related-parties-päätepisteillä. - Ei asiakas-
status-kenttää, katso 1.3. - Nykyiset asiakkaat siirtyvät mukana: v1:llä tai v2:lla luodut asiakkaat ovat osoitettavissa samalla tunnisteella v3-päätepisteissä. v3-luku on puhdistettu näkymä, vanhat arvot, jotka eivät läpäise v3-validointia, palautuvat poissaolevina. Ensimmäisen v3-kirjoituksen jälkeen tämä näkymä muuttuu pysyväksi: poissa olevat arvot eivät palaa itsestään. Rikasta siis aikaisin, budjetoi kertaluontoinen ajokerta, joka
PATCH-aa täydellisen profiilin omista tietueistasi ennen kuin luotat v3-lukuihin. v1-metadataon erillinen nimiavaruus eikä sitä siirretä, aseta se uudelleen v3:ssa. externalIdon ensiluokkainen ja yksilöllinen kaikkien asiakkaidesi kesken v3:ssa, ympäristökohtaisesti (409 duplicate_external_id). Asiakkaan arkistointi ei vapauta hänenexternalId-arvoaan, tyhjennä se PATCH:lla ennen DELETE:ä, jos aiot käyttää sitä uudelleen.DELETEon arkistointikaskadi (ei palautusta; tunnisteita ei koskaan käytetä uudelleen). Se estetään tuottamalla409 customer_has_active_resourcesplusblockingResources[]niin kauan kuin arkistoimaton tili tai käynnissä oleva transfer on olemassa.- PATCH-yhdistämissäännöt: nimenomainen
nulltyhjentää nullable-kentän, taulukot korvataan kokonaan (paitsi inline related parties, jotka upsertataan tunnisteen mukaan),metadata-avaimet yhdistetään. Täydelliset skeemat ja listasuodattimet ovat OpenAPI-spesifikaatiossa.
2.2 /rails, /banks, applications muuttuvat Capabilityiksi
- Capability on
method(ach,wire,rtp,pix,sepa,swift,spei,pse,transfers_3_0,faster_payments,sepa_instant,uaefts,card,stablecoin_transfersja niin edelleen) plusaccountType(pooledtainamed,nullei-pankkimenetelmille) plusdirections(payintaipayout). JulkinencapabilityIdon määritelty pari (sepa_pooled,ach_named) tai pelkkä menetelmäcard- jastablecoin_transfers-tapauksissa. - Jokainen capability-pyyntö synnyttää applicationin, per-yritys-tietueen osoitteessa
.../capabilities/{capabilityId}/applications(plus/{applicationId}/history), omilla tiloillaan (1.6) jastatusReason-arvolla. Se on pyynnön kirjausjälki; päivittäin pollaat itse capabilitya. capabilities/supportedpalauttaa saatavuuden (available,betataidisabled), kelpoisuuden ja tarjolla olevat instituutiot. Pankin valinta tapahtuu pyyntöhetkellä valinnaiseninstitutions-taulukon kautta, erillistä/banks-resurssia ei ole. Sen jättäminen pois (tai[]-arvon lähettäminen) valitsee kaikki oletusinstituutiot;isDefault: trueon asiakas- ja capability-kohtainen lippu, ei globaali. Ei-tyhjä lista syrjäyttää oletukset, ja pankkituetulle capabilitylle, jolla ei ole sovellettavaa oletusta, palautetaan422 capability_institutions_required. Instituutiotunnisteet ovat läpinäkymättömiä, siedä uusia.stablecoin_transfersmyönnetään automaattisesti asiakkaan luonnissa ja syntyy tilaanready(sitä ei siis koskaan pyydetä eikä sitä voi peruuttaa).cardon vain yksityishenkilöille.openTaskIdscapabilityssa on “mitä teen seuraavaksi” -osoittimesi. Avoin tarkoittaaaction_requiredtaiin_review, ja koonti sisältää jaetut asiakastason taskit, jotka tavoitetaan aktiivisten riippuvuuksien kautta.canceltoimii vain tiloistapendingtairestrictedja ilman estäviä resursseja, muuten409 capability_not_cancelable, jonka virherunko listaablockingResources. Uudelleen pyytäminen peruutuksen jälkeen on tuore luonti uudella idempotency-avaimella.- Pollaa GET. Capabilityn tila päivittyy, kun luet; pollaa
GET .../capabilities/{capabilityId}tai tilaacapability.status_changed, älä cachettaa. - Yhden menetelmän pyytäminen voi tehdä sukulaismenetelmistä välittömästi saatavilla, käsittele capabilityja joukkona, jonka luet uudelleen, älä yksittäisenä rivinä, jota seuraat.
- Käytä
tasks-previewnäyttääksesi onboarding-pyynnöt ennen sitoutumista pyyntöön. - Verifiointi ei ole kertaluontoinen: uusia taskeja voi ilmestyä jo
ready-tilaiselle capabilitylle (jaksottainen tai tapahtumavetoinen uusintaverifiointi). Pidä task-silmukka kytkettynä koko asiakkaan elinkaaren ajan, ei vain onboardingissa.
2.3 Asiakirjat ja KYC muuttuvat Taskeiksi ja Submissioneiksi
Nimeämishuomio. Nämä päätepisteet toimitettiin lyhyen aikaa nimillä
requirements ja fulfillments. 2.8.2026 alkaen julkiset nimet ovat tasks ja submissions. Uudelleennimeäminen koski vain resursseja ja päätepistepolkuja, taskin sisällä oleva requirements[]-taulukko ja sen requirementId säilyttävät nämä nimet.GET /v3/customers/{customerId}/tasks, vastaa POST .../tasks/{taskId}/submissions.
Tuon silmukan ympärillä:
- Raakatiedostojen tallennus:
POST/GET/DELETE /v3/customers/{customerId}/documents(plus/{documentId}), lataa kerran API-avaimellasi ja viittaa sitten asiakirjatunnisteisiin submission-vastauksissa. Tämä korvaa jokaisen upload-token- ja direct-upload-vastaanoton. - Aivan uudet luvut:
GET /v3/tasks(kauppiaslaajuinen postilaatikko),GET /v3/transfers/{transferId}/tasks,GET .../tasks/{taskId}/history,GET .../tasks/{taskId}/submissions(plus/{submissionId}).
- Vastaustyypit:
profile,text,date,single_select,multi_select,boolean,attestation,document,resource_reference,absence. Kunkin requirementinrequest-objekti kertoo, minkä tyypin se odottaa. - Submissionin on vastattava jokaiseen toimintaa vaativaan requirementiin nykyisellä kierroksella, tarkalla sinun lukemallasi
taskRevision-arvolla. Osittaiset submissionit hylätään. profile-vastaukset kirjoittavat läpi: ne päivittävät asiakasprofiilin normaalin validointireitin kautta ja arvioivat välittömästi uudelleen jokaisen samaan intake-työhön viittaavan capabilityn. Sisar-intake-taskit, joiden kaikki requirementit on täytetty, sulkeutuvat automaattisesti.- Requirementit voivat muodostaa vaihtoehtoisia ryhmiä (
alternativeKey): lähetä tasan yksi ryhmästä. changes_requestedkasvattaaremediationRound-arvoa ja kantaareviewFeedback-tietoa. Lue task uudelleen ja lähetä uudelleen tuoreella idempotency-avaimella.- Isännöidyt verifiointi-URLit näkyvät vain asiakaskohtaisessa task-detaljissa (
GET /v3/customers/{customerId}/tasks/{taskId}) ja vain niin kauan kuin istunto vaatii toimintaa; listat jaGET /v3/tasks/{taskId}ovat tarkoituksellisesti URL-vapaita. - Käyttöehdot ovat myös task:
openTaskIdsvoi sisältää taskincategory: "terms_of_service", jonka isännöity hyväksymissivu linkitetään samalla tavalla (vain asiakaskohtainen detalji). Yleiset submissionit eivät voi hyväksyä ehtoja, eikä KYC-hyväksyntä koskaan tarkoita ehtojen hyväksyntää. - Taskit on rajattu capability-kohtaisesti, joten “sama” pyyntö (esimerkiksi osoitteentodistus) voi ilmestyä kerran per capability. Dedupliko käyttöliittymässäsi requirementin
key-arvolla. - Ei käännöskerrosta:
/v1/documents-osoitteeseen postaaminen ei avaa v3-capabilityja. Kun asiakas on v3:ssa, ohjaa kaikki pyynnöt taskien kautta.
2.4 Tilit ja walletit
Luonti, erotettuna
origin-arvon plus type-arvon perusteella. Myönnetyt pankkitilit ottavat yhden method-arvon; ulkoiset pankkitilit ottavat sen sijaan methods-taulukon (method-arvon lähettäminen sinne hylätään):
countrymyönnetyillä pankkitileillä on valinnainen (oletusarvo per menetelmä); ulkoisilla pankkitileillä anna se nimenomaisesti. Wallet-tilit eivät kanna maata lainkaan.settlement.accountIdon pakollinen myönnetyillä pankkitileillä: se nimeää myönnetyn wallet-tilin, joka vastaanottaa pankkitilille tehtyjen talletusten selvitetyt varat.- Myönnetyt tilit paljastavat
details-kentän (IBAN tai routing plus tili tai osoite), versioidunrouting-kentän (talletuskoordinaatit voivat vaihtua, renderöi aina uusin luku),fees-kentän jabalances-kentän. - Verkot:
polygon,ethereum,base,arbitrum,optimism,bsc,avalanche. - Capability-portti koskee vain myönnettyjä tilejä: sellaisen luominen ei-valmiin capabilityn alle epäonnistuu capability-koodatulla virheellä, pyydä capability ensin (2.2). Ulkoiset tilit eivät tarvitse capabilitya (eivätkä asiakkaan hyväksyntää); ne saavat vain pyyntöskeeman ja pankkitietojen validoinnin.
- Myönnetyt pankkitilit syntyvät tilaan
provisioning,details: null. Pollaa tiliä tai tarkkaileaccount.status_changedkunnesready. DELETEarkistoi, ei koskaan poista lopullisesti. Tilit, joihin viitataan käynnissä olevista transfereista, palauttavat409 account_has_active_transfers. Yritä uudelleen sen jälkeen kun nuo transferit ovat saavuttaneet päättyvän tilan.- Uutta v3:ssa: Rules, pysyvät ohjeet myönnetyllä wallet-tilillä (
POST/GET /v3/customers/{customerId}/rules,GET/PATCH/DELETE .../rules/{ruleId}), jotka pyyhkäisevät saapuvat varat automaattisesti toiselle tilille tai wallet-destinationille. Ei v1- tai v2-vastinetta.
2.5 Vastaanottajat ja destinationit
v2:ssa ei ollut vastaanottajakäsitettä. Jos olet v2:ssa ja maksat kolmansille osapuolille, tämä on uusi pinta, ei uudelleennimeäminen.
- Recipient on kuka:
individual(etu- ja sukunimi) taibusiness(yrityksen nimi), pakollisellarelationship-arvolla (employee,contractor,vendor,subsidiary,merchant,customer,landlord,family,other). Recipients ja destinationit ovat vain kolmansille osapuolille. Ensimmäisen osapuolen maksu ei käytä recipientia lainkaan: kohdista quotendestinationId-arvoksi jokin asiakkaan omistaacc_-tileistä (2.6). - Destination on minne: menetelmäkohtaisesti tyypitetty,
sepa(iban, bic valinnainen),achtaiwire(routing plus tili),swift(täydet koordinaatit plus valinnainen välittäjä),spei(clabe),pse,transfers_3_0(cbu) ja niin edelleen, sekä wallet-destinationit. Jokaisella destinationilla on oma tilansa. Tarkkailedestination.status_changed. - Fiat-destinationit vaativat vastaanottajan täydellisen
address-tiedon (katu, kaupunki, postinumero, maa) ennen luontia. Puuttuvat osat epäonnistuvat virheellä422 recipient_address_required. Wallet-destinationit ohittavat osoitteen mutta vaativat ylätasonownership-arvon (self_custodiedtaicustodialcustodian-nimellä). - Edunsaajan nimen tarkkuus on tärkeää: vastaanottavat pankit vertailevat tilin laillista nimeä. Lähetä täsmällinen laillinen etu- plus sukunimi tai yrityksen nimi, älä näyttönimeä.
- Menetelmäkohtaiset destinationin kenttäskeemat löytyvät OpenAPI-spesifikaatiosta.
2.6 Quotes ja transfers
destinationIdottaaacc_-tunnisteen (asiakkaan omistama tili) taidst_-tunnisteen (vastaanottajan destination). Fiat-rahoitteisten quotesien (payinien) on kohdistettavaacc_-tiliin,dst_-kohde tarkoittaa aina payoutia (muuten422 quote_direction_invalid).externalIdquoteissa ja transfereissa on ei-yksilöllinen korrelaatioviite (kaikuu luvuissa, suodatettavissa listoissa). Ympäristökohtainen yksilöllisyyssääntö (2.1) koskee vain asiakkaanexternalId-arvoa.- Suorita quote tasan kerran, ennen
expiresAt-arvoa. Vanhentunut quote epäonnistuu virheellä409 quote_expired, toinen suoritus virheellä409 quote_already_executed(virhe kantaa olemassa olevantransferId-arvon). - Transferin peruutusta ei vielä tueta:
POST .../cancelpalauttaa409 transfer_not_cancelablejokaisessa tilassa. Nykyisetcanceled-transferit tulevat rahoitusikkunan vanhenemisesta rahoittamattomalla payinilla, eivät tästä päätepisteestä. - Payinit alkavat tilassa
awaiting_funds: renderöiGET .../instructionsmaksajalle, pankkikoordinaatit plus viite- tai memokoodi fiatille, talletusosoite kryptolle. Viitekoodi on tapa, jolla talletus yhdistetään. Näytä se aina. stateplusstateDetailkoneluettaviin alitiloihin;action_requiredtarkoittaa, että vaatimustenmukaisuustask on liitetty (openTaskIds,GET .../tasks), vastaa submissionien kautta.- Myönnetyillä tileillä havaitut saapuvat talletukset näkyvät transfereina, joilla on
origin: "inbound_deposit"(arvon"quoted"sijaan). - Maksuverkoston viitteet on koottu
references-kohtaan:transactionHash,traceNumber,imad,uetr,explorerUrl,returnedTransferId.
Kaksi migraatiovaroitusta:
- Transferit eivät ylitä versiorajoja. v1:llä tai v2:lla luodut transferit eivät ole luettavissa v3:sta. Lista jättää ne pois ja
GET /v3/transfers/{transferId}palauttaa 404. Siirrä luonti ensin, säilytä v1-lukupolku kunnes nuo transferit saavuttavat päättyvät tilat, ja poista se sitten. - Ei token-vaihtoja.
stablecoin_movevaatii saman valuutan sisään ja ulos: USDC:stä USDT:hen epäonnistuu virheellä422 recipient_destination_invalidjacurrency_mismatch-kenttävirheellä. Sama verkko molemmilla puolilla, ei siltausta, ja wallet-walletiin-siirrot tukevat tällä hetkellä vain maksutonta toimitusta: quote, jonka alusta- tai kehittäjämaksu ei ole nolla, epäonnistuu virheellä422 amount_not_deliverable.
2.7 Webhookit
Tapahtumaluettelo:
customer.created, customer.updated, customer.archived, capability.created, capability.status_changed, application.status_changed, recipient.status_changed, destination.status_changed, account.created, account.status_changed, account.details_changed, transfer.created, transfer.state_changed, api.deprecation.
GET /v3/webhooks/portalpalauttaa isännöidyn hallintaportaalin URLin toimituslokeille, uusintayrityksille ja manuaaliselle toistolle.transfer.createdtoimitetaan tällä hetkellä vanhalla v1-payload-muodolla (v3-kirjekuori aktivoituu, kun v1-webhookit poistetaan käytöstä). Käsittele se puhtaasti vihjeenä ja hae transfer GET:llä; älä rakenna sen rungon varaan.- Tapahtumat ovat vihjeitä: vastaanotettaessa hae resurssi ja toimi luvun perusteella. Älä koskaan rakenna tilaa tapahtuma-payloadin tai järjestyksen varaan. Toimitus on vähintään-kerran ja voi olla viivästynyt tai uudelleenjärjestetty. Dedupliko tapahtumatunnisteella ja palauta menetetyt tapahtumat kunkin listan sisältävällä
updatedAfter-suodattimella. - Tilaa
api.deprecation, versioiden käytöstäpoiston koneellinen kanava. - Ei
task.*-tapahtumaa tällä hetkellä: lähettämisen jälkeen pollaa taskia tai sen vanhempaa.
2.8 Sandbox
Sama perus-URL; sandbox-API-avain valitsee ympäristön.
v3-sandbox simuloi arviointisilmukan päästä päähän: luo task, lähetä siihen,
review se tilaan accepted tai rejected ja katso, kuinka capability aukeaa. Harjoittele korjaus-UX:si ennen tuotantoa. Sekä sandboxissa luodut taskit että pyydetyillä capabilityilla ilmestyvät tavalliset intake-taskit voidaan arvioida tällä tavoin; kuten tuotannossa, task-webhookeja ei laukaista, pollaa (2.7).
2.9 Vanhat päätepisteet ilman v3-korvaajaa
Näillä ei ole v3-korvaajaa. Useimmat pysyvät v1:ssä muuttumattomina (säilytä olemassa olevat kutsusi); kaksi poistetaan kokonaan (katso Käsittely):
Jokainen muu julkinen v1- tai v2-päätepiste esiintyy jossakin yllä olevista kartoitustaulukoista.
2.10 Ehdotettu migraatiojärjestys
Jokainen vaihe toimitetaan itsenäisesti; v1 tai v2 ja v3 ajavat rinnakkain samaa asiakaskuntaa vasten. Harjoittele jokaista vaihetta sandbox-avaimellasi (2.8) ennen kuin toistat sen tuotannossa.1
Perusinfrastruktuuri
Idempotency-Key kaikissa vaikuttavissa pyynnöissä (POST, PATCH, PUT, DELETE; sandbox-päätepisteet vapautettu); rahat merkkijonoina; kursorisivutuksen apurit.2
Webhookit
Rekisteröi v3-päätepisteet tapahtumaa kohti, mukaan lukien
api.deprecation. v1:n yhden päätepisteen konfiguraatio on erillinen pinta, jätä se paikoilleen; molemmat ajavat rinnakkain vaiheen 9 tyhjennykseen asti.3
Profiilin rikastaminen
PATCH /v3/customers/{id} täydellisellä profiililla, joka sinulla on (v1 keräsi vähemmän kuin v3 paljastaa), ja aseta metadata uudelleen. Tee tästä tietoisesti ensimmäinen v3-kirjoitus per asiakas: se täyttää puhdistetun näkymän ennen kuin siitä tulee pysyvä (2.1).4
Luvut
Osoita asiakas-, capability- ja tililukemat v3:een; kirjoita asiakastilan logiikka uudelleen kohdan 1.3 mukaan. Vasta vaiheen 3 jälkeen, rikastamattomat luvut palauttavat vanhat-virheelliset kentät poissaolevina.
5
Onboarding-kirjoitukset
Luo
POST /v3/customers -kutsulla; pyydä capabilityja /rails-, /banks- tai applicationien sijaan; rakenna task-silmukka (suurin uusi UI-työ, tasks-preview auttaa näyttämään pyynnöt etukäteen). Tästä eteenpäin lopeta /v1/documents-postaus v3-vetoisille asiakkaille, ne eivät avaa capabilityja (2.3).6
Tilit
Myönnä v3:n kautta; siirrä tuonnit
origin: external-arvoon.7
Maksut ulos
Vastaanottajat plus destinationit, sitten quote ja transfer.
8
Maksut sisään
Quote, transfer, instructions; jatka viitekoodin näyttämistä.
9
Tyhjennys
Transferit eivät ylitä versiorajoja (2.6). Säilytä v1- tai v2-lukupolku ja v1-webhook-päätepiste siellä luoduille transfereille, kaksoislue kunnes ne saavuttavat päättyvät tilat, ja poista sitten vanha asiakas ja v1-webhook-konfiguraatio.
2.11 Sudenkuoppien tarkistuslista
- Tuore UUID per looginen operaatio, säilytettynä työn kanssa ja uudelleenkäytettynä uusintayrityksessä; älä koskaan käytä avainta uudelleen muutetulla rungolla (
409 idempotency_conflict). Sandbox-päätepisteet on vapautettu otsakkeesta. - Rikasta olemassa olevat asiakkaat (
PATCHtäydellinen profiili, asetametadatauudelleen, se ei siirry) ennen mitään muuta v3-kirjoitusta, ensimmäinen v3-kirjoitus tekee puhdistetusta näkymästä pysyvän. -
externalIdon ympäristökohtaisesti yksilöllinen eikä sitä vapauteta arkistoinnissa, tyhjennä sePATCHilla ennenDELETEä, jos aiot käyttää sitä uudelleen. - Asiakas-
status-kenttää ei ole olemassa, johda valmius capability-kohtaisesti. -
action_requiredjain_reviewtarkoittavat molemmat avointa taskia. - Submissionit ovat arviointiohjattuja (lähettäminen ei ole sama kuin avattu) ja niiden on vastattava jokaiseen toimintaa vaativaan requirementiin tarkalla
taskRevision-arvolla. Ristiriidassa lue uudelleen ja rakenna uudelleen. -
task.*-webhookia ei ole olemassa, pollaa taskia (tai sen vanhempaa) jokaisen lähetyksen jälkeen. - Uusintayritys
changes_requested-tapauksessa tarkoittaa taskin lukemista uudelleen, tuoreita vastauksia, tuoretta idempotency-avainta. -
/v1/documents-osoitteeseen postaaminen ei koskaan avaa v3-capabilitya, kun asiakas on taskeissa, ohjaa jokainen pyyntö taskien kautta. - Uusia taskeja voi ilmestyä jo
ready-tilaiselle capabilitylle, pidä task-silmukka kytkettynä onboardingin jälkeen, ei vain sen aikana. - Capability
canceltoimii vain tiloistapendingtairestrictedilman estäviä resursseja (409 capability_not_cancelable); uudelleen pyytäminen peruutuksen jälkeen on tuore luonti tuoreella idempotency-avaimella. - Capabilityn on oltava
readyennen kuin sen alle myönnetään tilejä tai sitä vasten tehdään quoteja. - Quotessa on määrä tasan yhdellä puolella; ei suuntakenttää; suorita tasan kerran ennen
expiresAt-arvoa (409 quote_expiredtai409 quote_already_executed). - Stablecoin-siirrot ovat vain saman valuutan ja saman verkon (USDC:stä USDT:hen epäonnistuu
422); wallet-walletiin-siirrot tukevat vain maksutonta toimitusta. -
DELETEarkistoi, ei koskaan poista lopullisesti. Tilin poisto estyy käynnissä olevista transfereista (409 account_has_active_transfers); asiakkaan poisto lisäksi mistä tahansa arkistoimattomasta tilistä (409 customer_has_active_resources,blockingResources[]nimeää ne). - v1- tai v2-transferit ovat näkymättömiä v3-luvuille (lista jättää pois, GET palauttaa 404), kaksoislue kunnes tyhjennetty, poista sitten vanhat polut.
- Talletus-
routingja instructions voivat vaihtua, renderöi aina uusin GET ja näytä aina viitekoodi. - Webhookit ovat vihjeitä; GET on totuus, dedupliko tapahtumatunnisteella, palauta menetetyt tapahtumat
updatedAfter-suodattimella.