Migrare a v3

• Parte 1, il concetto. Leggi prima questa. v3 è un rimodellamento, non una rinominazione: se mappi i vecchi endpoint uno a uno, combatterai contro l’API. Dieci minuti qui ti fanno risparmiare giorni dopo.
• Parte 2, l’API. Mappatura endpoint per endpoint, esempi di richieste, macchine a stati e una check-list di migrazione.

​

Parte 1, il concetto

​

1.1 Perché esiste v3

​

1.2 Il modello di oggetti

1. Le capabilities regolano tutto. Gli account sono provisioned sotto una capability ready; le quote sono valutate contro una capability. L’onboarding equivale a portare a ready le capabilities che ti servono.
2. Le task si attaccano ovunque. Una capability, un account o un transfer in corso possono portare openTaskIds. Ovunque le vedi, il loop è lo stesso: leggere la task, inviare le risposte, attendere la revisione, rileggere il genitore.

​

1.3 La prontezza è per capability, non per customer

• “Può operare su X?” diventa capability X status == "ready".
• “Deve fare qualcosa?” diventa qualsiasi task con stato action_required (la capability tipicamente mostra restricted con statusReason.resolution: "complete_tasks").
• “Stiamo aspettando Swipelux?” diventa tasks in_review, capability pending.

​

1.4 Il loop delle task

• Una task porta requirements[], le singole richieste. Ognuna ha un requirementId per task, una key stabile che nomina la richiesta (per esempio prova di indirizzo, deduplica la tua UI su di essa) e una request tipizzata che descrive esattamente quale input è desiderato (testo, data, selezione, documento, attestazione, e così via).
• L’invio è soggetto a revisione: non muta mai direttamente lo stato della capability o dell’account, l’accettazione sì. Un’eccezione: le risposte profile si propagano al profilo del customer all’invio (2.3). Dopo l’invio, interroga la task o la risorsa genitore.
• taskRevision (eco della revision della task) è una protezione di concorrenza: se la task è cambiata dopo la lettura, rileggila e ricostruisci le tue risposte.
• absence è una risposta di prima classe (“non ho questo perché…”), usala invece di lasciare i requirements in sospeso.

​

1.5 Movimentazione di denaro

​

1.6 Una macchina a stati per risorsa

​

1.7 Convenzioni

• Riutilizzare una chiave con un corpo diverso produce 409 idempotency_conflict finché la chiave è mantenuta (almeno 7 giorni), quindi non pianificare mai il riutilizzo di una chiave. Genera un UUID nuovo per operazione logica e persistilo con il tuo job.
• Il replay copre anche gli errori: se la richiesta originale si è conclusa con un 4xx terminale, la stessa chiave più il corpo restituiscono la stessa risposta di problema.
• Due richieste concorrenti con la stessa chiave: una vince, l’altra riceve 409. Riprova quella perdente dopo la stabilizzazione della vincente; il replay restituisce la risposta originale.

​

1.8 Il percorso d’oro

​

Parte 2, l’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"]
  }
}

• La creazione è progressiva: { "type": "individual" } da solo è una creazione valida. I dati mancanti non invalidano mai il customer, emergono in seguito come task di intake sulle capabilities che li richiedono.
• Le aziende portano business più i dati di registrazione. Il CRUD degli azionisti di v1 si mappa sulle related parties, ampliato per coprire amministratori, dirigenti e proprietari: creale in linea alla creazione del customer (ognuna ottiene un id stabile rp_) o gestiscile tramite gli endpoint dedicati related-parties.
• Nessun campo status del customer, vedi 1.3.
• I customer esistenti vengono conservati: i customer creati su v1 o v2 sono indirizzabili con lo stesso id sugli endpoint v3. La lettura v3 è una vista sanificata, i valori legacy che falliscono la validazione v3 tornano assenti. Dopo la tua prima scrittura v3 quella vista diventa permanente: i valori assenti non tornano da soli. Arricchisci presto, pianifica un passaggio unico che PATCH il profilo completo dai tuoi record prima di affidarti alle letture v3. Il metadata di v1 è un namespace separato e non viene riportato, reimpostalo in v3.
• externalId è di prima classe e unico tra i tuoi customer su v3, per ambiente (409 duplicate_external_id). Archiviare un customer non rilascia il suo externalId, cancellalo con PATCH prima di DELETE se intendi riutilizzarlo.
• DELETE è un archivio a cascata (nessun ripristino; gli id non vengono mai riutilizzati). È bloccato con 409 customer_has_active_resources più blockingResources[] finché esiste un account non archiviato o un transfer in corso.
• Regole di merge PATCH: null esplicito cancella un campo nullable, gli array sostituiscono per intero (tranne le related parties in linea, che fanno upsert per id), le chiavi di metadata si fondono. Gli schemi completi e i filtri di lista sono nella specifica OpenAPI.

