Processing Refunds in Colombia

In Colombia there is no dedicated refund or return endpoint. Unlike Mexico — where a credit can be returned through the Return a Money Movement API (POST /money_movements_return) — refunding a Colombian payin means initiating a brand new payout with Create a Money Movement (POST /money_movements) that sends the funds back to the original payer.

This has one important consequence: to refund a payin you need the payer's account details, and most Colombian payin rails do not expose them. The only exception is Bre-B, whose credit transactions carry the sender's data, letting you build the refund without any extra lookup. Two Bre-B credit transaction types expose this sender data:

breb_credit — generated when funds are received through a static Cobre Key.

r2p_breb_credit — generated when funds are received through a Bre-B Direct Link or Checkout (Request to Pay over Bre-B). It carries the same sender fields plus a money_movement_id referencing the originating r2p_breb money movement.

This guide covers both scenarios:

Bre-B payins — sender data travels in the transaction; refund directly from breb_credit or r2p_breb_credit.

All other payins (PSE, Bancolombia, Nequi, Direct Debit) — no payer data is returned by the rail; you must obtain the counterparty details by other means before refunding.

Actions performed on a Refund

A refund in Colombia is not a distinct object. It is a standard payout money_movement that you create back toward the original payer. Concretely, refunding requires:

Action	Endpoint	Purpose
Identify the original payin	Obtain one Transaction / Obtain one Account Transactions	Read the credit transaction you intend to refund and, for Bre-B, extract sender data from its `metadata` (`breb_credit` or `r2p_breb_credit`).
Register the payer as a counterparty	Create a Counterparty	Create a `breb_key`, `cc`, `ch`, or `dp` counterparty pointing back to the payer.
Send the refund	Create a Money Movement	Initiate a Bre-B, Fast Pay, or ACH payout for the refund amount.

There is no refund movement type and no geo: col variant of /money_movements_return. Any attempt to call the return endpoint for a Colombian credit will not apply.

How to Get Started

Before sending a refund

You need a funded Cobre Balance in Colombia

The refund is a payout, so the source_id must reference a Virtual Balance (Cobre Balance) or a Connect Account with geo equal to col, with sufficient balance to cover the refund.

Identify the payin you are refunding

Retrieve the original credit transaction so you can confirm the amount, currency (cop), and — for Bre-B — read the sender details. A refund amount must never exceed the original credited amount.

Decide the refund rail

A refund toward a breb_key counterparty is sent over Bre-B. A refund toward a cc, ch, or dp counterparty is sent over Fast Pay (if the destination institution supports it) or ACH (if it does not).

Provide an idempotency header

The POST /money_movements endpoint requires the idempotency header (string, min length 9), valid for 24 hours. Use a deterministic key derived from the original transaction id so retries never double-refund.

Scenario 1 — Refunding a Bre-B payin

When you receive funds through Bre-B, the resulting credit transaction includes the sender's account information in its metadata. This applies to both breb_credit (funds received through a static Cobre Key) and r2p_breb_credit (funds received through a Bre-B Direct Link or Checkout). This is everything you need to register the payer as a counterparty and send the funds back — no external lookup required.

Step 1 — Read the sender data from the credit transaction

A breb_credit transaction (static Cobre Key payin) looks like this:

{
  "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"
  }
}

An r2p_breb_credit transaction (Direct Link or Checkout payin) carries the same sender fields, plus a money_movement_id that references the r2p_breb money movement that generated the credit:

{
  "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"
  }
}

The metadata fields you will reuse are identical across both types:

Bre-B credit field	Meaning	Used for
`sender_name`	Name of the payer who sent the funds	`counterparty_fullname`
`sender_id`	Payer's identification number	`counterparty_id_number`
`sender_id_type`	Payer's identification type (e.g. `cc`)	`counterparty_id_type`
`sender_account_number`	Payer's account number	`account_number`
`sender_account_type`	Payer's account type (`ch`, `cc`, `dp`)	counterparty `type`
`sender_bank_code`	Payer's bank code	`beneficiary_institution`

