External management API

All calls shall be done by GET-method.
Server side replies have 'Content-type: application/json' type and have at least next structure:
where reply
{"response":{"code":"fail"}}
means that call is failed.

And reply like 
{"response":{"code": "ok", "data":{ /* Some data here */}}}
means that call is successfull.

Replies for successfull calls have additional information within "response" body.

First call in an any sequence of calls must be 'session_start'.
Any sequence of calls must be completed by 'session_end' call.
Sequence may contain any number of another calls between 'session_start' and 'session_end'.
Two consecutive calls shall be within 30 seconds interval.


1. 'session_start' function. 
Must be first in the call sequence. 
Parameters are - login, tkn, key, nonce, msg
Where:
'login' is an operator username.
'key' is a reseller API key.
'nonce' is a randomly generated number or character sequence. 
'msg' is a message that contains a description of an following operations, payment method, etc... (Like 'PayPal payment')
'tkn' is a md5 hash of string produced by concatenation (+) of values 'nonce', 'login' and operators password, delimited by symbol ':'.

Code sample: How to get 'tkn' in php.
$tkn = md5($nonce.':'.$login.':'.$password);

Call sample: https://url/vpi/?action=session_start&login=payment_gw&nonce=942617&key=YOUR_API_KEY&msg=Payment%20gateway&tkn=DEADBEAFDEADBEAFDEADBEAFDEADBEAF
Return value - json encoded data with 'ok' and 'seq' value in the 'data' body (string length 128bit) or with 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"seq":"DEADBEAFDEADBEAFDEADBEAFDEADBEAF"}}}

2. 'seq' parameter in consecutive calls.

Derivatives from 'seq' parameter must be used in in every consecutive call except 'session_start'.
To get right 'seq' parameter, client must to get md5 hash from 'seq' parameter used in previous call.

F(1)='seq' /* for step #1 - 'session_start' */
F(n)md5(F(n-1)) /* for step #n */

3. 'session_end' call.
Must be last in the call sequence.
Has the single parameter - 'seq' as md5('seq')

Call sample: https://url/vpi/?action=session_end&seq=01234567890ABCDEF01234567890ABCD
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok"}}

4. 'disable_user' call. 
Parameters are - 'seq' as md5('seq'), 'uid' as number, 'cause' as string
Call sample: https://url/vpi/?action=disable_user&seq=EADBEAFDEADBEAFDEADBEAFDEADBEAFD&uid=15,cause=XXX
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"msg":"User 15 has been disabled: XXX"}}}

5. 'enable_user' call. 
Parameters are - 'seq' as md5('seq'), 'uid' as number, 'cause' as string
Call sample: https://url/vpi/?action=enable_user&seq=ADBEAFDEADBEAFDEADBEAFDEADBEAFDE&uid=15,cause=XXX
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"msg":"User 15 has been enabled: XXX"}}}

6. 'get_uid' call. 
Parameters are - 'seq' as md5('seq'), 'uid' as number, 'user' as string (username) and 'pwd' as string (users password).
Call sample: https://url/vpi/?action=get_uid&seq=DBEAFDEADBEAFDEADBEAFDEADBEAFDEA&user=test1&pwd=abracadabra
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"uid":15, "can_top_up":1 /* 1 - user can top up own account. 0- can not */ }}}

7. 'get_tariff_list' call. 
Has the single parameter - 'seq' as md5('seq')
Call sample: https://url/vpi/?action=get_tariff_list&seq=FDEADBEAFDEADBEAFDEADBEAFDEADBEA
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"tariffs":[
{"id":12, "name":"Best time", "subject":"Time", "cost":2, "currency":"EUR"},
{"id":15, "name":"Another tariff", "subject":"Traffic", "cost":2, "currency":"USD"},
{"id":21, "name":"Hotel 24 hours", "subject":"Fixed", "cost":12, "currency":"EUR"}
]}}}

