Movimientos Masivos de Dinero

El Bulk Money Movement te permite procesar múltiples Money Movements desde un solo archivo cargado, lo que lo hace ideal para PayOuts de alto volumen y procesamiento de lotes operativo.

Bulk se usa comúnmente para:

Ejecutar desembolsos masivos (ej., nómina, pagos a proveedores, reembolsos).

Reducir el número de llamadas API enviando muchos Money Movements en una sola solicitud.

Crear el archivo JSON con la lista de Money Movements

El paso inicial es crear tu archivo JSON que indica los movimientos de dinero que necesitan ser procesados.

Requisitos del archivo JSON

Reglas clave para el archivo JSON de entrada:

El payload debe ser un arreglo JSON: empieza con [ y termina con ].

Cada solicitud de Money Movement debe estar dentro de { } y separada por comas. Aquí hay un ejemplo del formato de diseño:

[ 
   { 
       money_movement_request_1
   },
   {
       money_movement_request_2
   }
]

Los comentarios no están permitidos (ej., // ...). Por ejemplo:

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",     //Comments are not allowed
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"MX Payment - Saldo Crobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    }
]

El monto debe enviarse en la unidad de moneda más pequeña (ej., 100.00 MXN → 10000).

El tamaño máximo del archivo de entrada es aproximadamente 4.7 MB.

Tipos soportados

Bulk money movements permite dos tipos de objetos money movement.

Usando un counterparty_id ya creado: Lo siguiente representa un formato JSON válido que contiene dos cuerpos de solicitud Create a Money Movement que es aceptado por bulk money movements:

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"SPEI Payment - Saldo Cobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    },
    {
        "amount":500,
        "source_id":"acc_aJmUHHWDOB",
        "destination_id":"cp_c0jhj7gn7v",
        "metadata":
        {
            "description":"ACH Payment Bancolombia",
        },
        "external_id":"BBM_32656"
    }
]

Sin un counterparty_id creado previamente: El proceso te permite crear un counterparty directamente incluyendo los detalles del cuerpo de solicitud Create a Counterparty dentro del destino. Lo siguiente representa un formato JSON válido que contiene un money movement SPEI con un destino counterparty válido y es aceptado por bulk money movements:

[
    {
        "amount": 1,
        "source_id": "acc_poyBrvkPRI",
        "destination":
        {
            "geo": "mex",
            "type": "clabe",
            "alias": "cccc",
            "metadata":
            {
                "account_number": "710969000037970288",
                "counterparty_fullname": "Company",
                "counterparty_id_type": "rfc",
                "counterparty_id_number": "ND"
            }
        },
        "metadata":
        {
            "description": "TEST PRO BMM",
            "reference": "009911"
        }
    }

]

Counterparties soportados

Payout vía Bulk soporta los siguientes tipos de destino:

Contrapartes Payout Colombia

Contrapartes Payout México

Tipo de Destino	Tipo de Contraparte	Rails
Cuenta Corriente	`cc`	Fast Pay / ACH
Cuenta de Ahorro	`ch`	Fast Pay / ACH
Depósito Electrónico	`dp`	Fast Pay / ACH
Clave BreB	`breb_key`	BreB / Fast Pay* / ACH*
Cobre Balance	`cobre_balance`	Fast Pay

Idempotencia de contrapartes en Bulk

El proceso de bulk money movement verifica la existencia de la contraparte antes de la creación asegurando que no haya sido creada previamente. Esto se logra verificando la idempotencia a través de la concatenación de los siguientes campos:

Tipo de Contraparte	Campos Concatenados
`cc`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, y counterparty_phone
`ch`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, y counterparty_phone
`dp`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, y counterparty_phone
`cobre_balance`	geo, type, cobre_tag, counterparty_email, counterparty_fullname, counterparty_id_number, counterparty_id_type, y counterparty_phone

Flujo de autorización (opcional)

Puedes enviar tu Bulk Money Movement para aprobación configurando la bandera checker_approval a true en el encabezado de la solicitud.

Si eliges enviar el bulk para aprobación, todos los Money Movements dentro del archivo serán enviados para aprobación y, si no se encuentra ningún error de validación o técnico, los money movements serán creados con un estado pending_approval.

Para aprender más sobre aprobaciones, consulta Bulk Money Movements Approval ~~o documentación de aprobación de money movements individuales~~.

Ciclo de vida del Bulk

Un Payout a través de Bulk Money Movement sigue un ciclo de vida simple:

1. Construir el archivo JSON
Construye el archivo JSON con todos los Money Movements a ser procesados.

2. Cargar el archivo
Carga el archivo para crear el Bulk Money Movement.

3. Proceso de validación
Cobre valida el archivo e inicia el procesamiento de cada Money Movement, rastreando el estado del proceso bulk (ej., validating, processing, completed, etc.).

4. Creación de Money Movement
Los Money Movements creados a través de Bulk incluirán un batch_id (útil para reconciliación).