​

2.2 /rails, /banks, applications diventano Capabilities

• Una capability equivale a method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers, e così via) più accountType (pooled o named, null per metodi non bancari) più directions (payin o payout). Il capabilityId pubblico è la coppia qualificata (sepa_pooled, ach_named) o il metodo semplice per card e stablecoin_transfers.
• Ogni richiesta di capability genera un’application, il record per tentativo sotto .../capabilities/{capabilityId}/applications (più /{applicationId}/history), con i propri stati (1.6) e statusReason. È la traccia di audit di una richiesta; nel quotidiano, interroga la capability stessa.
• capabilities/supported restituisce disponibilità (available, beta o disabled), idoneità e istituzioni offerte. La selezione della banca avviene al momento della richiesta tramite l’array opzionale institutions, non c’è una risorsa /banks separata. Ometterlo (o inviare []) seleziona tutte le istituzioni di default; isDefault: true è un flag specifico di customer e capability, non globale. Una lista non vuota sovrascrive i default e una capability bancaria senza un default applicabile restituisce 422 capability_institutions_required. Gli id di istituzione sono opachi, tollera quelli nuovi.
• stablecoin_transfers è auto-concessa alla creazione del customer e nasce ready (quindi non viene mai richiesta né annullata). card è solo per individuals.
• openTaskIds sulla capability è il tuo puntatore “cosa fare dopo”. Aperto equivale a action_required o in_review, e il rollup include task condivise a livello di customer raggiunte tramite dipendenze attive.
• cancel funziona solo da pending o restricted e senza risorse bloccanti, altrimenti 409 capability_not_cancelable, il cui corpo di problema elenca blockingResources. Ri-richiedere dopo un’annullamento è una creazione nuova con una nuova chiave di idempotenza.
• Interroga il GET. Lo stato della capability si aggiorna quando lo leggi; interroga GET .../capabilities/{capabilityId} o iscriviti a capability.status_changed, non fare caching.
• Richiedere un metodo può rendere disponibili contemporaneamente metodi correlati, tratta le capabilities come un insieme da rileggere, non come una singola riga da tracciare.
• Usa tasks-preview per mostrare le richieste di onboarding prima di impegnarti in una richiesta.
• La verifica non è una tantum: nuove task possono comparire su una capability già ready (riverifica periodica o guidata da eventi). Mantieni il loop delle task attivo per tutto il ciclo di vita del customer, non solo durante l’onboarding.

​

2.3 Documenti e KYC diventano Tasks e Submissions

• Archiviazione file grezzi: POST/GET/DELETE /v3/customers/{customerId}/documents (più /{documentId}), carica una volta con la tua chiave API, quindi referenzia gli id documento nelle risposte di submission. Questo sostituisce ogni intake upload-token e direct-upload.
• Letture completamente nuove: GET /v3/tasks (inbox a livello di merchant), GET /v3/transfers/{transferId}/tasks, GET .../tasks/{taskId}/history, GET .../tasks/{taskId}/submissions (più /{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" } }
  ]
}

• Tipi di risposta: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. L’oggetto request di ogni requirement ti dice quale tipo si aspetta.
• Una submission deve rispondere a ogni requirement azionabile del round corrente, con il taskRevision esatto che hai letto. Le submission parziali vengono rifiutate.
• Le risposte profile si propagano: aggiornano il profilo del customer tramite il normale percorso di validazione e rivalutano immediatamente ogni capability che riferisce lo stesso lavoro di intake. Le task di intake sorelle i cui requirements sono tutti soddisfatti si chiudono automaticamente.
• I requirements possono formare gruppi alternativi (alternativeKey): invia esattamente uno del gruppo.
• changes_requested incrementa remediationRound e porta reviewFeedback. Rileggi la task, invia di nuovo con una nuova chiave di idempotenza.
• Gli URL di verifica ospitata compaiono solo nel dettaglio della task per customer (GET /v3/customers/{customerId}/tasks/{taskId}) e solo mentre la sessione è azionabile; le liste e GET /v3/tasks/{taskId} sono deliberatamente senza URL.
• I termini di servizio sono anch’essi una task: openTaskIds può includere una task con category: "terms_of_service" la cui pagina di accettazione ospitata è collegata allo stesso modo (solo dettaglio per customer). Le submission generiche non possono accettare i termini, e l’approvazione KYC non implica mai l’accettazione dei termini.
• Le task hanno ambito per capability, quindi la “stessa” richiesta (per esempio prova di indirizzo) può comparire una volta per capability. Deduplica nella tua UI per la key del requirement.
• Nessun livello di traduzione: postare su /v1/documents non sbloccherà le capabilities v3. Una volta che un customer è su v3, canalizza ogni richiesta tramite le task.

