SnapPay开放服务OpenAPI

API Endpoint

接口规则

1. 协议规则

商户接入开放服务网关，调用API必须遵循以下规则：

规则 说明
传输方式 为保证交易安全性，正式环境采用HTTPS传输
提交方式 采用POST方法提交
数据格式 除部分文件上传下载接口外，请求和返回数据均为JSON格式，Content-Type:application/json
字符编码 统一采用UTF-8字符编码
签名算法 MD5/RSA 签名方式
签名要求 请求返回及异步通知都需要校验签名，详细签名方法请参考签名规范
判断逻辑 先判断协议字段(HTTP状态码)返回，再判断报文返回码，最后判断交易状态
语言支持 Accept-Language：客户端可接受语言，如：en-US,zh-CN等，目前中文，英文，该值通过http header进行传递

2. 服务地址

环境 接口服务地址
正式环境 https://open.snappay.ca/api/gateway

正式环境的调试参数

商户模式接入：
商户号：901800000116
APPID：9f00cd9a873c511e
签名密钥：7e2083699dd510575faa1c72f9e35d43   （MD5方式）

3. 参数规定

必要性

  • M - 必选参数

  • C - 部分条件满足的情况下为必选参数

  • O - 可选参数

参数类型

KEY 名称 样例 说明
NUMBER 数字类 123
AMOUNT 金额类 88.05 以结算货币的基本单位为准，如美元（USD）的基准单位是美元
TEXT 文本类 张三
DATE 时间类 2018-08-02 15:16:51 格林威治标准时间（UTC-0）格式：YYYY-MM-DD HH:mm:ss
BOOLEAN 布尔值类 true true 或者 false
JSONObject JSON对象类 {“key”:“value”}
JSONArray JSON数组类 [1,2,3,4,5]

4. 请求报文 - 公共参数

KEY 名称 类型 必要性 描述
app_id 应用ID TEXT(32) M 开放服务网关分配给接入应用的ID，请联系技术人员提供
format 请求数据格式 TEXT(4) M 仅支持JSON
charset 请求使用的编码格式 TEXT(8) M 仅支持UTF-8
sign_type 签名算法 TEXT(8) M 目前支持MD5/RSA的签名算法
sign 签名 TEXT(32) M 接口签名标识，用于判断商户真实性，防止报文被篡改，详见签名规范
version 版本 TEXT(8) M 固定值：1.0
timestamp 发送请求的时间 DATE O 和标准时间前后不能超过15分钟
格林威治标准时间（UTC-0）格式：YYYY-MM-DD HH:mm:ss。缺省为当前UTC时间。

5. 响应报文 - 公共参数

KEY 名称 类型 必要性 描述
code 状态码 TEXT(32) M 状态码，0 表示请求成功，其他表示失败
msg 错误信息 TEXT(128) M 当有错误发生时，此msg包含有错误信息
sign 签名 TEXT(32) M 接口签名标识，用于判断商户真实性，防止报文被篡改，详见签名规范
app_id和sign_type无效时，不会返回签名
total 返回数据总数 NUMBER M 满足条件的数据总数，获取分页数据时有效
data 返回数据 JSONArray M 数组中包括1个或多个JSONObject，具体参数由各业务API定义
psn 接口序列号 TEXT(32) M 接口序列号，用于错误查找及请求记录

签名规范

1. 选择签名算法

签名算法可支持 RSA(SHA256)、MD5，对请求数据统一签名。

在RSA的签名时，需要私钥和公钥一起参与签名。私钥与公钥皆是客户通过OPENSSL来生成得出的（注意密钥的长度为2048）。客户把生成出的公钥与开放API网关技术人员配置好的网关公钥做交换。因此，在签名时，客户要用到的是自己的私钥及开放API网关的公钥。

在MD5签名时，需要开放服务网关MD5安全校验码（Key）参与签名。安全校验码（Key）是以英文字母和数字组成的32位字符串，该签名Key由开放服务网关进行分配，请务必保证此签名Key不被泄露。

2. 生成待签名字符串

第一步：确立待签名参数

在客户请求参数列表中和开放服务网关返回参数列表和异步通知参数列表中，对所有API请求参数（包括公共请求/响应参数和业务请求/响应参数，但除去sign_type,sign参数和byte[]类型的参数及值为NULL或空字符串的参数）。

