NAV Navbar
json

接入流程说明

认真阅读本文档并严格准守端口的规范。在开始接入前请确保您的商户已经在Synopay系统创建,并且生成了商户号与APIKEY。在接入过程中如果遇到文档里没有提到的未知错误,请咨询我司的技术部门。

接口总述

我司提供交易类接口,查询类接口。交易接口可完成网页支付,H5支付交易的处理以及退款交易处理;查询类接口用于处理查询交易订单。
支付单和退款单提交均为PUT方式,订单查询均为GET方式;包含Request Entity的请求参数格式为json
除跳转页面外,所有的Accept均为application/json;所有的PUT/POST请求Content-Type为application/json
系统使用UTF-8字符集
参数分为三种:Path Variable/Query Param/JSON entity
- Path Variable:包含在URI内的参数
- Query Param:在URI末尾?后的key=value形式的参数
- JSON entity:只在PUT/POST请求中使用
所有返回JSON的API,成功访问返回状态值均为200(不论执行结果)。JSON固定包含字段return_code,若值为SUCCESS则表示执行成功; 其他值表示执行失败,此时可查询错误码了解对应的错误类型,此时还会携带return_msg字段作为错误描述信息

签名说明

每次请求都必须加入签名信息作为请求校验。校验参数全部以Query Param参数的方式附加在URL后面,顺序不分先后。 签名过程:

1. 连接生成签名的原始字符串,需要4个参数,使用&连接,无需转码

valid_string=partner_code&time&nonce_str&credential_code

参数名称 说明 示例
partner_code 商户编码,由4~6位大写字母或数字构成(请查看审核成功的邮件通知;或登录商户管理后台查看) 60007
time UTC毫秒时间戳,取当前UTC时间的毫秒数时间戳,Long类型,5分钟内有效 1569740075455
nonce_str 随机字符串,无长度限制,请使用URL安全字符(避开&,=等符号),请注意HTTP URL的最大长度限制,建议长度在10到30位 ksduh1289d1238y
credential_code 系统为商户分配的开发校验码,请妥善保管,不要在公开场合泄露(登录商户管理后台查看) xxxxxxxxxxx

2.使用SHA256进行签名,并转为小写字符串

sign=sha256(valid_string).toLowerCase()

3.在请求中把签名使用的time,nonce_str和生成的sign一同作为Query Param参数发送

valid_string=60007&1569740075455&ksduh1289d1238y&pQ5Jc9eoTqwduQ3p2WmvSy0cewce
sign=64712672795f94fa3bfb2e88ac09cb75d09bcf8a3c3dcaa529d8290dd6587060

业务场景描述

生产环境网关地址:http://api.synopay.com

QRCode支付

QRCode支付单适用于PC端网页/应用进行支付,用户使用微信/支付宝客户端扫描下单后生成的二维码完成支付。
返回值包括二维码字符串,二维码图片,支付地址。商户可以自行展示二维码完成付款。

服务地址

PUT /api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/pay

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
channel String Y 支付渠道,大小写敏感,允许值: Alipay, Wechat
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
code_url String 支付码字符串,商户可以据此自行生产二维码
qrcode_img String Base64封装的二维码图片,可直接作为img的src属性

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

微信JSAPI支付

JSAPI适用于在微信内打开的网页进行支付,如果用户从微信公众号进入支付页要求公众号已完成认证。
请求跳转至Synopay下单地址,将自动拉起微信内置收银台完成支付。

服务地址

