版本：Next

SaaS CNP交易接口文档

1. 简介

提供Server To Server cnp交易接口给服务商（下述描述机构均为服务商）调用。

注：涉及金额字段，单位均为元

请求地址，请求头信息参看文档: saas公共请求及响应参数-3. 请求公共参数信息

响应头信息参看文档: saas公共请求及响应参数-4. 响应公共参数信息

2.cnp接口

2.1 预下单

介绍：用于预先创建订单,后拉起收银台发起支付

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值：1.0.0
language	String	否	语言	语言（zh_CN，zh_TW，en_US）默认取值：zh_CN
interfaceName	String	是	接口名称	填写：`preOrder`
businessType	String	是	业务类型	填写：`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围：RSA-SHA256，ECDSA-SHA256，HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
productNo	String	是	产品编号	参考附录-枚举字典 1. 产品编码; cnp场景目前固定 C202
merchantNo	String	是	商户号

Object

是

商户信息对象

order

字段名

类型

是否必传

字段名称

说明

externalOrderNo

String

是

商户订单号

业务方订单号/外部订单号

currency

String

是

订单币种

参考附录-枚举字典 12. 币种

amount

String

是

订单交易金额

String

是

付款人电子邮箱

webSite

String

是

所属网站

下单来源网站

language

String

是

网站语言

参考附录-枚举字典 16. 语言例：zh ,注意:不能使用zh_CN

orderTitle

String

否

订单标题

orderDetails

String

否

订单描述

如"饼干一包，水果一袋"

externalAdditionalData

String

否

订单附加数据

jsonStr 格式

goodsDetails

字段名	类型	是否必传	字段名称
sku	String	是	商品编号
productName	String	是	商品名称
price	Number	是	商品单价
quantity	Number	是	商品购买数量
productImage	String	否	商品图片URL
productUrl	String	否	商品链接URL

Array

否

商品信息列表

shippingAddress

字段名	类型	是否必传	字段名称	说明
shippingFirstName	String	是	名字
shippingLastName	String	是	姓氏
shippingAddress1	String	是	地址1
shippingAddress2	String	否	地址2
shippingCity	String	是	城市
shippingState	String	是	州/省
shippingCountry	String	是	国家代码	参考附录-枚举字典 15. 国别列表,两位代码
shippingZipCode	String	是	邮编
shippingPhone	String	是	电话

Object

是

收货地址对象

billingAddress

字段名	类型	是否必传	字段名称	说明
billingFirstName	String	是	名字
billingLastName	String	是	姓氏
billingAddress1	String	是	地址1	使用dm/3ds则必填。为避免交易失败，中文地址建议翻译为英文地址
billingAddress2	String	否	地址2
billingCity	String	是	城市
billingState	String	是	州/省
billingCountry	String	是	国家代码	参考附录-枚举字典 15. 国别列表, 两位代码
billingZipCode	String	是	邮编
billingPhone	String	是	电话

Object

是

账单地址对象

Object

是

订单信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: preOrder' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: C55VGlDUx3HZsyhP3RI1HeQdVlMICUWVYXF6BqKReHVoc27h76iNKijukuR/heWocSpevat+thQJKt25XwKUuRU+6JW7UOILd29261sTssBgRIvHlIYN4RMG4s5PxTQu2ftNz+0um8+V0BoFI/Q8/vYUtlZPMVaJ4+qZLskj5NevkIBQz7dkP2xCobQAdCSvhJAXGmfiWD6FujEbB+ICdidmkoCHlqMqpCxVOPjPP/GTscJYJi3lZ7KGD22zVX6s7/u6ggOq2pW888rLudal5osmNz0ISflLyF980KzYFvVs/hEzwOeMFiSmv5iDMXcwNvDtDCW1hDvxfmrMyq6QSg==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908071916833_38",
    "requestTime":"2025-09-08T07:19:16.833+08:00",
    "nonceStr":"rbqEJuEb7UhZIxK1u8VHnk7I2fk1zLvT",
    "data":{
        "merchant":{
            "merchantNo":"********",
            "productNo" : "C202"
        },
        "order":{
            "externalOrderNo":"EXT_ORDER_20250908151916",
            "amount":"10",
            "tipAmount":"0",
            "currency":"USD",
            "language":"zh",
            "email":"gw816@163.com",
            "webSite":"www.baidu.com",
            "orderTitle":"订单title",
            "orderDetails":"一袋饼干",
            "externalAdditionalData":"{}",
            "goodsDetails":[{
                "sku":"123456",
                "productName":"测试产品名",
                "price":500,
                "quantity":2,
                "productImage":"",
                "productUrl":""
            }],
            "shippingAddress":{
                "shippingFirstName": "Peter 三",
                "shippingLastName": "zh张",
                "shippingAddress1": "广东省广州市测试 测试 测试测试 测试 测试*",
                "shippingAddress2": "广东省广州市测试 Another",
                "shippingCity": "New York",
                "shippingState": "NY",
                "shippingCountry": "CN",
                "shippingZipCode": "10001",
                "shippingPhone": "1231230080"
            },
            "billingAddress":{
                "billingFirstName": "John",
                "billingLastName": "Doe",
                "billingAddress1": "456 Oak St",
                "billingAddress2": null,
                "billingCity": "Los Angeles",
                "billingState": "CA",
                "billingCountry": "CN",
                "billingZipCode": "90001",
                "billingPhone": "987-654-3210"
            }
        }
    }
}'

响应参数

字段名

类型

是否必返

字段名称

说明

order

字段名	类型	是否必返	字段名称	说明
productNo	String	是	产品编号	参考附录-枚举字典 1. 产品编码
merchantNo	String	是	商户号
externalOrderNo	String	是	商户订单号	调用方唯一
orderNo	String	是	平台订单号
currency	String	是	订单币种
amount	String	是	订单交易金额
orderStatus	String	是	订单状态	参考附录-枚举字典订单状态
orderTime	String	是	下单时间	ISO8601 格式例如 2025-09-08T15:19:16.346+00:00
orderZoneId	String	是	商户所在地时区	商户时区/下单时区,例如 Asia/Hong_Kong
language	String	否	网站语言
email	String	否	付款人电子邮件
webSite	String	否	所属网站
orderTitle	String	否	订单标题
orderDetails	String	否	订单描述
externalAdditionalData	String	否	订单附加数据

Object

是

订单信息对象

响应Headers数据示例：

signature: idCYp8R2h4TPiLLN+E+K3F9uKwScaJjlAUwxut8PwEh4EfHn526IPZuw1MITfEmsQA06sNYrr5hI7dsaBJrBWLV8UFWKfuSkg2aPn94THa3TD/NZt5r7NxGYVAT2IGmw2q+h+z5hFQSBRENsz1r1GIhtQogaH2klN5m5XQNgJlHuGoMNpbCY8MRtDhVjmILrXHb1SrqsMQKW74r4EbjwXi6ZTV4c/OnYIXemg6us8v3kw9h4pKKWPsZh+jP9Y7Xk51SUFxOemxMayrW1xoDuOzZt0W5jCaX07KDrn4CKkFx0IPCnxjiv5vfavONN3/kbt0BYzqLMnFzWTVgIoCWN0w==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T07:19:16.363+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": {
            "externalOrderNo": "EXT_ORDER_20250908151916",
            "orderNo": "10820250908000014101",
            "amount": "10",
            "currency": "USD",
            "orderStatus": "01",
            "orderTime": "2025-09-08T15:19:16.346+00:00",
            "externalAdditionalData": "{}",
            "merchantNo": "4344000047",
            "productNo": "C202",
            "orderZoneId": "Asia/Hong_Kong",
            "orderTitle": "订单title",
            "language": "zh",
            "email": "gw816@163.com",
            "webSite": "www.baidu.com"
        }
    }
}

2.2 修改订单

介绍：订单修改只能修改商品信息,收货地址信息,账单地址信息

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值：1.0.0
language	String	否	语言	语言（zh_CN，zh_TW，en_US）默认取值：zh_CN
interfaceName	String	是	接口名称	填写：`updateOrderInfo`
businessType	String	是	业务类型	填写：`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围：RSA-SHA256，ECDSA-SHA256，HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户编号

