在哥伦比亚处理退款

在哥伦比亚，没有专用的退款或退回接口端点。与墨西哥不同——在墨西哥，可通过退回资金流动 API（POST /money_movements_return）退回贷记款项——在哥伦比亚退还收款意味着需要使用创建资金流动（POST /money_movements）发起一笔全新的出款，将资金退回给原始付款方。

这带来了一个重要影响：要退还收款，您需要掌握付款方的账户信息，而大多数哥伦比亚收款通道都不会暴露这些信息。唯一的例外是 Bre-B，其贷记交易会携带付款方数据，使您无需任何额外查询即可完成退款操作。有两种 Bre-B 贷记交易类型会暴露付款方数据：

breb_credit — 通过静态 Cobre Key 收到资金时生成。

r2p_breb_credit — 通过 Bre-B Direct Link 或收银台（即基于 Bre-B 的请求付款）收到资金时生成。它携带相同的付款方字段，以及一个引用原始 r2p_breb 资金流动的 money_movement_id。

本指南涵盖以下两种场景：

Bre-B 收款 — 付款方数据随交易传送；直接通过 breb_credit 或 r2p_breb_credit 发起退款。

其他所有收款（PSE、Bancolombia、Nequi、Direct Debit）— 支付通道不返回付款方数据；退款前须通过其他途径获取交易对手方详情。

退款执行操作

在哥伦比亚，退款并非独立对象。它是一笔标准的出款 money_movement，由您向原始付款方发起。具体而言，发起退款需要：

操作	接口端点	用途
识别原始收款	获取单笔交易 / 获取单笔交易	读取您打算退款的贷记交易，并对于 Bre-B，从其 `metadata` 中提取付款方数据（`breb_credit` 或 `r2p_breb_credit`）。
将付款方注册为交易对手方	创建交易对手方	创建指向付款方的 `breb_key`、`cc`、`ch` 或 `dp` 交易对手方。
发送退款	创建资金流动	按退款金额发起 Bre-B、Fast Pay 或 ACH 出款。

不存在 refund 资金流动类型，也没有针对哥伦比亚的 /money_movements_return 的 geo: col 变体。任何尝试针对哥伦比亚贷记交易调用退回接口端点的操作均不适用。

快速上手

发送退款前

You need a funded Cobre Balance in Colombia

退款是一笔出款，因此 source_id 必须引用 geo 为 col 且余额充足的虚拟余额（Cobre Balance）或 Connect 账户，以覆盖退款金额。

Identify the payin you are refunding

检索原始贷记交易，以确认 amount、currency（cop），以及——对于 Bre-B——读取付款方详情。退款金额不得超过原始入账金额。

Decide the refund rail

向 breb_key 交易对手方发起的退款通过 Bre-B 发送。向 cc、ch 或 dp 交易对手方发起的退款通过 Fast Pay（如目标机构支持）或 ACH（如不支持）发送。

Provide an idempotency header

POST /money_movements 接口端点需要 idempotency 请求头（字符串，最小长度 9），有效期 24 小时。请使用从原始交易 id 派生的确定性密钥，确保重试操作不会产生重复退款。

场景一 — 退还 Bre-B 收款

通过 Bre-B 收到资金后，生成的贷记交易在其 metadata 中包含付款方的账户信息。这适用于 breb_credit（通过静态 Cobre Key 收到资金）和 r2p_breb_credit（通过 Bre-B Direct Link 或收银台收到资金）。这些信息足以将付款方注册为交易对手方并退还资金——无需任何外部查询。

第一步 — 从贷记交易中读取付款方数据

breb_credit 交易（静态 Cobre Key 收款）示例如下：

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

r2p_breb_credit 交易（Direct Link 或收银台收款）携带相同的付款方字段，以及引用生成该贷记交易的 r2p_breb 资金流动的 money_movement_id：

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

两种类型中可复用的 metadata 字段完全相同：

Bre-B 贷记字段	含义	用于
`sender_name`	付款方姓名	`counterparty_fullname`
`sender_id`	付款方身份证号	`counterparty_id_number`
`sender_id_type`	付款方证件类型（如 `cc`）	`counterparty_id_type`
`sender_account_number`	付款方账号	`account_number`
`sender_account_type`	付款方账户类型（`ch`、`cc`、`dp`）	交易对手方 `type`
`sender_bank_code`	付款方银行代码	`beneficiary_institution`

