1 API设计文档

1.1 接入说明

第三方页游接入只允许以划账的模式接入，即计费中心只提供通宝充值游戏币的接口，向第三方用户账户充值游戏币。关于货币体系说明参见#货币体系及支付场景说明。

1.2 划账流程

划账体系处理流程如下图：

注：

• 单次交易的最大时间为5分钟，如果5分钟未得到发货确认，系统自动回滚预冻的账户，并将订单状态标记为“取消”。
• 第10步确认发货第三方可以反复调用，以防止确认请求超时，直到得到接口服务器的确认，或超过单次交易的最大时间。
• 用户确认支付后理论上应该在5s内完成交易，如果超过此时间，前端显示友好提示。

1.3 API调用时序

如上图所示：

步骤	步骤说明	调用的接口
Step1	应用调用支付接口获取交易订单以及支付URL。即上图中的第2步。	发起通宝充值游戏币
Step2	打开上一步中获取的支付URL进行支付。即上图中的第5步。	打开支付页面
Step3	奕奕回调应用的发货URL。即上图中的第7步	回调发货URL
Step4	应用调用发货通知接口。即上图中的第10步	应用调用发货通知

2 API详细说明

2.1 Step1 发起通宝充值游戏币

调用地址:

    正式地址：http://api.unipay.5211game.com/v0/pay/exchange_goods.aspx

    测试地址：http://101.226.247.45:8030/v0/pay/exchange_goods.aspx

调用方式：GET,POST

参数说明：

参数	必选	类型	描述
uid	True	int	奕奕用户Id。
access_token	True	string	用户登录后,认证系统返回的token。
appid	True	long	申请应用时分配的AppId。
sig	True	string	请求串的签名，以app_secret作为密钥，具体签名算法见 奕奕开放平台第三方应用签名参数sig的说明。
userip	True	string	用户Ip。
ts	True	long	linux时间戳，以秒为单位。 注意开发者的机器时间与奕奕计费开放平台的时间相差不能超过5分钟。
zonename	True	string	分区中文名称，支付确认页面上显示。
zoneid	True	int	分区id，支付发货回调时返回给第三方应用。
moneyname	True	string	虚拟货币名称，支付页面显示时使用。
amount	True	int	充值虚拟货币额度：支付确认页面显示，发货时提供。
tbvalue	True	int	这笔交易对应的通宝价值。
deliver_url	True	string	此次交易发货回调地址。

返回结果：

类型：JSON

说明：

参数	描述
ret	返回码。具体返回码含义详见下文。
msg	如果错误，返回错误信息 utf-8。
token	交易订单号用于后续支付流程。后续交易订单有效期为5分钟，如果5分钟后使用次订单则会返回订单无效错误。
url_params	支付链接参数，原封不动的提供给奕奕支付跳转链接即可。

2.2 打开支付页面

您在上一步获取了订单支付的唯一地址后，可以将页面打开，提供用户进行下一步的支付行为。

2.3 回调发货URL

调用地址:

    http://[第三方发货服务器地址]

    例如：http://www.iamgame.com/payconfirm.aspx 或者 http://www.payok.com/payconfirm.php

调用方式：POST

参数说明：

参数	必选	类型	描述
uid	True	int	奕奕用户Id。
appid	True	long	申请应用时分配的AppId。
ts	True	long	linux时间戳，以秒为单位。 注意开发者的机器时间与奕奕计费开放平台的时间相差不能超过5分钟。
amount	True	int	充值虚拟货币数量。
token	True	string	应用调用 发起通宝充值游戏币 接口成功返回的交易token。 注意，交易token的有效期为5分钟，必须在获取到token后的5分钟内传递该token，否则将会返回token不存在的错误。
billno	True	string	支付流水号。用于对账。
version	True	string	协议版本号。
zoneid	True	int	游戏的分区id。
sig	True	string	请求串的签名，由需要签名的参数生成。具体签名算法见 奕奕开放平台第三方应用签名参数sig的说明。

返回结果：

类型：JSON

说明：

参数	描述
ret	返回码。0成功，其他为错误。
msg	如果错误，返回错误信息 utf-8。

2.4 应用调用发货通知

接口说明：

调用本接口后，奕奕支付后台的处理方式如下：

1. 当奕奕支付后台在5秒内收到第三方应用的发货响应，则直接展示交易结果，交易成功的话则立刻完成扣款，交易结束。

2. 当奕奕支付后台检测到第三方发货超过5秒时：

（1）奕奕支付后台不会立刻认为交易失败，而是将交易暂时挂起，同时冻结用户本次支付的金额，并提示用户交易进行中。：

注：界面上提示“交易进行中”主要是为了让界面更友好，原因还需要具体分析，看到底是发送超时还是接受超时。

回调发货要经过公网，可能的超时包括发送超时及接受超时两种情况。对于发送超时（可能是由于接入支付时填错了发货IP导致的），第三方应用会收不到发货请求，同时奕奕后台系统提示用户交易进行中。

（2）此后奕奕支付后台等待第三方应用的发货通知。应用在进行发货后应该调用本接口通知奕奕后台已经发货。如果最终发货成功，则完成扣款，否则不扣款。

调用说明：

在调用该接口前，请务必注意如下事项：

关注点	注意事项
调用时间	1. 本接口必须在回调发货处理完成后再发起，建议异步实现。
	2. 奕奕支付后台回调发货URL后，等待发货通知的最长时间为5分钟，如果超出5分钟后收到发货通知，则认为交易失败。因此请在回调发货处理完成后5分钟之内调用本接口。