Object

是

商户信息对象

order

字段名

类型

是否必传

字段名称

说明

externalOrderNo

String

否

商户订单号

与orderNo二选一

orderNo

String

否

平台订单号

二者都传时 orderNo优先于externalOrderNo

goodsDetails

字段名	类型	是否必传	字段名称
sku	String	是	商品编号
productName	String	是	商品名称
price	Number	是	商品单价
quantity	Number	是	商品购买数量
productImage	String	否	商品图片URL
productUrl	String	否	商品链接URL

Array

否

商品信息列表

shippingAddress

字段名	类型	是否必传	字段名称
shippingFirstName	String	是	名字
shippingLastName	String	是	姓氏
shippingAddress1	String	是	地址1
shippingAddress2	String	否	地址2
shippingCity	String	是	城市
shippingState	String	是	州/省
shippingCountry	String	是	国家代码
shippingZipCode	String	是	邮编
shippingPhone	String	是	电话

Object

是

收货地址对象

billingAddress

字段名	类型	是否必传	字段名称	说明
billingFirstName	String	是	名字
billingLastName	String	是	姓氏
billingAddress1	String	是	地址1	使用dm/3ds则必填。为避免交易失败，中文地址建议翻译为英文地址
billingAddress2	String	否	地址2
billingCity	String	是	城市
billingState	String	是	州/省
billingCountry	String	是	国家代码
billingZipCode	String	是	邮编
billingPhone	String	是	电话

Object

是

账单地址对象

Object

是

订单信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: updateOrderInfo' \
--header 'language: zh_CN' \
--header 'interfaceversion: 1.0.0' \
--header 'signature: RuDTdEf/fwXaLk50u+WytuLPRXB1FiF1oBau+NXo/Df49+ZmXiLJWuU6RU8c/II7+m5NLYAZi2OPbiBNkR3fPXzla6C049sfa04f62lVdkb3I4SC+PjiRxMN3wnkD9aI6xY2EOT7IhwbBOhKtUCi25/4nmK2yIE8ftUbor2GVZSsb+Try4uhDw0u1dG/sK/YPvuoKwFnOWQQFr6BV3A/knvqs7aksQge7IA5huFRkI8KPDSADtGoDRGut5GqPywjj4Q2BpwfCyh/fdNRlxB+S1Sbaie6tVTTRrNZMlRII89l9HSz+CAQE0hwO4A5tsvVLXkunDcuZ0UShQO75Mlz1Q==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908074336198_f9",
    "requestTime":"2025-09-08T07:43:36.198+08:00",
    "nonceStr":"48cMgLw4pRLic9mnFgevS8oqv7sDohkO",
    "data":{
        "merchant":{
            "merchantNo":"********"
        },
      "order":{
            "externalOrderNo":"EXT_ORDER_20250827180716",
            "orderNo": "10820250908000014101",
            "goodsDetails":[{
                "sku":"123456",
                "productName":"测试产品名11213123",
                "price":500,
                "quantity":2,
                "productImage":"",
                "productUrl":""
            }],
            "shippingAddress":{
                "shippingFirstName": "Peter 三1123",
                "shippingLastName": "zh张",
                "shippingAddress1": "广东省广州市测试 测试 测试测试 测试 测试*",
                "shippingAddress2": "广东省广州市测试 Another",
                "shippingCity": "New York",
                "shippingState": "NY",
                "shippingCountry": "US",
                "shippingZipCode": "10001",
                "shippingPhone": "1231230080"
            },
            "billingAddress":{
                "billingFirstName": "John123123",
                "billingLastName": "Doe",
                "billingAddress1": "456 Oak St",
                "billingAddress2": null,
                "billingCity": "Los Angeles",
                "billingState": "CA",
                "billingCountry": "US",
                "billingZipCode": "90001",
                "billingPhone": "987-654-3210"
            }
        }
    }
}'

响应参数

字段名

类型

是否必返

字段名称

说明

order

字段名	类型	是否必返	字段名称
merchantNo	String	是	商户编号
orderNo	String	是	平台订单号
externalOrderNo	String	是	商户订单号
orderStatus	String	是	订单状态

Object

是

订单信息对象

响应Headers数据示例：

signature: Oil2Qv4rKWTwlDwVA39b4mGqRX8kBY3kWtJhUHQnrGvDR48Q8h/0VuQYkp+tz0q28XPKftUG8XUf4lkcGRkEfTn/E2P6pV7HeVvmLzMkpp2na8NnViflTWZCf9jF0xZI6cLXCdd8cJZZKhJkxbGp6l6V3cxU6Dl/pCSVNM2Ys9q618516Ynd4mGI4KPW/pmsLJiGuWFT8M8LwEZEM4ZkM+EofXDWVCoNjhMiIZeCdN0V49plKJfkmJYKM5n3IAZ1BwMiivM6FQygF5/MtgZ5MlEq+qFTw/13EVYC9X2PuwRi/BKyItHQanCP4LuCzM9Pnl/4KLJ3HG2Z675qjqreIA==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T07:02:16.596+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": {
            "externalOrderNo": "EXT_ORDER_20250908150138",
            "orderNo": "10820250908000014097",
            "orderStatus": "01",
            "merchantNo": "********"
        }
    }
}

2.3 拉起支付收银台

