Funcionalidades Transversales
Conciliación con Reportes Cobre en Colombia Resumen general# Esta guía explica cómo conciliar correctamente transacciones de PayOut (desembolsos) y PayIn (cobranzas) en la plataforma de Cobre para pagos locales en Colombia. Comprender la relación entre Money Movements, Transactions y tus registros internos es esencial para una conciliación financiera precisa. Conceptos clave# Money Movement vs Transaction# En la plataforma de Cobre, cada operación de pago involucra dos identificadores clave: Identificador Descripción Ejemplo Cuándo se genera Money Movement ID Identificador único de la solicitud/operación de pago mm_ady1n4g4udCuando se crea el money movement Transaction ID Identificador único del asiento en el libro contable trx_sjrirldkmkCuando los fondos se debitan o acreditan a tu Cobre Balance
Un Money Movement puede generar una o más Transactions
Cada Transaction está vinculada a un Money Movement
Los Money Movements representan la intención; las Transactions representan los cambios reales de saldo
Métodos de identificación# Al crear cualquier money movement (PayOut o PayIn), tienes dos formas de identificarlo y rastrearlo: 1. Money Movement ID (generado por Cobre)# Generado por: la plataforma de Cobre automáticamente
Formato: prefijo mm_ seguido de una cadena alfanumérica
Unicidad: globalmente único en todas las operaciones de Cobre
Disponibilidad: siempre presente en la respuesta del API cuando se crea el money movement
Caso de uso: identificador principal para el seguimiento con Cobre
2. External ID (provisto por el cliente)# Generado por: tu sistema (provisto en la solicitud del API)
Formato: cualquier formato de cadena que definas (hasta 255 caracteres)
Unicidad: debe ser único dentro de tu organización
Disponibilidad: campo opcional en la solicitud; se devuelve en las respuestas
Caso de uso: vincular operaciones de Cobre con tus registros internos (facturas, órdenes, etc.)
curl --request POST \
--url https:
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'idempotency: ' \
--data '{
"source_id" : "acc_1232145215" ,
"destination_id" : "cp_5YFeIDhNkz" ,
"amount" : 1000 ,
"external_id" : "clientUser1234" ,
"metadata" : {
} ,
"checker_approval" : false
} '{
"id" : "mm_0987654321" ,
"batch_id" : "bat_0987654321" || "chk_0987654321" ,
"external_id" : "clientUser1234" ,
"mm_approval_id" : "" ,
"creator" : "usr_bGcdf26rR4" ,
"type" : "fast_pay" ,
"geo" : "col" ,
"status" : {
"state" : "initiated" ,
"code" : "string" ,
"description" : "string"
} ,
"source_id" : "acc_KJnAkypWSc" ,
"source" : { } ,
"destination_id" : "cp_5YFeIDhNkz" ,
"destination" : { } ,
"currency" : "cop" ,
"amount" : 100 ,
"metadata" : {
} ,
"created_at" : "2026-06-24T15:37:37Z" ,
"updated_at" : "2026-06-24T15:37:38Z" ,
"checker_approval" : false
} Conciliación de PayOut# Los PayOuts (desembolsos) te permiten enviar dinero desde tu Cobre Balance a cuentas bancarias externas o counterparties. Estructura de la solicitud de PayOut# Al crear un PayOut, especificas: Campo Descripción Requerido source_idTu Cobre Balance (cuenta de origen) ✅ Sí destination_idCuenta del beneficiario/counterparty ✅ Sí amountMonto a desembolsar (en unidades menores, p. ej., centavos) ✅ Sí external_idTu referencia única para seguimiento No, pero recomendado
Flujo de Transactions de PayOut# Flujo esperado: desembolso exitoso# ┌─────────────────────────────────────┐
│ 1. Create PayOut Money Movement │
│ POST /v1/money_movements │
│ • Amount: 10,000 COP │
│ • External ID: INV-2025-001 │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 2. Money Movement Created │
│ • MM ID: mm_ady1n4g4ud │
│ • Status: processing │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 3. Debit Transaction Created │
│ • TRX ID: trx_sjrirldkmk │
│ • Type: debit │
│ • Amount: -10,000 COP │
│ • Account: Source Balance │
│ • Instant application │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 4. Funds Sent Successfully │
│ • MM Status: completed │
│ • Destination received funds │
└─────────────────────────────────────┘1.
Money Movement ID: mm_ady1n4g4ud
External ID: INV-2025-001
2.
Transaction de débito aplicada (inmediata): Transaction ID: trx_sjrirldkmk
Saldo de la cuenta: se reduce en 10,000 COP de inmediato
Vinculada al Money Movement: mm_ady1n4g4ud
3.
Estado del Money Movement: completed
Tu Cobre Balance: se reduce permanentemente en 10,000 COP
Beneficiario: recibió 10,000 COP
Registro de conciliación: Money Movement ID External ID Tipo Monto Transactions Impacto final en saldo mm_ady1n4g4udINV-2025-001PayOut 10,000 COP 1 débito (trx_sjrirldkmk) -10,000 COP
Flujo alternativo: desembolso rechazado# ┌─────────────────────────────────────┐
│ 1. Create PayOut Money Movement │
│ POST /v1/money_movements │
│ • Amount: 10,000 COP │
│ • External ID: INV-2025-002 │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 2. Money Movement Created │
│ • MM ID: mm_xyz789def │
│ • Status: processing │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 3. Debit Transaction Created │
│ • TRX ID: trx_abc123first │
│ • Type: debit │
│ • Amount: -10,000 COP │
│ • Account: Source Balance │
│ • Instant application │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 4. Destination Rejects Payment │
│ • MM Status: rejected │
│ • Reason: Invalid account, etc. │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 5. Credit Transaction Created │
│ • TRX ID: trx_abc123second │
│ • Type: credit (reversal) │
│ • Amount: +10,000 COP │
│ • Account: Source Balance │
│ • Funds returned to origin │
└─────────────────────────────────────┘1.
Money Movement ID: mm_xyz789def
External ID: INV-2025-002
2.
Transaction de débito aplicada (inmediata): Transaction ID: trx_abc123first
Saldo de la cuenta: se reduce en 10,000 COP de inmediato
3.
Estado del Money Movement: rejected
Motivo: la cuenta de destino rechazó el pago o es inválida
4.
Transaction de crédito aplicada (reverso): Transaction ID: trx_abc123second
Saldo de la cuenta: se restaura en 10,000 COP
Vinculada al mismo Money Movement: mm_xyz789def
5.
Estado del Money Movement: rejected
Tu Cobre Balance: cambio neto = 0 COP (débito + crédito)
Beneficiario: no recibió fondos
Registro de conciliación: Money Movement ID External ID Tipo Monto Transactions Impacto final en saldo mm_xyz789defINV-2025-002PayOut 10,000 COP 2 transactions: 1. Débito: trx_abc123first (-10,000) 2. Crédito: trx_abc123second (+10,000) 0 COP (revertido)
Buenas prácticas de conciliación de PayOut# ✅ Rastrea ambos IDs: guarda money_movement_id y external_id en tus registros ✅ Monitorea cambios de estado: un PayOut con 2 transactions (débito + crédito) indica un rechazo ✅ Usa webhooks: suscríbete a eventos de cambio de estado para actualizar registros en tiempo real ✅ Consulta el Transaction Report: descarga reportes filtrados por rango de fechas para conciliar todos los movimientos ✅ Verificación de saldo neto: para PayOuts rechazados, verifica que las transactions de débito y crédito se compensen Conciliación de PayIn# Los PayIns (cobranzas) te permiten recibir dinero en tu Cobre Balance desde pagadores. Cobre ofrece dos métodos de PayIn: 1.
Direct Link — Generar un link de pago para un pagador específico
2.
CheckOut — Crear una página de pago flexible con múltiples opciones
Estructura de la solicitud de PayIn# Al crear un PayIn, especificas: Campo Descripción Requerido counterparty_idInformación del pagador ✅ Sí destination_idTu Cobre Balance (a donde llegan los fondos) ✅ Sí amountMonto a cobrar ✅ Sí (o monto abierto para CheckOut) external_idTu referencia única para seguimiento No, pero recomendado payment_methodsMétodos de pago permitidos ✅ Sí
Flujo de Transactions de PayIn# Flujo esperado: cobranza exitosa (Direct Link)# ┌─────────────────────────────────────┐
│ 1. Create Direct Link │
│ POST /v1/money_movements │
│ • Amount: 10,000 COP │
│ • External ID: ORDER-2025-050 │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 2. Direct Link Created │
│ • MM ID: mm_payin123abc │
│ • Payment link URL generated │
│ • Status: processing │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 3. Payer Opens Link │
│ • Chooses payment method │
│ • Completes payment │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 4. Payment Confirmed │
│ • MM Status: completed │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 5. Credit Transaction Created │
│ • TRX ID: trx_credit999xyz │
│ • Type: credit │
│ • Amount: +10,000 COP │
│ • Account: Destination Balance │
└─────────────────────────────────────┘1.
Money Movement ID: mm_payin123abc
External ID: ORDER-2025-050
URL de pago: compartida con el pagador
2.
El pagador completa el pago: El pagador usa el link para pagar
El método de pago se procesa exitosamente
3.
Estado del Money Movement actualizado: El estado cambia a: completed
4.
Transaction de crédito creada (solo después de completarse): Transaction ID: trx_credit999xyz
Saldo de la cuenta: aumenta en 10,000 COP
Vinculada al Money Movement: mm_payin123abc
5.
Estado del Money Movement: completed
Tu Cobre Balance: aumenta en 10,000 COP
Pagador: pagó exitosamente
Registro de conciliación: Money Movement ID External ID Tipo Monto Transactions Impacto final en saldo mm_payin123abcORDER-2025-050PayIn (Direct Link) 10,000 COP 1 crédito (trx_credit999xyz) +10,000 COP
Flujo esperado: cobranza exitosa (CheckOut)# ┌─────────────────────────────────────┐
│ 1. Create CheckOut │
│ POST /v1/checkouts │
│ • Amount: 10,000 COP (or open) │
│ • External ID: INV-2025-150 │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 2. CheckOut Created │
│ • CheckOut ID: chk_809821845 │
│ • Payment page URL generated │
│ • Status: pending │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 3. Payer Opens CheckOut │
│ • Chooses payment method │
│ • Enters amount (if open) │
│ • Completes payment │
│ MM ID: mm_checkout456def │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 4. Payment Confirmed │
│ • MM Status: completed │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 5. Credit Transaction Created │
│ • TRX ID: trx_checkout888ghi │
│ • Type: credit │
│ • Amount: +10,000 COP │
│ • Account: Destination Balance │
└─────────────────────────────────────┘Pasos de conciliación: (igual que Direct Link)El flujo es idéntico a Direct Link, con el mismo patrón de creación de transactions: La transaction de crédito solo se crea cuando status = completed
Si el pago falla o es rechazado, no se crea ninguna transaction
Registro de conciliación: Money Movement ID External ID Tipo Monto Transactions Impacto final en saldo mm_checkout456defINV-2025-150PayIn (CheckOut) 10,000 COP 1 crédito (trx_checkout888ghi) +10,000 COP
Flujo alternativo: cobranza fallida# ┌─────────────────────────────────────┐
│ 1. Create Direct Link/CheckOut │
│ • Amount: 10,000 COP │
│ • External ID: ORDER-2025-999 │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 2. Money Movement Created │
│ • MM ID: mm_failed777ghi │
│ • Status: processing │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 3. Payer Attempts Payment │
│ • Payment method fails │
│ • Insufficient funds, etc. │
└──────────────┬──────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ 4. Payment Rejected │
│ • MM Status: rejected │
│ • NO transaction created │
└─────────────────────────────────────┘1.
Money Movement ID: mm_failed777ghi
External ID: ORDER-2025-999
2.
El método de pago del pagador fue declinado
El estado cambia a: rejected
3.
No se crea ninguna Transaction: Importante: no se genera transaction de crédito
Tu Cobre Balance permanece sin cambios
4.
Estado del Money Movement: rejected
Tu Cobre Balance: sin cambio (impacto 0 COP)
Pagador: no pagó exitosamente
Registro de conciliación: Money Movement ID External ID Tipo Monto Transactions Impacto final en saldo mm_failed777ghiORDER-2025-999PayIn 10,000 COP 0 transactions 0 COP (no se recibieron fondos)
Buenas prácticas de conciliación de PayIn# ✅ Crédito solo al completarse: las transactions SOLO se crean cuando status = completed ✅ Rastrea pagos pendientes: monitorea money movements en estado processing para la acción del pagador ✅ Gestiona rechazos: los money movements con estado rejected tendrán 0 transactions ✅ Usa external_id: vincula a tus órdenes, facturas o registros de clientes ✅ Integración con webhooks: recibe notificaciones cuando los pagadores completen pagos ✅ Conciliación por transaction: usa el Transaction Report para verificar que todos los créditos coincidan con money movements completados Transaction Reports# Cobre proporciona Transaction Reports para facilitar la conciliación en todos tus money movements. Estructura del reporte# Los siguientes campos en el layout del reporte ayudarán a realizar el proceso de conciliación: Campo Descripción Ejemplo idIdentificador único de la transaction trx_sjrirldkmkmetadata.money_movement_idMoney movement vinculado mm_ady1n4g4udtypeTipo de operación col_debit, col_credit, r2p_creditcredit_debit_typeDébito o crédito debit, creditamountMonto de la transaction 10000 (en unidades menores)currencyCódigo de moneda COPaccount_idTu Cobre Balance afectado acc_123abcmetadata.mm_external_idTu referencia INV-2025-001created_atTimestamp de la transaction 2024-06-24T15:37:38Z
Consulta de Transaction Reports# {
"id" : "repo_kJs8GO03vC" ,
"resource" : "string" ,
"start_date" : "2024-09-28T00:00:00Z" ,
"end_date" : "2024-10-05T00:00:00Z" ,
"offset" : "-05:00" ,
"requested_at" : "2024-10-28T12:39:11Z" ,
"created_at" : "2024-10-28T12:39:11Z" ,
"metadata" : {
"account_id" : "acc_123456" ,
"statement_date" : "2025-05"
} ,
"file_name" : "20240928_20241028_transactions_repo_kjs8go03vc.csv" ,
"file_format" : "csv" ,
"file_layout" : "transactions_csv_v1" ,
"sensitive_data" : false
} Flujo de trabajo de conciliación# Proceso paso a paso# 1. Descargar Transaction Report# 2. Agrupar por Money Movement ID# Organiza las transactions por su money movement vinculado: Money Movement: mm_ady1n4g4ud
├─ Transaction 1: trx_sjrirldkmk (debit: -10,000 COP)
Money Movement: mm_xyz789def
├─ Transaction 1: trx_abc123first (debit: -10,000 COP)
├─ Transaction 2: trx_abc123second (credit: +10,000 COP)3. Hacer match de External IDs# Cruza external_id con tus sistemas internos: Cobre External ID: INV-2025-001
→ Coincide con factura interna: INV-2025-001
→ Money Movement: mm_ady1n4g4ud
→ Impacto neto: -10,000 COP4. Verificar el impacto neto en saldo# Completed: 1 transaction de débito (impacto neto: negativo)
Rejected: 1 transaction de débito + 1 transaction de crédito (impacto neto: cero)
Completed: 1 transaction de crédito (impacto neto: positivo)
Rejected: 0 transactions (impacto neto: cero)
Fórmulas de conciliación# Cálculo esperado de saldo# Saldo actual = Saldo anterior + Créditos - Débitos
Saldo anterior: 100,000 COP
Créditos (PayIns): +50,000 COP
Débitos (PayOuts): -30,000 COP
Saldo actual: 100,000 + 50,000 - 30,000 = 120,000 COP
Cantidad de transactions por Money Movement# Completed: 1 transaction (débito)
Rejected: 2 transactions (débito + reverso en crédito)
Completed: 1 transaction (crédito)
Escenarios comunes de conciliación# Escenario 1: Todos los PayOuts exitosos#
Money Movements: 5 PayOuts
Transactions esperadas: 5 débitos
Impacto neto: -50,000 COP (suma de todos los PayOuts)
Escenario 2: PayOut con rechazo#
Money Movement: mm_rejected001
Transaction 1: -10,000 COP (debit)
Transaction 2: +10,000 COP (credit)
Impacto neto: 0 COP
Estado: rejected
Escenario 3: PayIn completado#
Money Movement: mm_payin001
Transaction 1: +25,000 COP (credit)
Impacto neto: +25,000 COP
Estado: completed
Escenario 4: PayIn pendiente (sin pago aún)#
Money Movement: mm_pending001
Transactions: 0
Impacto neto: 0 COP
Estado: pending
Acción: Esperar a que el pagador complete el pago
Solución de problemas# Problema 1: Falta External ID en el reporte# Problema: la transaction muestra external_id en nullCausa: no se proporcionó external_id al crear el money movementSolución: incluye siempre external_id en tus solicitudes al APIProblema 2: Diferencia de saldo# Problema: el saldo calculado no coincide con el saldo realCausa: faltan transactions o reversos no reportadosSolución: 1.
Consulta el historial completo de transactions del periodo
2.
Revisa money movements rechazados (2 transactions cada uno)
3.
Verifica los estados de todos los money movements
Problema 3: Conciliación duplicada# Problema: la misma transaction se concilia dos vecesCausa: uso de external_id no únicoSolución: asegúrate de que external_id sea único por money movementProblema 4: PayIn sin transaction# Problema: PayIn completado no tiene transaction de créditoCausa: el estado del money movement no es completedSolución: revisa el estado del money movement; las transactions solo se crean cuando está en completedReferencia de endpoints del API# Crear PayOut# Crear Direct Link (PayIn)# Crear CheckOut (PayIn)# Obtener estado de Money Movement#
GET /v1/money_movements/{money_movement_id}
Obtener detalle de Transaction#
GET /v1/transactions/{transaction_id}
Descargar Transaction Report# Puntos clave# ✅ Cada money movement tiene un ID único — usa money_movement_id como identificador principal ✅ Los external_id son críticos — proporciona siempre external_id para la conciliación ✅ El timing de transactions difiere — PayOuts crean débitos inmediatos; PayIns crean créditos solo al completarse ✅ Los rechazos crean reversos — rechazos de PayOut generan 2 transactions (débito + crédito) ✅ Usa Transaction Reports — descarga reportes por rango de fechas para conciliación masiva ✅ Monitorea cambios de estado — suscríbete a webhooks para actualizaciones en tiempo real ✅ Fórmula de saldo neto — PayOuts completed = -monto, PayIns completed = +monto, rechazos = 0 Modified at 2026-02-13 23:29:47