Passer au contenu principal
POST
curl
L’endpoint Créer un lien bancaire de Didit démarre une exécution de Bank Link sur votre serveur, pour connecter une banque ou renouveler une connexion, et renvoie l’url hébergée. Chaque champ a une valeur par défaut : la requête la plus simple est {}, à laquelle vous ajoutez les paramètres souhaités. Associez l’id renvoyé à votre utilisateur et confirmez le résultat vous-même avec Récupérer un lien bancaire ou le webhook bank.link.completed. Voir le guide de démarrage rapide et Bank Link.

Autorisations

x-api-key
string
header
requis

La clé API de votre application, disponible dans Developers -> API keys de la Business Console. La clé principale a un accès complet. Une clé nommée peut être limitée : aucun accès, lecture ou écriture par ressource, restreinte à certains workflows ou à certaines sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou à cette action, ou que la requête provient d'une adresse hors de sa liste d'adresses IP ; 404 sur une route de session signifie que la session se trouve hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL des images, vidéos et PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys.

En-têtes

Idempotency-Key
string

Clé facultative de sécurisation des nouvelles tentatives, que vous choisissez pour une opération, d'au plus 255 caractères (un UUID convient). Une requête répétée avec la même clé, le même endpoint, les mêmes paramètres de requête et le même corps reçoit la première réponse, avec le même statut et le même corps, et n'est ni exécutée ni facturée une seconde fois. La même clé avec un autre endpoint, d'autres paramètres de requête ou un autre corps renvoie 409 idempotency_key_reused. Tant que la première requête est encore en cours, elle renvoie 409 idempotency_key_in_progress avec Retry-After. Une requête échouée (tout 4xx ou 5xx) n'est pas enregistrée, vous pouvez donc la renvoyer avec la même clé. Les clés sont propres à votre application, que vous appeliez avec une clé API ou un jeton d'accès. Voir Nouvelles tentatives et idempotence.

Required string length: 1 - 255

Corps

application/json

Créez un lien bancaire. La requête la plus simple est {} plus ce que vous voulez : chaque champ a une valeur par défaut.

mode
enum<string>
défaut:connect

connect (par défaut) crée une nouvelle connexion. renew nécessite connection_id et réutilise les paramètres de cette connexion.

Options disponibles:
connect,
renew
connection_id
string<uuid>

La connexion à renouveler. Uniquement avec mode: renew.

access
enum<string>
défaut:one_time

one_time (par défaut) lit les données une seule fois. ongoing maintient l'accès ouvert jusqu'à la fin du consentement ou jusqu'à ce que quelqu'un y mette fin. Lorsque institution_id est renseigné, une banque qui ne peut pas maintenir l'accès ouvert répond 400 ongoing_access_not_available avant tout écran. Sans ce paramètre, le sélecteur de banques ne liste que les banques qui le peuvent.

Options disponibles:
one_time,
ongoing
country
string

Facultatif. Sans ce champ, la personne choisit parmi les pays que votre application a activés. Il doit s'agir d'un pays couvert par Bank Link ; tout autre pays, y compris ZZZ, répond 400 invalid_request avec field: country. Un corps de requête vide reste valide.

Pattern: ^[A-Z]{3}$
institution_id
string

Banque facultative à présélectionner, issue de list_institutions. Le sélecteur est ignoré.

Maximum string length: 64
segment
enum<string>
défaut:any

Filtre le sélecteur et indique à la banque quelle connexion ouvrir lorsqu'elle distingue les différents accès. Valeur par défaut : any.

Options disponibles:
personal,
business,
any
data
enum<string>[]

Ce qu'il faut lire. accounts est toujours inclus : nom, type, devise, identifiants et nom du titulaire lorsque la banque le partage. Par défaut ["accounts"].

Maximum array length: 3
Options disponibles:
accounts,
balances,
transactions
history_days
integer
défaut:90

Nombre de jours d'historique de transactions à demander, de 1 à 365, 90 par défaut. La banque peut en fournir moins : chaque compte indique ce qu'il a fourni dans history_coverage. Ne peut pas être envoyé avec history_from.

Plage requise: 1 <= x <= 365
history_from
string<date>

Date de début de l’historique à demander, à la place de history_days. Ne peut pas être envoyée avec history_days : les deux ensemble répondent 400 history_window_ambiguous. Une date antérieure à 365 jours, ou future, répond 400 window_not_available.

extended_history
enum<string>
défaut:standard

allow_extra_auth permet à une banque qui demande une confirmation supplémentaire de fournir l'historique plus ancien.

Options disponibles:
standard,
allow_extra_auth