5. Recibir actualizaciones de estado
Rastrea el progreso usando endpoints de recuperación y/o Webhooks.

Incluso si un Money Movement encuentra un error funcional, el objeto Money Movement puede ser creado aún y el error se reflejará en la descripción de su estado.

Proceso de bulk money movement

La plataforma recibirá y validará un archivo que contiene múltiples money movements.
Una vez validado, se actualizará la marca de tiempo de ejecución y el número total de pagos.
Luego el proceso ejecutará todos los money movements listados en el archivo y completará el proceso actualizando el tiempo de ejecución y el número total de pagos.

Estados de bulk money movement

Validating: Estado inicial del bulk money movement. Refleja el momento cuando el proceso comenzó a validar el formato del archivo.

Failed: Estado que indica que el proceso de validación ha encontrado un error.

Processing: Estado que indica que el archivo ha sido validado, y cada money movement en el archivo será procesado.

Pending Approval: Estado que indica que el archivo está esperando aprobación.

Canceled: Estado que indica que el proceso de bulk money movement ha sido cancelado.

Completed: Estado que indica que el proceso de bulk money movement ha sido completado.

El bulk money movement solo validará el formato del archivo cargado. Si ocurre un error funcional, el objeto Money Movement será creado aún, y el error (del Diccionario de errores) será incluido en la descripción del money movement.

Formatos de archivo permitidos

Mientras continuamos evolucionando el proceso de bulk money movement para incorporar nuevos formatos disponibles, los siguientes están permitidos:

Formato de archivo	Formato de objeto	Tamaño máximo
JSON	Solicitud Money Movement	4.7 Mb

Acciones realizadas en Bulk Money Movements

🔑 Crear

🔍 Recuperación

👍 Aprobación

Descripción: Creación de Bulk Money Movement.
Qué esperar después de la acción: Se crea Bulk Money Movement en Cobre.
📘 Aprende más:

🔗 Crear un Bulk Money Movement

Cómo empezar

Antes de comenzar, recomendamos revisar las siguientes consideraciones.

Antes de usar esta API

Prepara tu archivo JSON

Crea un arreglo JSON que contenga todas las solicitudes de Money Movement.

Sigue los requisitos del archivo JSON.

Asegúrate de que cada entrada use un destination_id existente o un objeto destination en línea.

Considera aprovechar la idempotencia de Counterparty según los campos concatenados por tipo de contraparte.

Asegúrate de tener la solicitud de money movement correcta

Asegúrate de que los campos del money movement estén correctamente representados:

Recuerda que la combinación entre origen y destino debe tener una combinación de money movement válida.

El source_id tiene que ser válido y existir.

El destination_id (si se proporciona) tiene que ser válido y existir.

Los campos dentro de los metadata necesitarán estar alineados dependiendo de la combinación de money movement de origen y destino.

El amount es la unidad más pequeña de la moneda (ej., 100.00 MXN debe representarse como 10000).

El tamaño máximo del archivo json de entrada es aproximadamente 4.7 MB.

Considera usar external_id para vincular cada pago a un objeto o proceso externo

Considera implementar la lógica checker_approval.

Envía tu Bulk money movement para aprobación (opcional)

Usa el Endpoint de Decisión de Bulk Money para proporcionar el resultado de la decisión sobre el Bulk.

Ver Flujo de aprobación de Bulk Money Movements para más detalles.

Implementa Webhooks para rastrear el estado del Money Movement

Para mantenerte informado sobre el estado de las transacciones Payout, recomendamos encarecidamente implementar Webhooks. Los Webhooks notifican a tu sistema cuando un pago es iniciado, procesado, completado, o falla. También suscríbete a los eventos requeridos para recibir notificaciones sobre débitos y créditos de transacciones.

Ver Notificaciones y suscripciones para más detalles.

Qué esperar después de usar esta API

Actualizaciones de estado del proceso Bulk

El proceso bulk transiciona a través de estados como validating, processing, y completed.

Reconcilia usando batch_id

Los Money Movements creados desde bulk incluyen un batch_id, permitiendo correlación entre el lote y cada payout resultante.

Maneja errores por Money Movement

Algunos Money Movements pueden fallar debido a requisitos funcionales. Usa endpoints de recuperación y Webhooks para identificar y reintentar solo las entradas afectadas.

Movimientos Masivos de Dinero

Crear el archivo JSON con la lista de Money Movements#

Requisitos del archivo JSON#

Tipos soportados#

Counterparties soportados#

Idempotencia de contrapartes en Bulk#

Flujo de autorización (opcional)#

Ciclo de vida del Bulk#

Proceso de bulk money movement#

Estados de bulk money movement#

Formatos de archivo permitidos#

Acciones realizadas en Bulk Money Movements#

Cómo empezar#

Antes de usar esta API#

Qué esperar después de usar esta API#