Conciliación de PayIns en Colombia

Conciliar PayIns en Colombia significa hacer coincidir el Movimiento de Dinero creado para una colección (Direct Link, Checkout o R2P) con la Transacción de crédito que produce en tu Cobre Balance — con dos excepciones importantes: las Cobre Keys estáticas y las referencias de cuenta de Transfer-In, ninguna de las cuales crea nunca un Movimiento de Dinero.

Esta guía cubre el comportamiento específico de PayIn en Colombia. Para el modelo general del ciclo de vida del Movimiento de Dinero, consulta Movimiento de Dinero; para conciliación de PayOuts, consulta Conciliación de PayOuts; para conciliación a nivel de balance, consulta Conciliación del Balance de Apertura y Cierre.

Movimientos de Dinero vs. Transacciones

Identificador	Prefijo	Se genera cuando	Representa
ID del Movimiento de Dinero	`mm_`	Se crea el PayIn (Direct Link, Checkout o R2P)	La intención de cobro y su estado del ciclo de vida
ID de la Transacción	`trx_`	El PayIn se completa y se acreditan los fondos	El registro contable real que afecta el balance

Siempre proporciona external_id al crear un Movimiento de Dinero de PayIn. Se retorna en la respuesta y es la forma más simple de hacer coincidir una colección de Cobre con tu factura u orden interna.

Esto no aplica a las Cobre Keys estáticas ni a las referencias de cuenta de Transfer-In — consulta más abajo. Ninguna tiene Movimiento de Dinero ni external_id; cada una se concilia con su propio campo de referencia (metadata.key_value para Cobre Keys, metadata.account_reference para Transfer-In).

Ejemplo — cómo se desarrolla un PayIn de Direct Link (PSE) y su Transacción, paso a paso:

Se crea el Movimiento de Dinero

