发起支付

请求方式和路径

POST /payin/v1/createPayment

请求头

字段名	类型	必传	描述
content-type	string	是	`application/json`
x-api-key	string	是	`Paydify`提供，跟`appId`相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

请求体

字段名	类型	必传	描述
mchTxnId	string(60)	是	商户侧订单ID，最长 60 位
txnAmount	string(20)	是	订单金额，如`100.23`
currency	string(8)	是	订单金额（`txnAmount`）的计价币种，可传范围由 app 产品类型决定（开通时二选一，传错会被拒单、不自动折算）：稳定币收单 app 传 `USDT`/`USDC`，用户按此金额直接支付；法币收单 app 传 `USD`/`SGD`，按实时汇率折算为稳定币（见 `paymentCurrency`）。参看支持的币种
paymentCurrency	string(8)	否	法币收单专用：指定法币金额折算成哪种稳定币（`USDT`/`USDC`），用户即以该稳定币付款，缺省取 app 配置的默认稳定币；稳定币收单 app 无需传
checkoutMode	string(20)	是	收银台模式，固定值：`MERCHANT`（商户下发支付金额）
payMethod1	string(20)	否	支付使用的钱包，枚举值参看支持的链和币种
payMethod2	string(20)	否	支付使用的链，枚举值参看支持的链和币种
notificationUrl	string(300)	是	支付结果回调商户的地址，仅支持 `https`
successReturnUrl	string(300)	否	支付成功后跳转的地址
failReturnUrl	string(300)	否	支付失败后跳转的地址
pendingReturnUrl	string(300)	否	支付中跳转的地址
source	string(20)	否	订单来源标签
txnTitle	string(30)	否	支付标题，默认使用商户入驻时提供的商户名称
txnDesc	string(60)	否	支付描述信息
accountInfo	object[]	否	收款账号信息列表，如`[{"toAddress":"0xttttttt22222","network":"ETH"}]`。元素字段：`toAddress`（收款地址，元素存在时必填）、`network`（目标链，如 ETH / BSC / SOL / TRX / BASE，可选；未传则回退到外层 `payMethod2`）。不传或传空数组时走历史逻辑（取商户配置的收款地址）；兼容旧版单对象写法
payerInfo	object	否	付款人信息，如`{"uid":"123456"}`
mchExtInfo	string(512)	否	商户扩展信息，JSON字符串，该字段仅进行透传，将在回调中被带回
lifetime	int	否	订单超时周期，单位毫秒，默认30分钟
merchantId	string(60)	否	订单归属商户 ID（子商户）。合作伙伴（Partner）凭据代发时必填；商户自有凭据可不传，默认归属凭据所属商户。最长 60 字符
merchantAppId	string(64)	否	归属商户下的应用 ID，用于归属商户存在多个已授权应用时消歧。凭据覆盖该商户多个应用时必填；仅一个授权应用时可不传，系统自动匹配。最长 64 字符

响应头参数

字段名	类型	必传	描述
x-api-key	string	是	`Paydify`提供，跟`appId`相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

返回值

字段名	类型	描述
code	string	响应码，`SYS_SUCCESS`表示成功
message	string	响应消息
messageDetail	string	响应消息详情
success	boolean	是否成功
data.txnId	string	`Paydify`侧的订单ID
data.mchTxnId	string	商户侧的订单ID
data.state	string	支付状态，枚举值参看支付状态
data.errorMsg	string	支付失败原因说明
data.qrCode	string	支付链接二维码base64数据
data.deeplink	string	原生支付链接
data.httplink	string	HTTP支付链接

示例

# 请求

# 成功返回值
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "txnId": "P1167515578018041857",
    "mchTxnId": "MCH_TXN_987_1756287002",
    "state": "INIT",
    "errorMsg": "",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAL4AAACoCAYAAABe+//hGBxxxxxxxxxx",
    "deeplink": "bitkeep://pay?txnId=P20250827173005906",
    "httplink": "https://payrouter.paydify.com/en/pay/middle?txnId=P1167515578018041857&_needChain=base"
  },
  "success": true
}

# 失败返回值
{
  "code": "SYS_ERROR",
  "message": "System error",
  "messageDetail": "Error details",
  "data": null,
  "success": false
}