两种交易类型中的 key_value 均为您的收款密钥（breb_credit 为静态密钥，r2p_breb_credit 为动态密钥），而非付款方的密钥。对于 r2p_breb_credit，您还可以使用 money_movement_id 将退款追溯至原始收款资金流动。

最快捷的退款路径是将付款方注册为 breb_key 交易对手方，并通过 Bre-B 退款。如果您没有付款方的 Bre-B 密钥，则将其注册为 cc、ch 或 dp 交易对手方（使用 sender_account_type 作为 type），并通过 Fast Pay 或 ACH 退款——参见场景二。

第二步 — 将付款方注册为交易对手方

如果您打算通过 Bre-B 退款且持有付款方的密钥，请创建 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 是 breb_key 交易对手方唯一必填的 metadata 字段。响应返回带 cp_ 前缀的交易对手方 id。

第三步 — 创建退款资金流动

使用交易对手方 id 作为 destination_id，您的 Cobre Balance 作为 source_id，原始入账金额（或更低的部分金额）以分为单位作为 amount。

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

对于 breb_key 目标，metadata 为 Bre-B 变体：description 为必填项（最多 40 个字符），仅作说明用途。成功调用将返回一个 type: breb、geo: col、currency: cop、status.state: initiated 的 money_movement。

将 external_id 设置为从原始交易派生的值，使退款可在报告和对账中追溯至原始收款。

场景二 — 退还其他哥伦比亚收款（PSE、Bancolombia、Nequi、Direct Debit、收银台、转入）

Bre-B 以外的收款通道不在贷记交易中返回付款方的账户详情。没有 sender_account_number、sender_bank_code 或 sender_name 可供读取。要发起退款，您必须通过自有渠道获取付款方账户信息（例如，从订单记录、客户服务或直接询问付款方），然后将其注册为交易对手方。

第一步 — 获取付款方账户详情

由于支付通道不提供这些信息，您需要自行收集：

付款方的全名和身份信息（counterparty_id_type、counterparty_id_number）。

目标银行（beneficiary_institution，来自哥伦比亚银行代码目录）。

目标 account_number 和账户类型（cc、ch 或 dp）。

第二步 — 将付款方注册为 `cc`、`ch` 或 `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"
  }
}

对于 cc/ch/dp 交易对手方，counterparty_fullname、beneficiary_institution、account_number、counterparty_id_type 和 counterparty_id_number 均为必填项。

第三步 — 通过 Fast Pay 或 ACH 创建退款资金流动

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

对于 cc/ch/dp 目标，当目标机构支持 Fast Pay 时，metadata 为 Fast Pay 变体；否则为 ACH 变体。两种情况下，description 均为必填项（最多 40 个字符）。响应返回 type: fast_pay 或 type: ach、geo: col、currency: cop。

通过资金流动 API 发送退款后的预期结果

通过 Webhooks 追踪退款。 订阅资金流动事件，以跟踪退款的生命周期（initiated → processing → completed，或 failed/rejected）。请参阅通知与订阅。

生成借记交易。 退款结算后，来源 Cobre Balance 中将出现一笔借记交易（Bre-B 退款为 breb_debit，Fast Pay/ACH 退款为 col_debit），与原始贷记交易相抵。

使用 external_id 进行对账。 由于退款是独立的资金流动，请通过您设置的 external_id 将其关联回原始收款，并通过 GET /money_movements?external_id=... 或在报告中进行筛选。

退款不可逆。 一旦 completed，退款资金流动无法通过 API 撤销；如需纠正，则需发起一笔新的资金流动。

在哥伦比亚处理退款

退款执行操作#

快速上手#

发送退款前#

场景一 — 退还 Bre-B 收款#

第一步 — 从贷记交易中读取付款方数据#

第二步 — 将付款方注册为交易对手方#

第三步 — 创建退款资金流动#

场景二 — 退还其他哥伦比亚收款（PSE、Bancolombia、Nequi、Direct Debit、收银台、转入）#

第一步 — 获取付款方账户详情#

第二步 — 将付款方注册为 cc、ch 或 dp 交易对手方#

第三步 — 通过 Fast Pay 或 ACH 创建退款资金流动#

通过资金流动 API 发送退款后的预期结果#