External management API

1. session_start function. Should be first in a sequence. Parameters are - username, md5(password), key, message
Key is a randomly generated sequence. Msg is a message that contains a description of an
operations, payment method, etc... (Like 'PayPal payment')

Example of invokation: http://url/vpi/index.php?action=session_start&username=payment_gw&password=XXX&key=YOUR_KEY&message=YYY
Return value - xml-file with session_id (string length 128bit) or with fail in a case of error
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<response_code>ok</response_code>
<session>34VDNI123AAWQERWVC56</session>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>
 
2. session_end function. Should be last in a sequence. Parameter are - sequence_id as F(session)
All sessions has a time limitations. It increases error_counter for client, when session was not ended
with session_end call. And may causes to block client.

Example of invokation: http://url/vpi/index.php?action=session_end&sequince_id=YYY
Return values - xml-file with ok or fail.
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>ok</response_code></response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

3. get_provider_list function. Parameters are - sequence_id as F(session), service as string
Example of invokation: http://url/vpi/index.php?action=get_provider_list&sequince_id=YYY&service=rad
Return value - xml-file with a list of providers or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<response_code>ok</response_code>
<providers>
    <provider>
        <id>1</id>
        <name>EkoPLC</name>
    </provider>
    <provider>
        <id>2</id>
        <name>Another Provider</name>
    </provider>
</providers>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

4. get_tariff_list function. Parameters are - sequence_id as F(session), service as string, provider_id as number
Example of invokation: http://url/vpi/index.php?action=get_tariff_list&sequince_id=YYY&service=rad&provider_id=15
Return value - xml-file with a list of tariffs or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<response_code>ok</response_code>
<tariffs>
    <tariff>
        <id>1</id>
        <name>Best time</name>
	<subject>Time</subject>
	<cost>2</cost>
	<currency>EUR</currency>
    </tariff>
    <tariff>
        <id>2</id>
        <name>Another tariff</name>
	<subject>Traffic</subject>
	<cost>2</cost>
	<currency>USD</currency>
    </tariff>
    <tariff>
	<id>2</id>
	<name>Hotel - 24 hours</name>
	<subject>Fixed</subject>
	<cost>12</cost>
	<currency>EUR</currency>
    </tariff>
</tariffs>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

5. disable_user function. Parameters are - sequence_id as F(session), service as string, user_id as number, cause as string
Example of invokation: http://url/vpi/index.php?action=disable_user&sequince_id=YYY&service=rad&user_id=15,cause=XXX
Return value - xml-file with an ok or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>ok</response_code></response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

6. enable_user function. Parameters are - sequence_id as F(session), service as string, user_id as number, cause as string
Example of invokation: http://url/vpi/index.php?action=enable_user&sequince_id=YYY&service=rad&user_id=15,cause=XXX
Return value - xml-file with an ok or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>ok</response_code></response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

7. create_user function. Parameters are - sequence_id as F(session), service as string, tariff_id as number, cause as string
Cause is a message, that contains cause of user creation: action from payment gateway, etc..

Example of invokation: http://url/vpi/index.php?action=create_user&sequince_id=YYY&service=rad&tariff_id=15,cause=XXX
Return value - xml-file with an ok, username, password, user_id and rechrgable flag ('yes' or 'no')
 or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<response_code>ok</response_code>
	<username>TEST</username>
	<password>123</password>
	<user_id>15008</user_id>
	<can_be_recharged>yes</can_be_recharged>
</response>
Created user has zero account balance and has disabled.
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

8. proceed_payment function. Parameters are - sequence_id as F(session), service as string, user_id as number, sum as number, currency as string, doc_id as string, cause as string, hash as string
Cause should contain type of payment (PayPal, Credit card - VISA, etc..)
Currency - currency sign for payment, beacose suite is a multicurrency application.
Doc_id is a unique transaction id from payment gateway processing software.

Example of invokation: http://url/vpi/index.php?action=proceed_payment&sequince_id=YYY&service=rad&user_id=15&sum=10&currency=Euro&doc_id=123&cause=XXX&hash=ZZZ
where hash is md5(concatenation of values of all parameters from left to right)
Return value - xml-file with an ok and amount or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<response_code>ok</response_code>
<amount>12</amount>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

9. get_user_id function. Parameters are - sequence_id as F(session) as string, 
service as string ('rad' for example), uname as string (username), passwd as string (users password).

Example of invokation: http://url/vpi/index.php?action=get_user_id&seqence_id=XXX&service=rad&uname=test1&passwd=abra
Return value - xml-file with on ok, user_id and rechargable flag or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<response_code>ok</response_code>
	<user_id>15009</user_id>
	<can_be_recharged>no</can_be_recharged>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>

10. get_tariff_list_enabled function. Parameters are - sequence_id as F(session), service as string
Example of invokation: http://url/vpi/index.php?action=get_tariff_list_enabled&sequince_id=YYY&service=rad
Return value - xml-file with a list of tariffs, enabled for this gateway's username/password or fail in a case of error.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<response_code>ok</response_code>
<tariffs>
    <tariff>
        <id>1</id>
        <name>Best time</name>
	<subject>Time</subject>
	<cost>2</cost>
	<currency>EUR</currency>
    </tariff>
    <tariff>
        <id>2</id>
        <name>Another tariff</name>
	<subject>Traffic</subject>
	<cost>2</cost>
	<currency>USD</currency>
    </tariff>
    <tariff>
	<id>2</id>
	<name>Hotel - 24 hours</name>
	<subject>Fixed</subject>
	<cost>12</cost>
	<currency>EUR</currency>
    </tariff>
</tariffs>
</response>
or
<?xml version="1.0" encoding="UTF-8" ?>
<response><response_code>fail</response_code></response>



All invokation does through GET-method.
F(session) is
md5(YOUR_KEY+SESSION_ID) for step #1 (First call after session_start) and md5(F(n-1)) for step #n