注意：根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、@等），那么该值需要做URL Encoding，这样请求接收方才能接收到正确的参数值。这种情况下，待签名数据应该是原生值而不是encoding之后的值。例如：调用某接口需要对请求参数email进行数字签名，那么待签名数据应该是"[email protected]"，而不是"email=test%40msn.com"。

如下参数数组：

String[] parameters = {
  "app_id=wxd16bdc77aa30ce7e",
  "method=pay.orderquery",
  "provider_id=2088101568338364",
  "format=JSON",
  "charset=UTF-8",
  "sign_type=MD5",
  "version=1.0",
  "timestamp=2018-10-30 14:19:23",
  "merchant_no=100001876",
  "out_trade_no=TB20181030000875",
  "trans_no="
};

处理后需要参与签名的参数为（根据规则，sign_type和trans_no不参与签名）

String[] parameters = {
  "app_id=wxd16bdc77aa30ce7e",
  "method=pay.orderquery",
  "provider_id=2088101568338364",
  "format=JSON",
  "charset=UTF-8",
  "version=1.0",
  "timestamp=2018-10-30 14:19:23",
  "merchant_no=100001876",
  "out_trade_no=TB20181030000875"
};

第二步：参数排序

参数名ASCII码从小到大排序（从a到z的顺序排序，若遇到相同首字母，则看第二个字母，以此类推）。 第一步排序后的数组为

String[] parameters = { 
  "app_id=wxd16bdc77aa30ce7e",
  "charset=UTF-8",
  "format=JSON",
  "merchant_no=100001876",
  "method=pay.orderquery",
  "out_trade_no=TB20181030000875",
  "provider_id=2088101568338364",
  "timestamp=2018-10-30 14:19:23",
  "version=1.0"
};

第三步：参数拼接

使用“&”字符连接已排序的参数，上一步示例连接后的字符串为：

app_id=wxd16bdc77aa30ce7e&charset=UTF-8&format=JSON&merchant_no=100001876&method=pay.orderquery&out_trade_no=TB20181030000875&provider_id=2088101568338364&timestamp=2018-10-30 14:19:23&version=1.0

3. 签名

MD5签名

  1. 请求时签名

当拿到请求时的待签名字符串后，需要把安全校验码（Key）直接拼接到待签名字符串后面，形成新的字符串，利用MD5的签名函数对这个新的字符串进行签名运算，再将得到的字符串所有字符转换为小写，从而得到32位签名结果字符串（该字符串赋值于参数sign）。

  1. 异步通知/同步返回时验证签名

当获得到异步通知/同步返回时的待签名字符串后，同理，需要把安全校验码（Key）直接拼接到待签名字符串后面，形成新的字符串，利用MD5的签名函数对这个新的字符串进行签名运算，从而得到32位签名结果字符串。此时这个新的字符串需要与开放服务网关异步通知/同步返回参数中的参数sign的值进行验证是否相等，来判断签名是否验证通过。

RSA签名

  1. 请求时签名

当拿到请求时的待签名字符串后，把待签名字符串与客户的私钥一同放入RSA的签名函数中进行签名运算(SHA256WithRSA签名运算并进行Base64编码)，从而得到签名结果字符串。

  1. 异步通知/同步返回时验证签名

当获得通知或同步返回时的待签名字符串后，把待签名字符串、开放服务网关提供的公钥、通知或同步返回参数中的参数sign的值三者一同放入RSA的签名函数中进行非对称的签名运算(SHA256WithRSA签名运算并进行Base64编码)，来判断签名是否验证通过。

详细的签名方法请参考SDK中的签名和验签函数，RSA密钥生成及签名验证测试，你可以参照支付宝提供的工具。 请参考以下地址获取RSA密钥生成和签名验签工具: https://docs.open.alipay.com/291/105971/

支付类API

发起条码（刷卡）支付

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.barcodepay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "auth_code": "131234567677911364",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_operation_method": 4,
      "pay_user_account_id": "2088101117955611",
      "pay_user_account_name": "15900000000",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.barcodepay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "auth_code": "281234567885302264",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}\"",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_operation_method": 4,
      "pay_user_account_id": "2088101117955611",
      "pay_user_account_name": "15900000000",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55"
    }
  ]
}

发起条码（刷卡）支付
POST

收银员使用扫码设备读取用户手机微信支付宝"付款码"，将二维码通过本接口上送至开放服务网关发起支付。

