Payments integration API

Base diagram of dialogs between game site and game are shown on Pict.1.

schema.png

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 nameTypeDescriptionIs parameter mandatoryPossible valuesLimits
projectIdIntegerProject identifier on game siteMandatory1234 
userIdStringUsers identification number in game site (game know this parameter) Mandatory2516 char
actionStringThis parameter is used for action identifications (for example: site currency info request)Mandatoryinfo, buy4 char
serverStringGame's server nameMandatory 128 char
characterNameStringUser's ingame character nameMandatory 128 char
amountIntegerQuantity of buying game currencyMandatory (Not mandatory in case, when action = info)100 
priceIntegerPrice of game currency pack in Coins.Mandatory (Not mandatory in case, when action = info)10 
signStringMD5 hash which used for data sign.Mandatory (in case when action = buy)81861fc1957d8cba34057451ac81d68c32 char
param1StringAdditional users or transaction identifierOptional 256 char
param2StringAdditional users or transaction identifierOptional 256 char
param3StringAdditional users or transaction identifierOptional 256 char
responseFomatStringResponse format identifier. Default value JSONOptionaljson, xml4 char
user_balanceStringResponse. In this field will returned users balance 100 
notEnoughMoneyBooleanParameter to test "not enough money" error in Sandbox.Optional, default - falsetrue, 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&param1=just_for_test&sign=81861fc1957d8cba34057451ac81d68c

Response codes and description are shown in table 2.

Table 2. Response codes

Response codeDescriptionInformation
0OKCan be returned in any case. This is success code.
1Not enough money for purchaseCan be returned when action = buy. This is error code.
2Wrong checksumCan be returned when action = info or buy. This is error code.
3User not existCan be returned when action = info or buy. This is error code.
4Temporary errorSometimes shit happens, but I hope, you never receive this cod.
6Unknown actionCan be returned only in case when action != (info, buy). This is error code.
7Incomplete dataCan be returned only in case, when not all mandatory params are received. This is error code.
8Wrong project idCan be returned in case when project ID not registered in system or not valid. This is error code.
9No information foundCan 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"}

Помощь