介绍：拉起支付收银台

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值：1.0.0
language	String	否	语言	语言（zh_CN，zh_TW，en_US）默认取值：zh_CN
interfaceName	String	是	接口名称	填写：`pullPayment`
businessType	String	是	业务类型	填写：`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围：RSA-SHA256，ECDSA-SHA256，HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号
productNo	String	是	产品编号	参考附录-枚举字典 1. 产品编码

Object

是

商户信息对象

order

字段名	类型	是否必传	字段名称	说明
externalOrderNo	String	否	商户订单号	与 orderNo 二选一
orderNo	String	否	平台订单号	二者都传时 orderNo优先于externalOrderNo

Object

是

订单信息对象

transaction

字段名	类型	是否必传	字段名称	说明
merchantSerialNo	String	是	商户交易流水号
externalAdditionalData	String	否	交易附加数据
returnUrl	String	是	收银台重定向地址	支付成功后，支付网关跳回商户的地址
notifyUrl	String	是	支付结果通知地址	支付成功后，后台通知商户支付结果的地址。如使用cnp系统的3ds功能，需上送以通知交易结果。

Object

是

交易信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: pullPayment' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: IyYBGmF4U9TCTiQmuja1pkIsjyJkLgF2W4Rvb1U3oSC0xABFlNalEstq7yYOqCujCPjrB5XbMTbY01OaOBTtsypX+8IhqDtbBpDwWU8l38Pe5bUR46xL3Bm1T+OyX+EjEhvSNFsL7NBtHmLEG3iUdTgjM3iNPYRCehQV7pTb+f+mO5yrmpX/i+6v8EBhT5olE3i9bOCOIy3n6S0j26MSYPgpoA/0LioVkCjjVo2J+BCY51CxyMpKNjAQ7HXNbW1rDJcswlfwjfaXZE1W66wVPgc/88ohRfQ9FvhEtPZkBD/LvNQ3v7WLZQktkylIikSA4TDomCS7qqm8T/JW3ioEVQ==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908070333042_25",
    "requestTime":"2025-09-08T07:03:33.042+08:00",
    "nonceStr":"HyuTIa6VT0PfcVGLaKf1LGO8DHz58hUA",
    "data":{
        "merchant":{
            "merchantNo":"*********"
        },
        "order":{
            "externalOrderNo":"EXT_ORDER_20250908150138",
            "orderNo": "10820250908000014097"

        },
        "transaction":{
            "merchantSerialNo":"4416409948944886",
            "returnUrl":"https://www.baidu.com/",
            "notifyUrl":"https://example.com/notify"
        }

    }
}'

响应参数

字段名

类型

是否必返

字段名称

说明

transaction

字段名	类型	是否必返	字段名称	说明
merchantNo	String	是	商户号
productNo	String	是	产品编号
externalOrderNo	String	是	商户订单号
orderNo	String	是	平台订单号
merchantSerialNo	String	是	商户交易流水号
transactionNo	String	是	平台交易流水号	系统生成
transactionTime	String	是	交易发起时间
status	String	是	交易状态	参考附录-枚举字典 11. 交易状态
cashUrl	String	是	收银台地址
externalAdditionalData	String	否	交易附加数据

Object

是

交易信息对象

响应Headers数据示例：

signature: kNG/8hcqaVIzeqhufxpI7P1phMaDyipFmi7hjp1E/dRI/YxxJuE67t7YfLcD+Nvour2UyexsvtGCefAXuVZgQnHDGCr7XHmJDzkuxe1YD6KI6O8ILgF3FOqawZKBUkCQGl/XwYscuTWeJVh4PD0oRf3LDiAmaNG/V2t+r5a308/usJOzK45Zf/dHfxylXKCindvQ7OAVSmvSElB0o7s0gh5DsYLzy1ZOI9BdVlIWHOGUiJYZlmV+8hF5zhGrOplGZTCDedIhQQO+g/whqpZv0icmTWcfHyyF9S6mOaPV87V+xCVR1e0JBdix7F8Arn0I8wmveYW0EPDLakhh/M9kAQ==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T07:03:34.833+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "transaction": {
            "merchantNo": "4344000047",
            "productNo": "C202",
            "merchantSerialNo": "4416409948944886",
            "amount": 10.00,
            "transactionNo": "TKF6406BAB8900000914193615962112",
            "orderNo": "10820250908000014097",
            "externalOrderNo": "EXT_ORDER_20250908150138",
            "currency": "USD",
            "status": "11",
            "transactionTime": "2025-09-08T07:03:33.362+00:00",
            "cashUrl": "https://payment-cnp-test.cogolinks.com/cnp/cashier?amount=10.00&orderNo=10820250908000014097&orgNo=S20250325000001&merchantNameEn=Resto+test+merchants&merchantNameCn=Resto%E5%AF%B9%E6%8E%A5%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7&transactionNo=TKF6406BAB8900000914193615962112&merchantNo=4344000047&token=ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnZjbWRPYnlJNklsTXlNREkxTURNeU5UQXdNREF3TVNJc0luUnlZVzV6WVdOMGFXOXVUbThpT2lKVVMwWTJOREEyUWtGQ09Ea3dNREF3TURreE5ERTVNell4TlRrMk1qRXhNaUlzSW0xbGNtTm9ZVzUwVG04aU9pSTBNelEwTURBd01EUTNJbjAuMmNNWEFlbjFYZFlCbS1WcTV1bF9VYVNDWkxLOXRMNjBySVYtLUwxak5hUQ%253D%253D"
        }
    }
}

2.4 订单查询

介绍：查询订单及其关联交易

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值:1.0.0
language	String	否	语言	语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceName	String	是	接口名称	填写:`queryOrder`
businessType	String	是	业务类型	填写:`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法	取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号

Object

是

商户信息对象

order

字段名	类型	是否必传	字段名称	说明
externalOrderNo	String	否	商户订单号	与orderNo 二选一
orderNo	String	否	平台订单号	二者都传时 orderNo优先于externalOrderNo

Object

是

订单信息对象

Curl请求示例

curl --location --request POST 'https:///${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: queryOrder' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: GsRVAfmJo8WhlcFMxgG/Gcwq7hiGg8GpuCXV4SIzhTDO+3+X0b/5Y5sGUs29OT0E4NzAkMmcUVQwaEhKsTPLyBhFm8F29tYlqKlycLJBXWUVDnVeOBbQSBszXwC9xItwfdJ9/pH6SIVIqkTcQjZIuxzkQQ/Ka6zV3LaRxUtK7s6899PMOMgJqwp1oNzVMftfN6wAzx0cAlIeJStjnKBTMEuPsFLV2g29n7w/TcEiwqCISr/CHSuD7WIbUtZf5ti8a6hO/B7xB45PL1GVVoZ72Co9j6HXnJmQMBkiEs6C02zlJZeTH5HXhKHp1f26QKnMB1MVSzBNj9YJ55Khi+gujQ==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908070525953_3e",
    "requestTime":"2025-09-08T07:05:25.953+08:00",
    "nonceStr":"lZJEDUYuYx32Paue1yKnVwvbs4Yzb3QV",
    "data":{
        "merchant":{
            "merchantNo":"********"
        },
        "order":{
            "externalOrderNo":"EXT_ORDER_20250828102026",
            "orderNo":"10820250908000014097"
        }
    }
}'

响应参数

字段名

类型

是否必返

字段名称

说明

order

字段名

类型

是否必返

字段名称

说明

productNo

String

是

产品编号

merchantNo

String

是

商户号

externalOrderNo

String

是

商户订单号

业务方订单号

orderNo

String

是

platform订单号

currency

String

是

订单币种

amount

String

是

订单交易金额

refundedAmount

number

是

订单退款金额

orderStatus

String

是

订单状态

参考附录-枚举字典订单状态

