代付订单 · 哥伦比亚

请求

代付 API 用于向受益人发起代付交易。本页为 哥伦比亚（国家码 co）的代付说明。bankCode 为收款机构 字母编码（见地区说明），bankCard 为收款账号或钱包账号等；另须按网关要求填写 accountType、documentType、documentNo、accountPhone、accountEmail 等字段。完整银行清单与证件、账户类型见地区支付说明 — 哥伦比亚。

请求路径

域名：推荐使用统一域名 openapi.toppayment.com（路径不变）；原国别域名（如 global-co-openapi.toppayment.com）仍可用。

环境	地址
沙箱	`https://openapi.toppayment.com/sandbox/co/disbursement/cash`
生产	`https://openapi.toppayment.com/co/disbursement/cash`

代付 bankCode / bankName 见地区支付说明 — 哥伦比亚。

请求头

字段	必填	类型	描述
Content-Type	M	String	HTTP内容类型规范固定值：application/json 正确解析请求所必需

请求体

字段	必填	类型	描述
mchNo	M	String(32)	商户编号平台分配的唯一商户标识符用于商户认证和交易路由
orderNum	M	String(50)	商户订单号唯一交易标识符格式：字母数字字符串用于交易跟踪和参考
amount	M	Number(32,8)	交易金额格式：数值类型示例：100.50 哥伦比亚地区：须为正数，整数或最多两位小数，不允许全为 0，不允许三位及以上小数。
bankCode	M	String(32)	收款银行/钱包编码（哥伦比亚）见地区支付说明 — 哥伦比亚中「代付银行及对应编码」
bankCard	M	String(50)	银行卡号/账号/钱包账号等具体格式以实际网关与收款行要求为准
accountType	M	String(32)	账户类型：CORRIENTE / AHORROS / BRE-B / WALLET（忽略大小写），见地区支付说明 — 哥伦比亚
documentType	M	String(16)	证件类型：CC / CE / NIT / PAS（忽略大小写），见地区支付说明 — 哥伦比亚
documentNo	M	String(100)	证件号码不校验号码位数与 `documentType` 的对应关系。
accountPhone	M	String(32)	收款人手机号须非空；不做本地号段格式强校验。
accountEmail	M	String(255)	收款人邮箱须为有效邮箱格式
accountName	M	String(50)	账户名收款人姓名，最长 50，Unicode 字母数字空格
description	O	String(255)	描述交易目的或描述格式：UTF-8编码字符串
feeType	M	Number(0或1)	手续费类型 0 : 代付金额内扣除(实际到账金额=下单金额-手续费) 1 : 手续费另计(实际到账金额=下单金额)
downNotifyUrl	M	String(164)	异步通知地址交易状态更新的Webhook通知URL 格式：有效的HTTP/HTTPS URL 用于实时交易状态通知
timestamp	M	String(13位数字)	时间戳请求时间戳示例：1749451858772
sign	M	String	签名请求认证的数字签名参见签名生成

请求体示例 – 付款请求（示例为 `BANCOLOMBIA` + 占位账号；以实际网关为准）：

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "COPAYOUT1234561",
    "amount": 100.50,
    "bankCode": "BANCOLOMBIA",
    "bankCard": "1234567890123456",
    "accountType": "CORRIENTE",
    "documentType": "CC",
    "documentNo": "1234567890",
    "accountPhone": "+573001234567",
    "accountEmail": "[email protected]",
    "accountName": "Maria Lopez",
    "description": "test",
    "feeType": 1,
    "downNotifyUrl": "https://example.com/notify",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

响应

HTTP响应

字段	必填	类型	描述
Content-Type	M	String	HTTP响应内容类型规范固定值：application/json 指示JSON响应格式

响应字段

字段	必填	类型	描述
success	M	Boolean	请求是否成功 true：成功，false：失败
code	M	String	响应状态码 9999：成功其他：请根据订单状态码判断，不能直接处理订单失败,以免造成资金损失
msg	O	String	响应消息可读的响应状态描述包含订单详细信息
timeStamp	M	Number	响应时间戳服务器响应时间（毫秒级）
data	M	Object	响应数据对象包含交易详细信息
orderNum	M	String	商户订单号与请求中提供的orderNum相同用于交易跟踪和参考
platOrderNum	M	String	平台订单号系统生成的内部交易参考号用于内部交易管理和支持
amount	M	Number	交易金额确认的交易金额
fee	M	Number	手续费交易产生的手续费
feeType	M	Number	手续费类型 1：商户承担手续费
status	M	Number	交易状态订单当前处理状态码
statusMsg	M	String	状态消息订单状态的文字描述
bankCode	M	String	银行代码（哥伦比亚）含义见地区支付说明 — 哥伦比亚
bankCard	M	String	银行卡号/账户号收款人的银行账户号码或钱包账号
accountName	M	String	账户名收款人账户名称
description	O	String	描述交易目的或描述

响应示例

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": "SUCCESS",
    "timeStamp": 1767772957433,
    "data": {
        "orderNum": "COPAYOUT12345617",
        "platOrderNum": "TRANS2008811496544403456",
        "amount": 100.50,
        "fee": 2,
        "feeType": 1,
        "status": 1,
        "statusMsg": "ORDER_RECEIVED_PROCESSING",
        "bankCode": "BANCOLOMBIA",
        "bankCard": "1234567890123456",
        "accountName": "Maria Lopez",
        "description": "test"
    }
}

通知

HTTP请求

字段	必填	类型	描述
Content-Type	M	String	HTTP请求内容类型规范固定值：application/json 指示JSON请求格式

通知体

字段	必填	类型	描述
platOrderNum	M	String	平台订单号系统生成的内部交易参考号用于内部交易管理和支持
version	M	String	版本号接口版本标识示例：v1
orderNum	M	String	商户订单号与原始请求中提供的orderNum相同用于交易识别和验证
amount	M	Number	交易金额确认的交易金额
fee	M	Number	手续费交易产生的手续费
feeType	M	Number	手续费类型 1：商户承担手续费
status	M	Number	交易状态取值见交易状态码
statusMsg	M	String	状态消息订单状态的文字描述
bankCode	M	String	银行代码（哥伦比亚）见地区支付说明 — 哥伦比亚
bankCard	M	String	银行卡号/账户号
accountName	M	String	账户名
description	O	String	描述
sign	M	String	签名回调数据的数字签名

重要响应

通知响应： 请仅返回字符串SUCCESS以确认收到通知

{
    "platOrderNum": "TRANS2008812168572567552",
    "version": "v1",
    "orderNum": "COPAYOUT12345648",
    "amount": 111.00,
    "fee": 3,
    "feeType": 1,
    "status": 2,
    "statusMsg": "supplement success!",
    "bankCode": "BANCOLOMBIA",
    "bankCard": "1234567890123456",
    "accountName": "Maria Lopez",
    "description": "test",
    "sign": "…"
}

SUCCESS

代付订单 · 哥伦比亚

# 请求

# 请求路径

# 请求头

# 请求体

# 请求体示例 – 付款请求（示例为 BANCOLOMBIA + 占位账号；以实际网关为准）：

# 响应

# HTTP响应

# 响应字段

# 响应示例

# 通知

# HTTP请求

# 通知体

# 返回

请求