​

2.4 Account e wallet

// 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 sui conti bancari issued è opzionale (di default per metodo); sui conti bancari esterni fornirlo esplicitamente. I conti wallet non portano paese affatto.
• settlement.accountId è richiesto sui conti bancari issued: identifica il conto wallet issued che riceve i fondi liquidati dai depositi sul conto bancario.
• I conti issued espongono details (IBAN o routing più account o address), routing versionato (le coordinate di deposito possono ruotare, mostra sempre l’ultima lettura), fees, balances.
• Reti: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• La barriera della capability si applica solo agli account issued: crearne uno contro una capability non pronta fallisce con un errore codificato per capability, richiedi prima la capability (2.2). Gli account esterni non necessitano di capability (né di approvazione del customer); ricevono solo la validazione dello schema della richiesta e delle coordinate bancarie.
• I conti bancari issued nascono provisioning con details: null. Interroga il conto o ascolta account.status_changed fino a ready.
• DELETE archivia, non elimina mai in modo definitivo. Gli account referenziati da transfer in corso restituiscono 409 account_has_active_transfers. Riprova dopo che quei transfer raggiungono uno stato terminale.
• Nuovo in v3: Rules, istruzioni permanenti su un conto wallet issued (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}) che spazzano automaticamente i fondi in ingresso verso un altro account o una destination wallet. Nessun equivalente in v1 o v2.

​

2.5 Recipient e destination

