Payments integration API
Base diagram of dialogs between game site and game are shown on Pict.1.
Pict.1.
Schema of Requests and Responses between game and game site
1. Info Request
This request is optional. This request can be used for receiving information about users balance on the game site and game currency.
For performing this step, game must send Post or Get request on game site payments application with following parameters:
- projectId
- userId
- action=info
- sign
(For more information and parameter description see Table 1)
Example:
For this example we use follow values:
- projectId = 12
- userId = 123
- action=info
shared password: sharedPassword
value off parameter sign is calculation in follow steps:
you must take value from projectId, userId, action and shared password, after them you must concatenate this values to the string and perform md5 hash calculating.
For this example:
md5('12123infosharedPassword')
Example of Request:
https://api.rbkgames.com/api/callback/paymentsApi?projectId=1&userId=123&action=info&sign=e93014c0d0cd35b9bb12ddf76dca68e1
After Request you will return the follow answer (In JSON format):
{"projectId":12,"userId":123,"action":"info","remoteIp":"127.0.0.1","user_balance":100,"result":0,"description":"OK"}
*you can select format of returned data. By defaults format is JSON, but you can switch format of response to XML format, for more details see Table 1.
2. Buy Request
This step is for site currency to game currency exchanging (buying)
In this Request game must send Post or Get request on game site payments application with following parameters:
- projectId
- userId
- action
- amount
- price
- server
- characterName
- sign
+ secret key.
This is minimal set of the parameters, what should be in request. Full description of parameters are shown in Table1.
Value off parameter sign is calculation in follow steps:
you must take value from projectId, userId, action, amount, price and shared password, after them you must concatenate this values to the string and perform md5 hash calculating.
Example of signature generation for next case:
- projectId: 1234
- userId: 123
- action: buy
- amount: 100
- price: 10
- secret key: sharedPassword
md5 = (“1234123buy10010sharedPassword”)
Table 1. Description of transmitted data
| Parameter name | Type | Description | Is parameter mandatory | Possible values | Limits |
|---|---|---|---|---|---|
| projectId | Integer | Project identifier on game site | Mandatory | 1234 | |
| userId | String | Users identification number in game site (game know this parameter) | Mandatory | 25 | 16 char |
| action | String | This parameter is used for action identifications (for example: site currency info request) | Mandatory | info, buy | 4 char |
| server | String | Game's server name | Mandatory | 128 char | |
| characterName | String | User's ingame character name | Mandatory | 128 char | |
| amount | Integer | Quantity of buying game currency | Mandatory (Not mandatory in case, when action = info) | 100 | |
| price | Integer | Price of game currency pack in Coins. | Mandatory (Not mandatory in case, when action = info) | 10 | |
| sign | String | MD5 hash which used for data sign. | Mandatory (in case when action = buy) | 81861fc1957d8cba34057451ac81d68c | 32 char |
| param1 | String | Additional users or transaction identifier | Optional | 256 char | |
| param2 | String | Additional users or transaction identifier | Optional | 256 char | |
| param3 | String | Additional users or transaction identifier | Optional | 256 char | |
| responseFomat | String | Response format identifier. Default value JSON | Optional | json, xml | 4 char |
| user_balance | String | Response. In this field will returned users balance | 100 | ||
| notEnoughMoney | Boolean | Parameter to test "not enough money" error in Sandbox. | Optional, default - false | true, false |
Example of request for next case:
User with userId 123 wants to buy 100 game currency, which cost 10 money, in game which have id number 1234. Secret key: sharedPassword, additional parameter param1: just_for_test
https://api.rbkgames.com/api/callback/paymentsApi?projectId=1234&userId=123&action=buy&price=10&amount=100¶m1=just_for_test&sign=81861fc1957d8cba34057451ac81d68c
Response codes and description are shown in table 2.
Table 2. Response codes
| Response code | Description | Information |
|---|---|---|
| 0 | OK | Can be returned in any case. This is success code. |
| 1 | Not enough money for purchase | Can be returned when action = buy. This is error code. |
| 2 | Wrong checksum | Can be returned when action = info or buy. This is error code. |
| 3 | User not exist | Can be returned when action = info or buy. This is error code. |
| 4 | Temporary error | Sometimes shit happens, but I hope, you never receive this cod. |
| 6 | Unknown action | Can be returned only in case when action != (info, buy). This is error code. |
| 7 | Incomplete data | Can be returned only in case, when not all mandatory params are received. This is error code. |
| 8 | Wrong project id | Can be returned in case when project ID not registered in system or not valid. This is error code. |
| 9 | No information found | Can be returned in case when action = info. This is error. |
Example of response (in JSON format)
After request, game site will return response which contain code and description of request result. If response format not shown, data will be returned in JSON format. Response codes and description are shown in table 2.
{"projectId":1234,"userId":123,"action":"buy","amount":100,"price":"10","sign":"81861fc1957d8cba34057451ac81d68c", "remoteIp":"127.0.0.1","result":0,"description":"OK"}
