创建代付订单

简述

商户 Payout 下单接口

请求 URL

/pay/payout/createOrder

请求参数

body

参数名	必选	类型	长度	说明
merchantId	是	String	32	商户编码(平台分配)
merOrderId	是	String	64	商户订单号，在商户系统保证唯一
subMerId	否	String	32	二级商户编号如存在则上送
orderType	是	String	32	交易类型固定值：`online_payout`
paymentType	是	String	32	付款方式： `stcpay`：STCPay 付款（`该付款方式货币只能为 SAR`） `cardpay`：卡付款
orderCurrency	是	String	10	付款币种例如：SAR
orderAmt	是	String	16	付款金额，付款金额不能小于 0.01
feeType	是	Int	1	手续费承担方式： `0`：客户承担 `1`：商户承担
remarks	否	String	128	付款备注
customerInfo	是	`Object`	-	客户信息，对象格式（Object:customerInfo）
serverNotifyUrl	否	String	255	服务端支付结果通知地址。商户如果传该字段，以此 URL 为准给商户服务端回调；如果未传该字段，以后端配置的 URL 给商户服务端回调

Object:customerInfo

注意

代付 KWD 或 AED 货币，需要客户信息中存在 bankAddress 或者 swiftCode
STCPay 付款，需要客户信息中存在 stcAccount 账户信息
卡付款，需要客户信息中存在 bankCode 和 iban 账户信息
如果客户信息中存在 idNumber、idPhoto、signedPhoto、mobile，当前代付订单走标准付款
如果客户信息中缺失 idNumber、idPhoto、signedPhoto、mobile 其中一个或多个，当前代付订单走快捷付款

参数名	必选	类型	长度	说明
merCustomerId	否	String	64	商户系统中客户 ID
enFirstName	是	String	64	客户英文名称-前
enMiddleName	否	String	64	客户英文名称-中
enLastName	否	String	64	客户英文名称-后
arFirstName	是	String	64	客户阿拉伯文名称-前
arMiddleName	否	String	64	客户阿拉伯文名称-中
arLastName	否	String	64	客户阿拉伯文名称-后
idNumber	否	String	32	客户身份证号
idPhoto	否	String	255	客户身份证照片路径（`文件上传`接口返回）
signedPhoto	否	String	255	客户签名照片路径（`文件上传`接口返回）
mobile	否	String	12	客户沙特手机号，要求格式： `5xxxxxxxx` `05xxxxxxxx` `966xxxxxxxx`
email	否	String	64	客户邮箱地址
address	否	String	128	客户地址
stcAccount	条件	String	12	客户 STCPay 账户，`STCPay 付款时必填`，要求格式： `5xxxxxxxx` `05xxxxxxxx` `966xxxxxxxx`
bankCode	条件	String	64	平台银行编码，`卡付款时要求客户具备此信息`
cardNo	否	String	32	银行卡号
iban	条件	String	32	客户 IBAN，`卡付款时要求客户具备此信息`
swiftCode	条件	String	32	客户银行 Swift Code，`代付 KWD 或 AED 货币要求客户具备此信息`
bankAddress	条件	String	128	客户银行地址，`代付 KWD 或 AED 货币要求客户具备此信息`

请求示例

json

{
  "merchantId": "MER12345678",
  "merOrderId": "TEST1234567890",
  "subMerId": "SME30245285",
  "orderType": "online_payout",
  "paymentType": "cardpay",
  "orderCurrency": "SAR",
  "orderAmt": "100",
  "feeType": 1,
  "remarks": "Test Order",
  "serverNotifyUrl": "https://xxxxx.com/xxxx/xxx",
  "customerInfo": {
    "merCustomerId": "12345678",
    "enFirstName": "Mohammed",
    "enMiddleName": "Ali",
    "enLastName": "Khaled",
    "arFirstName": "محمد",
    "arMiddleName": "علي",
    "arLastName": "خالد",
    "idNumber": "1234512345",
    "idPhoto": "images/customer/20250526/d1b55874817a4ea1961fc93bb2b793c6.jpg",
    "signedPhoto": "images/customer/20250808/d0c3a9907fa540afb9631266bd6714d5.png",
    "mobile": "512345678",
    "email": "demo@example.com",
    "address": "Riyadh, Saudi Arabia",
    "stcAccount": "512345678",
    "bankCode": "SAU0004",
    "cardNo": "1234567891",
    "iban": "SA123456789123456789",
    "swiftCode": "INMASARI",
    "bankAddress": "INMA BANK, KSA"
  }
}