提醒1：接口返回错误码为0，表示交易请求提交成功，但不表示交易成功；提交支付请求后开放服务网关会同步返回支付结果。当请求超时，商户系统应等待5秒后调用查询订单API，查询支付实际交易结果；当返回交易状态为"USERPAYING"时，商户系统可设置间隔时间(建议10秒)重新查询支付结果，直到支付成功或超时(建议30秒)；

提醒2：在调用查询接口返回后，如果交易状态不明晰，请调用撤销订单API，此时如果交易失败则关闭订单，该单不能再支付成功；如果交易成功，则将扣款退回到用户账户。当撤销无返回或错误时，请再次调用。

提醒3: 请勿调用扣款后立即调用撤销订单API，建议至少15s后再调用。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.barcodepay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) O 目前支持的支付方式有：
ALIPAY
WECHATPAY
UNIONPAY_QR(银联云闪付)
后台会根据授权码的格式自动判断支付方式并覆盖
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD。标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
auth_code 授权码 TEXT(256) M 扫码支付授权码
示例：支付宝 - 28763443825664394
description 订单描述 TEXT(128) M 支付订单的简要描述
例：Ipad mini 16G 白色
notify_url 后台通知地址 TEXT(256) O 商户后台接收开放服务网关支付异步通知回调地址
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

扩展参数

KEY 名称 类型 必要性 描述
store_no SnapPay分配的门店号 TEXT(8) O 门店号用于区分同一个商户的不同门店。该号码由SnapPay在创建商户时分配。我们建议在请求中提供门店号以便于通过支付宝的风险控制。例如：“store_no”:“80000026”

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态：
USERPAYING-交易创建，等待买家付款
CLOSE-交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS-交易完成

当trans_status交易状态为：SUCCESS-交易完成 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY-支付宝
WECHATPAY-微信支付
UNIONPAY_QR-银联云闪付
pay_operation_method 支付操作方式 NUMBER M 4：扫码支付
5：条码支付
6：H5支付
8：APP支付
9：PC网页支付
10: WAP手机支付
pay_user_account_id 买家用户标识 TEXT(32) M 支付宝返回支付用户的ID,例如：2088101117955611
微信返回商户appid下用户唯一标识，例如：wx37150978513678
pay_user_account_name 买家账号 TEXT(32) O 159****5620或[email protected]
注：支付宝支付返回，微信支付时返回为空
trans_currency 标价币种 TEXT(32) M 符合ISO 4217标准的三位字母代码，币种列表详见货币类型
exchange_rate 汇率 TEXT(16) M 标价币种兑换支付币种汇率
trans_amount 交易总金额 AMOUNT M 交易总金额
c_trans_fee 顾客承担手续费 AMOUNT O 交易手续费由顾客承担部分的金额
customer_paid_amount 顾客实付金额 AMOUNT M 交易过程中从顾客资金账户中实际扣减的金额
discount_bmopc 支付通道商户优惠金额 AMOUNT O 商户在支付通道的服务提供方（微信、支付宝等）的系统发布营销活动（优惠券、代金券、满减、单品优惠），用户支付时享受的金额减免
discount_bpc 支付通道优惠金额 AMOUNT O 支付通道提供方（微信、支付宝等）给用户提供的优惠，在交易过程中直接减免，如：鼓励金、立减、红包等营销活动
trans_end_time 交易完成时间 DATE M

扫码支付下单

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.qrcodepay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "qrcode_url": "https://qrcode-url"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.qrcodepay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "qrcode_url": "https://qrcode-url"
    }
  ]
}

扫码支付下单
POST

商户系统先调用此接口在开放服务网关后台生成预支付交易单，返回正确的预支付交易会话标识后再引导用户扫码完成支付。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.qrcodepay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY-支付宝
WECHATPAY-微信支付
UNIONPAY_QR-银联云闪付
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
description 订单描述 TEXT(128) M 支付订单的简要描述。例：Ipad mini 16G 白色
notify_url 通知地址 TEXT(256) O 接收开放服务网关支付异步通知回调地址
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

扩展参数

KEY 名称 类型 必要性 描述
store_no SnapPay分配的门店号 TEXT(8) O 门店号用于区分同一个商户的不同门店。该号码由SnapPay在创建商户时分配。我们建议在请求中提供门店号以便于通过支付宝的风险控制。例如：“store_no”:“80000026”

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
qrcode_url 二维码链接 TEXT(128) M 可将该参数值生成二维码展示出来进行扫码支付;
当支付方式为 UNIONPAY_QR-银联云闪付 时，此参数为BASE64编码的二维码图片，请直接转换为图片供支付扫码

