提交付款业务单据

能力概览

接入方 Payout 创建服务

调用地址

/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 推送，未传入时使用后台配置地址

Object:customerInfo

注意

KWD 或 AED 付款场景下，用户信息需提供 bankAddress 或 swiftCode 至少一项。
STCPay 付款场景下，用户信息需提供 stcAccount。
银行卡付款场景下，用户信息需提供 bankCode 与 iban。
用户信息同时包含 idNumber、idPhoto、signedPhoto、mobile 时，付款单据按标准付款处理。
用户信息缺少 idNumber、idPhoto、signedPhoto、mobile 中任一字段时，付款单据按快捷付款处理。

字段	提交要求	数据类型	长度限制	业务含义
merCustomerId	否	String	64	接入方系统内的用户唯一标识
enFirstName	是	String	64	用户英文名的 first name 部分
enMiddleName	否	String	64	用户英文名的 middle name 部分
enLastName	否	String	64	用户英文名的 last name 部分
arFirstName	是	String	64	用户阿拉伯文姓名的 first name 部分
arMiddleName	否	String	64	用户阿拉伯文姓名的 middle name 部分
arLastName	否	String	64	用户阿拉伯文姓名的 last name 部分
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
bankAddress	条件	String	128	用户开户银行地址；KWD 或 AED 付款时需提供该字段或 swiftCode

请求示例

json

{
  "merchantId": "MER74021658",
  "merOrderId": "PO202605090001",
  "subMerId": "SME81573042",
  "orderType": "online_payout",
  "paymentType": "cardpay",
  "orderCurrency": "SAR",
  "orderAmt": "258.75",
  "feeType": 1,
  "remarks": "Supplier settlement batch A",
  "serverNotifyUrl": "https://merchant.example.com/notify/payout",
  "customerInfo": {
    "merCustomerId": "CUS20260509001",
    "enFirstName": "Fahad",
    "enMiddleName": "Omar",
    "enLastName": "Saleh",
    "arFirstName": "فهد",
    "arMiddleName": "عمر",
    "arLastName": "صالح",
    "idNumber": "1098765432",
    "idPhoto": "images/customer/20260509/8b63f1a42d7e4c9aa12d87f30e61c5b2.jpg",
    "signedPhoto": "images/customer/20260509/3f24d9b7a5e84c11b9804a6552f8d731.png",
    "mobile": "0559876543",
    "email": "fahad.saleh@example.com",
    "address": "King Fahd Road, Riyadh",
    "stcAccount": "559876543",
    "bankCode": "SAU0009",
    "cardNo": "4111111111112222",
    "iban": "SA0380000000608010167519",
    "swiftCode": "RJHISARI",
    "bankAddress": "Al Rajhi Bank, Riyadh"
  }
}

响应参数

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	接入方系统内的用户标识
enFirstName	String	用户英文名的 first name
enMiddleName	String	用户英文名的 middle name
enLastName	String	用户英文名的 last name
arFirstName	String	用户阿拉伯文姓名的 first name
arMiddleName	String	用户阿拉伯文姓名的 middle name
arLastName	String	用户阿拉伯文姓名的 last name
idNumber	String	用户身份证件号码
idPhoto	String	用户身份证件照片访问地址
signedPhoto	String	用户签名照片访问地址
mobile	String	用户沙特手机号
email	String	用户邮箱地址
address	String	用户联系地址或居住地址

响应示例

json

{
  "code": 10000,
  "message": "success",
  "data": {
    "merchantId": "MER74021658",
    "orderId": "OUT260509112601208845321",
    "merOrderId": "PO202605090001",
    "subMerId": "SME81573042",
    "orderType": "online_payout",
    "paymentType": "cardpay",
    "orderCurrency": "SAR",
    "orderAmt": "258.75",
    "feeType": 1,
    "orderPaymentType": "standard",
    "orderStatus": 0,
    "orderStatusDesc": "2026-05-09 11:26:01",
    "remarks": "Supplier settlement batch A",
    "accountInfo": {
      "type": 1,
      "account": "4111111111112222",
      "bankCode": "SAU0009",
      "iban": "SA0380000000608010167519",
      "swiftCode": "RJHISARI",
      "bankAddress": "Al Rajhi Bank, Riyadh"
    },
    "customerInfo": {
      "merCustomerId": "CUS20260509001",
      "enFirstName": "Fahad",
      "enMiddleName": "Omar",
      "enLastName": "Saleh",
      "arFirstName": "فهد",
      "arMiddleName": "عمر",
      "arLastName": "صالح",
      "idNumber": "1098765432",
      "idPhoto": "https://cdn.example.com/images/customer/20260509/8b63f1a42d7e4c9aa12d87f30e61c5b2.jpg",
      "signedPhoto": "https://cdn.example.com/images/customer/20260509/3f24d9b7a5e84c11b9804a6552f8d731.png",
      "mobile": "0559876543",
      "email": "fahad.saleh@example.com",
      "address": "King Fahd Road, Riyadh"
    }
  },
  "success": true
}

提交付款业务单据 ​

能力概览 ​

调用地址 ​

请求参数 ​

请求示例 ​

响应参数 ​

响应示例 ​

提交付款业务单据

能力概览

调用地址

请求参数

请求示例

响应参数

响应示例