orderTime

String

是

下单时间

orderSource

String

是

订单来源

01：设备下单（无人售货柜、充电桩），02：云下单（Saas厂商）

paymentType

String

是

付款类型

参考附录-枚举字典 6. 支付类型

orderZoneId

String

是

交易所在地时区

商户时区/下单时区,例如 Asia/Hong_Kong

language

String

否

网站语言

String

否

电子邮件

webSite

String

否

所属网站

orderTitle

String

否

订单标题

orderDetails

String

否

订单描述

externalAdditionalData

String

否

外部附加数据

goodsDetails

字段名	类型	是否必返	字段名称	说明
sku	String	否	商品编号
productName	String	否	商品名称
price	Number	否	商品单价	单位：元
quantity	Number	否	商品数量
productImage	String	否	商品图片URL
productUrl	String	否	商品链接URL

Array

否

商品信息列表

shippingAddress

字段名	类型	是否必返	字段名称
shippingFirstName	String	否	名字
shippingLastName	String	否	姓氏
shippingAddress1	String	否	地址1
shippingAddress2	String	否	地址2
shippingCity	String	否	城市
shippingState	String	否	州/省
shippingCountry	String	否	国家
shippingZipCode	String	否	邮编
shippingPhone	String	否	电话

Object

否

收货地址信息

billingAddress

字段名	类型	是否必返	字段名称
billingFirstName	String	否	名字
billingLastName	String	否	姓氏
billingAddress1	String	否	地址1
billingAddress2	String	否	地址2
billingCity	String	否	城市
billingState	String	否	州/省
billingCountry	String	否	国家
billingZipCode	String	否	邮编
billingPhone	String	否	电话

Object

否

账单地址信息

Object

是

订单信息对象

transaction

字段名	类型	是否必返	字段名称	说明
transactionNo	String	是	platform交易流水号
merchantSerialNo	String	是	商户交易流水号
transactionType	String	是	交易类型	参考附录-枚举字典 3. 交易类型
currency	String	是	交易币种
amount	Number	是	交易金额
transactionTime	String	是	交易发起时间
completionTime	String	否	交易完成时间
status	String	是	交易状态	参考附录-枚举字典 11. 交易状态
originalTransactionNo	String	否	原平台交易流水号

Array

是

交易信息列表

一个订单可能存在多笔交易记录

响应Headers数据示例：

signature: phdKQ6eySKqloGtOvu9vOO4coQUzdimMKLl9BH433Gh0VlLWiF98c6jAY50EHvD+4vjIk/31sTKzK74EHrbc/Xr9AslJ8KgLu+bx4oZKqAla8dE+wzCdkwXR9nq5EffUY6u/bxIYCjK93NMsHOFxrWrTYgMaolWYOCYWxRBNHAK2TnxUHg0hSNybiRwvv5Ouw8y+RFn0f2OO5eQoyJzRzaza13jUmWr5K3qQzgRQUYH5iiolwAHNAf11aoGkgiHdkEfQ5dPfH0en/TGOEh8PKqMsdz4SoNS4/JcC/j5KLniKiFQucyYVxdD0iB+pnFZygx3rtgltZoBdk9zfXZ3nhA==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T07:05:25.662+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": {
            "externalOrderNo": "EXT_ORDER_20250908150138",
            "orderNo": "10820250908000014097",
            "amount": "10.00",
            "currency": "USD",
            "orderTime": "2025-09-08T15:01:39.000+00:00",
            "email": "gw816@163.com",
            "goodsDetails": [
                {
                    "sku": "123456",
                    "productName": "测试产品名11213123",
                    "price": 500,
                    "quantity": 2,
                    "productImage": "",
                    "productUrl": ""
                }
            ],
            "shippingAddress": {
                "shippingFirstName": "Peter 三1123",
                "shippingLastName": "zh张",
                "shippingAddress1": "广东省广州市测试 测试 测试测试 测试 测试*",
                "shippingAddress2": "广东省广州市测试 Another",
                "shippingCity": "New York",
                "shippingState": "NY",
                "shippingCountry": "US",
                "shippingZipCode": "10001",
                "shippingPhone": "1231230080"
            },
            "billingAddress": {
                "billingFirstName": "John123123",
                "billingLastName": "Doe",
                "billingAddress1": "456 Oak St",
                "billingAddress2": null,
                "billingCity": "Los Angeles",
                "billingState": "CA",
                "billingCountry": "US",
                "billingZipCode": "90001",
                "billingPhone": "987-654-3210"
            },
            "externalAdditionalData": "{}",
            "merchantNo": "4344000047",
            "productNo": "C202",
            "orderZoneId": "Asia/Hong_Kong",
            "paymentType": "01",
            "orderSource": "02",
            "refundedAmount": 0.00,
            "orderStatus": "01",
            "language": "zh",
            "webSite": "www.baidu.com"
        },
        "transaction": [
            {
                "transactionNo": "TKF6406BAB8900000914193615962112",
                "amount": 10.00,
                "currency": "USD",
                "transactionType": "01",
                "status": "21",
                "transactionTime": "2025-09-08T07:03:33.000+00:00",
                "completionTime": "2025-09-08T07:05:08.000+00:00",
                "merchantSerialNo": "4416409948944886"
            }
        ]
    }
}

2.5 交易查询