公众号/H5支付下单

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.h5pay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "pay_channel_trade_type": "MWEB",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "h5pay_url: `https://h5pay_url`": "Hello, world!",
      "alipay_trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.h5pay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "pay_channel_trade_type": "JSAPI",
  "pay_user_account_id": "2088101106499364",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}\"",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "h5pay_url: `https://h5pay_url`": "Hello, world!",
      "alipay_trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}

公众号/H5支付下单
POST

商户系统先调用此接口在开放服务网关后台生成预支付交易单，返回正确的预支付交易会话标识后再跳转到开放服务网关支付页面地址，开放服务网关H5收银台完成支付后，会跳转回商户页面。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.h5pay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY-支付宝
WECHATPAY-微信支付
pay_channel_trade_type 通道支付调用方式 TEXT(16) O MWEB：默认为该值，返回支付地址，调用者前端跳转到该页面完成支付
ORDERSTR: 只支持支付宝内置浏览器打开电商网站，调用者通过AlipayJSBridge把得到的order_str直接提交给支付宝。适用于支付宝自提业务等。微信不支持ORDERSTR。参考：2.2无支付宝交易号唤起支付(使用方法2) link
out_order_no 商户订单号 TEXT(50) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
description 订单描述 TEXT(128) M 支付订单的简要描述
例：Ipad mini 16G 白色
notify_url 后台通知地址 TEXT(256) O 商家后台接收开放服务网关支付异步通知回调地址
return_url 前台回调地址 TEXT(1024) O 商家H5页面接收支付成功跳转的页面地址
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
out_order_no 商户订单号 TEXT(50) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS - 交易完成
h5pay_url H5收银台支付地址 TEXT(128) C 开放服务网关返回的支付地址，商家H5页面跳转到该地址，完成支付
order_str 拼接的支付orderStr字串 TEXT(1024) C 支付宝pay_channel_trade_type=ORDERSTR返回此参数.参考: 2.2无支付宝交易号唤起支付(使用方法2) link

Native App支付下单

POST 
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.inapppay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "subject": "iPad",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "refer_url": "https://refer-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"sub_app_id\": \"wxd930ea5d5a258f4f\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "sdk_params": {
        "alipay_request_params": "key1=value1&key2=value2",
        "appid": "wxd930ea5d5a258f4f",
        "partnerid": "10000100",
        "prepayid": "1101000000140415649af9fc314aa427",
        "package": "Sign=WXPay",
        "noncestr": "random",
        "timestamp": "1397527777",
        "sign": "XXXXXXXXXXX"
      },
      "trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.inapppay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "subject": "iPad",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "refer_url": "https://refer-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "sdk_params": {
        "alipay_request_params": "key1=value1&key2=value2",
        "appid": "wxd930ea5d5a258f4f",
        "partnerid": "10000100",
        "prepayid": "1101000000140415649af9fc314aa427",
        "package": "Sign=WXPay",
        "noncestr": "random",
        "timestamp": "1397527777",
        "sign": "XXXXXXXXXXX"
      },
      "trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}

Native App支付下单
POST

