TOPPay 托管式界面接入文档
一、概述
本文档是海外支付的统一接口规范和开发指南。主要提供MG平台服务器和CP(产品内容提供者)服务器之间的交互接口规范。本文主要描述海外支付的接入和使用方法，该文档仅供研发接入参考。涉及到本地化支付的业务合同，需前置告知开发者有关于发货toppay这边的实际通知机制为多次，做前置风险规避，该条款为Meetgames的免责声明。
二、接入前准备
- 接入前期准备工作，在Meetgames控制台创建游戏后获取以下参数：
| 参数名称 | 参数说明 |
|---|---|
| appId | 平台分配给CP的应用 AppID |
| secretKey | 平台分配给CP的本地化支付秘钥 PaySecret |
- 接入前期准备工作，在Meetgames控制台配置充值回调接口：
| 参数名称 | 参数说明 |
|---|---|
| 充值结果回调接口 | 即充值结果通知地址，当支付成功后，MG平台服务器会将支付结果回调给该接口 |
三、通信协议
本接口采用HTTP 协议作为通信协议，调用方通过构造HTTP 请求（POST/GET 方式）发起接口请求。
请求与响应内容采用UTF-8字符编码
服务器请求示例
POST https://api-gamepay.meetsocial.com/xxx/xxx
Content-Type: application/json
success
- 响应数据示例
Content-Type: application/json
{
"code": 0,
"message": "success",
"result": {
"xxx": "xxx",
}
}
- 响应错误数据示例
Content-Type: application/json
{
"code": 5003,
"message": "parameter_error",
"success": false
}
四、接口列表
1、创建订单接口
接口描述：此接口会返回收银台url，地址有效时长为24小时
返回数据格式：JSON
版本：2
HTTP请求方式：POST
请求方：CP服务器
响应方：MG平台服务器
请求参数
| 字段名称 | 类型 | 是否必填 | 备注 |
|---|---|---|---|
| appId | Long | 是 | 支付应用id（在Meetgames平台获取AppId） |
| outTradeNo | String | 是 | CP订单号（字符限制长度64） |
| currencyCode | String | 是 | 货币编号, 如USD |
| amount | Long | 是 | 订单总金额（货币最小单位，如美分）例子：1000 |
| orderSign | String | 是 | 密钥（参照下面的加密方式） |
| product | Object | 是 | 查看product对象 |
| redirectUrl | String | 否 | 支付成功后跳转地址，不传默认不会回跳，会停留在收银台结果页 |
| ip | String | 否 | 用户IP，建议传入，能提高支付成功率和风控准确率 |
| roleId | String | 否 | 角色ID，建议传入，能提高支付成功率和风控准确率 |
| String | 否 | 用户邮箱，建议传入，能提高支付成功率和风控准确率 | |
| phone | String | 否 | 用户手机号，建议传入，能提高支付成功率和风控准确率 |
| locale | String | 否 | 不传默认为en，您的付款页面的语言设置。选项包括：en, zh, ja, ko, ar, fr, es, de, it, nl |
- product对象：
| 字段名称 | 类型 | 是否必填 | 备注 |
|---|---|---|---|
| productId | String | 是 | 商品ID（字符限制长度64） |
| productName | String | 是 | 商品名（字符限制长度64） |
| price | Long | 是 | 商品售价（货币最小单位，如美分）例子：1000 |
| productCount | int | 是 | 数量 |
| remark | String | 否 | 备注（字符限制长度255） |
- 加密方式
用此方式拼接以amount、outTradeNo、currencyCode、secretKey这4个字段，最终md5对此字符串加密。计算md5签名时，应以utf-8编码取字符串。
如amount=aaaa&outTradeNo=xxx& currencyCode=xxx&secretKey=xxx
- 响应结果
| 字段名称 | 类型 | 备注 |
|---|---|---|
| url | String | 收银台地址 |
| orderNo | String | MG平台服务器订单号 |
| outTradeNo | String | CP订单号 |
{
"code": 0,
"message": "success",
"result": {
"url": "https://xxx",
"orderNo":xxx,
"outTradeNo":xxxxxx
}
}
- Code编码
| 状态码 | 说明 |
|---|---|
| 0 | 成功 |
| 999 | 系统异常 |
| 5003 | 请求参数错误 |
| 5014 | 币种错误 |
| 5017 | 验签校验错误 |
| 5023 | 订单重复提交 |
| 5026 | 该应用未配置支付方式 |
| 5032 | AppId应用已禁用，请联系Meetgames平台 |
2、主动查询支付订单状态接口
- 接口描述：主动查询订单支付状态
- 返回数据支持格式：JSON
- 版本：2
- HTTP请求方式 ：POST
- 请求方：CP服务器
- 响应方：平台服务器
- 请求地址：https://api-gamepay.meetsocial.com/order/queryPayOrder/v2
- 请求参数
| 字段名称 | 类型 | 是否必填 | 备注 |
|---|---|---|---|
| orderNo | String | 是 | MG平台服务器订单号 |
- 响应结果
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
| outTradeNo | Y | String | CP订单号 |
| orderNo | Y | String | MG平台服务器订单号 |
| tradeNo | N | String | 支付渠道流水号 |
| paymentChannelCode | Y | String | 支付方式（目前值为 AIRWALLEX_CREDIT_CARD） |
| paymentAmount | Y | Long | 订单价格（货币最小单位）例子：1000 |
| currencyCode | Y | String | 货币编号, 如USD |
| paymentStatus | Y | String | 回调状态，订单支付成功：Order_Successed , 订单未支付：Order_Unpaid |
| isRefund | Y | bool | 是否已退款, true为已退款成功，false为未退款 |
| isTimeout | Y | bool | MG收银台是否已超时，true为收银台已超时，false为收银台未超时 |
| createdTime | Y | Long | 下单时间戳（在MG平台下单） |
| payTime | N | Long | 支付时间戳（MG调用第三方接口的时间） |
| orderSign | Y | String | md5加密后的签名(参考以下加密方式) |
- 验证充值是否成功，务必在保证sign正确情况下，outTradeNo、paymentAmount、currencyCode也要进行对比，保证充值正确性
- 加密方式：
用此方式拼接以outTradeNo、orderNo、tradeNo、paymentChannelCode、paymentAmount、currencyCode、paymentStatus、isRefund、isTimeout、payTime、secretKey这7个字段，最终md5对此字符串加密。计算md5签名时，应以utf-8编码取字符串。
如outTradeNo=xxx&orderNo=xxx&tradeNo=xxx&paymentChannelCode=xxx&paymentAmount=xxx& currencyCode=xxx&paymentStatus=xxx&isRefund=false&isTimeout=false&payTime=xxx&secretKey=xxx
{
"code": 0,
"message": "success",
"result": {
"outTradeNo": "xxx",
"orderNo": "xxx",
"tradeNo": "xxx",
"paymentChannelCode": "xxx",
"paymentAmount": 1,
"currencyCode": "USD",
"paymentStatus": "Order_Successed",
"isRefund": false,
"isTimeout": false,
"createdTime": 111111111,
"payTime": 111111111,
"orderSign": "xx"
}
}
- 错误Code编码
| 状态码 | 说明 |
|---|---|
| 0 | 成功 |
| 999 | 系统异常 |
| 5024 | 订单不存在 |
3、充值结果回调接口
- 接口描述：即充值结果通知地址，当支付成功后，平台服务器会将支付结果在notify告诉CP服务器,由CP提供地址。
- 返回数据支持格式：JSON
- 版本：2
- HTTP请求方式 ：POST
- 请求方：CP服务器
- 响应方：平台服务器
- 请求地址：cp提供回调地址
- Data信息
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
| outTradeNo | Y | String | CP订单号 |
| orderNo | Y | String | MG平台服务器订单号 |
| tradeNo | N | String | 支付渠道流水号 |
| paymentChannelCode | Y | String | 支付方式（目前值为 AIRWALLEX_CREDIT_CARD） |
| paymentAmount | Y | Long | 订单价格（货币最小单位）例子：1000 |
| currencyCode | Y | String | 货币编号, 如USD |
| paymentStatus | Y | String | 回调状态，订单支付成功：Order_Successed |
| isRefund | Y | bool | 是否已退款, true为已退款成功，false为未退款 |
| isTimeout | Y | bool | MG收银台是否已超时，true为收银台已超时，false为收银台未超时 |
| createdTime | Y | Long | 下单时间戳（在MG平台下单） |
| payTime | N | Long | 支付时间戳 (在第三方通道下单) |
| orderSign | Y | String | md5加密后的签名(参考以下加密方式) |
- 验证充值是否成功，务必在保证orderSign正确情况下，outTradeNo、paymentAmount、currencyCode也要进行对比，保证充值正确性
- 加密方式
用此方式拼接以outTradeNo、orderNo、tradeNo、paymentChannelCode、paymentAmount、currencyCode、paymentStatus、isRefund、isTimeout、payTime、secretKey这7个字段，最终md5对此字符串加密。计算md5签名时，应以utf-8编码取字符串。
如outTradeNo=xxx&orderNo=xxx&tradeNo=xxx&paymentChannelCode=xxx&paymentAmount=xxx& currencyCode=xxx&paymentStatus=xxx&isRefund=false&isTimeout=false&payTime=xxx&secretKey=xxx
- 响应数据说明（如果对应的订单CP已经处理完成，请保持返回
"true"字符串）
| 响应内容 | 描述 |
|---|---|
| true | true表示处理订单成功，MG平台服务端方收到响应true后不会再通知给cp方（也可返回其他错误信息，MG平台服务器方收到true以外的字符串后都会多次重复通知） |
五、接口备注
在用户支付订单完成后，MG平台服务器会向商户方服务器发起通知，并异步不断尝试直到获取结果。以下为异步通知接口说明：
必须保证服务器异步通知页面(webhook_url)上无任何字符,如空格、HTML 标签、开发系统自带抛出的异常提示信息等;
程序执行完后必须打印输出“true”(不包含引号，不能加入换行符，缩进符等不可见字符)。如果商户反馈给平台服务器的字符不是 true 这 4 个字符,平台服务器会不断重发通知,一般情况下, 一共7次通知(再次通知时间从首次通知失败后，按2m、10m、10m、1h、2h、6h、12h时间规则执行)。7次结束之后将不在重试。
cookies、session 等在此页面会失效,即无法获取这些数据;
该方式的调试与运行必须在服务器上,即互联网上能访问;
CP方不仅要对回调的签名进行验证，还需要对回调的金额进行比对，两方一致方可发货，避免用户造假篡改订单内容
六、支付测试
- 测试支付时，请使用外币种储蓄卡或信用卡