Uniquement pour l'accès continu. Nombre de jours pendant lesquels demander à la banque de maintenir l'accès ouvert, 1 ou plus. Par défaut : la durée maximale autorisée par la banque. La connexion indique la date que la banque a effectivement accordée dans consent.expires_at. Avec access: one_time, elle répond 400 invalid_request avec field: consent_days.

Plage requise: 1 <= x <= 32767
ownership
object

Comparaison facultative du titulaire du compte avec une personne ou une entreprise.

end_user
object

La personne ou l'entreprise qui connecte le compte.

redirect_url
string<uri>

Où le navigateur est redirigé à la fin, avec link_id, status et un state signé (à titre indicatif uniquement : le webhook et get_link font foi). Dans une application sandbox, une adresse http simple vers localhost, 127.0.0.1 ou [::1] (quel que soit le port ou le chemin, sans identifiants ni fragment) ne nécessite aucun enregistrement. Toute autre adresse renvoie 400 redirect_url_not_registered : l'enregistrement d'autres adresses n'est pas encore disponible. Sans redirect_url, la personne termine sur la page de résultat propre à Didit.

Maximum string length: 2048
allowed_origins
string<uri>[]

Acceptées mais non utilisées aujourd'hui : réservées au Bank Link intégré de Didit, qui n'est pas encore disponible. Origines HTTPS, jusqu'à 50.

Maximum array length: 50
language
string

Code de langue facultatif, par exemple es ou pt-BR. Sinon, la langue du navigateur.

Maximum string length: 16
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
vendor_data
string

Votre propre référence, renvoyée sur le lien et sur la connexion.

Maximum string length: 255
expires_in
integer
défaut:3600

Durée de vie du lien en secondes, de 300 à 86400. Valeur par défaut : 3600.

Plage requise: 300 <= x <= 86400
duplicates
enum<string>
défaut:reuse

reuse (par défaut) finalise un lien qui renvoie vers des comptes déjà partagés, comme un renouvellement de cette connexion. allow crée une seconde connexion indépendante.

Options disponibles:
reuse,
allow
allow_one_time_fallback
boolean
défaut:false

Avec ongoing, permet à la personne de poursuivre avec une lecture ponctuelle auprès d'une banque qui ne peut pas maintenir l'accès ouvert, après avoir confirmé l'accès réduit sur son propre écran. Le devis indique le coût de cette option. Uniquement avec access: ongoing : avec un accès ponctuel, la réponse est 400 invalid_request avec field: allow_one_time_fallback.

accept_reduced_grant
boolean
défaut:false

Lorsque la banque ou la personne accorde moins que ce que vous avez demandé, le lien est finalisé avec succès et seuls les périmètres accordés sont facturés. Sinon, le lien se termine en failed avec reduced_grant et rien n'est facturé.

sandbox
object

Applications sandbox uniquement : sélectionne le client Test Bank de Didit. Ignoré dans une application de production.

Réponse

Le lien a été créé.

Une exécution de Bank Link pour une personne : connecter une banque ou renouveler une connexion. Confirmez vous-même un lien avec get_link : ne faites jamais confiance à un identifiant envoyé par le navigateur.

id
string<uuid>
requis

Identifiant du lien.

mode
enum<string>
requis
Options disponibles:
connect,
renew
access
enum<string>
requis
Options disponibles:
one_time,
ongoing
status
enum<string>
requis

Statut du lien. completed, cancelled, expired et failed sont des statuts définitifs.

Options disponibles:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
requis

La page hébergée vers laquelle orienter la personne. Renvoyée uniquement à la création du lien ; null lors des lectures ultérieures, car le token n'est pas stocké.

client_token
string | null
requis

Le jeton du Bank Link intégré de Didit, qui n'est pas encore disponible : ouvrez url dès aujourd'hui. Renvoyé uniquement à la création du lien ; null lors des lectures suivantes. Usage unique et de courte durée. Il ne contient aucune donnée personnelle. Ne le journalisez jamais.

expires_at
string<date-time>
requis

Quand un lien non utilisé cesse de fonctionner.

connection_id
string<uuid> | null
requis

La connexion créée ou renouvelée par ce lien, une fois que status vaut completed.

check_id
string<uuid> | null
requis

Le résultat de la comparaison de l'actionnariat de ce lien, lorsque ownership.compare a été demandé avec une valeur autre que none.

reused
boolean
requis

true lorsque le lien a été finalisé comme un renouvellement d'une connexion existante, car la personne partage déjà exactement ces comptes (duplicates: reuse). Aucun montant n'est facturé deux fois.

error
object | null
requis

Pourquoi le lien a échoué, lorsque status vaut failed. Sinon null.

quote
object
requis

Le prix d'un lien, figé à sa création. Le montant facturé est celui du devis. Les lectures ne sont jamais facturées.

vendor_data
string | null
requis

Votre référence issue de la requête.

Dernière modification le 22 novembre 2026