Saltar al contenido principal
POST
curl
Didit’s endpoint para crear un Bank Link inicia una ejecución de Bank Link en tu servidor, para conectar un banco o renovar una conexión, y devuelve la url alojada. Todos los campos tienen un valor por defecto, así que la solicitud más sencilla es {} más lo que quieras enviar. Guarda el id devuelto junto a tu usuario y confirma el resultado por tu cuenta con Obtener un enlace bancario o con el webhook bank.link.completed. Consulta la guía de inicio rápido y Bank Link.

Autorizaciones

x-api-key
string
header
requerido

La clave de API de tu aplicación, desde Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener permisos limitados: ninguno, lectura o escritura por recurso, restringida a algunos flujos o solo a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, está revocada o ha caducado; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud procede de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, vídeos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Encabezados

Idempotency-Key
string

Clave opcional que eliges para garantizar la seguridad de los reintentos en una operación, de hasta 255 caracteres (puede usarse un UUID). Una solicitud repetida con la misma clave, endpoint, parámetros de consulta y cuerpo recibe la primera respuesta, con el mismo código de estado y el mismo cuerpo, y no se ejecuta ni se factura de nuevo. La misma clave con otro endpoint, otros parámetros de consulta o un cuerpo distinto devuelve 409 idempotency_key_reused. Si la primera solicitud sigue en curso, devuelve 409 idempotency_key_in_progress con Retry-After. Una solicitud fallida (cualquier 4xx o 5xx) no se almacena, así que puedes volver a enviarla con la misma clave. Las claves pertenecen a tu aplicación, tanto si llamas con una clave de API como con un token de acceso. Consulta Reintentos e idempotencia.

Required string length: 1 - 255

Cuerpo

application/json

Crea un enlace bancario. La solicitud más sencilla es {} más lo que quieras indicar: todos los campos tienen un valor por defecto.

mode
enum<string>
predeterminado:connect

connect (predeterminado) crea una conexión nueva. renew requiere connection_id y reutiliza la configuración de esa conexión.

Opciones disponibles:
connect,
renew
connection_id
string<uuid>

La conexión que se va a renovar. Solo con mode: renew.

access
enum<string>
predeterminado:one_time

one_time (predeterminado) lee los datos una sola vez. ongoing mantiene el acceso abierto hasta que termine el consentimiento o alguien lo detenga. Con institution_id definido, un banco que no puede mantener el acceso abierto responde 400 ongoing_access_not_available antes de mostrar ninguna pantalla. Sin él, el selector de bancos solo muestra los que sí pueden.

Opciones disponibles:
one_time,
ongoing
country
string

Opcional. Sin este campo, la persona elige entre los países que habilitó tu aplicación. Debe ser un país que Bank Link atienda; cualquier otro, incluido ZZZ, responde 400 invalid_request con field: country. Un cuerpo de solicitud vacío sigue siendo válido.

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

Banco opcional que preseleccionar, de list_institutions. Omite el selector.

Maximum string length: 64
segment
enum<string>
predeterminado:any

Filtra el selector e indica al banco qué inicio de sesión abrir cuando el banco separa los inicios de sesión. Valor por defecto any.

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

Qué leer. accounts se incluye siempre: nombre, tipo, moneda, identificadores y el nombre del titular cuando el banco lo comparte. Valor por defecto ["accounts"].

Maximum array length: 3
Opciones disponibles:
accounts,
balances,
transactions
history_days
integer
predeterminado:90

Días de historial de transacciones que solicitar, de 1 a 365; por defecto, 90. El banco puede entregar menos: cada cuenta indica lo que entregó en history_coverage. No puede enviarse junto con history_from.

Rango requerido: 1 <= x <= 365
history_from
string<date>

Fecha de inicio del historial que quieres solicitar, en lugar de history_days. No se puede enviar junto con history_days: si se envían ambos, responde 400 history_window_ambiguous. Una fecha de hace más de 365 días, o futura, responde 400 window_not_available.

extended_history
enum<string>
predeterminado:standard

allow_extra_auth permite que un banco que pide una confirmación adicional libere el historial anterior.

Opciones disponibles:
standard,
allow_extra_auth