商户系统先调用此接口在开放服务网关后台生成预支付交易单，返回正确的预支付后调用支付宝SDK完成支付。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.inapppay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY-支付宝
WECHATPAY-微信支付
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
subject 商品名称 TEXT(128) M 商品的名称。例：Ipad
description 订单描述 TEXT(128) M 支付订单的简要描述。例：Ipad mini 16G 白色
notify_url 后台通知地址 TEXT(256) O 商家后台接收开放服务网关支付异步通知回调地址
refer_url 商户网站地址 TEXT(256) M 商家的官方网站
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(127,JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

扩展参数

KEY 名称 类型 必要性 描述
sub_app_id 微信开放平台分配的App Id TEXT(18) C 商户在微信开放平台申请移动应用或小程序得到的APPID（此APPID需要发邮件给SnapPay进行绑定）。当您在SnapPay绑定了多个APPID时，此为必选项，指定当前交易请求所使用的APPID

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

When code=0, data[0] returns the following parameters:

KEY 名称 类型 必要性 描述
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS - 交易完成
sdk_params 调用 Alipay 或 微信支付 SDK 所需要的参数 TEXT(JSON格式) M 调用 Alipay 或 微信支付 SDK 所需要的参数
trade_no 支付订单号 TEXT(128) M 开放服务网管的支付订单号

当payment_method = ALIPAY时 sdk_params返回的JSON如下：

KEY 名称 类型 必要性 描述
alipay_request_params 调用Alipay SDK所需字符串 TEXT(256) M 调用Alipay SDK所需字符串

如何调用Alipay SDK​

请参考下面的链接调用Alipay SDK
https://global.alipay.com/doc/app/sdk_integration
https://global.alipay.com/doc/app/android_sdk

当payment_method = WECHATPAY时 sdk_params返回的JSON如下：

KEY 名称 类型 必要性 描述
appid 商户应用ID TEXT(32) M 商户在微信开放平台上申请的APPID
partnerid 服务商的商户ID TEXT(32) M 服务商在微信的商户ID
prepayid 预支付交易会话ID TEXT(32) M 微信的预支付订单号
package 扩展字段 TEXT(128) M 固定值Sign=WXPay
noncestr 随机字符串 TEXT(32) M 随机字符串
timestamp 时间戳 TEXT(10) M 时间戳
sign 签名 TEXT(32) M 服务商生成的签名

如何调用WeChat SDK​

请参考下面的链接调用WeChat SDK

https://pay.weixin.qq.com/wiki/doc/api/app/app_sl.php?chapter=8_5

下载安卓演示APP的apk和源代码

下载安卓演示APP的apk, 点击 这里
下载安卓演示APP的源代码, 点击 这里

Web网页支付下单

POST Try JavaTry PHP
RequestsAliPayUnionPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.webpay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "browser_type": "WAP"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "webpay_url": "https://webpay-url"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.webpay",
  "merchant_no": "901800002555",
  "payment_method": "UNIONPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "browser_type": "PC"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "webpay_url": "https://webpay-url"
    }
  ]
}

Web网页支付下单
POST

商户系统先调用此接口在开放服务网关后台生成预支付交易单，再跳转到开放服务网关返回的支付页面地址进入支付宝/银联国际等第三方支付收银台完成支付，支付成功后会跳转回商户页面。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.webpay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY-支付宝
UNIONPAY-银联国际
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
description 订单描述 TEXT(128) M 支付订单的简要描述。例：Ipad mini 16G 白色
notify_url 后台通知地址 TEXT(256) O 商家后台接收开放服务网关支付异步通知回调地址
return_url 前台回调地址 TEXT(1024) O 商家H5页面接收支付成功跳转的页面地址
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中
browser_type 浏览器类型 TEXT(8) O PC：电脑网站支付，默认
WAP：手机网站支付
UNIONPAY仅支付PC网站支付

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

When code=0, data[0] returns the following parameters:

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS - 交易完成
webpay_url PC收银台支付地址 TEXT(128) M 平台返回的支付地址，商家PC页面跳转到该地址，完成支付

微信小程序支付下单

POST 
RequestsWeChatPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.minipay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "pay_user_account_id": "xxxxxx",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"sub_app_id\": \"wxd930ea5d5a258f4f\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "request_payment": {
        "appid": "wxd930ea5d5a258f4f",
        "timestamp": "1397527777",
        "noncestr": "random",
        "package": "prepay_id=wx2017033010242291fcfe0db70013231072",
        "signType": "MD5",
        "paySign": "xxxxxx"
      },
      "trade_no": "TW0xxxxxxx"
    }
  ]
}

微信小程序支付下单
POST

商户系统先调用此接口在开放服务网关后台生成预支付交易单，返回正确的预支付后调起支付。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.minipay
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
payment_method 支付方式 TEXT(16) M 目前只支付：
WECHATPAY-微信支付
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，可以视为交易流水号，同一商户下订单号不能重复，即使交易没有成功
trans_currency 标价币种 TEXT(8) O 符合ISO 4217标准的三位字母代码，如：CAD，USD标价币种必须与商户申请的结算币种一致，不填写则默认为CAD
trans_amount 订单金额 AMOUNT M 最大值：100000000.00
pay_user_account_id 用户子标识 TEXT(64) M 微信Openid，下单前需要调用【网页授权获取用户信息】接口获取到用户的Openid。
description 订单描述 TEXT(128) M 支付订单的简要描述。例：Ipad mini 16G 白色
notify_url 后台通知地址 TEXT(256) O 商家后台接收开放服务网关支付异步通知回调地址
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回
effective_minutes 订单有效分钟数 NUMBER O 设置订单有效分钟数，超出有效时长不支付，订单将被关闭，不能再进行支付，默认为5分钟
取值范围：5分钟—60分钟
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

