创建在线收款单

能力概览

• 接入方在线 Payin 创建服务

调用地址

• /pay/merchant/createOrder

请求参数

• body

字段	提交要求	数据类型	长度限制	业务含义
merchantId	是	String	32	平台分配给接入方的唯一商户标识
merOrderId	是	String	64	接入方系统生成的收款订单号，需保证在接入方侧唯一
subMerId	否	String	32	二级商户标识；存在二级接入方场景时传入
orderType	是	String	32	收款交易类型，固定传入 online_payin
paymentType	否	String	100	指定可用支付方式；可不传，支持多个值并使用英文逗号分隔。 取值见支付方式清单
orderAmt	是	String	12	收款订单金额，按两位小数格式提交，如：100.00
orderCurrency	是	String	10	收款订单币种代码，例如：SAR
expireTime	是	String	4	收款订单有效时长，单位为 min，默认 30min
serverNotifyUrl	否	String	255	支付结果服务端通知地址；传入时平台按该 URL 推送，未传入时使用后台配置地址
frontRedirectUrl	是	String	255	支付完成后前端页面跳转的目标地址
productInfo	是	List<Object>		收款订单关联的商品明细列表，元素结构见 Object:productInfo
customerInfo	是	Object		支付用户资料对象，结构见 Object:customerInfo
deliveryInfo	条件	Object		物流配送资料对象；当 productInfo.productType=physical 时必须提交
orderDesc	否	String	128	收款订单的业务说明
cashierIsSdk	否	String	2	收银台接入模式，未传入时默认为 0 0：统一收银台 1：SDK 方式

• Object:productInfo

字段	提交要求	数据类型	长度限制	业务含义
productType	是	String	32	商品形态分类 virtual：虚拟商品 physical：实体商品
productName	是	String	128	商品展示名称
productSku	否	String	100	接入方商品 SKU 或商品编码
productQuantity	是	String	5	本笔订单中的商品购买数量
productUnitPrice	是	String	12	商品单价，按两位小数提交，如：1.00
productCurrency	是	String	10	商品金额对应的币种代码，如：SAR
productDesc	否	String	128	商品补充描述信息
productAvatarUrl	是	String	255	商品图片的可访问 URL

• Object:customerInfo

字段	提交要求	数据类型	长度限制	业务含义
customerUid	是	String	40	接入方系统内的支付用户唯一标识
customerName	是	String	128	支付用户姓名
customerPlatform	是	String	128	用户发起购买行为的应用或平台名称
customerPhone	条件	String	18	用户手机号；当 productType=physical 时必须提交
customerEmail	是	String	64	支付用户邮箱地址

• Object:deliveryInfo

字段	提交要求	数据类型	长度限制	业务含义
firstName	是	String	64	收货人名
lastName	是	String	64	收货人姓
phone	是	String	18	收货人手机号
country	是	String	128	收货地址所属国家
city	是	String	128	收货地址所属城市
address	是	String	128	收货地址的详细街道信息
zipCode	是	String	10	收货地址邮政编码

请求示例

{
  "merchantId": "MER20460873",
  "merOrderId": "PAYIN202605090001",
  "subMerId": "SME70451236",
  "orderType": "online_payin",
  "paymentType": "cardpay,applepay",
  "orderAmt": "186.40",
  "orderCurrency": "SAR",
  "expireTime": "30",
  "serverNotifyUrl": "https://merchant.example.com/notify/payin",
  "frontRedirectUrl": "https://merchant.example.com/payment/result",
  "productInfo": [
    {
      "productType": "physical",
      "productName": "Wireless Headphones",
      "productSku": "SKU-HP-20260509",
      "productQuantity": "1",
      "productUnitPrice": "186.40",
      "productCurrency": "SAR",
      "productDesc": "Bluetooth audio device",
      "productAvatarUrl": "https://merchant.example.com/assets/products/headphones.png"
    }
  ],
  "customerInfo": {
    "customerUid": "UID20260509001",
    "customerName": "Noura Ahmed",
    "customerPlatform": "SaudiPays Demo Store",
    "customerPhone": "0551234567",
    "customerEmail": "noura.ahmed@example.com"
  },
  "deliveryInfo": {
    "firstName": "Noura",
    "lastName": "Ahmed",
    "phone": "0551234567",
    "country": "Saudi Arabia",
    "city": "Riyadh",
    "address": "Olaya Street Building 18",
    "zipCode": "12213"
  },
  "orderMemo": "PAYIN-MEMO-20260509",
  "cashierIsSdk": "0"
}

响应参数

• data

字段	数据类型	业务含义
merchantId	String	当前收款订单所属的接入方标识
orderId	String	平台生成的收款交易订单号
merOrderId	String	接入方提交的收款订单号，按请求原值返回
subMerId	String	二级接入方标识
orderType	String	收款交易类型，取值为 online_payin
paymentType	String	本订单可用支付方式，可包含多个值并使用英文逗号分隔。 取值见支付方式清单
paymentUrl	String	用户完成支付所需访问的收银台跳转链接
orderStatus	String	收款订单当前处理状态： init：初始化 pending：处理中 success：成功 fail：失败 expired：已过期

响应示例

{
  "code": 10000,
  "message": "success",
  "data": {
    "merchantId": "MER20460873",
    "orderId": "TRD20260509104532001876",
    "merOrderId": "PAYIN202605090001",
    "subMerId": "SME70451236",
    "orderType": "online_payin",
    "paymentType": "cardpay,applepay",
    "paymentUrl": "https://openapi-uat.saudipays.cn/en-US/order/TRD20260509104532001876",
    "orderStatus": "init"
  }
}