8. 'create_user' call.
Parameters are - 'seq' as md5('seq'), 'tariff' as number, 'cause' as string.
Cause is a message, that contains cause of user creation: action from payment gateway, etc..

Call sample: https://url/vpi/?action=create_user&seq=BEAFDEADBEAFDEADBEAFDEADBEAFDEAD&tariff=21&cause=XXX
Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"username":"test21", "password":"abracadabra", "uid":15, "can_top_up":0}}}

Attention, please! All created via robo-interface users are blocked by default. 
To be able log in, such user must be enabled by 'enable_user' call.

Attention, please! Created via robo-interface user with flag 'can_top_up':1 has zeroed account. To be able to log in, 
such user must top up account first.

9. 'proceed_payment' call. 
Parameters are - 'seq' as md5('seq'), 'uid' as number, 'cause' as string, 'sum' as number, 'doc' as string, 'hash' as string
'cause' should contain type of payment (PayPal, Credit card - VISA, etc..)
'doc' is a unique transaction id from payment gateway processing software or reference to internal document of reseller.

Call sample: https://url/vpi/?action=proceed_payment&seq=EAFDEADBEAFDEADBEAFDEADBEAFDEADB&uid=15&sum=10&doc=123&cause=XXX&hash=ZZZ
where hash is md5(concatenation of values of all parameters except hash from left to right)
'hash' is a md5 hash of string produced by concatenation (+) of values 'seq', 'uid', 'sum', 'doc', 'cause', delimited by symbol ':'.

Code sample: How to get 'hash' in php.
$hash = md5($seq.':'.$uid.':'.$sum.':'.$doc.':'.$cause);

Return value - json encoded data with 'ok' or 'fail' in a case of error

{"response":{"code": "fail"}} 

{"response":{"code": "ok", "data":{"uid":15, "sum":10, "action":"Top up"}}}


10. Sequence sample.

Please note: To prevent misunderstanding, 'seq' parameter in a samples will be represented as md5(...).

10.1 Start the session

https://url/vpi/?action=session_start&login=payment_gw&nonce=942617&key=YOUR_API_KEY&msg=Reseller%20pint&tkn=md5(942617:payment_gw:$password)

{"response":{"code": "ok", "data":{"seq":"DEADBEAFDEADBEAFDEADBEAFDEADBEAF"}}}

10.2 Get list of available tariffs

https://url/vpi/?action=get_tariff_list&seq=md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF)

{"response":{"code": "ok", "data":{"tariffs":[
{"id":12, "name":"Best time", "subject":"Time", "cost":2, "currency":"EUR"},
{"id":15, "name":"Another tariff", "subject":"Traffic", "cost":2, "currency":"USD"},
{"id":21, "name":"Hotel 24 hours", "subject":"Fixed", "cost":12, "currency":"EUR"}
]}}}

10.3 Create new user for tariff 12 "Best time"

Call sample: https://url/vpi/?action=create_user&seq=md5(md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF))&tariff=12&cause=New%20ticket%20creation

{"response":{"code": "ok", "data":{"username":"vZ12RfGy", "password":"RT12qWViu", "uid":115, "can_top_up":1}}}

10.4 Enable created user

Call sample: https://url/vpi/?action=enable_user&seq=md5(md5(md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF)))&uid=115,cause=New%20ticket%20creation

{"response":{"code": "ok", "data":{"msg":"User 115 has been enabled: New ticket creation"}}}

10.5 Top up account

https://url/vpi/?action=proceed_payment&seq=md5(md5(md5(md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF))))&uid=115&sum=10&doc=123&cause=Cashdesk&hash=md5(md5(md5(md5(md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF)))):115:10:123:Cashdesk)

{"response":{"code": "ok", "data":{"uid":115, "sum":10, "action":"Top up"}}}

10.6 Close session

https://url/vpi/?action=session_end&seq=md5(md5(md5(md5(md5(DEADBEAFDEADBEAFDEADBEAFDEADBEAF)))))

{"response":{"code": "ok"}}