GET /wechat_jsapi_gateway/partners/{partner_code}_order_{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识
redirect String Y 支付成功后跳转页面

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

支付宝JSAPI支付

JSAPI适用于在支付宝内打开的网页进行支付,如果用户从支付宝进入支付页。
请求跳转至Synopay下单地址,将自动拉起支付宝内置收银台完成支付。

服务地址

GET /gateway/alipay/partners/{partner_code}/orders/{order_id}/app_pay

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识
redirect String Y 支付成功后跳转页面

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

支付宝H5支付

H5支付适用场景为移动端App或者手机自带浏览器进行支付,用户下单后浏览器跳转至支付宝支付页面并自动拉起支付宝客户端完成支付。
返回值包括跳转支付地址,直接跳转至支付地址完成支付。

服务地址

PUT /api/v1.0/h5_payment/partners/{partner_code}/orders/{order_id}/pay

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
channel String Y 支付渠道,大小写敏感,允许值: Alipay
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识
redirect String Y 支付成功后跳转页面

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
pay_url String 跳转URL

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

微信小程序支付

接入微信小程序需完成海外主体认证,并且认证主体需要与在Synopay开通的商户主体一致。

服务地址

PUT /api/v1.0/gateway/partners/{partner_code}/microapp_orders/{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识
appid String Y 小程序appid
customer_id String Y 小程序openid

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
sdk_params String 小程序支付所需参数(Json字符串)

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

RetailPay 线下扫描客户二维码支付

线下支付订单接口用于带有扫码设备的收银终端进行对接,商户输入金额后要求客户出示支付码,用扫码枪扫码后将扫码内容和金额一并提交并完成支付操作。

服务地址

PUT /api/v1.0/micropay/partners/{partner_code}/orders/{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
auth_code String Y 扫描用户微信客户端得到的支付码
device_id String Y 设备ID

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String PAYING:等待支付、CREATE_FAIL:订单创建失败、CLOSED:已关闭、PAY_FAIL:支付失败、PAY_SUCCESS:支付成功
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
total_fee Int 订单金额,单位是货币最小面值单位
real_fee Int 实际支付金额
channel String 支付渠道
pay_time String 支付时间(yyyy-MM-dd HH:mm:ss,GMT-5)
create_time String 订单创建时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,GMT-5)
currency String 币种,通常为USD

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
AUTHCODEEXPIRE 二维码已过期
NOTENOUGH 余额不足
NOTSUPORTCARD 不支持卡类型
AUTH_CODE_ERROR 二维码被重复提交
AUTH_CODE_INVALID 不是微信支付二维码
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

支付宝 Online Payment

用于PC端支付宝支付,创建订单后跳转到返回的pay_url(需附加签名参数和redirect参数),随后进入支付宝支付页面完成支付 该接口仅现仅支持支付宝。

服务地址

PUT /api/v1.0/alipay/partners/{partner_code}/orders/{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
redirect String Y 支付成功后跳转页面
operator String Y 操作人员标识

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
pay_url String 跳转URL

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

APP支付

用于移动端APP调用支付渠道SDK支付,调用API创建订单,得到SDK调用参数,将参数传递给SDK拉起对应渠道App(微信、支付宝)支付,并由渠道App直接返回支付结果。

服务地址

PUT /api/v1.0/gateway/partners/{partner_code}/app_orders/{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
description String Y 订单标题(最大长度128字符,超出自动截取)
price int Y 金额,单位为货币最小单位,例如使用100表示1.00 USD
currency String Y 币种代码 USD
channel String Y 支付渠道,必填,大小写敏感。允许值: Alipay, Wechat
notify_url String Y 支付通知url,详见支付通知api,不填则不会推送支付通知
operator String Y 操作人员标识
system String Y 客户端操作系统类型。允许值: android, iphone, ipad
version String N 客户端版本号
appid String N 微信appid,微信通道要求必填

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String SUCCESS表示创建订单成功,EXISTS表示订单已存在
channel String 支付渠道
partner_code String 商户编码
full_name String 商户注册全名
partner_name String 商户名称
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
sdk_params String 调用SDK的参数字符串

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
ORDER_PAID 订单已支付
ORDER_EXIST 订单已存在
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

创建报关单

用于商户提交海关需要的订单附件信息。仅支持微信和支付宝,微信只支持一个月内的支付订单进行报关申请。

服务地址

PUT /api/v1.0/customs/partners/{partner_code}/declare/report/{client_report_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
client_report_id String Y 商户申请报关单号,要求同一商户唯一

JSON字段

参数名称 参数类型 是否非空 说明
order_id String Y 商户支付订单号,要求同一商户唯一
custom String Y 海关编号 * 渠道海关编号
mch_custom_id String Y 商户在海关备案的编号
mch_custom_name String Y 商户海关备案名称

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
report_id String Synopay海关单号
client_report_id String 商户申请报关单号
report_status String 报关单状态: PROCCESSING,SUBMITED,FAILED,SUCCESS
channel String 支付渠道
custom String 海关编号
mch_custom_no String 商户在海关备案的编号
mch_custom_name String 商户海关备案名称
order_id String Synopay订单号
transaction_id String 支付渠道订单号
order_currency String 币种
order_amount Double 订单金额
report_time String 报关时间
creation_date String 报关单创建时间
last_update_date String 更新时间

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

查询报关单

用于商户查询报关单号的状态。

服务地址

GET /api/v1.0/customs/partners/{partner_code}/declare/query/{client_report_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
client_report_id String Y 商户申请报关单号,要求同一商户唯一

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
report_id String Synopay海关单号
report_status String 报关单状态: PROCCESSING,SUBMITED,FAILED,SUCCESS
report_id String Synopay海关单号
client_report_id String 商户申请报关单号
return_msg Stirng 错误描述,仅在执行结果不为SUCCESS情况下出现
order_id String Synopay订单号
partner_order_id String 商户订单ID

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

重新提交报关单

用于重新提交未报关成功的报关单

服务地址

PUT /api/v1.0/customs/partners/{partner_code}/redeclare/report/{client_report_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
client_report_id String Y 商户申请报关单号,要求同一商户唯一

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
report_id String Synopay海关单号
client_report_id String 商户申请报关单号
report_status String 报关单状态: PROCCESSING,SUBMITED,FAILED,SUCCESS
channel String 支付渠道
custom String 海关编号
mch_custom_no String 商户在海关备案的编号
mch_custom_name String 商户海关备案名称
order_id String Synopay订单号
transaction_id String 支付渠道订单号
order_currency String 币种
order_amount Double 订单金额
report_time String 报关时间
creation_date String 报关单创建时间
last_update_date String 更新时间

错误码

名称 说明
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

获取当前汇率

获取当前各渠道USD兑CNY汇率值(1USD=?CNY),该汇率仅做参考,以实际成交汇率为准

服务地址

GET /api/v1.0/gateway/partners/{partner_code}/channel_exchange_rate

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
wechat_rate Double 微信汇率
alipay_retail_rate Double 支付宝线下渠道汇率
alipay_online_rate Double 支付宝线上渠道汇率

错误码

名称 说明
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限

查询订单状态

服务地址

GET /api/v1.0/gateway/partners/{partner_code}/orders/{order_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String PAYING:等待支付、CREATE_FAIL:订单创建失败、CLOSED:已关闭、PAY_FAIL:支付失败、PAY_SUCCESS:支付成功、PARTIAL_REFUND:部分退款、FULL_REFUND:全额退款
如果需要可以用相同订单号再次发起支付单,支付成功或支付中的无法重复发起订单
channel_order_id String 渠道方(微信、支付宝等)订单ID
order_id String Synopay订单ID,同时也是微信订单ID,最终支付成功的订单ID可能不同
partner_order_id String 商户订单ID
total_fee int 订单金额,单位是货币最小面值单位
real_fee int 实际支付金额,单位是货币最小面值单位(目前等于订单金额,为卡券预留)
rate Double 交易时使用的汇率,1USD=?CNY
customer_id String 客户ID
pay_time String 支付时间(yyyy-MM-dd HH:mm:ss,GMT-5)
create_time String 订单创建时间(最新订单为准)(yyyy-MM-dd HH:mm:ss,GMT-5)
currency String 币种,通常为USD
channel String 支付渠道 Alipay

错误码

名称 说明
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

申请退款

服务地址

PUT /api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号
refund_id String Y 商户退款单号

JSON字段

参数名称 参数类型 是否非空 说明
fee Int Y 退款金额,单位是货币最小单位,单个订单退款单金额总和不能超过用户支付金额

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String WAITING:正在提交、CREATE_FAILED:提交失败、SUCCESS:提交成功、FAILED:退款失败、FINISHED:退款成功、CHANGE:退款无法到账,需要人工介入
refund_id String Synopay退款单号
partner_refund_id String 商户提交的退款单号
amount int 退款金额,单位是货币最小单位
currency String 币种,通常为USD

错误码

名称 说明
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
ORDER_NOT_PAID 订单未支付完成,无法退款
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

查询退款状态

服务地址

GET /api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成
order_id String Y 商户支付订单号
refund_id String Y 商户退款单号

Query Params

参数名称 参数类型 是否非空 说明
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Success 200

字段 参数类型 说明
return_code String 执行结果
result_code String WAITING:正在提交、CREATE_FAILED:提交失败、SUCCESS:提交成功、FAILED:退款失败、FINISHED:退款成功、CHANGE:退款无法到账,需要人工介入
refund_id String Synopay退款单号
partner_refund_id String 商户提交的退款单号
amount int 退款金额,单位是货币最小单位
currency String 币种,通常为USD

错误码

名称 说明
ORDER_NOT_EXIST 订单不存在
ORDER_MISMATCH 订单号与商户不匹配
ORDER_NOT_PAID 订单未支付完成,无法退款
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

查看账单

服务地址

GET /api/v1.0/gateway/partners/{partner_code}/orders

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成

Query Params

参数名称 参数类型 是否非空 说明
date String Y 订单创建日期,'yyyyMMdd'格式,GMT-5,不填默认查询所有订单
status String Y 订单状态。允许值: 'ALL', 'PAID', 'REFUNDED'
page Int N 页码,从1开始计算。默认值: 1
limit Int N 每页条数。默认值: 10
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Response ROOT

字段 参数类型 说明
return_code String 执行结果
data JSON[] 订单列表
pagination JSON 分页信息
analysis JSON 统计信息

Data

字段 参数类型 说明
order_id String Synopay订单ID
partner_order_id String 商户订单ID
total_fee int 订单金额,单位是货币最小单位
real_fee int 订单支付金额,单位是货币最小单位
channel String 支付渠道 Alipay
currency String 币种
create_time String 格式'yyyy-MM-dd HH:mm:ss',GMT-5,订单创建时间
pay_time String 格式'yyyy-MM-dd HH:mm:ss',GMT-5,支付时间,未支付订单为空
status String 订单状态:SUBMITTING:提交中、SUBMIT_FAIL:提交失败、WAITING_PAYMENT:等待支付、CLOSED:已关闭、PAYMENT_FAIL:支付失败、SUCCESS:支付成功、PARTIAL_REFUND:部分退款、FULL_REFUND:全额退款
order_body String 订单标题
gateway String 订单模式
partner_code String 商户编码
partner_name String 商户名称
refund_fee String 当前订单退款金额,货币最小单位

Pagination

字段 参数类型 说明
page int 页码
limit int 每页条数
totalCount int 总条数
totalPages int 总页数

Analysis

字段 参数类型 说明
order_count int 支付成功订单数(包含有退款订单)
total_fee int 成交订单总额,货币最小单位
real_fee int 支付总额,货币最小单位

错误码

名称 说明
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

查看清算详情

服务地址

GET /api/v1.0/gateway/partners/{partner_code}/settlements

Path Variable

参数名称 参数类型 是否非空 说明
partner_code String Y 商户编码,由4-6位大写字母或数字构成

Query Params

参数名称 参数类型 是否非空 说明
date String Y 清算日期,'yyyyMMdd'格式,GMT-5
time Long Y UTC毫秒时间戳
nonce_str String Y 随机字符串
sign String Y 签名

Response ROOT

字段 参数类型 说明
return_code String 执行结果
result_code String 业务执行结果
settle_from String 订单起始日期,yyyyMMdd
settle_to String 订单截止日期,yyyyMMdd
settle_days String 清算周期(T+n)
transaction_count int 流水总条目
order_count int 付款单数
refund_count int 退款单数
total_credit int 入账总金额(USD分)
total_debit int 支出总金额(USD分)
total_surcharge int 手续费总额(USD分)
total_transfer int 打款总额(USD分)
transactions JSON 流水列表

transactions

字段 参数类型 说明
transaction_time String 交易时间,格式yyyyMMddHHmmss,GMT-5
order_id String USAGMS订单ID
partner_order_id String 商户订单ID
channel_order_id String 渠道方(Alipay/Wechat)订单号
refund_id String USAGMS退款单ID(仅退款或退款失败补正)
partner_refund_id String 商户系统提交退款ID(仅退款或退款失败补正)
gateway String 下单接口
channel String 支付渠道 Alipay
type String 流水类型,Credit: 入账、Debit: 出账
currency String 币种
total_amount int 订单总金额,单位是货币最小单位
input_amount int 订单输入金额,单位是货币最小单位
customer_payment_amount int 用户实际支付金额,单位是货币最小单位
settle_amount int 结算金额,单位是USD分
surcharge_rate String 手续费费率(x%)
surcharge int 手续费金额,单位是USD分
transfer_amount int 打款金额,单位是USD分
exchange_rate double 使用汇率
remark String 备注

错误码

名称 说明
SYSTEMERROR 系统内部异常
INVALID_SHORT_ID 商户编码不合法或没有对应商户
SIGN_TIMEOUT 签名超时,time字段与服务器时间相差超过5分钟
INVALID_SIGN 签名错误
PARAM_INVALID 参数不符合要求,具体细节可参考return_msg字段
NOT_PERMITTED 未开通网关支付权限
INVALID_CHANNEL 不合法的支付渠道名称,请检查大小写

付款通知

若订单创建时提供了notifyUrl,系统会在用户支付成功后向这个地址主动发送支付成功状态推送,请求方式为POST,推送校验参数会包含在json内,商户系统应该验证校验参数,确定来源正确后再进行后续操作。 商户系统收到请求后应按要求返回参数,若Synopay未收到合法参数,视为商户未接收成功,商户系统应能够处理收到的重复请求。

返回参数

参数名称 参数类型 是否非空 说明 示例
sign String(32) Y 签名 FA1BA66DE31F653933F695FE00D58858
amount String(32) Y 付款总金额 0.06
merchantno String Y 商户号 60007
orderno String Y synopay订单号 60007201907241724268975
outTradeNo String Y 商户订单号(在付款时外部由自定生成规则传入) 201810101211302123
channel String Y 支付渠道 ALPPC
paymentState String Y 订单状态 3、取消 4、待处理 1、成功、 0、失败
payment_at String Y 订单支付时间 2019-07-24 17:24:57

海关编号

支付宝

海关名称 海关编码
杭州海关 HANGZHOU_ZONGSHU
广州海关 ZONGSHU
河南保税物流中心 ZHENGZHOU
新郑综合保税区(空港)(先推送HENAN报送地方国检,再推送ZONGSHU) HENAN, ZONGSHU
宁波海关 NINGBO
重庆海关 ZONGSHU
深圳海关(先推送SHENZHEN_ZS报送地方国检,再推送ZONGSHU) SHENZHEN_ZS, ZONGSHU
上海海关 SHANGHAI_CBT
西安海关 ZONGSHU
南沙国检 NANSHAGJ
天津海关 ZONGSHU
合肥海关 ZONGSHU
苏州海关 ZONGSHU
广州黄埔海关 GUANGZHOU_HUANGPU

英文版