扩展参数

KEY 名称 类型 必要性 描述
sub_app_id 微信公众平台分配的App Id TEXT(18) C 商户在微信公众平台申请移动应用或小程序得到的APPID（此APPID需要发邮件给SnapPay进行绑定）。当您在SnapPay绑定了多个APPID时，此为必选项，指定当前交易请求所使用的APPID

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

When code=0, data[0] returns the following parameters:

KEY 名称 类型 必要性 描述
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS - 交易完成
request_payment 支付参数 TEXT(JSON格式) M 小程序发起微信支付时所需要的参数，请不要更改
trade_no 支付订单号 TEXT(128) M 开放服务网管的支付订单号

request_payment 返回的JSON如下：

KEY 名称 类型 必要性 描述
appid 子商户应用ID TEXT(32) M 服务商的子商户在微信开放平台上申请的APPID
timestamp 时间戳 TEXT(10) M 时间戳
noncestr 随机字符串 TEXT(32) M 随机字符串
package 扩展字段 TEXT(128) M 固定值prepay_id=*
signType 签名方式 TEXT(32) M MD5
paySign 签名 TEXT(32) M SnapPay生成的签名

如何唤起微信 如何使用返回值唤起微信，点击这里

下载微信小程序演示源代码 点击 这里

订单类API

订单查询

POST Try JavaTry PHP
RequestsByOrderNoByTransNo
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderquery",
  "merchant_no": "901800002555",
  "out_order_no": "12345678"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_user_account_id": "2088101106499364",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55",
      "pay_operation_method": 4,
      "attach": "{\"orderId\": \"12345\"}"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderquery",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_user_account_id": "2088101106499364",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55",
      "pay_operation_method": 4,
      "attach": "{\"orderId\": \"12345\"}"
    }
  ]
}

订单查询
POST

该接口提供所有交易订单(支付,撤销,退款)的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。

需要调用查询接口的情况：

  1. 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；

  2. 调用支付接口后，返回系统错误或未知交易状态；

  3. 调用条码支付API，返回USERPAYING的状态；

  4. 调用撤销接口API之前，需确认支付状态；

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.orderquery
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
out_order_no 商户订单号 TEXT(64) C 商户系统内部订单号，同一商户下订单号不能重复。out_order_no或trans_no两个参数需提供一个
trans_no 交易号 TEXT(32) C 开放服务网关平台交易号。out_order_no或trans_no两个参数需提供一个
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

When code=0, data[0] returns the following parameters:

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_status 交易状态 TEXT(32) M 交易状态
USERPAYING - 交易创建，等待买家付款
CLOSE - 交易关闭，包括撤销关闭，超时未支付关闭，交易失败关闭
SUCCESS - 交易完成

当 trans_status交易状态为：SUCCESS-交易完成 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY 支付宝
WECHATPAY 微信支付
UNIONPAY 银联
pay_user_account_id 买家账号标识 TEXT(32) M 支付宝返回支付用户的ID，例如：2088101117955611
微信返回商户appid下用户唯一标识，例如：wx37150978513678
银行卡交易返回加脱敏的卡号信息，例如：6226***1982
pay_user_account_name 买家账号名称 TEXT(32) O 159****5620或[email protected]注：支付宝支付返回账号登录名，微信支付时返回为空
trans_currency 标价币种 TEXT(32) O 符合ISO 4217标准的三位字母代码，币种列表详见货币类型
exchange_rate 汇率 TEXT(16) O 标价币种兑换支付币种汇率，非RMB标价时有值
trans_amount 交易总金额 AMOUNT M 交易总金额
c_trans_fee 顾客承担手续费 AMOUNT O 交易手续费由顾客承担部分的金额
customer_paid_amount 顾客实付金额 AMOUNT M 交易过程中从顾客资金账户中实际扣减的金额
discount_bmopc 支付通道商户优惠金额 AMOUNT O 商户在支付通道的服务提供方（微信、支付宝等）的系统发布营销活动（优惠券、代金券、满减、单品优惠），用户支付时享受的金额减免
discount_bpc 支付通道优惠金额 AMOUNT O 支付通道提供方（微信、支付宝等）给用户提供的优惠，在交易过程中直接减免，如：鼓励金、立减、红包等营销活动
trans_end_time 交易完成时间 DATE M 支付成功或失败的时间
pay_operation_method 支付操作方式 NUMBER M 4：扫码支付
5：条码支付
6：H5支付
8：APP支付
9：PC网页支付
10: WAP手机支付
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据。该字段主要用于商户携带订单的自定义数据，且需要遵循JSON格式。在查询API和支付通知中原样返回

