退款 API
POST /v1/refunds），目前仍在开发中。Endpoint 链接、确切的响应形态以及轨道覆盖范围仍在最终确定中，并将随实现进度更新。money_movement_id 或 transaction_id 引用原始 payin，Cobre 会自动解析正确的 payout 轨道与交易对手。请求退款
POST /v1/refunds，并提供对原始 payin 的引用（money_movement_id 或 transaction_id），以及（对于部分退款）严格小于原始 payin 金额的 amount 来请求退款。Cobre 会验证原始 payin 尚未被全额退款，解析 payin 收款所用的轨道，并创建一笔 debit 最初收款 Cobre Balance 的 payout Money Movement。支持的轨道
| 国家/地区 | 轨道 | 可用性 |
|---|---|---|
| 哥伦比亚 | direct_debit_nequi | 可用 |
| 哥伦比亚 | r2p_breb | 可用 |
| 哥伦比亚 | r2p_pse | 开发中 |
| 哥伦比亚 | r2p_bancolombia | 开发中 |
| 哥伦比亚 | breb_credit（Breb 静态密钥交易） | 开发中 |
| 墨西哥 | spei_credit | 开发中 |
| 墨西哥 | r2p_spei | 开发中 |
关键术语
money_movement_id：Cobre 对 Money Movement 的内部标识符；引用原始 payin 的两种方式之一。transaction_id：原始 payin 的交易标识符；另一种可接受的引用。退款生命周期
| 状态 | 描述 |
|---|---|
processing | 退款已接受，其底层 payout 正在执行。 |
completed | 退款的 payout 已结算至付款人。 |
rejected | 退款请求未通过验证（例如金额超过仍可退余额）。 |
failed | 退款的 payout 未能完成。 |
waiting_for_information | 我们正在等待付款人提供银行账户与身份数据，以便发起退款。此状态仅适用于我们未从提供方收到付款人数据（PSE、Bancolombia）、因而无法在无付款人介入的情况下启动退款的支付方式。 |
退款汇总
rfe_ 前缀）代表一次退款请求及其自身生命周期，而退款汇总（rf_ 前缀）则跟踪整个 payin。original_amount — 原始 payin 金额。refunded_amount — 所有已完成尝试中已退并结算的金额。reserved_amount — 当前由进行中（尚未结算）尝试占用的金额。refundable_amount — 仍可退金额（original_amount 减去 refunded_amount 与 reserved_amount）。status — 汇总的整体派生状态（例如 partially_refunded 或 fully_refunded）。refunds[] — 针对此 payin 的各次尝试列表。External ID 映射
external_id 会映射到该 payout 的 external_id。external_id 由退款 ID 与原始 pay-in 的 external_id 拼接而成：payout.external_id = refund_id + original_payin_external_id示例
| 字段 | 值 |
|---|---|
原始 pay-in 的 external_id | order_98765 |
退款 id | rf_abc123 |
结果 payout 的 external_id | rf_abc123-order_98765 |
为何使用
refundable_amount，而无需在己方跟踪既往退款。退款幂等性
rf_{original_money_movement_id}_{uuid}），以便重试请求被识别为同一次退款尝试。退款允许的操作
🔑 创建
🔍 查询
描述： 通过调用
操作后的预期结果： 退款以
📘 了解更多：🔗 创建退款
POST /v1/refunds，使用 money_movement_id 或 transaction_id、amount 以及可选的 description，对现有 payin 请求全额或部分退款。操作后的预期结果： 退款以
processing 状态创建。Cobre 解析原始 payin 数据，或发送链接以采集数据，并自动发起对应的 payout。📘 了解更多：
如何开始
确认原始 payin 符合条件
退款必须引用尚未被全额退款的 payin Money Movement/Transaction。转入（transfer-in）交易不可退款。对于部分退款，请求的
amount 必须严格小于仍可退金额。确保发起的 Cobre Balance 资金充足
退款会借记收到原始 payin 的同一 Cobre Balance。该余额必须有足够资金才能处理退款——Cobre 不会从其他余额调取退款资金。
准备幂等键
从原始 payin 标识符派生幂等键，或使用您自定义的唯一密钥，以避免重试的退款请求被应用两次。
实现 Webhooks 以跟踪状态
由于退款作为 payout 异步结算，我们强烈建议实现 Webhooks 以跟踪其进度。更多详情请参见 通知与订阅。
开发中。
使用此 API 后的预期结果
退款已接受
退款请求通过验证后，将以
processing 状态创建，Cobre 开始向原付款人执行底层 payout。退款完成
当底层 payout 结算后，退款转为
completed，借记反映在发起的 Cobre Balance 上。退款拒绝或失败
若底层 payout 被金融机构或 Cobre 拒绝，退款为
rejected。若接受后底层 payout 无法完成，退款转为 failed。Modified at 2026-10-09 01:21:07