消息体组织规则

接入方联调参数信息

参数	来源	业务含义
接入方 keyId	平台生成，下发给接入方	Header 参数 merchantKeyId 的取值，用于识别当前调用使用的密钥配置
接入方编号 merchantId	平台生成，下发给接入方	Body 参数 merchantId 的取值，用于标识发起交易的接入方主体
加密/解密 aesKey	平台生成，下发给接入方	用于请求 Body 和响应 data 字段的 AES 加密及解密处理
接入方报文验签公钥	平台生成，下发给接入方	接入方验签平台响应报文时使用的 RSA 公钥
接入方签名私钥	接入方生成，接入方保留	接入方生成请求签名时使用的 RSA 私钥
平台验签公钥	接入方生成，上传至平台	平台校验接入方请求签名时使用的 RSA 公钥
接入方业务单据结果通知地址	接入方提供，上传至平台	平台推送交易、退款等异步结果通知的接收地址
接入方名称	入网 KYC 时填写	收银台页面展示的商户名称，存在二级接入方时优先展示二级接入方名称
接入方 logo	接入方提供，上传至平台	收银台页面展示的商户 Logo，存在二级接入方时优先展示二级接入方 Logo；图片格式 png/jpg，正方形，建议尺寸 120×120

调用方式

所有服务均通过 HTTPS POST 发送，调用地址格式如下：

POST https://openapi-uat.saudipays.cn/{接口路径}
Content-Type: application/json

固定 Header 参数

每个调用的 HTTP Header 中必须包含以下字段：

字段	提交要求	数据类型	业务含义
merchantKeyId	是	String	平台分配的密钥标识，用于匹配本次请求的商户密钥配置
version	是	String	接口协议版本，当前固定传入 1.0
timeStamp	是	String	请求发起时的秒级 Unix 时间戳
signature	是	String	使用接入方 RSA 私钥对请求 Body 密文签名后生成的签名值
content-language	是	String	指定平台响应文案语言： en-US（英语） ar-SA（阿拉伯语）

调用消息体结构

Body 加密释义

调用 Body 需先进行 AES 加密，再将密文作为 aesBuffer 字段的值发送；签名基于加密后的密文生成。

请求报文处理流程如下：

1. 生成业务请求 Body 明文。
2. 使用 AES 对 Body 明文加密，得到 aesBuffer 密文。
3. 使用接入方 RSA 私钥对 aesBuffer 密文生成签名。
4. 将签名结果填入 Header 的 signature 字段。

调用报文格式

POST https://openapi-uat.saudipays.cn/{接口路径}
Content-Type: application/json
merchantKeyId: {商户 keyId}
version: 1.0
timeStamp: {秒级时间戳}
signature: {RSA 私钥对 Body 密文的签名}
content-language: en-US

{
  "aesBuffer": "{Body 明文经 AES 加密后的密文}"
}

• 样例：Body 明文（加密前）

{
  "merchantId": "MER20460873",
  "merRefundOrderId": "RF202605090001",
  "origOrderId": "TRD2026041809304512468",
  "origMerOrderId": "PAYIN202604180001",
  "refundAmt": "36.50",
  "refundCurrency": "SAR",
  "refundDesc": "customer requested refund"
}

• 样例：完整调用报文（加密后）

POST https://openapi-uat.saudipays.cn/pay/merchant/{接口名称}
Content-Type: application/json
merchantKeyId: 9c4a72b5186d4f8e9a0137c25b6d90af
version: 1.0
timeStamp: 1778284800
signature: 根据请求 Body 密文使用商户 RSA 私钥签名
content-language: en-US

{
  "aesBuffer": "Yw9mR2hMZ0t4bHhzQ3ZxR2p0b0h4WnB2WkRLTmVUd3V5QkJ5cVZr..."
}

---

响应消息体结构

响应格式释义

所有服务响应的顶层结构固定如下，data 字段为 AES 加密后的密文：

{
  "code": 10000,
  "message": "success",
  "data": "{data 内所有字段经 AES 加密后的密文}"
}

验证签名后，使用 AES 密钥对 data 字段解密，即可获得业务数据。

• 样例：响应报文（data 为密文）

{
  "code": 10000,
  "message": "success",
  "data": "N2pJalVwU0N4aEZ2dVdHY1R6bU5PQnp5Wm1xS0xSZDFsV0Q5R1F..."
}

• 样例：data 解密后明文

{
  "merchantId": "MER20460873",
  "orderId": "ORD20260509104532001876",
  "merOrderId": "PAYIN202605090001",
  "subMerId": "SME70451236",
  "orderType": "online_payin",
  "paymentType": "cardpay,applepay",
  "paymentUrl": "https://openapi-uat.saudipays.cn/order=ORD20260509104532001876",
  "orderStatus": "pending"
}