介绍：交易查询

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值:1.0.0
language	String	否	语言	语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceName	String	是	接口名称	填写:`queryTransaction`
businessType	String	是	业务类型	填写:`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法	取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号

Object

是

商户信息对象

order

字段名	类型	是否必传	字段名称	说明
externalOrderNo	String	否	商户订单号
orderNo	String	否	平台订单号

Object

否

订单信息对象

transaction

字段名	类型	是否必传	字段名称	说明
transactionNo	String	否	平台交易流水号
merchantSerialNo	String	否	商户交易流水号

Object

是

交易信息对象

Curl请求示例

curl --location --request POST 'https:/${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: queryTransaction' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: exJt04QK0IzkWQVZTSaO3rfIGj8QbWyxzdTioaAIG+hvZ3CJnbxmkOqhSof8JUF9KWvoH04SpJxX5I/FzBjBQdkaPacjsudizNI1vcEmCyu8uO9fP7YxnXlMpW8tlGIdoi5M9RvigilE6JONqlB9Ft8UgDLCvFBOEBYZleaPTqB93IsJBOzeAv/pyGJ6Ky+QiCw1nirvYKTXVEqAaqL7JLV+1e8o3ho+UCmS3WokzDtDxsAgN+zqaeBiosD8jzEJfXyN7El44t2fVo3aqnhehtUniUvfPTCtz5eOoZyiwliQ4KslcFwe6xIdY4LX4mfVqW/ehXzbw0LiK/sKWR6USw==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908093146773_7d",
    "requestTime":"2025-09-08T09:31:46.773+08:00",
    "nonceStr":"PvFswQU8mleg9jJ842LAN3RUlF6eVf2i",
    "data": {
        "merchant": {
            "merchantNo": "4344000047"
        },
        "order": {
            "externalOrderNo": "EXT_ORDER_20250825141641",
            "orderNo": "10820250828000013314"
        },
        "transaction":{
            "transactionNo": "TKF6406BAB8900000914193615962112",
            "merchantSerialNo":null
        }

    }
}'

响应参数

字段名

类型

是否必传

字段名称

说明

transaction

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号
orderNo	String	是	平台订单号
externalOrderNo	String	是	商户订单号
merchantSerialNo	String	是	商户交易流水号
transactionNo	String	是	平台交易流水号
fundAgreementNo	String	是	资金入账协议编号
status	String	是	交易状态	参考附录-枚举字典 11. 交易状态
transactionType	String	是	交易类型	参考附录-枚举字典 3. 交易类型
paymentWay	String	是	支付方式	参考附录-枚举字典 5. 支付方式
paymentType	String	否	付款类型	参考附录-枚举字典 6. 支付类型
paymentSubtype	String	否	支付子类型	参考附录-枚举字典 7. 支付子类型
cardHolerMask	String	否	持卡人	持卡人掩码
cardNoMask	String	否	卡号	卡号掩码
cardType	String	否	卡类型
cardFlag	String	否	卡标志
cardBrand	String	否	卡组织
transactionTime	String	是	交易发起时间
completionTime	String	否	交易完成时间
transactionZoneId	String	是	交易时区
currency	String	是	交易币种
amount	Number	是	交易金额
refundAmount	Number	是	交易退款金额
localCurrency	String	是	本地交易币种
localTranAmount	Number	是	本地交易金额
localPayeeFee	Number	否	本地收款方服务费(扣)
localPayeeRefundFee	Number	否	本地收款方服务费(返)
marginAmount	Number	否	保证金金额
pendingSettlementAmount	Number	否	结算资金
localRefundAmount	Number	是	本地交易退款金额
localPayeeRefundTotalFee	Number	否	本地收款方服务费(扣)退款金额
externalAdditionalData	String	否	外部附加数据
originalTransactionNo	String	否	原平台交易流水号	若为退款/撤销，指向原始交易号

Object

是

交易信息对象

响应Headers数据示例：

signature: phdKQ6eySKqloGtOvu9vOO4coQUzdimMKLl9BH433Gh0VlLWiF98c6jAY50EHvD+4vjIk/31sTKzK74EHrbc/Xr9AslJ8KgLu+bx4oZKqAla8dE+wzCdkwXR9nq5EffUY6u/bxIYCjK93NMsHOFxrWrTYgMaolWYOCYWxRBNHAK2TnxUHg0hSNybiRwvv5Ouw8y+RFn0f2OO5eQoyJzRzaza13jUmWr5K3qQzgRQUYH5iiolwAHNAf11aoGkgiHdkEfQ5dPfH0en/TGOEh8PKqMsdz4SoNS4/JcC/j5KLniKiFQucyYVxdD0iB+pnFZygx3rtgltZoBdk9zfXZ3nhA==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T11:17:54.522+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": null,
        "transaction": {
            "transactionNo": "TK71E220C4AC00000914500127899648",
            "orderNo": "10820250908000014135",
            "externalOrderNo": "EXT_ORDER_20250908190506",
            "amount": 10.00,
            "refundAmount": 0.00,
            "currency": "USD",
            "transactionType": "01",
            "paymentWay": "02",
            "status": "00",
            "transactionTime": "2025-09-08T11:05:27.000+00:00",
            "transactionZoneId": "Asia/Hong_Kong",
            "completionTime": "2025-09-08T11:06:05.000+00:00",
            "paymentType": "01",
            "paymentSubtype": "04",
            "cardBrand": "01",
            "merchantSerialNo": "4416409948944886",
            "merchantNo": "4344000047",
            "cardNoMask": "401200****1112",
            "cardHolerMask": "Pe**er",
            "localCurrency": "HKD",
            "localTranAmount": 77.70,
            "localRefundAmount": 0.00,
            "marginAmount": 0.00,
            "pendingSettlementAmount": 0.00
        }
    }
}

2.6 关闭订单

介绍：只有未发生交易时才可以调用关单

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值:1.0.0
language	String	否	语言	语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceName	String	是	接口名称	填写:`close`
businessType	String	是	业务类型	填写:`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法	取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号

Object

是

商户信息对象

order

字段名	类型	是否必传	字段名称	说明
externalOrderNo	String	否	商户订单号	与orderNo二选一
orderNo	String	否	平台订单号	二者都传时 orderNo优先于externalOrderNo

Object

否

订单信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: close' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: f0AjyyZkUvUDtHs28UnQ6RovLNC0anzty6TMOqU6v3wBdyJNejAcy+u0pfTxL3WmtIx0OwtduLpxIrxtHIFgON0pMI1UpNOaskDZJIfi7e8C2O3s24hKxA7OKKWtgz2cHwMgrGtrHeCaJxFRxqrxLewtHfML8B+HYRYKltyAfoOLvpP1xpNXgctwhxGDhRSyC5GgJAiIIckVehoiIrlj3KZCqnFatG2E9LfKxWpL8E0cCVi2pzbb66rXsS+C/cCd8EAQioUt4MzTwPlivenpe8rdVw+NJjY8CR2FeJzckF5SKIyXkEjAGC0dM2TR/3TI/MOJ0fHEBPW+d1CzpHpkVA==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250908112410235_02",
    "requestTime":"2025-09-08T11:24:10.235+08:00",
    "nonceStr":"cJm5v6IMUeXJwFd7r9y6UYfLhn7uQJVB",
    "data":{
        "merchant":{
            "merchantNo":"********"
        },
        "order":{
            "externalOrderNo":"EXT_ORDER_20250826162403",
            "orderNo": "10820250908000014136"
        }
    }
}'

响应参数

字段名

类型

是否必传

字段名称

说明

order

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户编号
orderNo	String	是	平台订单号
externalOrderNo	String	是	商户订单号
orderStatus	String	是	订单状态	参考附录-枚举字典订单状态

Object

是

订单信息

响应Headers数据示例：

signature: phdKQ6eySKqloGtOvu9vOO4coQUzdimMKLl9BH433Gh0VlLWiF98c6jAY50EHvD+4vjIk/31sTKzK74EHrbc/Xr9AslJ8KgLu+bx4oZKqAla8dE+wzCdkwXR9nq5EffUY6u/bxIYCjK93NMsHOFxrWrTYgMaolWYOCYWxRBNHAK2TnxUHg0hSNybiRwvv5Ouw8y+RFn0f2OO5eQoyJzRzaza13jUmWr5K3qQzgRQUYH5iiolwAHNAf11aoGkgiHdkEfQ5dPfH0en/TGOEh8PKqMsdz4SoNS4/JcC/j5KLniKiFQucyYVxdD0iB+pnFZygx3rtgltZoBdk9zfXZ3nhA==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-08T11:24:14.174+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": {
            "externalOrderNo": "EXT_ORDER_20250908192334",
            "orderNo": "10820250908000014136",
            "orderStatus": "06",
            "merchantNo": "4344000047"
        }
    }
}

2.7 退款

