1. Transacciones
Fidi X Developer Preview
  • Fidi X
    • Introducción
    • Conceptos Fundamentales
    • Catálogo de APIs
      • Diccionario de Datos - Enumeraciones
      • Autenticación
        • Obtener Token de Acceso
      • Cuentas
        • Crear Cuenta
        • Obtener Cuenta por ID
        • Listar Cuentas por Ledger
        • Actualizar Cuenta
        • Eliminar Cuenta
        • Suspender Cuenta
        • Activar Cuenta
        • Obtener Balance de Cuenta
        • Obtener Cuentas linkeadas
        • Linkear Cuenta Bancaria
        • Deslinkear Cuenta Bancaria
      • Personas
        • Crear Persona
        • Listar Personas
        • Obtener Persona por ID
        • Actualizar datos de persona
        • Eliminar persona (soft delete)
        • Obtener jerarquía de persona
        • Bloquear persona y descendientes
        • Desbloquear persona y descendientes
      • Transacciones y Operaciones
        • Transacciones
          • Crear Retiros masivos
            POST
          • Obtener Transferencia Masiva
            GET
          • Crear Transacción
            POST
        • Operations
          • Listar Operaciones
      • Webhooks
        • Crear Suscripción Webhook
        • Listar Suscripciones
        • Obtener Suscripción
        • Actualizar Suscripción
        • Eliminar Suscripción
  • Casos de Uso
    • Cuentas Virtuales
      • Guía de implementación
      • Create Notification
  • Raíz
  1. Transacciones

Crear Retiros masivos

Desarrollando
POST
/fidix/v1/withdrawals
Próximamente:
Registra una solicitud de retiro masivo (lote de withdrawals) de fondos hacia cuentas bancarias externas. El cliente envía un lote de retiros individuales, cada uno con su monto, moneda, cuenta virtual de origen y los datos bancarios del destinatario final.
El endpoint valida y persiste el lote de forma síncrona, lo publica para su procesamiento asíncrono y responde de inmediato con el estado inicial del lote y de cada retiro. El débito en el ledger y la transferencia bancaria ocurren en segundo plano.
Idempotencia
El endpoint es idempotente por Idempotency-Key (UUID).
Mismo key + mismo body → 200 con el lote existente y el estado actual de sus retiros (no crea un lote nuevo).
Mismo key + body diferente → 409.
La comparación se hace por hash SHA-256 del body crudo: cambiar el orden de los campos o los espacios cuenta como body diferente.
Si el lote original quedó sin publicar por una falla previa, el reintento con el mismo key y body vuelve a publicarlo y responde con estado pending.
Unicidad del lote
withdrawal_reference_id es único. Crear un segundo lote con el mismo withdrawal_reference_id (con otro Idempotency-Key) retorna 409.
Comportamiento por item
Cada account_id se valida. Si la cuenta no existe, está cerrada, suspendida o inactiva, ese retiro queda registrado con status: failed y el resto del lote no se ve afectado. Los retiros válidos inician en pending.
Restricciones
El lote debe tener entre 1 y 100 retiros.
reference_id de cada retiro: máximo 20 caracteres, independientemente del banco sponsor.
amount es un string numérico positivo, sin separador de miles y con hasta 8 decimales.
El destino debe ser un banco chileno del catálogo soportado, y el tipo de cuenta debe ser checking_account, sight_account o savings_account.
description solo acepta letras (incluyendo acentuadas, ñ y ü), números, espacios y los caracteres - . , ; : ( ).
No se aceptan campos desconocidos en el body.

Este servicio puede recibir modificaciones

Solicitud

Autorización
JWT Bearer
Agregar el parámetro
Authorization
a Encabezados
Ejemplo:
Authorization: ********************
or
Parámetros de Header

Parámetros del Body application/jsonRequerido

Ejemplos

Respuestas

🟢200
application/json
HTTP 200 cuando es un replay idempotente (mismo Idempotency-Key + mismo body).
Bodyapplication/json

🟢201
🟠400
🟠401
🟠409
🟠422
🔴500
🔴502
🔴503
Solicitud Ejemplo de Solicitud
Shell
JavaScript
Java
Swift
curl --location 'https://sandbox.fidi.money/fidix/v1/withdrawals' \
--header 'traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' \
--header 'Idempotency-Key: 11b9e565-1a4b-4a25-b66a-6cc330b6d3f6' \
--header 'x-api-key: {{apikey}}' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "withdrawal_reference_id": "WD-REF-2026-001",
    "ledger_id": "4c72ccf9-9bf3-4e2d-911e-90834e1c7c26",
    "bank_sponsor": "INTERNACIONAL",
    "account_number": "001111213543",
    "withdrawals": [
        {
            "account_id": "12fbb9da-673a-452c-9104-ae0d8216c154",
            "reference_id": "WD-ITEM-001",
            "amount": "15.00",
            "currency": "CLP",
            "description": "Pago de Recaudacion",
            "destination": {
                "bank_code": "009",
                "account_number": "1234567890",
                "account_type": "checking_account",
                "customer_identification": "27453678-9",
                "customer_name": "Enel",
                "customer_email": "pagos@ejemplo.cl"
            }
        },
        {
            "account_id": "61d37283-e3c0-41fc-9266-4e2ea08fc70f",
            "reference_id": "WD-ITEM-002",
            "amount": "25.00",
            "currency": "CLP",
            "description": "Pago de Recaudacion 2",
            "destination": {
                "bank_code": "037",
                "account_number": "9876543210",
                "account_type": "sight_account",
                "customer_identification": "17487278-9",
                "customer_name": "Movistar",
                "customer_email": "cobranza@ejemplo.cl"
            }
        }
    ]
}'
Respuesta Ejemplo de Respuesta
200 - Ejemplo 1
{
    "data": {
        "withdrawal_request_id": "db3f8941-a40d-492b-bb9e-fd09e0119f70",
        "withdrawal_reference_id": "a1b08e7e-1de7-4d00-8c93-955ca0489492",
        "ledger_id": "4c72ccf9-9bf3-4e2d-911e-90834e1c7c26",
        "account_number": "001111213543",
        "bank_sponsor": "INTERNACIONAL",
        "status": "pending",
        "withdrawals": [
            {
                "id": "8fcf5083-b806-4b8c-8f3f-3a0fdbd3d6f9",
                "account_id": "12fbb9da-673a-452c-9104-ae0d8216c154",
                "reference_id": "e9e7cee7-47c9-4d82-9bac-64eb48df2705",
                "amount": "15.00",
                "currency": "CLP",
                "status": "pending",
                "created_at": "2026-07-14T20:56:26Z",
                "updated_at": "2026-07-14T20:56:26Z"
            },
            {
                "id": "4frf5083-b506-6b8c-yh3f-3a0fdbd3d548",
                "account_id": "61d37283-e3c0-41fc-9266-4e2ea08fc70f",
                "reference_id": "8dea39be-9d10-4dfc-af0f-1f35dbee2430",
                "amount": "25.00",
                "currency": "CLP",
                "status": "pending",
                "created_at": "2026-07-14T20:56:26Z",
                "updated_at": "2026-07-14T20:56:26Z"
            }
        ],
        "created_at": "2026-07-14T20:56:26Z",
        "updated_at": "2026-07-14T20:56:26Z"
    }
}
Modificado en 2026-11-03 21:13:55
Anterior
Transacciones y Operaciones
Siguiente
Obtener Transferencia Masiva
Built with