API de Reembolsos
POST /v1/refunds), actualmente en desarrollo. Los enlaces a endpoints, la forma exacta de la respuesta y la cobertura de rieles aún se están finalizando y se actualizarán a medida que avance la implementación.money_movement_id o transaction_id, y Cobre resuelve automáticamente el riel de payout y la contraparte correctos.Solicitar un reembolso
POST /v1/refunds con una referencia al payin original (money_movement_id o transaction_id) y, para un reembolso parcial, un amount estrictamente menor que el monto del payin original. Cobre valida que el payin original no haya sido reembolsado por completo, resuelve el riel en el que se recibió el payin y crea un Money Movement de payout debitando el Cobre Balance que recibió los fondos originales.Rieles soportados
| País | Riel | Disponibilidad |
|---|---|---|
| Colombia | direct_debit_nequi | Disponible |
| Colombia | r2p_breb | Disponible |
| Colombia | r2p_pse | En desarrollo |
| Colombia | r2p_bancolombia | En desarrollo |
| Colombia | breb_credit(transacciones de llaves estáticas BreB) | En desarrollo |
| México | spei_credit | En desarrollo |
| México | r2p_spei | En desarrollo |
Términos clave
money_movement_id: identificador interno de Cobre para un Money Movement; una de las dos formas aceptadas para referenciar el payin original.transaction_id: el identificador de transacción del payin original; la otra referencia aceptada.Ciclo de vida del reembolso
| Estado | Descripción |
|---|---|
processing | El reembolso fue aceptado y su payout subyacente se está ejecutando. |
completed | El payout del reembolso se liquidó hacia el pagador. |
rejected | La solicitud de reembolso no pasó la validación (por ejemplo, el monto excede lo que aún es reembolsable). |
failed | El payout del reembolso no pudo completarse. |
waiting_for_information | Estamos esperando a que el pagador comparta su cuenta bancaria y datos de identificación para iniciar el reembolso. Este estado solo aplica a los métodos de pago en los que no recibimos los datos del pagador desde el proveedor (PSE, Bancolombia) para iniciar el reembolso sin intervención del pagador. |
Resumen de reembolso
rfe_ prefix) representa una solicitud de reembolso y su propio ciclo de vida, mientras que el resumen (rf_ prefix) rastrea el payin en su conjunto.original_amount — el monto del payin original.refunded_amount — el monto ya reembolsado y liquidado a lo largo de todos los intentos completados.reserved_amount — el monto actualmente retenido por intentos en curso (aún no liquidados).refundable_amount — el monto aún disponible para reembolsar (original_amount menos refunded_amount y reserved_amount).status — el estado derivado general del resumen (por ejemplo partially_refunded o fully_refunded).refunds[] — la lista de intentos individuales sobre este payin.Por qué usarlo
refundable_amount antes de solicitar un nuevo reembolso parcial, sin rastrear reembolsos previos por su cuenta.Idempotencia de reembolsos
rf_{original_money_movement_id}_{uuid}) para que una solicitud reintentada se reconozca como el mismo intento de reembolso.Acciones permitidas sobre reembolsos
🔑 Crear
🔍 Consulta
Descripción: Solicite un reembolso total o parcial sobre un payin existente llamando a
Qué esperar después de la acción: Se crea un reembolso en estado
📘 Más información:
POST /v1/refunds con money_movement_id o transaction_id, amount y una description opcional.Qué esperar después de la acción: Se crea un reembolso en estado
processing. Cobre resuelve los datos del payin original o envía un enlace para capturarlos e inicia el payout correspondiente automáticamente.📘 Más información:
Cómo empezar
Confirme que el payin original es elegible
El reembolso debe referenciar un Money Movement/Transaction de tipo payin que no haya sido reembolsado por completo. Las transacciones de transfer-in no pueden reembolsarse. Para reembolsos parciales, el
amount solicitado debe ser estrictamente menor que el monto aún disponible para reembolsar.Asegúrese de que el Cobre Balance de origen tenga fondos
Un reembolso debita el mismo Cobre Balance que recibió el payin original. Ese balance debe tener fondos suficientes para que el reembolso se procese: Cobre no toma fondos de reembolso de ningún otro balance.
Prepare una clave de idempotencia
Derive una clave de idempotencia del identificador del payin original o use su propia clave única definida, de modo que las solicitudes de reembolso reintentadas no se apliquen dos veces.
Implemente Webhooks para rastrear el estado
Como un reembolso se liquida de forma asíncrona como un payout, recomendamos encarecidamente implementar Webhooks para rastrear su progreso.Consulte Notificaciones y Suscripciones para más detalles.
En desarrollo.
Qué esperar después de usar esta API
Reembolso aceptado
Una vez que una solicitud de reembolso pasa la validación, se crea en estado
processing y Cobre comienza a ejecutar el payout subyacente hacia el pagador original.Finalización del reembolso
Cuando el payout subyacente se liquida, el reembolso pasa a
completed y el débito se refleja en el Cobre Balance de origen.Rechazo o fallo del reembolso
Si el payout subyacente es rechazado por la institución financiera o por Cobre, el reembolso queda en
rejected. Si el payout subyacente no puede completarse después de la aceptación, el reembolso pasa a failed.Modified at 2026-09-15 19:39:45