IBAN de collecte

Un IBAN de collecte est un compte bancaire ouvert à votre nom chez notre banque partenaire. Vos clients y virent de l'argent ; votre solde de transfert est crédité automatiquement, et vous êtes prévenu par webhook.

C'est l'inverse d'un bénéficiaire : là-bas vous déclarez où vous envoyez, ici vous lisez où vous recevez.

Une portée de clé à part : iban

Ces routes exigent une clé de portée iban, distincte de collect et de payout. Une clé qui encaisse ne peut pas faire ouvrir un compte.

⚠ Ce n'est pas une précaution de principe. Faire ouvrir un compte est irréversible : la banque n'offre aucun moyen de défaire proprement une ouverture de trop. Une clé de site qui fuit pourrait multiplier les comptes, chacun recevant de l'argent que personne ne surveille.

La clé se crée depuis votre console, et seulement une fois le service ouvert de notre côté — après examen de votre dossier. Tant qu'il ne l'est pas, la création de clé rend 409 service_not_active.

En sandbox : une banque simulée

Avec une clé de test, POST /v1-ibans ouvre un compte auprès d'une banque simulée : aucun appel ne part vers une vraie banque, et les numéros de compte commencent par 999, qu'aucune banque réelle n'émet. Tout le reste est identique — même réponse, même iban.created.

Le scénario se choisit par les quatre derniers caractères de la référence (holder.reference, ou votre identifiant pour un compte à votre nom) :

Pour faire arriver un virement sur un IBAN de test :

POST /v1-ibans/{id}/simulate-transfer
{ "amount": 250000, "reference": "VIR-2026-0042" }

Il suit le chemin d'un virement réel : constaté, crédité sur votre solde de transfert, annoncé par topup.succeeded. La même reference rejouée n'est créditée qu'une fois. ⚠ Une clé live reçoit 404 : cette route n'existe pas en production.

Lister vos IBAN

GET /v1-ibans

{
  "object": "list",
  "data": [
    {
      "id": "…",
      "object": "iban",
      "rib": "CI93 CI201 01001 127586883703 85",
      "iban": "CI93CI2010100112758688370385",
      "account_number": "127586883703",
      "holder": "AVA CORP SARL",
      "reference": "MRCHmer_abc123",
      "branch": "VALSORIA",
      "bank_status": "ACTIVE",
      "active": true,
      "created_at": "2026-09-22T13:58:37Z"
    }
  ],
  "service": "active"
}

rib porte les espaces, tel que la banque l'écrit : c'est cette forme qu'on communique à un payeur. iban est la même valeur compactée, celle qu'on colle dans un virement. account_number est le numéro de compte — c'est lui que la banque nomme dans son relevé, et donc lui qui sert au rapprochement.

⚠ service est rendu même quand la liste est pleine. Une liste vide, seule, ne dit pas si vous n'avez pas encore d'IBAN ou si le service ne vous est pas ouvert. Lisez ce champ plutôt que de déduire du tableau.

Lire un compte, et ce qu'il a reçu

GET /v1-ibans/{id}

{
  "iban": { "id": "…", "account_number": "127273488039", "holder": "VALSORIA IMPEX CI", "…": "…" },
  "received": [
    {
      "id": "…",
      "object": "bank_transfer",
      "reference": "030626038387",
      "amount": 500000,
      "currency": "XOF",
      "received_on": "2026-06-03",
      "label": "127273488039/ VIRMT FAV VALSOR COMPTE EUCALYPTUS",
      "from_bank": "Banque diverse",
      "credited_at": "2026-09-22T16:57:27Z"
    }
  ]
}

⚠ received_on et credited_at ne sont pas la même date. La première est la date d'opération chez la banque ; la seconde, le moment où nous l'avons constatée. La banque ne nous prévient pas — nous relisons son relevé toutes les cinq minutes — et un virement passé en compensation la veille au soir peut donc être crédité le lendemain. Pour vos rapprochements comptables, c'est received_on qui fait foi.

Si vous avez plusieurs IBAN, c'est cette route qui répond à la question qui compte : lequel de mes comptes a reçu ce virement ? La liste ne le dit pas, et le webhook topup.succeeded porte désormais iban_id pour vous éviter d'avoir à chercher.