key_value in both transaction types is your receiving key (static for breb_credit, the dynamic key for r2p_breb_credit), not the payer's. For r2p_breb_credit you can also use money_movement_id to trace the refund back to the originating payin money movement.

The fastest refund path is registering the payer as a breb_key counterparty and refunding over Bre-B. If you do not have the payer's Bre-B key, register them instead as a cc, ch, or dp counterparty (using sender_account_type as the type) and refund over Fast Pay or ACH — see Scenario 2.

Step 2 — Register the payer as a counterparty

If you intend to refund over Bre-B and you hold the payer's key, create a breb_key counterparty:

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

key_value is the only required metadata field for a breb_key counterparty. The response returns a counterparty id with the cp_ prefix.

Step 3 — Create the refund money movement

Use the counterparty id as the destination_id, your Cobre Balance as the source_id, and the original credited amount (or a lower partial amount) as amount in cents.

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

For a breb_key destination, the metadata is the Bre-B variant: description is required (max 40 characters) and is informative only. A successful call returns a money_movement with type: breb, geo: col, currency: cop, and status.state: initiated.

Set external_id to a value derived from the original transaction so the refund is traceable back to the payin in reports and reconciliation.

Scenario 2 — Refunding any other Colombian payin (PSE, Bancolombia, Nequi, Direct Debit, Checkout, Transfer-In)

Payin rails external to Bre-B do not return the payer's account details in the credit transaction. There is no sender_account_number, sender_bank_code, or sender_name to read. To refund, you must obtain the payer's account information through your own channel (for example, from the order record, customer support, or by asking the payer) and then register them as a counterparty.

Step 1 — Obtain the payer's account details

Because the rail does not supply them, you are responsible for collecting:

The payer's full name and identification (counterparty_id_type, counterparty_id_number).

The destination bank (beneficiary_institution, from the Colombian Bank Codes catalog).

The destination account_number and account type (cc, ch, or dp).

Step 2 — Register the payer as a `cc`, `ch`, or `dp` counterparty

{
  "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"
  }
}

For a cc/ch/dp counterparty, counterparty_fullname, beneficiary_institution, account_number, counterparty_id_type, and counterparty_id_number are all required.

Step 3 — Create the refund money movement over Fast Pay or ACH

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

For a cc/ch/dp destination the metadata is the Fast Pay variant when the destination institution supports Fast Pay, otherwise the ACH variant. In both, description is required (max 40 characters). The response returns type: fast_pay or type: ach, geo: col, currency: cop.

What to expect after sending a refund usign the money movement API

Track the refund through Webhooks. Subscribe to money movement events to follow the refund's lifecycle (initiated → processing → completed, or failed/rejected). See Notifications & Subscriptions.

A debit transaction is generated. When the refund settles, a debit transaction appears in the source Cobre Balance (breb_debit for Bre-B refunds, col_debit for Fast Pay/ACH refunds), offsetting the original credit.

Reconcile using external_id. Because the refund is an independent money movement, link it back to the original payin through the external_id you set, and filter via GET /money_movements?external_id=... or in Reports.

Refunds are not reversible. Once completed, a refund money movement cannot be undone through the API; a correction would itself be a new money movement.

Processing Refunds in Colombia

Actions performed on a Refund#

How to Get Started#

Before sending a refund#

Scenario 1 — Refunding a Bre-B payin#

Step 1 — Read the sender data from the credit transaction#

Step 2 — Register the payer as a counterparty#

Step 3 — Create the refund money movement#

Scenario 2 — Refunding any other Colombian payin (PSE, Bancolombia, Nequi, Direct Debit, Checkout, Transfer-In)#

Step 1 — Obtain the payer's account details#

Step 2 — Register the payer as a cc, ch, or dp counterparty#

Step 3 — Create the refund money movement over Fast Pay or ACH#

What to expect after sending a refund usign the money movement API#