代收订单 · 玻利维亚

请求

收款 API 使商户能够通过收银台发起向客户收取付款的交易。本页为 玻利维亚（国家码 bo，币种 BOB）的代收能力说明。

请求路径

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

环境	地址
沙箱	https://openapi.toppayment.com/sandbox/bo/pay/prePay
生产	https://openapi.toppayment.com/bo/pay/prePay

玻利维亚当前仅支持 YAPE，详见 地区支付说明 — 玻利维亚。

请求头

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json

请求体

字段	必填	类型	描述
mchNo	M	String(32)	商户编号
orderNum	M	String(64)	商户订单号
amount	M	Number(32,8)	交易金额；须为正数、整数或最多两位小数
productDetail	M	String(100)	产品详情
method	M	String(16)	支付方式；当前仅支持 YAPE
payerAccountNo	C	String(64)	付款人 Yape 账号；method=YAPE 时必填
timestamp	M	String(13)	毫秒级时间戳
customerName	M	String(64)	付款人姓名
customerEmail	M	String(64)	付款人邮箱
customerPhone	M	String(32)	付款人电话
expiryPeriod	O	Number(1-9999)	交易有效期（分钟）
downNotifyUrl	M	String(255)	异步通知 URL
redirectUrl	O	String(512)	支付完成后的跳转 URL
sign	M	String	签名，见签名规则

请求体示例

Content-type: application/json

{
  "mchNo": "{{mchNo}}",
  "orderNum": "BO1234561",
  "amount": 100.50,
  "productDetail": "测试商品",
  "method": "YAPE",
  "payerAccountNo": "70012345",
  "timestamp": "1749451858772",
  "customerName": "Juan Perez",
  "customerEmail": "[email protected]",
  "customerPhone": "+59170000000",
  "expiryPeriod": 1440,
  "downNotifyUrl": "https://example.com/notify",
  "redirectUrl": "https://example.com/return",
  "sign": "按签名规则生成后替换"
}

响应

响应字段

字段	必填	类型	描述
success	M	Boolean	请求是否成功
code	M	String	9999：成功
msg	O	String	响应消息
timeStamp	M	Number	响应时间戳（毫秒）
data	M	Object	交易数据
orderNum	M	String	商户订单号
platOrderNum	M	String	平台订单号
amount	M	Number	交易金额
fee	M	Number	手续费
method	M	String	支付方式，当前为 YAPE
productDetail	M	String	产品详情
customerName	M	String	付款人姓名
customerEmail	M	String	付款人邮箱
customerPhone	M	String	付款人电话
validTime	M	Number	过期时间戳（毫秒）
cashierUrl	M	String	收银台 URL；将客户跳转至该地址完成支付

响应示例

{
  "success": true,
  "code": "9999",
  "msg": null,
  "timeStamp": 1767840272829,
  "data": {
    "orderNum": "BO1234561",
    "platOrderNum": "PRE2009093829059153920",
    "amount": 100.50,
    "fee": 2.0,
    "method": "YAPE",
    "productDetail": "测试商品",
    "customerName": "Juan Perez",
    "customerEmail": "[email protected]",
    "customerPhone": "+59170000000",
    "validTime": 1767926672819,
    "cashierUrl": "https://example.cashier/pay"
  }
}

通知

HTTP请求

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json

通知体

字段	必填	类型	描述
platOrderNum	M	String	平台订单号
version	M	String	版本号（示例：v1）
orderNum	M	String	商户订单号
amount	M	Number	交易金额
fee	M	Number	手续费
customerName	M	String	客户姓名
customerEmail	M	String	客户邮箱
customerPhone	M	String	客户电话
status	M	String	交易状态 取值见 交易状态码
sign	M	String	回调签名

返回

校验签名后，仅返回字符串 SUCCESS。

SUCCESS

通知示例

{
  "platOrderNum": "PRE2009165141186183168",
  "version": "v1",
  "orderNum": "BO1234561",
  "amount": 100.50,
  "fee": 2,
  "customerName": "Juan Perez",
  "customerEmail": "[email protected]",
  "customerPhone": "+59170000000",
  "status": "SUCCESS",
  "sign": "…"
}