调用次数	3. 由于应用无法得知奕奕支付后台是否在5s内收到应用成功发货的返回，故需要对每一次发货都进行结果通知。 为避免通知失败，本接口可以重复调用，直到收到奕奕支付服务器的响应。
返回结果	4. 本接口通知的发货结果（即参数provide_errno）必须和回调发货时的响应结果（即回调发货接口的返回码ret）一致，否则会被奕奕支付系统认为本笔交易异常。
	5. 该接口只是通知接口，返回结果只表明奕奕支付侧是否收到发货结果，最终的支付结果请以提供的账单为准。
	6. 每笔交易是否扣款都是以回调发货的返回错误码为依据，仅发货超时和返回信息格式不合法会触发平台挂起订单，等待异步调用本接口通知发货结果。
	7.异步通知发货结果仅为一个补通知的环节，平台交易以回调发货时的响应结果为准，且异步通知发货结果仅对已挂起的订单起作用，如果在回调发货时交易就结束，即使异步通知也不能改变订单状态。
其它	8.回调发货返回成功，而异步通知告知平台发货失败，被视为有假发货嫌疑，订单不会改变状态，交易成功。
	9.回调发货失败多次，会触发平台的锁定策略，可能导致收入受损，请尽可能提高回调发货的成功率。

调用地址:

    正式地址：https://api.unipay.5211game.com/v0/pay/confirm_exchange.aspx

    测试地址：http://101.226.247.45:8030/v0/pay/confirm_exchange.aspx

调用方式：POST

参数说明：

参数	必选	类型	描述
uid	True	int	奕奕用户Id。
access_token	True	string	用户登录后,认证系统返回的token。
appid	True	long	申请应用时分配的AppId。
sig	True	string	请求串的签名，以app_secret作为密钥，具体签名算法见 奕奕开放平台第三方应用签名参数sig的说明。
userip	False	string	用户ip
ts	True	long	linux时间戳，以秒为单位。 注意开发者的机器时间与奕奕计费开放平台的时间相差不能超过5分钟。
token	True	string	应用调用 发起通宝充值游戏币 接口成功返回的交易token。 注意，交易token的有效期为5分钟，必须在获取到token后的5分钟内传递该token，否则将会返回token不存在的错误。
billno	True	string	支付流水号。通过解析 回调发货URL 时传入的billno获得该参数的值。
version	False	string	协议版本号。
zoneid	True	int	分区id，支付回调发货时传递的分区号。
provide_errno	True	int	发货结果，0：表示发货成功，其他：表示失败。输入的值请务必与 回调发货URL 时的返回码ret的值一致，否则会被奕奕支付系统认为本笔交易异常
provide_errmsg	False	string	发货结果描述，最长为128字节。
amount	True	int	发放的游戏币数量。

返回结果：

类型：JSON

说明：

参数	描述
ret	返回码。0成功，其他为错误。
msg	如果错误，返回错误信息 utf-8。

3 第三方应用参数签名规则

2.1 构造源串

源串是由3部分内容用“&”拼接起来的： HTTP请求方式 & urlencode(uri) & urlencode(a=x&b=y&...)

源串构造步骤如下：

第1步：将请求的URI路径进行URL编码（URI不含host，URI示例：v0/pay/exchange_goods.aspx）。
请开发者关注：URL编码注意事项，否则容易导致后面签名不能通过验证。

第2步：将除“sig”外的所有参数按key进行字典升序排列。
注：除非文档中特别标注了某参数不参与签名，否则除sig外的所有参数都要参与签名。

第3步：将第2步中排序后的参数(key=value)用&拼接起来，并进行URL编码。
请开发者关注：URL编码注意事项，否则容易导致后面签名不能通过验证。

第4步：将HTTP请求方式（GET或者POST）以及第1步和第3步中的字符串用&拼接起来。

2.2 构造密钥

得到密钥的方式：在应用的app_secret末尾加上一个字节的“&”，即app_secret&，例如：228bf094169a40a3bd188ba37ebe8723&

2.3 生成签名值

1. 使用HMAC-SHA1加密算法，使用Step2中得到的密钥对Step1中得到的源串加密。
（注：一般程序语言中会内置HMAC-SHA1加密算法的函数，例如PHP5.1.2之后的版本可直接调用hash_hmac函数。）

2. 然后将加密后的字符串经过Base64编码。
（注：一般程序语言中会内置Base64编码函数，例如PHP中可直接调用 base64_encode() 函数。）

3. 得到签名结果

2.4 请求示例

本接口的签名生成较为复杂，许多应用在此出错，因此下面演示了sig签名的生成细节。开发者可以下面的示例来验证sig的计算方法，但不能直接复制。

method:POST

url_path: v0/pay/confirm_exchange.aspx

假设app_secret为： 1a3dbdef4a1b4e4ea36095cd74cd0f19

请求参数包括：

则生成sig时构造的源串为：

生成sig时构造的密钥为：

生成的签名为：

URL编码前的请求：

URL编码后的请求：

2.5 URL编码注意事项

URL编码规则：

签名验证时，要求对字符串中除了“-”、“_”、“.”之外的所有非字母数字字符都替换成百分号(%)后跟两位十六进制数。十六进制数中字母必须为大写。

注意事项：

1. 某些系统方法，例如.NET系统方法HttpUtility.UrlEncode会将‘=’编码成‘%3d’，而不是%3D，导致加密签名通不过验证，请开发者注意检查。

2. 某些语言的urlencode方法会把“空格”编码为“+”，实际上应该编码为“%20”。这也将生成错误的签名，导致签名通不过验证。

请开发者注意检查，手动将“+”替换为“%20”。

在PHP中，推荐用rawurlencode方法进行URL编码。