代收订单 · 土耳其
大约 4 分钟
概述
代收 API 用于向客户发起代收交易。本页为 土耳其(国家码 tr)的代收说明,支持以下两种下单方式:
| 下单方式 | 路径 | 说明 |
|---|---|---|
| 收银台模式 | /pay/prePay | 默认模式,返回 cashierUrl,用户跳转平台 H5 收银台完成支付 |
| API 模式 | /pay/transOrder | 请求中必须指定 method,直接返回 payData / payDataType |
- 金额单位为 TRY,正数,最多两位小数(示例:
100、100.50;100.555拒单)。 method仅支持BANK(银行转账),见 地区支付说明 — 土耳其。customerName、customerPhone必填。
接入说明
默认开通收银台模式。如需对接 API 模式,请联系客服申请商户白名单后再集成。
请求头
两种模式共用:
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | 固定值:application/json |
收银台模式(prePay)
请求路径
域名:推荐使用统一域名
openapi.toppayment.com(路径不变);原国别域名(如global-tr-openapi.toppayment.com)仍可用。
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/tr/pay/prePay |
| 生产 | https://openapi.toppayment.com/tr/pay/prePay |
请求体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 |
| orderNum | M | String(64) | 商户订单号 |
| amount | M | Number | 交易金额(TRY,最多两位小数) |
| productDetail | O | String(100) | 产品详情 |
| method | O | String(16) | 支付方式,可选;不传则用户在收银台选择。仅 BANK,见 土耳其代收编码 |
| timestamp | M | String(13) | 毫秒时间戳 |
| customerName | M | String(64) | 客户姓名 |
| customerEmail | O | String(64) | 客户邮箱 |
| customerPhone | M | String(32) | 客户手机号 |
| downNotifyUrl | M | String(255) | 异步通知地址 |
| redirectUrl | O | String(512) | 支付完成跳转地址 |
| sign | M | String | RSA 签名,参见 签名生成 |
请求体示例
{
"mchNo": "{{mchNo}}",
"orderNum": "TR1234561",
"amount": 100.50,
"productDetail": "test",
"method": "BANK",
"timestamp": "1749451858772",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "按签名规则生成后替换"
}
HTTP响应
两种模式共用:
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP响应内容类型规范 固定值:application/json 指示JSON响应格式 |
响应字段
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| success | M | Boolean | 请求是否成功 |
| code | M | String | 9999:成功;其他:失败 |
| msg | O | String | 响应消息,成功时为 null |
| timeStamp | M | Number | 响应时间戳(毫秒) |
| data | M | Object | 响应数据 |
| orderNum | M | String | 商户订单号 |
| platOrderNum | M | String | 平台订单号 |
| amount | M | Number | 交易金额 |
| fee | M | Number | 手续费 |
| method | O | String | 支付方式 |
| productDetail | O | String | 产品详情 |
| customerName | M | String | 客户姓名 |
| customerEmail | O | String | 客户邮箱 |
| customerPhone | M | String | 客户手机号 |
| validTime | M | Number | 订单过期时间(毫秒时间戳) |
| cashierUrl | M | String | 平台收银台 URL |
响应说明
收银台模式不返回 payData、payDataType;支付凭证字段仅见于 API 模式 响应。
响应示例
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "TR1234561",
"platOrderNum": "TRPTJ2009093829059153920",
"amount": 100.50,
"fee": 2.00,
"method": "BANK",
"productDetail": "test",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
API 模式(transOrder)
请求路径
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/tr/pay/transOrder |
| 生产 | https://openapi.toppayment.com/tr/pay/transOrder |
请求体
与收银台模式相比,差异如下:
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| method | M | String(16) | 支付方式。API 模式必传,仅 BANK,见 地区支付说明 — 土耳其 |
其余字段与收银台模式相同。
请求体示例
{
"mchNo": "{{mchNo}}",
"orderNum": "TRPAYINAPI1234561",
"amount": 100.50,
"productDetail": "test",
"method": "BANK",
"timestamp": "1749451858772",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "按签名规则生成后替换"
}
响应字段
公共响应字段与收银台模式相同。API 模式的支付凭证按下面规则返回:
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| payData | M | String | 支付数据。payDataType 为 VA 时是收款账号;为 CASHIER_URL 时是支付页链接 |
| payDataType | M | String | VA 或 CASHIER_URL。有收款账号时为 VA,否则为 CASHIER_URL |
| cashierUrl | O | String | 支付页链接。VA 时仅在同时给出支付页时有值,否则为 null;CASHIER_URL 时与 payData 相同 |
下例是只有支付页链接的返回。有收款账号时 payDataType 为 VA,payData 为账号。
响应示例
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "TRPAYINAPI1234561",
"platOrderNum": "TRPTJ2009093829059153920",
"amount": 100.50,
"fee": 2.00,
"method": "BANK",
"productDetail": "test",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay",
"payData": "https://example.cashier/pay",
"payDataType": "CASHIER_URL"
}
}
通知
两种下单方式的异步通知一致。
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": "TRPTJ2009093829059153920",
"version": "v1",
"orderNum": "TR1234561",
"amount": 100.50,
"fee": 2.00,
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"status": "SUCCESS",
"sign": "…"
}