Solo para monitorización continua. Cuántos días pedir al banco que mantenga abierto el acceso, 1 o más. Por defecto: el máximo que permita el banco. La conexión indica en consent.expires_at la fecha que el banco concedió realmente. Con access: one_time responde 400 invalid_request con field: consent_days.

Rango requerido: 1 <= x <= 32767
ownership
object

Comparación opcional del titular de la cuenta con una persona o una empresa.

end_user
object

La persona o empresa que conecta la cuenta.

redirect_url
string<uri>

Adónde va el navegador al final, con link_id, status y un state firmado (solo para mostrar: el webhook y get_link son la fuente de verdad). En una aplicación de sandbox, una dirección http simple de localhost, 127.0.0.1 o [::1] (cualquier puerto y ruta, sin credenciales ni fragmento) no requiere registro. Cualquier otra dirección responde 400 redirect_url_not_registered: el registro de otras direcciones todavía no está disponible. Sin redirect_url, la persona termina en la propia página de resultados de Didit.

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

Aceptado, pero hoy no se usa: reservado para Bank Link integrado de Didit, que aún no se ha publicado. Orígenes HTTPS, hasta 50.

Maximum array length: 50
language
string

Código de idioma opcional, como es o pt-BR. Si no se indica, se usa el idioma del navegador.

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

Su propia referencia, devuelta en el enlace y en la conexión.

Maximum string length: 255
expires_in
integer
predeterminado:3600

Duración del enlace en segundos, de 300 a 86400. Por defecto, 3600.

Rango requerido: 300 <= x <= 86400
duplicates
enum<string>
predeterminado:reuse

reuse (predeterminado) completa un enlace que resuelve a cuentas que ya compartes como una renovación de esa conexión. allow crea una segunda conexión independiente.

Opciones disponibles:
reuse,
allow
allow_one_time_fallback
boolean
predeterminado:false

Con ongoing, permite que la persona continúe con una lectura única en un banco que no puede mantener el acceso abierto, tras confirmar el acceso reducido en su propia pantalla. La cotización muestra lo que cuesta. Solo con access: ongoing: con acceso único responde 400 invalid_request con field: allow_one_time_fallback.

accept_reduced_grant
boolean
predeterminado:false

Cuando el banco o la persona concede menos de lo que solicitaste, completa el enlace y cobra solo los alcances concedidos. De lo contrario, el enlace termina en failed con reduced_grant y no se cobra nada.

sandbox
object

Solo para aplicaciones sandbox: elige el cliente de Didit Test Bank. Se ignora en una aplicación en producción.

Respuesta

El enlace fue creado.

Una ejecución de Bank Link para una persona: conectar un banco o renovar una conexión. Confirma tú mismo un enlace con get_link: nunca confíes en un id enviado por el navegador.

id
string<uuid>
requerido

Identificador del enlace.

mode
enum<string>
requerido
Opciones disponibles:
connect,
renew
access
enum<string>
requerido
Opciones disponibles:
one_time,
ongoing
status
enum<string>
requerido

Estado del enlace. completed, cancelled, expired y failed son estados finales.

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

La página alojada a la que hay que enviar a la persona. Se devuelve solo al crear el enlace; es null en las lecturas posteriores, porque el token no se almacena.

client_token
string | null
requerido

El token del Bank Link integrado de Didit, que todavía no está disponible: hoy, abre url. Se devuelve solo al crear el enlace; en lecturas posteriores es null. Tiene un único propósito y una vida corta. No contiene datos personales. No lo registres nunca en logs.

expires_at
string<date-time>
requerido

Cuándo deja de funcionar un enlace que no se ha canjeado.

connection_id
string<uuid> | null
requerido

La conexión que creó o renovó este enlace, una vez que status es completed.

check_id
string<uuid> | null
requerido

El resultado de propiedad de este enlace, cuando se solicitó ownership.compare distinto de none.

reused
boolean
requerido

true cuando el enlace se completó como una renovación de una conexión existente porque la persona ya comparte exactamente estas cuentas (duplicates: reuse). No se cobra dos veces.

error
object | null
requerido

Por qué falló el enlace, cuando status es failed. En caso contrario, null.

quote
object
requerido

El precio de un enlace, fijado al crearlo. El cargo es el de la cotización. Las lecturas nunca generan cargos.

vendor_data
string | null
requerido

Su referencia de la solicitud.

Última modificación el 22 de noviembre de 2026