响应参数

data

参数名	类型	说明
merchantId	String	商户编码
orderId	String	平台订单号
merOrderId	String	商户订单号
subMerId	String	二级商户编号
orderType	String	交易类型
paymentType	String	付款方式： `stcpay`：STCPay 付款 `cardpay`：卡付款
orderCurrency	String	付款币种
orderAmt	String	付款金额
feeType	Int	手续费承担方式： `0`：客户承担 `1`：商户承担
orderPaymentType	String	付款订单类型： `standard`：标准付款 `rapid`：快捷付款
orderStatus	Int	代付订单状态： `0`：未付款 `2`：付款中 `10`：付款成功 `20`：付款失败
orderStatusDesc	String	代付订单状态描述
remarks	String	付款备注
accountInfo	Object	付款账户信息，对象格式（Object:accountInfo）
customerInfo	Object	客户信息，对象格式（Object:customerInfo）

Object:accountInfo

参数名	类型	说明
type	Int	账户类型： `0`：未知 `1`：银行账户 `2`：STCPay 账户
account	String	账户：STCPay 账户银行卡号
bankCode	String	平台银行编码，STCPay 付款时为空
iban	String	客户 IBAN，STCPay 付款时为空
swiftCode	String	客户银行 Swift Code，STCPay 付款时为空
bankAddress	String	客户银行地址，STCPay 付款时为空

Object:customerInfo

参数名	类型	说明
merCustomerId	String	商户系统中客户 ID
enFirstName	String	客户英文名称-前
enMiddleName	String	客户英文名称-中
enLastName	String	客户英文名称-后
arFirstName	String	客户阿拉伯文名称-前
arMiddleName	String	客户阿拉伯文名称-中
arLastName	String	客户阿拉伯文名称-后
idNumber	String	客户身份证号
idPhoto	String	客户身份证照片 URL
signedPhoto	String	客户签名照片 URL
mobile	String	客户沙特手机号
email	String	客户邮箱地址
address	String	客户地址

响应示例

json

{
  "code": 10000,
  "message": "success",
  "data": {
    "merchantId": "MER12345678",
    "orderId": "OUT250923112601207221172",
    "merOrderId": "TEST1234567890",
    "subMerId": "SME30245285",
    "orderType": "online_payout",
    "paymentType": "cardpay",
    "orderCurrency": "SAR",
    "orderAmt": "100",
    "feeType": 1,
    "orderPaymentType": "standard",
    "orderStatus": 0,
    "orderStatusDesc": "2025-09-23 11:33:08",
    "remarks": "Test Order",
    "accountInfo": {
      "type": 1,
      "account": "1234567891",
      "bankCode": "SAU0004",
      "iban": "SA123456789123456789",
      "swiftCode": "INMASARI",
      "bankAddress": "INMA BANK, KSA"
    },
    "customerInfo": {
      "merCustomerId": "12345678",
      "enFirstName": "Mohammed",
      "enMiddleName": "Ali",
      "enLastName": "Khaled",
      "arFirstName": "محمد",
      "arMiddleName": "علي",
      "arLastName": "خالد",
      "idNumber": "1234512345",
      "idPhoto": "https://xxxx.com/images/v2/customer/20250526/d1b55874817a4ea1961fc93bb2b793c6.jpg",
      "signedPhoto": "https://xxxx.com/images/v2/customer/20250808/d0c3a9907fa540afb9631266bd6714d5.png",
      "mobile": "512345678",
      "email": "demo@example.com",
      "address": "Riyadh, Saudi Arabia"
    }
  },
  "success": true
}

创建代付订单 ​

简述 ​

请求 URL ​

请求参数 ​

请求示例 ​

响应参数 ​

响应示例 ​

创建代付订单

简述

请求 URL

请求参数

请求示例

响应参数

响应示例