介绍：退款

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值:1.0.0
language	String	否	语言	语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceName	String	是	接口名称	填写:`refund`
businessType	String	是	业务类型	填写:`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
merchantNo	String	是	商户号

Object

是

商户信息对象

transaction

字段名	类型	是否必传	字段名称	说明
transactionNo	String	是	原平台交易流水号	原交易单号
merchantSerialNo	String	是	商户交易流水号	商户退款交易流水号
amount	Number	是	交易金额	退款金额同原交易币种
notifyUrl	String	否	异步通知地址	退款结果通知地址
externalAdditionalData	String	否	外部附加信息

Object

是

交易信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: refund' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: b/K1jJDzsCrKggZHxK2iJt6CdCrRjOxCPRlqfP+eLL58FG31/NWY+TbmCamD8YrJ+RipFQ8NttAL3mn8CK/s+uWUI0MpyCNmvA9KVUgOw+LGW7lcwztWSD2rDG2mD/lUx9++4NGIUP5eYk6Rd7Pojgn+2NWShR8bbLXQ2GuaZhhJv0UuUPEXTqKTOIKCLlML+x9t2xaGKRbuyzw7vhLtoT3GVu1XO1cbmAm69uyCshaVXuOQyl1W3Td7+VTPgoN880/1f+4WR1TKFU68OCyjwprM8cyrDU9fwlAjbTgdUAV+ApmzB6EHWjBJvjvKUJjvqkDq1ldeE7yDWJN1DQy/fg==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: 129.226.223.13' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250909110755073_96",
    "requestTime":"2025-09-09T11:07:55.073+08:00",
    "nonceStr":"Twj5TX8Gy3tr5BgXw0ueLoZfnriRvAHi",
    "data":{
        "merchant": {
            "merchantNo": "********"
        },
        "transaction": {
            "transactionNo": "TK5970A4B16B00000914620757721088",
            "merchantSerialNo": "MERCHANT_SERIAL_20250901155945",
            "amount": 2.00,
            "notifyUrl": "https://example.com/notify"
        }
    }
}'

响应参数

字段名

类型

是否必传

字段名称

说明

transaction

字段名	类型	是否必传	字段名称	说明
merchantNo	string	是	商户号
originalTransactionNo	string	否	原平台交易流水号	关联的原交易单号
merchantSerialNo	string	是	商户交易流水号
transactionNo	string	是	平台交易流水号
externalOrderNo	String	是	商户订单号
orderNo	string	是	平台订单号
currency	string	是	交易币种	原始交易币种
amount	number	是	交易金额
localCurrency	String	是	本地币种
localTranAmount	Number	是	本地交易金额
localPayeeFee	Number	否	本地收款方服务费(扣)
localPayeeRefundFee	Number	否	本地收款方服务费(返)
status	string	是	交易状态	参考附录-枚举字典 11. 交易状态
transactionTime	string	是	交易发起时间
completionTime	string	是	交易完成时间
transactionType	string	是	交易类型	参考附录-枚举字典 3. 交易类型
paymentWay	string	是	支付方式	参考附录-枚举字典 5. 支付方式
transactionZoneId	string	是	交易时区	时区 ID（如 Asia/Hong_Kong）
fundAgreementNo	String	否	资金入账协议编号
externalAdditionalData	string	否	外部附加数据

object

是

交易信息对象

响应Headers数据示例：

signature: phdKQ6eySKqloGtOvu9vOO4coQUzdimMKLl9BH433Gh0VlLWiF98c6jAY50EHvD+4vjIk/31sTKzK74EHrbc/Xr9AslJ8KgLu+bx4oZKqAla8dE+wzCdkwXR9nq5EffUY6u/bxIYCjK93NMsHOFxrWrTYgMaolWYOCYWxRBNHAK2TnxUHg0hSNybiRwvv5Ouw8y+RFn0f2OO5eQoyJzRzaza13jUmWr5K3qQzgRQUYH5iiolwAHNAf11aoGkgiHdkEfQ5dPfH0en/TGOEh8PKqMsdz4SoNS4/JcC/j5KLniKiFQucyYVxdD0iB+pnFZygx3rtgltZoBdk9zfXZ3nhA==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-01T08:00:24.140+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "transaction": {
            "merchantNo": "1344000007",
            "merchantSerialNo": "MERCHANT_SERIAL_20250901155945",
            "amount": 1.00,
            "transactionNo": "TK7BC28F9A2300000912037006704640",
            "originalTransactionNo": "TK756A7B381E00000912023013048320",
            "orderNo": "10820250901000003606",
            "refundAmount": 0.00,
            "tipAmount": 0.00,
            "refundTipAmount": 0.00,
            "currency": "SGD",
            "localTranAmount": 6.05,
            "localRefundAmount": 0.00,
            "localTipAmount": 0.00,
            "localRefundTipAmount": 0.00,
            "localCurrency": "HKD",
            "transactionType": "08",
            "paymentWay": "02",
            "status": "00",
            "responseCode": "200",
            "transactionTime": "2025-09-01T08:00:22.000+00:00",
            "transactionZoneUTCTime": "2025-09-01T16:00:22.000+08:00",
            "transactionZoneId": "Asia/Hong_Kong",
            "timeZoneFlag": 0,
            "completionTime": "2025-09-01T08:00:24.000+00:00",
            "cardNoDigest": "b20d173ea33f6410da288ce12bfabb0aff83a88ab6a3e5937c7ae7e367076e8a"
        }
    }
}

2.8 下单并支付

介绍：用于下单并支付,改场景下收银台页面和功能由商户提供

接口地址: /saas/cnp

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值:1.0.0
language	String	否	语言	语言(zh_CN,zh_TW,en_US)默认取值:zh_CN
interfaceName	String	是	接口名称	填写:`orderAndSale`
businessType	String	是	业务类型	填写:`cnp`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围:RSA-SHA256,ECDSA-SHA256,HMAC-SHA256

请求参数

字段名

类型

是否必传

字段名称

说明

merchant

字段名	类型	是否必传	字段名称	说明
productNo	String	是	产品编号	参考附录-枚举字典 1. 产品编码 ; cnp场景目前固定 C202
merchantNo	String	是	商户号

Object

是

商户信息对象

order

字段名

类型

是否必传

字段名称

说明

externalOrderNo

String

是

商户订单号

业务方订单号/外部订单号

currency

String

是

订单币种

参考附录-枚举字典 12. 币种

amount

String

是

订单交易金额

String

是

付款人电子邮箱

webSite

String

是

所属网站

下单来源网站

language

String

是

网站语言

参考附录-枚举字典 16. 语言例：zh ,注意:不能使用zh_CN

orderTitle

String

否

订单标题

orderDetails

String

否

订单描述

如“饼干一包，水果一袋”

externalAdditionalData

String

否

订单附加数据

jsonStr 格式

goodsDetails

字段名	类型	是否必传	字段名称
sku	String	是	商品编号
productName	String	是	商品名称
price	Number	是	商品单价
quantity	Number	是	商品购买数量
productImage	String	否	商品图片URL
productUrl	String	否	商品链接URL

Array

否

商品信息列表

shippingAddress

字段名	类型	是否必传	字段名称	说明
shippingFirstName	String	是	名字
shippingLastName	String	是	姓氏
shippingAddress1	String	是	地址1
shippingAddress2	String	否	地址2
shippingCity	String	是	城市
shippingState	String	是	州/省
shippingCountry	String	是	国家代码	参考附录-枚举字典 15. 国别列表,两位代码
shippingZipCode	String	是	邮编
shippingPhone	String	是	电话

Object

是

收货地址对象

billingAddress

字段名	类型	是否必传	字段名称	说明
billingFirstName	String	是	名字
billingLastName	String	是	姓氏
billingAddress1	String	是	地址1	使用dm/3ds则必填。为避免交易失败，中文地址建议翻译为英文地址
billingAddress2	String	否	地址2
billingCity	String	是	城市
billingState	String	是	州/省
billingCountry	String	是	国家代码	参考附录-枚举字典 15. 国别列表两位代码
billingZipCode	String	是	邮编
billingPhone	String	是	电话

Object

是

账单地址对象

Object

是

订单信息对象

transaction

字段名

类型

是否必传

字段名称

说明

merchantSerialNo

String

是

商户交易流水号

amount

String

是

交易金额

paymentSubType

String

是

支付子类型

参考附录-枚举字典 7. 支付子类型

returnUrl

String

否

返回地址

支付完成后跳转地址

notifyUrl

String

否

异步通知地址

cnpPayEnvironment

字段名	类型	是否必传	字段名称	说明
userAgent	String	是	持卡人浏览器UserAgent	例：360Browser
ipAddress	String	是	持卡人 IP地址
panIsPaste	String	否	卡号是否粘贴	0：否；1：是
timeZone	Number	否	持卡人时区	偏移量例：8
acceptLanguage	String	否	持卡人浏览器请求语言	例：zh_CN
domain	String	否	支付网站域名
screenWidth	Number	否	持卡人屏幕宽度	px
screenHeight	Number	否	卡人屏幕高度	px

Object

是

支付环境信息

CNP 支付安全相关参数

cnpPayInfoVo

字段名	类型	是否必传	字段名称	说明
cardHolder	String	是	持卡人姓名
acctNo	String	是	卡号
expiryMonth	String	是	卡片到期月份	MM
expiryYear	String	是	卡片到期年份	YYYY
acctCvv	String	是	CVV 安全码	卡背面三位
tavv	String	否	3DS 交易认证值	token化卡号场景时,使用tavv 代替 acctCvv

Object

是

支付卡信息

Object

是

交易信息对象

Curl请求示例

curl --location --request POST 'https://${PAYMENT_DOMAIN}/saas/cnp' \
--header 'businesstype: cnp' \
--header 'interfacename: orderAndSale' \
--header 'interfaceversion: 1.0.0' \
--header 'language: zh_CN' \
--header 'signature: CHIeX4tJsmeZQEyVJkAOSfIq3oQQa4Qdr/9hS6Sy5ldSzP6EOPJXQl3qKf1XqAsW1BnqP1DAXpxoGYZosP38TvMZT53NK08rqs6w3jmL1gZ50yrEwVa6WWPrOZgwhIAcIli3IjjRLyi2lfnsfAwl4iL2/9GFRHPxd3upgM1JAL/2FwcCTUWmES99vqGe5drRP8q9iDh9hMjSSFkh834crn46S7qLZNhAE+cRh1dcKC48KbxpAhEL0gaUYrNLVeWynroIQkg6b0gk+JBjL8H9TmxzlToggPG+Mhqlvf7iZvysxtLHrZWamo4mIu3LPwKplaCp6kiDoLji0ve451x7CQ==' \
--header 'signmethod: RSA-SHA256' \
--header 'orgcertid: CFA36DA2E064916D6C5DE607EC6DCF1B2A58AD13' \
--header 'orgno: S20250325000001' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{
    "requestId":"S20250325000001_20250922092658036_8e",
    "requestTime":"2025-09-22T09:26:58.036+08:00",
    "nonceStr":"loPzrVKdURVrSnIhP4tSEXOkNCI8UjeK",
    "data":{
        "merchant":{
            "merchantNo":"********",
            "productNo" : "C202"
        },
        "order":{
            "externalOrderNo":"EXT_ORDER_20250922172658",
            "amount":"10",
            "currency":"USD",
            "language":"zh",
            "email":"gw816@163.com",
            "webSite":"www.baidu.com",
            "orderTitle":"订单title",
            "orderDetails":"一袋饼干",
            "externalAdditionalData":"{}",
            "goodsDetails":[{
                "sku":"123456",
                "productName":"测试产品名",
                "price":500,
                "quantity":2,
                "productImage":"",
                "productUrl":""
            }],
            "shippingAddress":{
                "shippingFirstName": "Peter 三",
                "shippingLastName": "zh张",
                "shippingAddress1": "广东省广州市测试 测试 测试测试 测试 测试*",
                "shippingAddress2": "广东省广州市测试 Another",
                "shippingCity": "New York",
                "shippingState": "NY",
                "shippingCountry": "CN",
                "shippingZipCode": "10001",
                "shippingPhone": "1231230080"
            },
            "billingAddress":{
                "billingFirstName": "John",
                "billingLastName": "Doe",
                "billingAddress1": "456 Oak St",
                "billingAddress2": null,
                "billingCity": "Los Angeles",
                "billingState": "CA",
                "billingCountry": "CN",
                "billingZipCode": "90001",
                "billingPhone": "987-654-3210"
            }
        },
        "transaction":{
            "merchantSerialNo":"test0009",
            "returnUrl":"https://www.baidu.com/",
            "notifyUrl":"https://webhook.site/1acb9fc2-11ae-4db8-bbbc-6858f35e87ec",
            "amount":"10",
            "paymentSubType":"04",
            "cnpPayEnvironment":{
                "userAgent":"360Brower",
                "ipAddress":"127.0.0.1",
                "panIsPaste":"0",
                "timeZone":8,
                "acceptLanguage":"zh_CN",
                "domain":"https://payment-cnp-test.cogolinks.com",
                "screenWidth":1029,
                "screenHeight":1646
            },
            "cnpPayInfoVo":{
                "cardHolder":"Peter",
                "acctNo":"4012001037141112",
                "expiryMonth":"12",
                "expiryYear":"2027",
                "acctCvv":"212",
                "tavv":""
            }
        }
    }
     
}'

响应参数

字段名

类型

是否必返

字段名称

说明

transaction

字段名	类型	是否必返	字段名称	说明
merchantNo	String	是	商户号
productNo	String	是	产品编号
externalOrderNo	String	是	商户订单号
orderNo	String	是	平台订单号
merchantSerialNo	String	是	商户交易流水号
transactionNo	String	是	平台交易流水号	系统生成
transactionTime	String	是	交易发起时间
status	String	是	交易状态	参考附录-枚举字典 11. 交易状态
cashUrl	String	是	收银台地址
externalAdditionalData	String	否	交易附加数据

Object

是

交易信息对象

响应Headers数据示例：

signature: idCYp8R2h4TPiLLN+E+K3F9uKwScaJjlAUwxut8PwEh4EfHn526IPZuw1MITfEmsQA06sNYrr5hI7dsaBJrBWLV8UFWKfuSkg2aPn94THa3TD/NZt5r7NxGYVAT2IGmw2q+h+z5hFQSBRENsz1r1GIhtQogaH2klN5m5XQNgJlHuGoMNpbCY8MRtDhVjmILrXHb1SrqsMQKW74r4EbjwXi6ZTV4c/OnYIXemg6us8v3kw9h4pKKWPsZh+jP9Y7Xk51SUFxOemxMayrW1xoDuOzZt0W5jCaX07KDrn4CKkFx0IPCnxjiv5vfavONN3/kbt0BYzqLMnFzWTVgIoCWN0w==
orgCertId: ****************************************
signMethod: RSA-SHA256

响应Body数据示例

{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2025-09-22T09:26:55.913+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "transaction": {
            "merchantNo": "********",
            "merchantSerialNo": "test0009",
            "amount": 10.00,
            "transactionNo": "TK73975781C600000896906672095232",
            "orderNo": "10820250922000015181",
            "externalOrderNo": "EXT_ORDER_20250922172658",
            "currency": "USD",
            "status": "21",
            "checkPayUrl": "https://test.allinpayhk.com/pay-web-h5/cnp_pay/directCashier?accessCode=85200309&mchtId=852999999528599&accessOrderId=TK73975781C600000896906672095232&language=cn"
        }
    }
}

3.交易通知

3.1交易回调业务方

介绍：相关交易逻辑完成后给业务方推送最终交易结果通知。

通知参数

参考交易查询响应结果

Curl请求示例

curl --location '${SERVICE_NOTIFY_URL}' \
--header 'Content-Type: application/json' \
--header 'orgNo: S**************' \
--header 'orgCertId: ****************************************' \
--header 'signMethod: RSA-SHA256' \
--header 'signature: gmEnbXHetb0a+iwz2xJwgYXKHHwYd9Yy8fumDlzOevruscS6yawHjgxZGDhW24+hrJDIS2vwDF879dUOk/YL3kGvoUHXe52UM0y/81+JJ9PD2Ic0C8agBOmSXEiG9ROfOjRDmfxz/zYOHhWGBuN7VtNlKxUxopw8l57MR1ouSLt+g3XEEqpNTqMhB3njTZ5CXZ/XZj95dfZUkkXtXdC1mPOtSkE55gNxTSECcfKDT78gmBMcJEgBpZHoaStEt+KEe6TZ7avmBpP43pccKALWDDkjmiCdXqDxl9a3HOpWj5bx9RALg6GuCDheNBBy/D0CRsQeBEljmBKmHTr1/IVbkQ==' \
--data '{
    "requestId": null,
    "requestTime": null,
    "responseTime": "2026-02-06T07:07:49.584+00:00",
    "respCode": 200,
    "respMsg": "success",
    "busCode": null,
    "busMsg": null,
    "busSubCode": null,
    "busSubMsg": null,
    "data": {
        "order": {
            "externalOrderNo": "2019669270895788570",
            "orderNo": "10820260206000044885",
            "orderDetails": "尖沙咀店",
            "amount": "67.00",
            "authorizeAmount": null,
            "addAmount": null,
            "currency": null,
            "orderTime": "2026-02-06T15:07:32.610+00:00",
            "email": null,
            "goodsDetails": null,
            "shippingAddress": null,
            "billingAddress": null,
            "externalAdditionalData": "{\"corporationId\":440021082,\"shopId\":400412410,\"paymentId\":2019669270895788570}",
            "orderStatus": null
        },
        "transaction": {
            "transactionNo": "TKF935A1770500001125888174817280",
            "orderNo": "10820260206000044885",
            "externalOrderNo": "2019669270895788570",
            "amount": 67,
            "refundAmount": 0,
            "currency": "HKD",
            "transactionType": "01",
            "paymentWay": "02",
            "status": "00",
            "transactionTime": "2026-02-06T07:07:32.958+00:00",
            "transactionZoneId": "Asia/Hong_Kong",
            "completionTime": "2026-02-06T07:07:48.225+00:00",
            "paymentType": "02",
            "paymentSubtype": "05",
            "cardFlag": "01",
            "cardBrand": "02",
            "merchantSerialNo": "048d2d00207d49258892626605429c11",
            "returnUrl": "https://f5cr35nvpnut.m.sea.restosuite.ai/payStatus?tableId=2010584954987540489&shopId=400412410&bizType=1100&routeName=createOrder&type=1&orderId=2019669270807646394&transId=2019669270866366468",
            "cardNoMask": "543121****4860",
            "merchantNo": "1344000031",
            "cardHolerMask": "n**e",
            "localCurrency": "HKD",
            "localTranAmount": 67,
            "localPayeeFee": 2.5,
            "localPayeeRefundFee": 0,
            "localPayeeRefundTotalFee": 0,
            "localRefundAmount": 0,
            "marginAmount": 0,
            "pendingSettlementAmount": 0
        }
    }
}
}'

SaaS CNP交易接口文档

1. 简介

2.cnp接口

2.1 预下单

Header 参数

请求参数

响应参数

2.2 修改订单

Header 参数

请求参数

响应参数

2.3 拉起支付收银台

Header 参数

请求参数

响应参数

2.4 订单查询

Header 参数

请求参数

响应参数

2.5 交易查询

Header 参数

请求参数

响应参数

2.6 关闭订单

Header 参数

请求参数

响应参数

2.7 退款

Header 参数

请求参数

响应参数

2.8 下单并支付

Header 参数

请求参数

响应参数

3.交易通知

3.1交易回调业务方

通知参数

1. 简介​

2.cnp接口​

2.1 预下单​

Header 参数​

请求参数​

响应参数​

2.2 修改订单​

Header 参数​

请求参数​

响应参数​

2.3 拉起支付收银台​

Header 参数​

请求参数​

响应参数​

2.4 订单查询​

Header 参数​

请求参数​

响应参数​

2.5 交易查询​

Header 参数​

请求参数​

响应参数​

2.6 关闭订单​

Header 参数​

请求参数​

响应参数​

2.7 退款​

Header 参数​

请求参数​

响应参数​

2.8 下单并支付​

Header 参数​

请求参数​

响应参数​

3.交易通知​

3.1交易回调业务方​

通知参数​

1. 简介

2.cnp接口

2.1 预下单

Header 参数

请求参数

响应参数

2.2 修改订单

Header 参数

请求参数

响应参数

2.3 拉起支付收银台

Header 参数

请求参数

响应参数

2.4 订单查询

Header 参数

请求参数

响应参数

2.5 交易查询

Header 参数

请求参数

响应参数

2.6 关闭订单

Header 参数

请求参数

响应参数

2.7 退款

Header 参数

请求参数

响应参数

2.8 下单并支付

Header 参数

请求参数

响应参数

3.交易通知

3.1交易回调业务方

通知参数