方案图

方案图.png

一般支付API文档

参考此文档开发API

商户私钥生成方法

openssl genrsa -out app_private_key.pem 2048  #生成私钥
openssl pkcs8 -topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -out app_private_key_pkcs8.pem #Java需要将私钥转换成PKCS8格式
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem #生成公钥

经过以上步骤,开发者可以在当前文件夹中(OpenSSL运行文件夹),看到app_private_key.pem(RSA私钥,非Java适用)、app_private_key_pkcs8.pem(pkcs8格式RSA私钥,Java适用)和app_public_key.pem(开发者RSA公钥)3个文件。开发者将私钥保留,将公钥上传到平台,用于验证签名。

公钥需要去除 -----BEGIN PUBLIC KEY----------END PUBLIC KEY----- 并转成一行字符串

公共参数

参数类型是否必填最大长度描述示例值
appIDString32平台分配的应用ID2019042300007148
mchIDString32平台分配的商户ID2019042600005436
signTypeString10生成签名字符串所使用的签名算法类型,目前支持SHA256WithRSASHA256WithRSA
signString344商户请求参数的签名串,详见签名详见示例
deviceInfoString256终端设备信息{"phone": "130xxxxxxxx"}
nonceStrString64随机字符串7JcFHZLaYHjzDZRCdXCZWoXg

公共返回结果

参数类型是否必填最大长度描述示例值
appIDString32调用接口时提供的应用ID2019042300007148
mchIDString32调用接口时提供的商户ID2019042600005436
nonceStrString64服务器返回的随机字符串7JcFHZLaYHjzDZRCdXCZWoXg
signTypeString10服务器使用的签名算法类型,目前支持SHA256WithRSASHA256WithRSA
signString344服务器提供的签名,详见验签详见示例

签名

1.将消息体序列化为JSON(不包含sign字段且要求为未经过pretty的最小JSON)
2.对消息体执行SHA256WithRSA签名过程(标准算法)
    2.1 对消息体进行SHA256取得摘要
    2.2 用开发者私钥对摘要进行RSA加密
    2.3 上步的结果即为平台所需要的签名

验签

1.将消息体序列化为JSON(不包含sign字段且要求为未经过pretty的最小JSON)
2.对消息体执行SHA256WithRSA验签过程(标准算法)
    2.1 对消息体进行SHA256取得摘要
    2.2 用平台公钥对摘要进行RSA解密
    2.3 上步结果与sign对比,一致即为验签通过

错误码

Code描述原因解决方案
100001参数错误参数格式有误或者未按规则上传请确认参数问题
100002appID不存在系统中缺少APPID请检查appID,或联系管理员分配
100003mchID不存在系统中缺少mchID请检查mchID,或联系管理员分配
100004appID与mchID不匹配提供的appID与mchID不匹配请检查mchID与appID是否匹配
100005签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
100006散户订单号重复同一笔交易不能多次提交请核实商户订单号是否重复提交

统一下单接口

请求地址

环境HTTPS请求地址HTTP方法请求 Content-Type返回 Content-Type
正式环境pay/orderPOSTapplication/json; charset=utf-8application/json; charset=utf-8

请求参数

参数类型是否必填最大长度描述示例值
bodyString128商品描述VIP1充值
detailString4096商品详情VIP1会员充值
customDataString1024用户自定义数据 查询订单时原样返回{"foo":"bar"}
externalOrderIDString256商户订单号8B4TtR228vrJ863eiuNCTB38
currencyCodeString16货币类型BTC
amountInt64bit订单金额666
timeExpireString24订单失效时间 最长为订单调用时刻 + 10天2019-06-03T16:00:00.000Z
limitPayString32限制支付方式,多个方式用,号分割BTC,ETH
notifyURLString1024退款结果回调地址

返回结果

当HTTP Code为 200

参数类型是否必填最大长度描述示例值
payIDString128支付订单号B8r97wQ22cNk2GUX46c4ju4D

当HTTP Code为 500

