Procesando Reembolsos en Colombia

En Colombia no existe un endpoint dedicado para reembolsos o devoluciones. A diferencia de México —donde un crédito puede devolverse a través del API Devolver un Movimiento de Dinero (POST /money_movements_return)— reembolsar un payin colombiano implica iniciar un nuevo payout con Crear un Movimiento de Dinero (POST /money_movements) que envía los fondos de vuelta al pagador original.

Esto tiene una consecuencia importante: para reembolsar un payin necesitas los datos de cuenta del pagador, y la mayoría de los rieles de payin colombianos no los exponen. La única excepción es Bre-B, cuyas transacciones de crédito incluyen los datos del remitente, lo que te permite construir el reembolso sin ninguna búsqueda adicional. Dos tipos de transacciones de crédito Bre-B exponen estos datos del remitente:

breb_credit — generado cuando se reciben fondos a través de una Cobre Key estática.

r2p_breb_credit — generado cuando se reciben fondos a través de un Direct Link o Checkout Bre-B (Request to Pay sobre Bre-B). Contiene los mismos campos del remitente más un money_movement_id que referencia el Money Movement r2p_breb originador.

Esta guía cubre ambos escenarios:

Payins Bre-B — los datos del remitente viajan en la transacción; reembolsa directamente desde breb_credit o r2p_breb_credit.

Todos los demás payins (PSE, Bancolombia, Nequi, Débito Directo) — el riel no devuelve datos del pagador; debes obtener los datos de la contraparte por otros medios antes de reembolsar.

Acciones Realizadas en un Reembolso

Un reembolso en Colombia no es un objeto distinto. Es un payout estándar de money_movement que creas de vuelta hacia el pagador original. Concretamente, reembolsar requiere:

Acción	Endpoint	Propósito
Identificar el payin original	Obtener una Transacción / Obtener transacciones de una cuenta	Lee la transacción de crédito que deseas reembolsar y, para Bre-B, extrae los datos del remitente desde su `metadata` (`breb_credit` o `r2p_breb_credit`).
Registrar al pagador como contraparte	Crear una Contraparte	Crea una contraparte `breb_key`, `cc`, `ch` o `dp` apuntando de vuelta al pagador.
Enviar el reembolso	Crear un Movimiento de Dinero	Inicia un payout Bre-B, Fast Pay o ACH por el monto del reembolso.

No existe un tipo de movimiento refund ni una variante geo: col de /money_movements_return. Cualquier intento de llamar al endpoint de devolución para un crédito colombiano no tendrá efecto.

Cómo Comenzar

Antes de Enviar un Reembolso

Necesitas un Cobre Balance fondeado en Colombia

El reembolso es un payout, por lo que el source_id debe referenciar un Virtual Balance (Cobre Balance) o una Cuenta Connect con geo igual a col, con saldo suficiente para cubrir el reembolso.

Identifica el payin que estás reembolsando

Recupera la transacción de crédito original para confirmar el amount, la currency (cop) y —para Bre-B— los datos del remitente. El monto de un reembolso nunca debe superar el monto acreditado original.

Decide el riel de reembolso

Un reembolso hacia una contraparte breb_key se envía por Bre-B. Un reembolso hacia una contraparte cc, ch o dp se envía por Fast Pay (si la institución destino lo soporta) o ACH (si no lo soporta).

Proporciona un header de idempotencia

El endpoint POST /money_movements requiere el header idempotency (string, longitud mínima 9), válido por 24 horas. Usa una clave determinista derivada del id de la transacción original para que los reintentos nunca generen un doble reembolso.

Escenario 1 — Reembolsando un Payin Bre-B

Cuando recibes fondos a través de Bre-B, la transacción de crédito resultante incluye la información de cuenta del remitente en su metadata. Esto aplica tanto para breb_credit (fondos recibidos a través de una Cobre Key estática) como para r2p_breb_credit (fondos recibidos a través de un Direct Link o Checkout Bre-B). Esta información es todo lo que necesitas para registrar al pagador como contraparte y enviar los fondos de vuelta — sin necesidad de búsqueda externa.

Paso 1 — Leer los Datos del Remitente de la Transacción de Crédito

Una transacción breb_credit (payin con Cobre Key estática) luce así:

