Migrer vers v3

• Partie 1, le concept. Lisez-la d’abord. v3 est une refonte, pas un renommage : si vous mappez les anciens endpoints un pour un, vous lutterez contre l’API. Dix minutes ici vous économiseront des jours plus tard.
• Partie 2, l’API. Mapping endpoint par endpoint, exemples de requêtes, machines à états et check-list de migration.

​

Partie 1, le concept

​

1.1 Pourquoi v3 existe

​

1.2 Le modèle d’objets

1. Les capabilities régissent tout. Les accounts sont provisionnées sous une capability ready ; les quotes sont tarifées contre une capability. L’onboarding équivaut à amener les capabilities dont vous avez besoin à ready.
2. Les tasks s’attachent partout. Une capability, une account ou un transfer en cours peuvent porter des openTaskIds. Où qu’elles apparaissent, la boucle est la même : lire la task, envoyer les réponses, attendre la revue, relire le parent.

​

1.3 La préparation est par capability, pas par customer

• « Peut-il opérer sur X ? » devient capability X status == "ready".
• « A-t-il quelque chose à faire ? » devient toute task avec le statut action_required (la capability affiche généralement restricted avec statusReason.resolution: "complete_tasks").
• « Attendons-nous Swipelux ? » devient tasks in_review, capability pending.

​

1.4 La boucle des tâches

• Une task porte requirements[], les demandes individuelles. Chacune a un requirementId par task, une key stable nommant la demande (par exemple justificatif de domicile, dédupliquez votre UI par elle) et une request typée qui décrit exactement l’entrée attendue (texte, date, sélection, document, attestation, etc.).
• La soumission est soumise à revue : elle ne mute jamais directement l’état de la capability ou de l’account, seule l’acceptation le fait. Une exception : les réponses profile sont propagées au profil du customer à la soumission (2.3). Après avoir soumis, sondez la task ou la ressource parente.
• taskRevision (écho de la revision de la task) est un garde-fou de concurrence : si la task a changé depuis votre lecture, relisez-la et reconstruisez vos réponses.
• absence est une réponse de premier ordre (« je n’ai pas cela parce que… »), utilisez-la plutôt que de laisser des requirements en suspens.

​

1.5 Mouvement d’argent

​

1.6 Une machine à états par ressource

​

1.7 Conventions

• Réutiliser une clé avec un corps différent provoque 409 idempotency_conflict tant que la clé est retenue (au moins 7 jours), alors ne planifiez jamais de réutiliser une clé. Générez un UUID neuf par opération logique et persistez-le avec votre job.
• Le rejeu couvre aussi les erreurs : si la requête d’origine s’est terminée par un 4xx terminal, la même clé plus corps renvoie la même réponse de problème.
• Deux requêtes concurrentes avec la même clé : l’une gagne, l’autre reçoit 409. Réessayez la perdante après le règlement de la gagnante ; le rejeu renvoie la réponse d’origine.

​

1.8 Le chemin doré

​

Partie 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 création est progressive : { "type": "individual" } seul est une création valide. Les données manquantes n’invalident jamais le customer, elles apparaissent plus tard comme tasks d’intake sur les capabilities qui en ont besoin.
• Les entreprises portent business plus des données d’immatriculation. Le CRUD des actionnaires de v1 se mappe sur les related parties, élargi pour couvrir dirigeants, mandataires et propriétaires : créez-les en ligne à la création du customer (chacune reçoit un id stable rp_) ou gérez-les par les endpoints dédiés related-parties.
• Aucun champ status sur le customer, voir 1.3.
• Les customers existants sont conservés : les customers créés sur v1 ou v2 sont adressables par le même id sur les endpoints v3. La lecture v3 est une vue assainie, les valeurs héritées qui échouent à la validation v3 reviennent absentes. Après votre première écriture v3, cette vue devient permanente : les valeurs absentes ne reviennent pas d’elles-mêmes. Enrichissez tôt, prévoyez une passe unique qui PATCHe le profil complet depuis vos propres enregistrements avant de vous appuyer sur les lectures v3. Le metadata de v1 est un espace de noms séparé et **n’**est pas repris, redéfinissez-le sur v3.
• externalId est de premier ordre et unique parmi vos customers en v3, par environnement (409 duplicate_external_id). Archiver un customer ne libère pas son externalId, effacez-le par PATCH avant DELETE si vous comptez le réutiliser.
• DELETE est un archivage en cascade (sans restauration ; les ids ne sont jamais réutilisés). Il est bloqué par 409 customer_has_active_resources plus blockingResources[] tant qu’il existe une account non archivée ou un transfer en cours.
• Règles de fusion PATCH : null explicite efface un champ nullable, les tableaux remplacent en entier (sauf les related parties en ligne, qui sont upsertées par id), les clés de metadata fusionnent. Les schémas complets et les filtres de liste sont dans la spécification OpenAPI.

