Refunds is still under active development — some of the functionality described in this document may not yet be available for your account. Contact your KAM (Key Account Manager) for the current rollout status.
Issue full and partial refunds on Colombia payin rails through a single API#
Refunds let Cobre clients return funds to a payer against an original payin, without building custom reversal logic per payment method. Instead of handling refund logic differently for every rail, clients call a single endpoint referencing the original transaction, and Cobre resolves the correct payout rail and route automatically.
Issue full or partial refunds against a completed payin money movement or transaction through a single API call.
Reference the original transaction by money_movement_id or transaction_id — no need to reconstruct payment or payer details manually.
Available today for Colombia, covering direct_debit_nequi (Nequi tokenization) and r2p_breb. Support for r2p_pse, r2p_bancolombia, and Static BreB key credits coming soon, along with Mexico coverage (spei_credit, r2p_spei).
Issue multiple partial refunds against the same original payin, up to its original amount.
A refund is modeled as a payout money movement linked back to an original payin. When a client requests a refund, Cobre debits the Cobre Balance that originally received the payin and creates a new payout to the payer, reusing the counterparty information already associated with that payin.Refunds only apply to payin money movements — transfer-in transactions are not eligible. Because a refund draws from the same balance that received the funds, the client must hold sufficient balance there for the refund to process; Cobre does not source refund funds from any other balance.
Clients can return the entire amount of a payin or a portion of it. Partial refunds can be issued more than once against the same original payin, as long as the combined refunded amount never exceeds what was originally received.
A refund can be requested using either the original payin's money_movement_id or its transaction_id, so clients can trigger a refund from whichever identifier they already track internally.
Clients do not choose or configure the refund rail. Cobre resolves the correct payout route based on the original payin's rail and the counterparty already on file for it.
Alongside each individual refund attempt, Cobre maintains a refund summary — a running-total accumulator per original payin. A single lookup returns the original amount, the amount already refunded, the amount currently reserved by in-flight attempts, the amount still refundable, and the list of individual attempts, without the client needing to fetch and add up every attempt itself.
3.5 Payer Data Capture for PSE and Bancolombia Refunds (v2)#
For rails where Cobre does not receive the payer's bank account and identification data as part of the original payin (r2p_pse, r2p_bancolombia), a refund attempt is created with a waiting_for_information status and Cobre returns a data_capture_url — a link the payer follows to securely submit the missing bank account and identification data. The refund proceeds automatically once the payer completes this step, before the data_capture_url_expires_at deadline.
Payin: the original money movement that credited a Cobre Balance and is eligible for a refund.
Refund: a payout money movement created by Cobre, referencing an original payin, that returns funds to the original payer.
Refund attempt (rfe_): an individual refund request against a payin, with its own status lifecycle.
Refund summary (rf_): the running-total accumulator across all refund attempts against a single original payin.
money_movement_id: Cobre's internal identifier for a money movement; one of two accepted ways to reference the original payin when requesting a refund.
transaction_id: the transaction identifier associated with the original payin; the other accepted reference for a refund request.
Cobre Balance: the virtual balance debited to fund the refund; must be the same balance that received the original payin.
data_capture_url: a link returned when a refund attempt is waiting_for_information, used by the payer to submit the bank account and identification data required to complete a PSE or Bancolombia refund.
Counterparty: the payer's account record Cobre reuses to route the refund.
A refund's completion depends on the same factors as any payout on the resolved rail — destination account validity and the underlying rail's own processing behavior. A refund cannot be requested against a payin that has already been fully refunded, and combined partial refunds cannot exceed the original payin amount.
Customer disputes or refund requests — returning funds to a payer who disputes or requests reversal of a payment already received.
Duplicate payment correction — planned as a future use case, returning funds from a payin that duplicates another completed payment.
Refunds fit these cases because they let a client resolve a payer-facing issue without leaving the Cobre platform or manually re-keying payout details already known from the original transaction.
Because a refund is issued as a payout money movement, it generates its own transaction record, distinct from — but linked to — the original payin's transaction. Clients can track a refund's status the same way they track any other money movement, and reconcile it against the debit it produces on the originating Cobre Balance.
Refunds are initiated by the client through the API — there is no payer-facing self-service refund flow. Because a refund can only draw from the balance that received the original payin, refund capacity is naturally bounded by that balance's available funds. Once a refund payout has executed, reversing it is not a built-in capability — undoing it requires a separate, manual process outside the refund flow.
✔ A single API to return funds to a payer, without rebuilding payout logic per rail.
✔ Full and partial refund support, referenced by either money_movement_id or transaction_id.
✔ Automatic rail and counterparty resolution based on the original payin.
✔ Built-in balance discipline — refunds only draw from the balance that received the original funds.
✔ A refund summary reporting running totals per payin, without manually adding up individual attempts.
✔ Secure payer data capture for PSE and Bancolombia refunds, so a refund can proceed even when Cobre does not already hold the payer's bank details.
Refunds give Cobre clients a direct way to resolve payer disputes and correction requests for Colombia payin rails today, with broader Colombia and Mexico rail coverage planned as the capability expands.