{
  "id": "trx_4c5cb9b93c355520646ff2d6b24076",
  "type": "breb_credit",
  "account_id": "acc_8fB1S8wlaF",
  "amount": 100000,
  "previous_balance": 0,
  "current_balance": 100000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-06-10T20:11:56Z",
  "created_at": "2026-06-10T20:11:56Z",
  "metadata": {
    "sender_account_number": "78110264",
    "sender_account_type": "ch",
    "sender_bank_code": "1809",
    "sender_id": "1018983923",
    "sender_id_type": "cc",
    "sender_name": "Juan Pérez",
    "key_value": "@COBRECOMERCICB1QB6HQ",
    "description": "Payin Bre-B"
  }
}

Una transacción r2p_breb_credit (payin con Direct Link o Checkout) contiene los mismos campos del remitente, más un money_movement_id que referencia el Money Movement r2p_breb que generó el crédito:

{
  "id": "trx_e340b2a53b5e1d64b25cfa27157f53",
  "type": "r2p_breb_credit",
  "amount": 100000,
  "previous_balance": 0,
  "current_balance": 100000,
  "currency": "cop",
  "credit_debit_type": "credit",
  "transaction_date": "2026-05-20T20:43:23Z",
  "created_at": "2026-05-20T20:43:23Z",
  "metadata": {
    "sender_account_number": "78110264",
    "sender_account_type": "ch",
    "sender_bank_code": "1809",
    "sender_id": "1018983923",
    "sender_id_type": "cc",
    "sender_name": "Juan Pérez",
    "key_value": "@CBI964MAQ",
    "description": "R2P Bre-B",
    "money_movement_id": "mm_InLDaOGhcHczoz"
  }
}

Los campos de metadata que reutilizarás son idénticos en ambos tipos:

Campo de crédito Bre-B	Significado	Utilizado para
`sender_name`	Nombre del pagador que envió los fondos	`counterparty_fullname`
`sender_id`	Número de identificación del pagador	`counterparty_id_number`
`sender_id_type`	Tipo de identificación del pagador (ej. `cc`)	`counterparty_id_type`
`sender_account_number`	Número de cuenta del pagador	`account_number`
`sender_account_type`	Tipo de cuenta del pagador (`ch`, `cc`, `dp`)	`type` de la contraparte
`sender_bank_code`	Código bancario del pagador	`beneficiary_institution`

key_value en ambos tipos de transacción es tu llave receptora (estática para breb_credit, la llave dinámica para r2p_breb_credit), no la del pagador. Para r2p_breb_credit también puedes usar money_movement_id para rastrear el reembolso hasta el Money Movement de payin originador.

La ruta de reembolso más rápida es registrar al pagador como contraparte breb_key y reembolsar por Bre-B. Si no tienes la llave Bre-B del pagador, regístralo en cambio como contraparte cc, ch o dp (usando sender_account_type como el type) y reembolsa por Fast Pay o ACH — ver Escenario 2.

Paso 2 — Registrar al Pagador como Contraparte

Si deseas reembolsar por Bre-B y cuentas con la llave del pagador, crea una contraparte breb_key:

{
  "geo": "col",
  "type": "breb_key",
  "alias": "refund-juan-perez",
  "metadata": {
    "key_value": "@PAYERKEY123",
    "counterparty_email": "juan.perez@example.co",
    "counterparty_phone": "+573001112233"
  }
}

key_value es el único campo de metadata requerido para una contraparte breb_key. La respuesta devuelve un id de contraparte con el prefijo cp_.

Paso 3 — Crear el Money Movement de Reembolso

Usa el id de la contraparte como destination_id, tu Cobre Balance como source_id, y el monto acreditado original (o un monto parcial menor) como amount en centavos.

{
  "amount": 100000,
  "source_id": "acc_8fB1S8wlaF",
  "destination_id": "cp_TRLlPDNQGZ",
  "metadata": {
    "description": "Refund trx_4c5cb9b93c"
  },
  "external_id": "refund_trx_4c5cb9b93c"
}

Para un destino breb_key, el metadata es la variante Bre-B: description es requerido (máximo 40 caracteres) y es solo informativo. Una llamada exitosa devuelve un money_movement con type: breb, geo: col, currency: cop y status.state: initiated.