​

2.2 /rails, /banks, applications deviennent Capabilities

• Une capability équivaut à method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers, etc.) plus accountType (pooled ou named, null pour les méthodes non bancaires) plus directions (payin ou payout). Le capabilityId public est la paire qualifiée (sepa_pooled, ach_named) ou la méthode seule pour card et stablecoin_transfers.
• Chaque demande de capability engendre une application, l’enregistrement par tentative sous .../capabilities/{capabilityId}/applications (plus /{applicationId}/history), avec ses propres statuts (1.6) et statusReason. C’est la trace d’audit d’une demande ; au quotidien, sondez la capability elle-même.
• capabilities/supported renvoie la disponibilité (available, beta ou disabled), l’éligibilité et les institutions proposées. La sélection de banque se fait au moment de la demande via le tableau optionnel institutions ; il n’y a pas de ressource /banks séparée. L’omettre (ou envoyer []) sélectionne toutes les institutions par défaut ; isDefault: true est un drapeau spécifique à un customer et une capability, pas global. Une liste non vide écrase les valeurs par défaut, et une capability adossée à une banque sans valeur par défaut applicable renvoie 422 capability_institutions_required. Les ids d’institution sont opaques, tolérez-en de nouveaux.
• stablecoin_transfers est auto-attribuée à la création du customer et naît ready (donc jamais demandée et non annulable). card est réservée aux individuals.
• openTaskIds sur la capability est votre pointeur « quoi faire ensuite ». Ouvert équivaut à action_required ou in_review, et le rollup inclut des tasks partagées au niveau customer atteintes par des dépendances actives.
• cancel ne fonctionne qu’à partir de pending ou restricted et sans ressources bloquantes, sinon 409 capability_not_cancelable, dont le corps de problème liste blockingResources. Redemander après annulation est une création neuve avec une nouvelle clé d’idempotence.
• Sondez le GET. L’état de la capability se rafraîchit lors de la lecture ; sondez GET .../capabilities/{capabilityId} ou abonnez-vous à capability.status_changed, ne cachez pas.
• Demander une méthode peut rendre disponibles des méthodes apparentées d’un coup, traitez les capabilities comme un ensemble à relire, pas comme une ligne unique à suivre.
• Utilisez tasks-preview pour montrer les demandes d’onboarding avant de vous engager sur une demande.
• La vérification n’est pas ponctuelle : de nouvelles tasks peuvent apparaître sur une capability déjà ready (revérification périodique ou pilotée par événement). Gardez la boucle des tasks branchée pour toute la vie du customer, pas seulement pour l’onboarding.

​

2.3 Documents et KYC deviennent Tasks et Submissions

• Stockage de fichiers bruts : POST/GET/DELETE /v3/customers/{customerId}/documents (plus /{documentId}), chargez une fois avec votre clé API puis référencez les ids de document dans les réponses de submission. Cela remplace tous les intakes upload-token et direct-upload.
• Lectures inédites : GET /v3/tasks (boîte de réception marchande), 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" } }
  ]
}

• Types de réponse : profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. L’objet request de chaque requirement indique quel type est attendu.
• Une submission doit répondre à chaque requirement actionnable de la ronde en cours, avec le taskRevision exact que vous avez lu. Les submissions partielles sont rejetées.
• Les réponses profile se propagent : elles mettent à jour le profil du customer via le chemin de validation normal et réévaluent immédiatement chaque capability référençant le même travail d’intake. Les tasks d’intake sœurs dont tous les requirements sont satisfaits se ferment automatiquement.
• Les requirements peuvent former des groupes alternatifs (alternativeKey) : soumettez exactement un du groupe.
• changes_requested incrémente remediationRound et porte reviewFeedback. Relisez la task, soumettez de nouveau avec une nouvelle clé d’idempotence.
• Les URL de vérification hébergée n’apparaissent que dans le détail de task par customer (GET /v3/customers/{customerId}/tasks/{taskId}) et uniquement tant que la session est actionnable ; les listes et GET /v3/tasks/{taskId} sont volontairement sans URL.
• Les conditions générales sont aussi une task : openTaskIds peut inclure une task avec category: "terms_of_service" dont la page d’acceptation hébergée est liée de la même façon (uniquement dans le détail par customer). Les submissions génériques ne peuvent pas accepter les conditions, et l’approbation KYC n’implique jamais l’acceptation des conditions.
• Les tasks ont une portée par capability, donc la « même » demande (par exemple justificatif de domicile) peut apparaître une fois par capability. Dédupliquez dans votre UI par la key du requirement.
• Aucune couche de traduction : publier vers /v1/documents ne débloquera pas les capabilities v3. Une fois qu’un customer est sur v3, canalisez toutes les demandes par les tasks.