Un identifiant qui n'est pas le vôtre rend 404, jamais 403 : confirmer l'existence d'un compte serait déjà en dire trop.

Faire ouvrir un IBAN

POST /v1-ibans

Sans corps, le compte est ouvert à votre nom, celui figurant à votre dossier. Réponse 201 : { "iban": { … } } — l'objet est ENVELOPPÉ sous la clé iban, comme dans la lecture d'un compte.

Ouvrir au nom d'un de vos clients

Si vous encaissez pour des tiers, vous pouvez leur ouvrir un IBAN chacun :

POST /v1-ibans
{
  "holder": {
    "name": "SCOP AGRI IMMO+",
    "reference": "CLI-4827",
    "tax_id": "CI-RCCM-2019-B-1234"
  }
}

reference est votre identifiant de ce client, chez vous. C'est elle qui rend l'appel non rejouable : deux appels avec la même référence ne font pas deux comptes. Sans elle, un intégrateur qui relance ouvre un second compte pour le même client — et la banque ne sait pas défaire.

⚠ L'argent reste à vous. Un virement reçu sur un IBAN de client crédite votre solde de transfert. Nous ne tenons pas de sous-solde par client : le compte porte son nom, mais c'est vous qui tenez sa comptabilité. Le tiers n'a aucun accès, ni à l'API, ni au compte.

⚠ L'identité est déclarative. Nous ne vérifions ni le nom ni le tax_id : vous avez fait votre propre vérification de ce client et vous en répondez. Les conditions du service IBAN le disent.

Chaque compte rendu porte alors :

"for_third_party": { "name": "SCOP AGRI IMMO+", "reference": "CLI-4827", "tax_id": "…" }

null sur les comptes ouverts à votre propre nom.

Vous avez droit à un compte en propre ET à un compte par client : les deux limites sont distinctes, et ouvrir des comptes pour vos clients ne consomme pas le vôtre.

⚠ Cet appel ne se rejoue pas

Si la banque ne répond pas, nous ne pouvons pas aller lui demander si le compte a été créé — elle n'offre aucune lecture par référence. Vous recevez alors :

{ "error": { "code": "iban_emission_incertaine", "message": "…" } }

avec un statut 502. Il veut dire exactement une chose : ne rejouez pas. Appelez GET /v1-ibans quelques minutes plus tard ; le compte y figurera s'il a été ouvert.

C'est pourquoi cette route n'utilise pas Idempotency-Key : une clé d'idempotence promet « rejouer rend la même réponse ». Ici, il n'y a rien à rejouer.

Les autres refus

Ce que chaque IBAN a reçu

Chaque compte rendu porte son cumul, et la liste porte un récapitulatif :

{
  "data": [
    { "account_number": "127273488039", "received_total": 500000,
      "received_count": 1, "last_received_on": "2026-06-03", "…": "…" }
  ],
  "summary": {
    "received_total": 500000,
    "received_count": 1,
    "transfer_balance": 500000,
    "currency": "XOF"
  }
}

⚠ received_total n'est PAS un solde, et transfer_balance n'en est pas la somme.

Un IBAN reçoit ; il ne paie jamais. Les décaissements sortent de votre solde de transfert, globalement, sans s'imputer à un compte d'entrée. Donc :

• received_total est tout ce qui est arrivé par ce compte, depuis toujours. Il ne décroît jamais.
• transfer_balance est ce qui reste disponible pour décaisser. Il baisse à chaque virement que vous envoyez, et peut monter par d'autres voies.

Les confondre ferait répartir deux fois le même argent entre vos clients. Si vous tenez leur compte, additionnez les mouvements (GET /v1-ibans/{id}), et ne déduisez jamais un disponible d'un cumul d'entrées.

Seuls les virements rapprochés sont comptés : un virement constaté mais que nous n'avons pas su attribuer n'a crédité personne, et n'entre dans aucun cumul.

On ne supprime pas un IBAN par API

Ce n'est pas un oubli. Un compte qui a reçu de l'argent doit rester rattaché : c'est lui qui explique d'où vient un approvisionnement passé. Fermer un compte se demande à la banque, et se fait de notre côté.

Les deux événements

topup.succeeded est détaillé dans Webhooks — c'est le seul événement que vous n'avez pas provoqué, et il obéit à des règles propres.

Version d'API 2026-08-25 · changements · spécification OpenAPI