{
  "id": "mm_z4ICqZzfIdG4A3",
  "external_id": "ORDER-2025-050",
  "type": "direct_link",
  "geo": "col",
  "status": {
    "state": "initiated",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_SsMCnqmUvS",
  "currency": "cop",
  "amount": 10000,
  "created_at": "2025-10-31T01:14:10Z",
  "updated_at": "2025-10-31T01:14:10Z"
}

El pagador completa el pago — se aplica la Transacción de crédito

{
  "id": "trx_lTTesMeNSbn1zA5RWeOX",
  "type": "r2p_credit",
  "account_id": "acc_SsMCnqmUvS",
  "amount": 10000,
  "previous_balance": 0,
  "current_balance": 10000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2025-10-31T01:14:50Z",
  "created_at": "2025-10-31T01:14:51Z",
  "metadata": {
    "sender_bank_code": "1019",
    "money_movement_id": "mm_z4ICqZzfIdG4A3",
    "description": "CustomRef123",
    "sender_name": "John Doe",
    "r2p_method": "pse",
    "tracking_key": "1890417980",
    "sender_id": "97710251"
  }
}

El campo metadata.money_movement_id de la Transacción (mm_z4ICqZzfIdG4A3) es lo que la vincula de vuelta al Movimiento de Dinero — este es el campo por el que agrupas al conciliar.

El Movimiento de Dinero llega a completed

{
  "id": "mm_z4ICqZzfIdG4A3",
  "external_id": "ORDER-2025-050",
  "type": "direct_link",
  "geo": "col",
  "status": {
    "state": "completed",
    "code": "",
    "description": ""
  },
  "source_id": "cp_5YFeIDhNkz",
  "destination_id": "acc_SsMCnqmUvS",
  "currency": "cop",
  "amount": 10000,
  "created_at": "2025-10-31T01:14:10Z",
  "updated_at": "2025-10-31T01:14:51Z"
}

Compara esto con una colección por Cobre Key estática o Transfer-In más abajo, ninguna de las cuales tiene Movimiento de Dinero ni money_movement_id en absoluto.

Tipos de Transacción de Crédito en Colombia

Dependiendo del método de cobro, un PayIn completado en Colombia produce uno de estos tipos de Transacción:

Tipo de Transacción	Método de cobro	¿Respaldado por un Movimiento de Dinero?
`col_credit`	Crédito de Connect Account (reportado por el banco)	Sí
`col_cb_credit`	Crédito de Cobre Balance (Direct Link / Checkout — PSE, Bancolombia)	Sí
`r2p_credit`	Request to Pay (PSE)	Sí
`dd_credit`	Cobro por registro de Direct Debit	Sí
`col_top_up_credit`	Top up	Sí
`r2p_breb_credit`	Bre-B Direct Link / Checkout (Request to Pay sobre Bre-B)	Sí
`breb_credit`	Cobre Key estática	No — ver más abajo
`transfer_credit`	Referencia de cuenta Transfer-In	No — ver más abajo

breb_credit y r2p_breb_credit llevan los datos del pagador (sender_name, sender_id, sender_account_number) directamente en la Transacción. Esta es la única familia de rieles en Colombia donde los datos del pagador están disponibles sin una consulta adicional — consulta Procesamiento de Reembolsos en Colombia.

Las Cobre Keys estáticas no crean un Movimiento de Dinero

Una Cobre Key es una llave Bre-B estática: una vez creada, cualquiera que la tenga puede enviarle dinero en cualquier momento, sin que Cobre inicie o rastree una solicitud de pago específica. Como no hay una solicitud que rastrear, no se crea ningún Movimiento de Dinero para una colección por Cobre Key — simplemente produce una Transacción breb_credit directamente en tu Cobre Balance, con metadata.key_value establecido en la Cobre Key que recibió los fondos.

Ejemplo — una Transacción breb_credit de una colección por Cobre Key estática:

{
  "id": "trx_sVT1Gn3qzHLpll6ThICH",
  "type": "breb_credit",
  "amount": 5000,
  "previous_balance": 0,
  "current_balance": 5000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2025-11-26T01:17:17Z",
  "created_at": "2025-11-26T01:17:17Z",
  "metadata": {
    "sender_account_number": "87041725528",
    "sender_account_type": "dp",
    "sender_bank_code": "1507",
    "sender_id": "97710251",
    "sender_id_type": "cc",
    "sender_name": "JOHN DOE",
    "key_value": "@CB5VLNRMCOBRECOMERCI",
    "description": ""
  }
}

No hay ningún money_movement_id en esta Transacción. En su lugar, metadata.key_value (@CB5VLNRMCOBRECOMERCI en este ejemplo) es tu llave de conciliación — identifica cuál de tus Cobre Keys recibió el pago.

Las referencias de cuenta Transfer-In tampoco crean un Movimiento de Dinero

Una referencia de cuenta Transfer-In es un número de cuenta bancaria colombiana real y reutilizable que Cobre te provisiona (hasta 300 por cliente). No tiene fecha de expiración y puede recibir transferencias bancarias B2B en cualquier momento — igual que una Cobre Key estática, no hay una solicitud iniciada por Cobre detrás de cada transferencia, por lo que no se crea ningún Movimiento de Dinero. Cada transferencia entrante simplemente produce una Transacción transfer_credit directamente en tu Cobre Balance, con metadata.account_reference establecido en la referencia de Transfer-In que recibió los fondos.

Ejemplo — una Transacción transfer_credit de una colección por Transfer-In:

{
  "id": "trx_f840c6adace259a504a56bdb6xxxxx",
  "type": "transfer_credit",
  "amount": 54700,
  "previous_balance": 4712500,
  "current_balance": 4767200,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-05-19T19:48:07Z",
  "created_at": "2026-05-19T19:48:08Z",
  "metadata": {
    "reference": "0038212345",
    "sender_name": "PEXTO COLOMBIA S",
    "sender_id": "9011830296",
    "sender_bank_code": "1066",
    "tracking_key": "291000003C6051234567",
    "description": "NC TRAN ELEC INTERNA",
    "account_reference": "291000123"
  }
}

No hay ningún money_movement_id en esta Transacción. metadata.account_reference (291000123 en este ejemplo) es tu llave de conciliación — identifica qué referencia de Transfer-In recibió los fondos. La Transacción también lleva directamente el sender_name, sender_id y sender_bank_code del pagador, sin necesidad de una consulta adicional.

key_value (Cobre Keys) y account_reference (Transfer-In) no son intercambiables — cada producto solo llena su propio campo. No construyas lógica de conciliación que use uno como respaldo del otro; primero decide según el type de la Transacción (breb_credit vs. transfer_credit).

Ciclo de Vida del PayIn e Impacto en el Balance

Una Transacción de PayIn en Colombia solo se crea cuando el Movimiento de Dinero llega a completed — esto aplica a todo método de cobro respaldado por un Movimiento de Dinero (Direct Link, Checkout, R2P, Direct Debit):

Estado terminal	¿Se crea una Transacción?	Impacto neto en el balance
`completed`	Sí — 1 crédito	Positivo (fondos recibidos)
`rejected` / `failed`	No	Ninguno

Las Cobre Keys estáticas y las referencias de Transfer-In no pasan por este ciclo de vida en absoluto — ver más arriba.

Los Reembolsos También Afectan la Conciliación

Colombia no tiene un endpoint dedicado para reembolsos. Reembolsar un PayIn completado significa crear un nuevo Movimiento de Dinero de PayOut de vuelta al pagador, que produce su propia Transacción de débito, separada del crédito original. Al conciliar, no asumas que el impacto en el balance de un PayIn completed es permanente — verifica si existe un PayOut relacionado posterior antes de cerrar el período. Consulta Procesamiento de Reembolsos en Colombia para el flujo completo.

Conciliar PayIns en Colombia

A demanda: Para PayIns respaldados por un Movimiento de Dinero, consulta Obtener todos los Movimientos de Dinero filtrando por state, external_id, destination_id (tu Cobre Balance), o un rango de fechas, y luego cruza con Obtener las Transacciones de una Cuenta filtrando credit_debit_type=credit y metadata.money_movement_id. Para Cobre Keys o Transfer-In, consulta las Transacciones directamente y filtra/agrupa por metadata.key_value o metadata.account_reference respectivamente — no hay Movimiento de Dinero que consultar en ninguno de los dos casos.

En bloque: Genera un reporte de Movimientos de Dinero (money_movement_csv_v1 para CSV, o money_movement_v1 para JSON) y un reporte de Transacciones (transactions_csv_v1 para CSV, o account_transactions_v1 para JSON) mediante Reportes, y filtra las filas exportadas a currency = COP. Agrupa las filas respaldadas por Movimiento de Dinero por metadata.money_movement_id — un PayIn completado debe tener exactamente una fila de crédito. Las filas de Cobre Key no tendrán money_movement_id; agrúpalas por metadata.key_value. Las filas de Transfer-In tampoco lo tendrán; agrúpalas por metadata.account_reference.

En tiempo real: Suscríbete a Notificaciones y Suscripciones en lugar de consultar repetidamente. Para PayIns respaldados por un Movimiento de Dinero, money_movements.status.completed (y .rejected / .failed) se dispara en cuanto cambia el estado. Las Cobre Keys y las referencias de Transfer-In no tienen un Movimiento de Dinero que emita un evento de estado — usa accounts.balance.credit en su lugar, y haz coincidir el evento con la Cobre Key o la referencia de Transfer-In correspondiente usando su metadata.key_value o metadata.account_reference. Para Transfer-In específicamente, suscríbete también a transfer_acc.status.processing / .enabled / .failed para rastrear cuándo una referencia queda lista para compartir con un pagador — algo separado de los créditos que después recibe.

La entrega de webhooks es de mejor esfuerzo, no garantizada para siempre — consulta Notificaciones y Suscripciones para conocer la ventana de reintentos. Trata los webhooks como tu señal en tiempo real y las consultas a demanda o los Reportes como el respaldo periódico que captura cualquier cosa que un webhook haya perdido.

Acciones Permitidas en la Conciliación de PayIns en Colombia

🔍 Consulta — Movimientos de Dinero

🔍 Consulta — Transacciones

🔑 Reportes

Descripción: Consulta PayIns en Colombia a demanda por estado, ID externo, Cobre Balance de destino o rango de fechas. No aplica a colecciones por Cobre Key estática o Transfer-In.

Qué esperar después de la acción: Una lista paginada de objetos Movimiento de Dinero con su status actual.

📘 Más información:

🔗 Obtener todos los Movimientos de Dinero

🔗 Obtener un Movimiento de Dinero

Cómo Empezar

Conoce qué métodos de cobro crean un Movimiento de Dinero

Direct Link, Checkout, R2P y Direct Debit sí lo hacen; las Cobre Keys estáticas y las referencias de Transfer-In no. Planifica tu llave de conciliación en consecuencia: money_movement_id para los primeros, metadata.key_value (Cobre Keys) o metadata.account_reference (Transfer-In) para los otros dos.

Siempre proporciona external_id en PayIns respaldados por un Movimiento de Dinero

Es consultable mediante el filtro external_id y es la forma más simple de hacer coincidir una colección con tu orden o factura interna.

Suscríbete a los eventos de estado del Movimiento de Dinero en lugar de consultar repetidamente

Consulta Notificaciones y Suscripciones para saber cuándo se completa un PayIn sin consultar la API repetidamente.

Rastrea los reembolsos como PayOuts separados

Como Colombia no tiene un endpoint dedicado para reembolsos, vigila los PayOuts posteriores que hagan referencia a un PayIn previamente completado.

Qué Esperar Después de Usar esta API

Los PayIns completados coinciden uno a uno con una Transacción de crédito

Los PayIns rechazados o fallidos no producen ninguna Transacción que afecte el balance. Las colecciones por Cobre Key o Transfer-In se saltan este ciclo de vida por completo.

Las colecciones por Cobre Key y Transfer-In se concilian por su propio campo de referencia, no por money_movement_id

Cada Transacción breb_credit lleva metadata.key_value; cada Transacción transfer_credit lleva metadata.account_reference. Los dos campos nunca son intercambiables.

Los PayIns reembolsados aparecen como un PayOut de seguimiento vinculado

La conciliación de un período determinado debe contemplar tanto el crédito original como cualquier débito de reembolso posterior.

Conciliación de PayIns en Colombia

Movimientos de Dinero vs. Transacciones#

Tipos de Transacción de Crédito en Colombia#

Las Cobre Keys estáticas no crean un Movimiento de Dinero#

Las referencias de cuenta Transfer-In tampoco crean un Movimiento de Dinero#

Ciclo de Vida del PayIn e Impacto en el Balance#

Los Reembolsos También Afectan la Conciliación#

Conciliar PayIns en Colombia#

Acciones Permitidas en la Conciliación de PayIns en Colombia#

Cómo Empezar#

Qué Esperar Después de Usar esta API#

Movimientos de Dinero vs. Transacciones

Tipos de Transacción de Crédito en Colombia

Las Cobre Keys estáticas no crean un Movimiento de Dinero

Las referencias de cuenta Transfer-In tampoco crean un Movimiento de Dinero

Ciclo de Vida del PayIn e Impacto en el Balance

Los Reembolsos También Afectan la Conciliación

Conciliar PayIns en Colombia

Acciones Permitidas en la Conciliación de PayIns en Colombia

Cómo Empezar

Qué Esperar Después de Usar esta API