​

2.4 Accounts et 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 sur les comptes bancaires émis est optionnel (par défaut selon la méthode) ; sur les comptes bancaires externes, fournissez-le explicitement. Les comptes wallet ne portent pas de pays du tout.
• settlement.accountId est requis sur les comptes bancaires émis : il désigne le compte wallet émis qui reçoit les fonds réglés depuis les dépôts sur le compte bancaire.
• Les comptes émis exposent details (IBAN ou routing plus account ou address), routing versionné (les coordonnées de dépôt peuvent tourner, affichez toujours la dernière lecture), fees, balances.
• Réseaux : polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• La barrière capability s’applique uniquement aux comptes émis : en créer un contre une capability non prête échoue avec une erreur codée par capability, demandez d’abord la capability (2.2). Les comptes externes n’ont besoin d’aucune capability (ni d’approbation du customer) ; ils obtiennent seulement la validation du schéma de requête et des coordonnées bancaires.
• Les comptes bancaires émis naissent provisioning avec details: null. Sondez le compte ou surveillez account.status_changed jusqu’à ready.
• DELETE archive, ne supprime jamais définitivement. Les comptes référencés par des transfers en cours renvoient 409 account_has_active_transfers. Réessayez après que ces transfers atteignent un état terminal.
• Inédit en v3 : Rules, instructions permanentes sur un compte wallet émis (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}) qui balaient automatiquement les fonds entrants vers un autre compte ou une destination wallet. Aucun équivalent en v1 ou v2.

​

2.5 Recipients et destinations

