Refund API
POST /v1/refunds), currently in development. Endpoint links, exact response shape, and rail coverage are still being finalized and will be updated as the implementation progresses.money_movement_id or transaction_id, and Cobre resolves the correct payout rail and counterparty automatically.Requesting a Refund
POST /v1/refunds with a reference to the original payin (money_movement_id or transaction_id) and, for a partial refund, an amount strictly less than the original payin amount. Cobre validates that the original payin has not already been fully refunded, resolves the rail the payin was received on, and creates a payout Money Movement debiting the Cobre Balance that received the original funds.Supported rails
| Country | Rail | Availability |
|---|---|---|
| Colombia | direct_debit_nequi | Available |
| Colombia | r2p_breb | Available |
| Colombia | r2p_pse | In development |
| Colombia | r2p_bancolombia | In development |
| Colombia | breb_credit(Breb static keys transactions) | In development |
| Mexico | spei_credit | In development |
| Mexico | r2p_spei | In development |
Key Terms
money_movement_id: Cobre's internal identifier for a Money Movement; one of two accepted ways to reference the original payin.transaction_id: the transaction identifier for the original payin; the other accepted reference.Refund Lifecycle
| State | Description |
|---|---|
processing | The refund has been accepted and its underlying payout is being executed. |
completed | The refund's payout has settled to the payer. |
rejected | The refund request did not pass validation (for example, amount exceeds what remains refundable). |
failed | The refund's payout could not be completed. |
waiting_for_information | We are waiting for the payer to share their bank account and identification data for us to initiate the refund. This status only applies for the payment methods in which we don't receive the payer's data from the provider (PSE, Bancolombia) to start the refund without payer's intervention |
Refund Summary
rfe_ prefix) represents one refund request and its own lifecycle, while the refund summary (rf_ prefix) tracks the payin as a whole.original_amount — the amount of the original payin.refunded_amount — the amount already refunded and settled across all completed attempts.reserved_amount — the amount currently held by in-flight (not yet settled) attempts.refundable_amount — the amount still available to refund (original_amount minus refunded_amount and reserved_amount).status — the summary's overall derived state (for example partially_refunded or fully_refunded).refunds[] — the list of individual attempts against this payin.Why use it
refundable_amount before requesting a new partial refund, without tracking prior refunds on your own side.Refund Idempotency
rf_{original_money_movement_id}_{uuid}) so a retried request is recognized as the same refund attempt.Allowed Actions on Refunds
🔑 Create
🔍 Retrieval
Description: Request a full or partial refund against an existing payin by calling
What to expect after the action: A refund is created in
📘 Learn more:
POST /v1/refunds with money_movement_id or transaction_id, amount and an optional description.What to expect after the action: A refund is created in
processing status. Cobre resolves the original payin data or sends a link to capture it and initiates the corresponding payout automatically.📘 Learn more:
How to Get Started
Confirm the original payin is eligible
The refund must reference a payin Money Movement/Transaction that has not already been fully refunded. Transfer-in transactions cannot be refunded. For partial refunds, the requested
amount must be strictly less than the amount still available to refund.Ensure the originating Cobre Balance is funded
A refund debits the same Cobre Balance that received the original payin. That balance must hold sufficient funds for the refund to process — Cobre does not source refund funds from any other balance.
Prepare an idempotency key
Derive an idempotency key from the original payin's identifier or use your own defined unique key so retried refund requests are not applied twice.
Implement Webhooks to track status
Since a refund settles asynchronously as a payout, we strongly recommend implementing Webhooks to track its progress.See Notifications & Subscriptions for more details.
In development.
What to expect after using this API
Refund accepted
Once a refund request passes validation, it is created in
processing status and Cobre begins executing the underlying payout to the original payer.Refund completion
When the underlying payout settles, the refund moves to
completed and the debit is reflected on the originating Cobre Balance.Refund rejection or failure
If the underlying payout is rejected by the financial institution or by Cobre, the refund is
rejected. If the underlying payout cannot be completed after acceptance, the refund moves to failed.Modified at 2026-09-09 23:31:09