Establece external_id con un valor derivado de la transacción original para que el reembolso sea rastreable hasta el payin en reportes y conciliaciones.

Escenario 2 — Reembolsando Cualquier Otro Payin Colombiano (PSE, Bancolombia, Nequi, Débito Directo, Checkout, Transfer-In)

Los rieles de payin externos a Bre-B no devuelven los datos de cuenta del pagador en la transacción de crédito. No hay sender_account_number, sender_bank_code ni sender_name que leer. Para reembolsar, debes obtener la información de cuenta del pagador por tu propio canal (por ejemplo, desde el registro del pedido, soporte al cliente, o solicitándola directamente al pagador) y luego registrarlo como contraparte.

Paso 1 — Obtener los Datos de Cuenta del Pagador

Dado que el riel no los proporciona, eres responsable de recopilar:

El nombre completo e identificación del pagador (counterparty_id_type, counterparty_id_number).

El banco destino (beneficiary_institution, del catálogo de Códigos bancarios colombianos).

El account_number y tipo de cuenta de destino (cc, ch o dp).

Paso 2 — Registrar al Pagador como Contraparte `cc`, `ch` o `dp`

{
  "geo": "col",
  "type": "cc",
  "alias": "refund-order-9931",
  "metadata": {
    "counterparty_fullname": "Juan Pérez",
    "beneficiary_institution": "1007",
    "account_number": "051304546110",
    "counterparty_id_type": "cc",
    "counterparty_id_number": "1018983923"
  }
}

Para una contraparte cc/ch/dp, counterparty_fullname, beneficiary_institution, account_number, counterparty_id_type y counterparty_id_number son todos requeridos.

Paso 3 — Crear el Money Movement de Reembolso por Fast Pay o ACH

{
  "amount": 50000,
  "source_id": "acc_8fB1S8wlaF",
  "destination_id": "cp_KL1CfGa9iO",
  "metadata": {
    "description": "Refund order 9931"
  },
  "external_id": "refund_order_9931"
}

Para un destino cc/ch/dp, el metadata es la variante Fast Pay cuando la institución destino soporta Fast Pay, o la variante ACH cuando no lo soporta. En ambos casos, description es requerido (máximo 40 caracteres). La respuesta devuelve type: fast_pay o type: ach, geo: col, currency: cop.

Qué Esperar Después de Enviar un Reembolso con el API de Money Movement

Rastrea el reembolso mediante Webhooks. Suscríbete a eventos de Money Movement para seguir el ciclo de vida del reembolso (initiated → processing → completed, o failed/rejected). Ver Notificaciones y Suscripciones.

Se genera una transacción de débito. Cuando el reembolso se liquida, aparece una transacción de débito en el Cobre Balance de origen (breb_debit para reembolsos Bre-B, col_debit para reembolsos Fast Pay/ACH), compensando el crédito original.

Concilia usando external_id. Dado que el reembolso es un Money Movement independiente, vincúlalo al payin original a través del external_id que estableciste, y filtra mediante GET /money_movements?external_id=... o en Reports.

Los reembolsos no son reversibles. Una vez completed, un Money Movement de reembolso no puede deshacerse a través del API; una corrección sería en sí misma un nuevo Money Movement.

Procesando Reembolsos en Colombia

Acciones Realizadas en un Reembolso#

Cómo Comenzar#

Antes de Enviar un Reembolso#

Escenario 1 — Reembolsando un Payin Bre-B#

Paso 1 — Leer los Datos del Remitente de la Transacción de Crédito#

Paso 2 — Registrar al Pagador como Contraparte#

Paso 3 — Crear el Money Movement de Reembolso#

Escenario 2 — Reembolsando Cualquier Otro Payin Colombiano (PSE, Bancolombia, Nequi, Débito Directo, Checkout, Transfer-In)#

Paso 1 — Obtener los Datos de Cuenta del Pagador#

Paso 2 — Registrar al Pagador como Contraparte cc, ch o dp#

Paso 3 — Crear el Money Movement de Reembolso por Fast Pay o ACH#

Qué Esperar Después de Enviar un Reembolso con el API de Money Movement#