• Recipient équivaut à qui : individual (prénom et nom) ou business (nom d’entreprise), avec relationship requis (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Recipients et destinations ne concernent que les tiers. Un payout à soi-même n’utilise pas de recipient du tout : ciblez l’une des propres accounts acc_ du customer comme destinationId de la quote (2.6).
• Destination équivaut à où : typée par méthode, sepa (iban, bic optionnel), ach ou wire (routing plus account), swift (coordonnées complètes plus intermédiaire optionnel), spei (clabe), pse, transfers_3_0 (cbu), etc., plus les destinations wallet. Chaque destination a son propre statut. Surveillez destination.status_changed.
• Les destinations fiat exigent l’address complète du recipient (rue, ville, code postal, pays) avant la création. Les pièces manquantes échouent avec 422 recipient_address_required. Les destinations wallet omettent l’adresse mais exigent un ownership de premier niveau (self_custodied, ou custodial avec un nom de custodian).
• La précision du nom du bénéficiaire compte : les banques réceptrices vérifient le nom légal du compte. Envoyez le prénom et le nom légaux exacts ou le nom d’entreprise, pas un pseudonyme d’affichage.
• Les schémas de champs de destination par méthode sont dans la spécification OpenAPI.

​

2.6 Quotes et 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 accepte un id acc_ (account du customer) ou dst_ (destination de recipient). Les quotes financées en fiat (payins) doivent cibler un compte acc_, une cible dst_ signifie toujours un payout (422 quote_direction_invalid sinon).
• externalId sur quotes et transfers est une référence de corrélation non unique (rendue en lecture, filtrable en liste). La règle d’unicité par environnement (2.1) s’applique uniquement à l’externalId du customer.
• Exécutez une quote exactement une fois, avant expiresAt. Une quote expirée échoue avec 409 quote_expired, une seconde exécution avec 409 quote_already_executed (le problème porte le transferId existant).
• L’annulation de transfer n’est pas encore prise en charge : POST .../cancel renvoie 409 transfer_not_cancelable dans tous les états. Les transfers canceled d’aujourd’hui proviennent de l’expiration de la fenêtre de financement sur un payin non financé, pas de cet endpoint.
• Les payins démarrent awaiting_funds : présentez GET .../instructions au payeur, coordonnées bancaires plus code de référence ou memo pour le fiat, adresse de dépôt pour la crypto. Le code de référence est comment le dépôt est apparié. Affichez-le toujours.
• state plus stateDetail pour des sous-états lisibles par machine ; action_required signifie qu’une task de conformité est attachée (openTaskIds, GET .../tasks), répondez par submissions.
• Les dépôts entrants détectés sur les comptes émis apparaissent comme transfers avec origin: "inbound_deposit" (contre "quoted").
• Les références de réseau de paiement sont consolidées sous references : transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Les transfers ne traversent pas les versions. Les transfers créés sur v1 ou v2 ne sont pas lisibles depuis v3. La liste les omet et GET /v3/transfers/{transferId} renvoie 404. Basculez d’abord la création, gardez le chemin de lecture v1 jusqu’à ce que ces transfers atteignent des états terminaux, puis abandonnez-le.
• Pas d’échange de tokens. stablecoin_move exige la même devise en entrée et en sortie : USDC vers USDT échoue avec 422 recipient_destination_invalid portant une erreur de champ currency_mismatch. Même réseau des deux côtés, sans pontage, et les déplacements wallet à wallet ne prennent actuellement en charge que la livraison sans frais : une quote dont les frais plateforme ou developer sont non nuls échoue avec 422 amount_not_deliverable.

​

2.7 Webhooks

• GET /v3/webhooks/portal renvoie une URL de portail de gestion hébergé pour les journaux de livraison, les réessais et le rejeu manuel.
• transfer.created est actuellement livré avec la forme de payload héritée v1 (l’enveloppe v3 s’active quand les webhooks v1 seront retirés). Traitez-le purement comme un indice et faites un GET du transfer ; ne construisez pas contre son corps.
• Les événements sont des indices : à la réception, faites un GET de la ressource et agissez sur la lecture. Ne construisez jamais l’état à partir des payloads ou de l’ordre d’événements. La livraison est au moins une fois et peut être retardée ou réordonnée. Dédupliquez par id d’événement, et récupérez les événements manqués avec le filtre inclusif updatedAfter de chaque liste.
• Abonnez-vous à api.deprecation, le canal machine pour les retraits de version.
• Aucun événement task.* aujourd’hui : après avoir soumis, sondez la task ou son parent.

​

2.8 Sandbox

​

2.9 Endpoints hérités sans remplacement en v3

​

2.10 Ordre de migration suggéré

​

2.11 Check-list des pièges

• UUID neuf par opération logique, persisté avec votre job et réutilisé au réessai ; ne réutilisez jamais une clé avec un corps modifié (409 idempotency_conflict). Les endpoints sandbox sont exemptés de l’en-tête.
• Enrichissez les customers existants (PATCH le profil complet, redéfinissez metadata, il n’est pas repris) avant toute autre écriture v3, la première écriture v3 rend la vue assainie permanente.
• externalId est unique par environnement et n’est pas libéré par l’archivage, effacez-le par PATCH avant DELETE si vous prévoyez de le réutiliser.
• Aucun champ status de customer n’existe, dérivez la préparation par capability.
• action_required et in_review signifient tous deux une task ouverte.
• Les submissions sont soumises à revue (soumettre n’équivaut pas à débloqué) et doivent répondre à chaque requirement actionnable avec le taskRevision exact. En cas de désaccord, relisez et reconstruisez.
• Aucun webhook task.* n’existe, sondez la task (ou son parent) après chaque soumission.
• Réessai changes_requested équivaut à relire la task, réponses nouvelles, nouvelle clé d’idempotence.
• Publier vers /v1/documents ne débloque jamais une capability v3, une fois qu’un customer est sur les tasks, canalisez toute demande par les tasks.
• De nouvelles tasks peuvent apparaître sur une capability déjà ready, gardez la boucle des tasks branchée après l’onboarding, pas seulement pendant.
• cancel de capability ne fonctionne que depuis pending ou restricted sans ressources bloquantes (409 capability_not_cancelable) ; redemander après annulation est une création neuve avec une nouvelle clé d’idempotence.
• La capability doit être ready avant d’émettre des comptes sous elle ou de tarifer contre elle.
• Une quote a le montant exactement sur un côté ; pas de champ de direction ; exécutez-la exactement une fois avant expiresAt (409 quote_expired ou 409 quote_already_executed).
• Les mouvements de stablecoin sont uniquement même devise, même réseau (USDC vers USDT échoue 422) ; wallet à wallet ne prend en charge que la livraison sans frais.
• DELETE archive, ne supprime jamais définitivement. La suppression de compte est bloquée par les transfers en cours (409 account_has_active_transfers) ; la suppression de customer l’est en plus par toute account non archivée (409 customer_has_active_resources, blockingResources[] les nomme).
• Les transfers v1 ou v2 sont invisibles aux lectures v3 (la liste omet, GET renvoie 404), double-lisez jusqu’au drain, puis abandonnez les anciens chemins.
• Le routing de dépôt et les instructions peuvent tourner, affichez toujours le dernier GET et affichez toujours le code de référence.
• Les webhooks sont des indices ; le GET est la vérité, dédupliquez par id d’événement, récupérez les événements manqués avec updatedAfter.

​

Étape suivante