• Recipient equivale a chi: individual (nome e cognome) o business (nome dell’azienda), con relationship obbligatorio (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Recipient e destination sono solo per terze parti. Un payout a se stessi non usa affatto un recipient: mira a uno dei propri account acc_ del customer come destinationId della quote (2.6).
• Destination equivale a dove: tipizzato per metodo, sepa (iban, bic opzionale), ach o wire (routing più account), swift (coordinate complete più intermediario opzionale), spei (clabe), pse, transfers_3_0 (cbu), e così via, più destination wallet. Ogni destination ha il proprio stato. Ascolta destination.status_changed.
• Le destination fiat richiedono l’address completo del recipient (via, città, codice postale, paese) prima della creazione. I pezzi mancanti falliscono con 422 recipient_address_required. Le destination wallet saltano l’indirizzo ma richiedono ownership di primo livello (self_custodied, o custodial con un nome di custode).
• L’accuratezza del nome del beneficiario è importante: le banche riceventi verificano il nome legale del conto. Invia nome e cognome legali esatti o il nome dell’azienda, non un soprannome di visualizzazione.
• Gli schemi dei campi di destination per metodo sono nella specifica OpenAPI.

​

2.6 Quote e transfer

// 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 accetta un id acc_ (account del customer) o dst_ (destination di recipient). Le quote finanziate in fiat (payin) devono puntare a un account acc_, un target dst_ significa sempre un payout (422 quote_direction_invalid altrimenti).
• externalId su quote e transfer è un riferimento di correlazione non univoco (restituito nelle letture, filtrabile nelle liste). La regola di unicità per ambiente (2.1) si applica solo all’externalId del customer.
• Esegui una quote esattamente una volta, prima di expiresAt. Una quote scaduta fallisce con 409 quote_expired, una seconda esecuzione con 409 quote_already_executed (il problema porta il transferId esistente).
• L’annullamento del transfer non è ancora supportato: POST .../cancel restituisce 409 transfer_not_cancelable in ogni stato. I transfer canceled di oggi derivano dalla scadenza della finestra di funding su un payin non finanziato, non da questo endpoint.
• I payin iniziano awaiting_funds: mostra GET .../instructions al pagatore, coordinate bancarie più codice di riferimento o memo per fiat, indirizzo di deposito per crypto. Il codice di riferimento è il modo in cui il deposito viene abbinato. Mostralo sempre.
• state più stateDetail per sottostati leggibili dalla macchina; action_required significa che una task di conformità è allegata (openTaskIds, GET .../tasks), rispondi tramite submission.
• I depositi in ingresso rilevati sugli account issued compaiono come transfer con origin: "inbound_deposit" (contro "quoted").
• I riferimenti della rete di pagamento sono consolidati sotto references: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• I transfer non attraversano le versioni. I transfer creati su v1 o v2 non sono leggibili da v3. La lista li omette e GET /v3/transfers/{transferId} risponde 404. Passa prima la creazione, mantieni il percorso di lettura v1 finché quei transfer raggiungono stati terminali, poi eliminalo.
• Nessuno swap di token. stablecoin_move richiede la stessa valuta in ingresso e in uscita: USDC verso USDT fallisce con 422 recipient_destination_invalid con un errore di campo currency_mismatch. Stessa rete su entrambi i lati, senza bridging, e i movimenti wallet-to-wallet attualmente supportano solo la consegna a zero commissioni: una quote la cui commissione di piattaforma o developer non sia zero fallisce con 422 amount_not_deliverable.

​

2.7 Webhook

• GET /v3/webhooks/portal restituisce un URL di portale di gestione ospitato per log di consegna, retry e replay manuale.
• transfer.created viene attualmente consegnato con la forma di payload legacy v1 (la busta v3 si attiva quando i webhook v1 saranno dismessi). Trattalo puramente come un indizio e fai GET del transfer; non costruire contro il suo corpo.
• Gli eventi sono indizi: alla ricezione, fai GET della risorsa e agisci sulla lettura. Non costruire mai lo stato dai payload o dall’ordine degli eventi. La consegna è almeno una volta e può essere ritardata o riordinata. Deduplica per id di evento e recupera gli eventi persi con il filtro inclusivo updatedAfter di ogni lista.
• Iscriviti a api.deprecation, il canale automatico per le dismissioni di versione.
• Nessun evento task.* oggi: dopo l’invio, interroga la task o il suo genitore.

​

2.8 Sandbox

​

2.9 Endpoint legacy senza sostituzione in v3

​

2.10 Ordine di migrazione suggerito

​

2.11 Check-list dei tranelli

• UUID nuovo per operazione logica, persistito con il tuo job e riutilizzato in retry; non riutilizzare mai una chiave con un corpo modificato (409 idempotency_conflict). Gli endpoint sandbox sono esenti dall’header.
• Arricchisci i customer esistenti (PATCH il profilo completo, reimposta metadata, non viene riportato) prima di qualsiasi altra scrittura v3, la prima scrittura v3 rende permanente la vista sanificata.
• externalId è unico per ambiente e non viene rilasciato dall’archiviazione, cancellalo con PATCH prima di DELETE se intendi riutilizzarlo.
• Non esiste un campo status del customer, deriva la prontezza per capability.
• action_required e in_review significano entrambi una task aperta.
• Le submission sono soggette a revisione (inviare non equivale a sbloccato) e devono rispondere a ogni requirement azionabile con il taskRevision esatto. In caso di disallineamento, rileggi e ricostruisci.
• Non esiste webhook task.*, interroga la task (o il suo genitore) dopo ogni invio.
• Retry di changes_requested equivale a rileggere la task, nuove risposte, nuova chiave di idempotenza.
• Postare su /v1/documents non sblocca mai una capability v3, una volta che un customer è sulle task, canalizza ogni richiesta tramite le task.
• Nuove task possono comparire su una capability già ready, mantieni il loop delle task attivo dopo l’onboarding, non solo durante.
• cancel della capability funziona solo da pending o restricted senza risorse bloccanti (409 capability_not_cancelable); ri-richiedere dopo l’annullamento è una creazione nuova con una nuova chiave di idempotenza.
• La capability deve essere ready prima di emettere account sotto di essa o quotare contro di essa.
• La quote ha l’importo esattamente su un lato; nessun campo di direzione; esegui esattamente una volta prima di expiresAt (409 quote_expired o 409 quote_already_executed).
• I movimenti di stablecoin sono solo stessa valuta e stessa rete (USDC verso USDT fallisce 422); wallet-to-wallet supporta solo la consegna a zero commissioni.
• DELETE archivia, non elimina mai in modo definitivo. La delete dell’account è bloccata dai transfer in corso (409 account_has_active_transfers); la delete del customer inoltre da qualsiasi account non archiviato (409 customer_has_active_resources, blockingResources[] li nomina).
• I transfer v1 o v2 sono invisibili alle letture v3 (la lista li omette, GET 404s), fai doppia lettura fino al drenaggio, poi elimina i vecchi percorsi.
• Il routing di deposito e le istruzioni possono ruotare, mostra sempre l’ultimo GET e mostra sempre il codice di riferimento.
• I webhook sono indizi; il GET è la verità, deduplica per id di evento, recupera gli eventi persi con updatedAfter.

​

Passo successivo