跳至主要內容

代收订单 · 土耳其

TOPPAY Team大约 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-TypeMString固定值: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

请求体

字段必填类型描述
mchNoMString(32)商户编号
orderNumMString(64)商户订单号
amountMNumber交易金额(TRY,最多两位小数)
productDetailOString(100)产品详情
methodOString(16)支付方式,可选;不传则用户在收银台选择。仅 BANK,见 土耳其代收编码
timestampMString(13)毫秒时间戳
customerNameMString(64)客户姓名
customerEmailOString(64)客户邮箱
customerPhoneMString(32)客户手机号
downNotifyUrlMString(255)异步通知地址
redirectUrlOString(512)支付完成跳转地址
signMStringRSA 签名,参见 签名生成

请求体示例

{
    "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-TypeMStringHTTP响应内容类型规范
固定值:application/json
指示JSON响应格式

响应字段

字段必填类型描述
successMBoolean请求是否成功
codeMString9999:成功;其他:失败
msgOString响应消息,成功时为 null
timeStampMNumber响应时间戳(毫秒)
dataMObject响应数据
orderNumMString商户订单号
platOrderNumMString平台订单号
amountMNumber交易金额
feeMNumber手续费
methodOString支付方式
productDetailOString产品详情
customerNameMString客户姓名
customerEmailOString客户邮箱
customerPhoneMString客户手机号
validTimeMNumber订单过期时间(毫秒时间戳)
cashierUrlMString平台收银台 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

请求体

与收银台模式相比,差异如下:

字段必填类型描述
methodMString(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 模式的支付凭证按下面规则返回:

字段必填类型描述
payDataMString支付数据。payDataType 为 VA 时是收款账号;为 CASHIER_URL 时是支付页链接
payDataTypeMStringVA 或 CASHIER_URL。有收款账号时为 VA,否则为 CASHIER_URL
cashierUrlOString支付页链接。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-TypeMString固定值:application/json

通知体

字段必填类型描述
platOrderNumMString平台订单号
versionMString版本号(示例:v1)
orderNumMString商户订单号
amountMNumber交易金额
feeMNumber手续费
customerNameMString客户姓名
customerEmailMString客户邮箱
customerPhoneMString客户电话
statusMString交易状态
取值见 交易状态码
signMString回调签名

返回

校验签名后,仅返回字符串 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": "…"
}