参数类型是否必填最大长度描述示例值
codeInt64bit错误码详见错误码
detailString4096详情详见错误码

收银台页面

请求地址

环境HTTPS请求地址HTTP方法
正式环境pay/order/{:payID}GETapplication/json; charset=utf-8application/json; charset=utf-8

查询订单

请求地址

环境HTTPS请求地址HTTP方法请求 Content-Type返回 Content-Type
正式环境pay/order/{:externalOrderID}GETapplication/json; charset=utf-8application/json; charset=utf-8

请求参数

参数类型是否必填最大长度描述示例值
externalOrderIDString256商户订单号8B4TtR228vrJ863eiuNCTB38

返回结果

当HTTP Code为 200

参数类型是否必填最大长度描述示例值
currencyCodeString16货币类型BTC
amountInt64bit订单金额666
paymentTimeString24订单支付时间2019-06-03T16:00:00.000Z
payIDString128支付订单号8B4TtR228vrJ863eiuNCTB38
tradeStatusString4096交易状态SUCCESS
SUCCESS — 支付成功
REFUND — 退款
NOTPAY — 未支付
CLOSED — 已关闭
USERPAYING -- 用户支付中
PAYERROR -- 支付失败(未知原因原因)

当HTTP Code为 500

参数类型是否必填最大长度描述示例值
codeInt64bit错误码详见错误码
detailString4096详情详见错误码

关闭订单

暂未实现

请求地址

环境HTTPS请求地址HTTP方法请求 Content-Type返回 Content-Type
正式环境pay/order/{:externalOrderID}/closePOSTapplication/json; charset=utf-8application/json; charset=utf-8

申请退款

请求地址

环境HTTPS请求地址HTTP方法请求 Content-Type返回 Content-Type
正式环境pay/order/{:externalOrderID}/refundPOSTapplication/json; charset=utf-8application/json; charset=utf-8

请求参数

参数类型是否必填最大长度描述示例值
externalOrderIDString256商户订单号8B4TtR228vrJ863eiuNCTB38
currencyCodeString16货币类型BTC
refundAmountInt64bit退款金额666
refundDescString256退款原因,若商户传入,会在下发给用户的退款消息中体现退款原因
notifyURLString1024退款结果回调地址

返回结果

当HTTP Code为 200

当HTTP Code为 500

参数类型是否必填最大长度描述示例值
codeInt64bit错误码详见错误码
detailString4096详情详见错误码

查询退款

请求地址

环境HTTPS请求地址HTTP方法请求 Content-Type返回 Content-Type
正式环境pay/order/{:externalOrderID}/refundGETapplication/json; charset=utf-8application/json; charset=utf-8

请求参数

参数类型是否必填最大长度描述示例值
externalOrderIDString256商户订单号8B4TtR228vrJ863eiuNCTB38

返回结果

当HTTP Code为 200

参数类型是否必填最大长度描述示例值
currencyCodeString16货币类型BTC
refundAmountInt64bit退款金额666
refundDescString 退款原因,若商户传入,会在下发给用户的退款消息中体现退款原因
refundStatusString32退款状态SUCCESS
SUCCESS—退款成功
EFUNDCLOSE—退款关闭
PROCESSING—退款处理中
refundChannelString32退款渠道ORIGINAL
ORIGINAL—原路退款
OTHER—其他渠道

当HTTP Code为 500

参数类型是否必填最大长度描述示例值
codeInt64bit错误码详见错误码
detailString4096详情详见错误码

支付结果通知

将查询订单接口结果直接POST到notifyURL参数指定的地址
Body Content-Type 为 application/json; charset=utf-8
接口成功处理需返回200
处理异常返回500
平台会尝试再次推送(总共3次)
注意验证服务器签名

退款结果通知

将查询退款接口结果直接POST到notifyURL参数指定的地址
Body Content-Type 为 application/json; charset=utf-8
接口成功处理需返回200
处理异常返回500
平台会尝试再次推送(总共3次)
注意验证服务器签名