订单支付结果异步通知

POST 
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345",
  "out_order_no": "12345678",
  "trans_status": "SUCCESS",
  "payment_method": "WECHATPAY",
  "pay_user_account_id": "wx37150978513678",
  "trans_currency": "CAD",
  "exchange_rate": 5.21,
  "trans_amount": 100.5,
  "c_trans_fee": 0.5,
  "customer_paid_amount": 524.09,
  "discount_bmopc": 0.1,
  "discount_bpc": 0.1,
  "trans_end_time": "2018-08-02 15:16:55",
  "attach": "{\"orderId\": \"12345\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0"
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345",
  "out_order_no": "12345678",
  "trans_status": "SUCCESS",
  "payment_method": "ALIPAY",
  "pay_user_account_id": "2088101106499364",
  "pay_user_account_name": "159****5620",
  "trans_currency": "CAD",
  "exchange_rate": 5.21,
  "trans_amount": 100.5,
  "c_trans_fee": 0.5,
  "customer_paid_amount": 524.09,
  "discount_bmopc": 0.1,
  "discount_bpc": 0.1,
  "trans_end_time": "2018-08-02 15:16:55",
  "attach": "{\"orderId\": \"12345\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0"
}

订单支付结果异步通知
POST

支付完成后，开放服务网关会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。

对后台通知交互时，如果开放服务网关收到商户的应答不是成功，开放服务网关认为通知失败，开放服务网关会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但开放服务网关不保证通知最终能成功。（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。

推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。特别提醒：商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄漏导致出现“假通知”，造成资金损失。

接口地址

该链接是通过交易请求时提交的参数notify_url设置，如果链接无法访问，商户将无法接收到开放服务网关异步通知。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，同一商户下订单号不能重复
trans_status 交易状态 TEXT(32) M SUCCESS - 交易成功
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY 支付宝
WECHATPAY 微信支付
UNIONPAY 银联
pay_user_account_id 买家账号标识 TEXT(32) M 支付宝返回支付用户的ID,例如：2088101117955611
微信返回商户appid下用户唯一标识，例如：wx37150978513678
银行卡交易返回加脱敏的卡号信息，例如：
6226***1982
pay_user_account_name 买家账号名称 TEXT(32) O 159****5620或[email protected] 注：支付宝支付返回账号登录名，微信支付时返回为空
trans_currency 标价币种 TEXT(32) O 符合ISO 4217标准的三位字母代码，币种列表详见货币类型
exchange_rate 汇率 TEXT(16) O 标价币种兑换支付币种汇率，非RMB标价时有值
trans_amount 交易总金额 AMOUNT M 交易总金额
c_trans_fee 顾客承担手续费 AMOUNT O 交易手续费由顾客承担部分的金额
customer_paid_amount 顾客实付金额 AMOUNT M 交易过程中从顾客资金账户中实际扣减的金额
discount_bmopc 支付通道商户优惠金额 AMOUNT O 商户在支付通道的服务提供方（微信、支付宝等）的系统发布营销活动（优惠券、代金券、满减、单品优惠），用户支付时享受的金额减免
discount_bpc 支付通道优惠金额 AMOUNT O 支付通道提供方（微信、支付宝等）给用户提供的优惠，在交易过程中直接减免，如：鼓励金、立减、红包等营销活动
trans_end_time 交易完成时间 DATE M 交易成功时间
attach 商户附加信息 TEXT(127,JSON格式) O 附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据

响应参数

商户处理后同步返回给开放服务网关的参数：

KEY 名称 类型 必要性 描述
code 返回状态码 TEXT(32) M 固定值：0

订单撤销

POST Try JavaTry PHP
RequestsCancelOrder
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.ordercancel",
  "merchant_no": "901800002555",
  "out_order_no": "12345678"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678"
    }
  ]
}

订单撤销
POST

支付交易返回失败或支付系统超时，调用该接口撤销交易。如果此订单用户支付失败，开放服务网关支付系统会将此订单关闭；如果用户支付成功，开放服务网关支付系统会将此订单资金退还给用户。

注意：当天的交易单可调用撤销，其他正常支付的单如需实现相同功能请调用申请退款API。提交支付交易后调用【查询订单API】，没有明确的支付结果再调用【撤销订单API】。调用支付接口后请勿立即调用撤销订单API，建议支付后至少15s后再调用撤销订单接口。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 此接口固定值为：pay.ordercancel
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
out_order_no 商户订单号 TEXT(64) M 商户系统内部订单号，同一商户下订单号不能重复
此处指商户原消费交易的订单号
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(32) M 商户系统内部订单号

订单退款

POST Try JavaTry PHP
RequestsOrderRefund
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderrefund",
  "merchant_no": "901800002555",
  "out_order_no": "12345678",
  "out_refund_no": "87654321",
  "refund_amount": 50,
  "refund_desc": "defect product"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "out_refund_no": "87654321",
      "trans_status": "SUCCESS",
      "refund_trans_no": "TRANS67890",
      "refund_trans_end_time": "2018-08-02 15:18:25"
    }
  ]
}

订单退款
POST

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，开放服务网关将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。

注意：

1. 交易时间超过3个月的订单无法提交退款；

2. 退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号。

3. 每个支付订单的部分退款次数不能超过10次

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 接口固定值为：pay.orderrefund
merchant_no 商户号 TEXT(32) M 商户号，在SnapPay入驻后生成的定常数字，用于标识商户身份
out_order_no 商户订单号 TEXT(64) M 商户系统内部支付订单号，同一商户下订单号不能重复
此处指商户原消费交易的订单号
out_refund_no 商户退款单号 TEXT(64) M 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔。
当前退款交易的订单号
refund_amount 退款金额 AMOUNT M 本次申请退款金额
refund_desc 退款原因 TEXT(64) O 例：商品已售完
extension_parameters 扩展参数 TEXT(JSON格式) O 扩展输入参数，后续定义增加的参数存储于此JSON可变结构中

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
trans_no 交易号 TEXT(32) M 开放服务网关平台交易号
out_order_no 商户订单号 TEXT(64) M 商户系统内部支付原订单号
out_refund_no 商户退款单号 TEXT(64) M 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔。
trans_status 交易状态 TEXT(8) M 交易状态
REFUNDING - 交易创建，等待退款
CLOSE - 交易关闭，退款失败
SUCCESS - 退款成功

当 trans_status交易状态为：SUCCESS-交易完成 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
refund_trans_no 退款交易号 TEXT(32) M 开放服务网关平台退款单号
refund_trans_end_time 退款完成时间 DATE M

实时汇率查询

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.exchangerate",
  "basic_currency_unit": "CAD",
  "payment_method": "WECHATPAY"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "exchange_rate": "5.21"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.exchangerate",
  "basic_currency_unit": "CAD",
  "payment_method": "ALIPAY",
  "pay_type": "ONLINE"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "exchange_rate": "5.21"
    }
  ]
}

实时汇率查询
POST

获取指定币种对人名币实时参考兑换汇率，分微信和支付宝线上、线下。仅供参考，以真实交易的汇率为准。

请求参数

公共参数

参见请求报文 - 公共参数

业务参数

KEY 名称 类型 必要性 描述
method 请求方法 TEXT(128) M 接口固定值为：pay.exchangerate
basic_currency_unit 币种单位 TEXT(8) M CAD，USD等
payment_method 支付方式 TEXT(16) M 目前支持的支付方式有：
ALIPAY - 支付宝
WECHATPAY - 微信支付
pay_type 支付类型 TEXT(16) O 支付宝支持的支付类型有：
ONLINE - 线上(默认值)
OFFLINE-线下

响应参数

公共参数

参见响应报文 - 公共参数

业务参数

当 code=0 时，data[0] 返回如下参数：

KEY 名称 类型 必要性 描述
exchange_rate 汇率 TEXT M 如：6.917600

Created by SnapPay Inc. on 15 Jul 2020