Web integration API

From BetgamesTV
(Redirected from Standard Web API v1.0)
Jump to navigation Jump to search

BetGames.TV Partner API

API process flow.png

API process flow.

Game communication processes:

  1. Iframe game client sends requests to BetGames.TV server;
  2. BetGames.TV server communicates with Partner API to withdraw / deposit players money.

In order to integrate BetGames.TV game client, partner (you) is obliged to implement simple XML-based API described in this document.

Integration involves these steps:

  1. Implementation of Partner API in Partner testing environment;
  2. Passing all the test procedures with BetGames.TV engineer (note: before testing procedures please provide a test token page);
  3. Customization of html iframe client in compliance with Partner web-portal design (note: please check "Proper Way to Present Betgames.tv on your website.pdf");
  4. Launching in a production environment.

This document describes Partner API.

Token system

On game initialization Partner server generates alphanumeric string called Token and passes it to the client javascript code. This string should satisfy these requirements:

  1. Contain both letters and digits;
  2. Be minimum 10 symbols and maximum 100 symbols lenght;
  3. Be unique for each player;
  4. Expire after a short period of time (should be configurable, by default 1 minute, but for production has to be changed to 60 minutes).

Important: each successful API method call refreshes token lifetime.

Partner is responsible for implementing token logic.

Token correctness is being tested by BetGames.TV side during testing procedure.

Security check

In order to check the validity of the requests and responses, all the xml packets are being signed. Packets contain “signature” and “time” parameters. Before the request is being proceeded, API should perform validity check of the signature. And perform the validity check of the request creation time. Responses are being signed and checked the same way.

Time parameter

All the requests and responses should contain time parameter. It is equal to the number of seconds since Unix Epoch (January 1 1970 00:00:00 GMT). In PHP there is a method time(), which returns this value. Other programming languages also have similar methods. During XML packet validation, this value should also be checked. If the time of XML packet creation till this validation is more than 60 seconds, this packet is considered to be expired and invalid. The proper error should be returned.

Request example:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>ping</method>
    <token>-</token>
    <signature>6094dc0397895ee55c93b01f54477527</signature>
    <time>1423124661</time>
    <params></params>
</root>

Example of successful response:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>ping</method>
    <token>-</token>
    <success>1</success>
    <error_code>0</error_code>
    <error_text></error_text>
    <time>1423124663</time>
    <params></params>
    <signature>dee0dda6b4adc6c4e0f67c7e19a3ad0b</signature>
</root>

Signature parameter

Signature is being calculated as MD5 sum of all the parameters and secret key concatenation. Secret key is being generated for each partner personally.

Singnature generation is being explained in following example. We need to sign the following response:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>get_account_details</method>
    <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
    <success>1</success>
    <error_code>0</error_code>
    <error_text></error_text>
    <time>1423127764</time>
    <params>
        <user_id>150205</user_id>
        <username>test_player</username>
        <currency>eur</currency>
        <info>Vilnius, LT</info>
    </params>
</root>
  1. Assemble the parameters string (it's important to assemble parameters in the right order): methodget_account_detailstokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423127764user_id150205usernametest_playercurrencyeurinfoVilnius, LT Response string must be builded in the same order as XML elements are. Additional parameters (params) are being added in the end of this string in the same order they are going in the request.
  2. Add current partner secret key. We receive the following string: methodget_account_detailstokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423127764user_id150205usernametest_playercurrencyeurinfoVilnius, LT1JD4U-S7XB6-GKITA-DQXHP
  3. Calculate MD5 for the received string: ca9fd88a49f039f5bde952c31247f09a
  4. Singing the response:
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>get_account_details</method>
    <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
    <success>1</success>
    <error_code>0</error_code>
    <error_text></error_text>
    <time>1423127764</time>
    <params>
        <user_id>150205</user_id>
        <username>test_player</username>
        <currency>eur</currency>
        <info>Vilnius, LT</info>
    </params>
    <signature>ca9fd88a49f039f5bde952c31247f09a</signature>
</root>

Signature validation is being made in similar way. In example you received the following request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>ping</method>
    <token>-</token>
    <time>1423124660</time>
    <params></params>
    <signature>6094dc0397895ee55c93b01f54477527</signature>
</root>
  1. Assemble parameters string without “signature” parameter: methodpingtoken-time1423124660
  2. Add the secret key: methodpingtoken-time14231246601JD4U-S7XB6-GKITA-DQXHP
  3. Count MD5: 6094dc0397895ee55c93b01f54477527
  4. This md5 sum is equal to the signature parameter. So the validity check is passed.

XML methods. Common notes

BetGames.TV server uses XML to communicate with Partner API via a HttpWebRequest. XML structure is described below. XML structure differs in accordance to method being called.

XML packet specifications

All requests and responses should be wrapped in root packet:

<?xml version="1.0" encoding="UTF-8"?>
<root>
</root>

Methods parameters

Required request params:

Example:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>get_account_details</method>
    <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
    <signature>59514741eae44d72480de631b98f51ce</signature>
    <time>1423127764</time>
    <params></params>
</root>

Required response params:

  • method (varchar) – called method name;
  • token (varchar) — token from the request;
  • success (int) – 1 or 0, response status, in case of success returns 1;
  • error_code (int) – Partner internal error code. In case of success returns 0; Note: code 404 is prohibited (being used by BetGames.TV in case of network connection problems);
  • error_text (varchar) – text description of the error;
  • params — packet for answer additional params;

Example:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <method>get_account_details</method>
    <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
    <success>1</success>
    <error_code>0</error_code>
    <error_text></error_text>
    <time>1423127764</time>
    <params>
        <user_id>150205</user_id>
        <username>test_player</username>
        <currency>eur</currency>
        <info>Vilnius, LT</info>
    </params>
    <signature>ca9fd88a49f039f5bde952c31247f09a</signature>
</root>

Common notes and recommendations

Bet structure

For each bet_id, there will be only one transaction_id for payin and only one transaction_id for payout. It could be described as one row in DB table, for example: (bet_id, transaction_payin_id, transaction_payout_id). Field type for bet_id and transaction_id in database must be BIGINT UNSIGNED.

Transaction_bet_payin method checks order

Firstly check if this transaction already exists in your DB. If so don't update player balance, and return success status. Elsewhere check players balance and respond accordingly. For example, if the system repeats same transaction twice in a row and it withdraws the whole balance, your API would respond successfully both times. Elsewhere if balance check is on the first place, second call would return error which is wrong behavior.

Text encoding

To avoid any encoding problems, please provide errors text and user names in Latin symbols only. For example:

Do:

<error_text>Bet not found.</error_text>
<username>john_doe</username>
<info>Beijing</info>

And do NOT:

<error_text>Įvyko klaida</error_text>
<username>Кирилл_Ш</username>
<info>北京</info>

On player logout in partner system

If the player logs out from the Partner's system, current player's token should become invalid.

Payout's retry policy

If the partner server is unavailable or responds with incorrect error code to payout requests, Betgames will repeat payout's until successful response is received. To save traffic and prevent from creating big load for partners' systems, the time interval between payout's increases and will be repeated in following order:

  • 5 times every 5 seconds
  • 5 times every minute
  • 5 times every 2 minutes
  • 5 times every 5 minutes
  • 5 times every 10 minutes
  • every hour (until we cancel the payout or partner fixes issue on their side)
  • API Methods

    Method ping

    Description: Method is being used for detecting API service availability status.

    Flowchart diagram:

    Ping new2.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>ping</method>
        <token>-</token>
        <time>1423124660</time>
        <params></params>
        <signature>6094dc0397895ee55c93b01f54477527</signature>
    </root>
    
    • Signature calculation string:
      methodpingtoken-time14231246601JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      6094dc0397895ee55c93b01f54477527

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>ping</method>
        <token>-</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423124663</time>
        <params></params>
        <signature>dee0dda6b4adc6c4e0f67c7e19a3ad0b</signature>
    </root>
    
    • Signature calculation string:
      methodpingtoken-success1error_code0error_texttime14231246631JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      dee0dda6b4adc6c4e0f67c7e19a3ad0b

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>ping</method>
        <token>-</token>
        <success>0</success>
        <error_code>1</error_code>
        <error_text>wrong signature</error_text>
        <time>1423124663</time>
        <signature>2f731bac67c9a363602f773ac71d12b3</signature>
    </root>
    
    • Signature calculation string:
      methodpingtoken-success0error_code1error_textwrong signaturetime14231246631JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      2f731bac67c9a363602f773ac71d12b3

    Method get_account_details

    Description: Method is called when the player logs in. Method passes the token generated by Partner server. Method returns players data in case player is logged in to the Partner website and token is valid. Player currency should be the same as in Partner database.

    Flowchart diagram:

    Get account details new.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_account_details</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <signature>59514741eae44d72480de631b98f51ce</signature>
        <time>1423127764</time>
        <params></params>
    </root>
    
    • Signature calculation string:
      methodget_account_detailstokenc2696fe0-eba8-012f-596c-528c3f9e4820time14231277641JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      59514741eae44d72480de631b98f51ce

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_account_details</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423127764</time>
        <params>
            <user_id>150205</user_id>
            <username>test_player</username>
            <currency>eur</currency>
            <info>Vilnius, LT</info>
        </params>
        <signature>ca9fd88a49f039f5bde952c31247f09a</signature>
    </root>
    
    • Signature calculation string:
      methodget_account_detailstokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423127764user_id150205usernametest_playercurrencyeurinfoVilnius, LT1JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      ca9fd88a49f039f5bde952c31247f09a

     

    Required Response Child-Elements for <params>
    Field Type Description
    user_id varchar User_id created at partner side.
    username varchar Username at partner side.
    Important: this field is optional and can have value "-".
    currency varchar Please specify the list of the available currencies from ISO 4217 currency list.
    info varchar Additional information about the user.
    Important: this field is optional and can have value "-".

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_account_details</method>
        <token>a2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>3</error_code>
        <error_text>invalid token</error_text>
        <time>1423147340</time>
        <signature>bec2559abe0c28466027e383ac86ce19</signature>
    </root>
    
    • Signature calculation string:
      methodget_account_detailstokena2696fe0-eba8-012f-596c-528c3f9e4820success0error_code3error_textinvalid tokentime14231473401JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      bec2559abe0c28466027e383ac86ce19

    Method refresh_token

    Description: Method validates the token. This method is being called when the player is idle.

    Flowchart diagram:

    Refresh token new.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>refresh_token</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <signature>122ed52b84777c09a56bc5b0e777a174</signature>
        <time>1423127764</time>
        <params></params> 
    </root>
    
    • Signature calculation string:
      methodrefresh_tokentokenc2696fe0-eba8-012f-596c-528c3f9e4820time14231277641JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      122ed52b84777c09a56bc5b0e777a174

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>refresh_token</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423125818</time>
        <params></params>
        <signature>1cf45d34ef9951c5e9ae5494312f095b</signature>
    </root>
    
    • Signature calculation string:
      methodrefresh_tokentokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime14231258181JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      1cf45d34ef9951c5e9ae5494312f095b

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>refresh_token</method>
        <token>abc-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>3</error_code>
        <error_text>invalid token</error_text>
        <time>1423229288</time>
        <signature>e4546f45daec49d6dadf751eb08c17c9</signature>
    </root>
    
    • Signature calculation string:
      methodrefresh_tokentokenabc-eba8-012f-596c-528c3f9e4820success0error_code3error_textinvalid tokentime14232292881JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      e4546f45daec49d6dadf751eb08c17c9

    Method request_new_token

    Description:Method creates and returns new valid token, in the same time old token becomes invalid.

    Description: Method returns valid token. If current token is live, you have to refresh and return it.

    Flowchart diagram:

    Request new token new.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>request_new_token</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <signature>8106b7478f92a57f3f6b725f6007e5a8</signature>
        <time>1423126078</time>
        <params></params>
    </root>
    
    • Signature calculation string:
      methodrequest_new_tokentokenc2696fe0-eba8-012f-596c-528c3f9e4820time14231260781JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      8106b7478f92a57f3f6b725f6007e5a8

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>request_new_token</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423126078</time>
        <params>
            <new_token>c2696fe0-eba8-012f-596c-528c3f9e4820</new_token>
        </params>
        <signature>b8cf58866581b73797305b2cb9ed7673</signature>
    </root>
    
    • Signature calculation string:
      methodrequest_new_tokentokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423126078new_tokenc2696fe0-eba8-012f-596c-528c3f9e48201JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      b8cf58866581b73797305b2cb9ed7673

     

    Required Response Child-Elements for <params>
    Field Type Description
    new_token varchar You have to refresh current token lifetime and return it as new_token.

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>request_new_token</method>
        <token>abc-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>3</error_code>
        <error_text>invalid token</error_text>
        <time>1345808201</time>
        <signature>f0dcd1cbc56e880230268b907e6baba6</signature>
    </root>
    
    • Signature calculation string:
      methodrequest_new_tokentokenabc-eba8-012f-596c-528c3f9e4820success0error_code3error_textinvalid tokentime13458082011JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      f0dcd1cbc56e880230268b907e6baba6

    Method get_balance

    Description: Method returns current player balance in players currency.

    Flowchart diagram:

    Get balance new.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_balance</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <signature>1f1c4dbe2d6fe35ccd7b0cb3081c2c5f</signature>
        <time>1423126078</time>
        <params></params>
    </root>
    
    • Signature calculation string:
      methodget_balancetokenc2696fe0-eba8-012f-596c-528c3f9e4820time14231260781JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      1f1c4dbe2d6fe35ccd7b0cb3081c2c5f

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_balance</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423126129</time>
        <params>
            <balance>50000</balance>
        </params>
        <signature>9f336db3614e5105cd5c7b32de5d65e6</signature>
    </root>
    
    • Signature calculation string:
      methodget_balancetokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423126129balance500001JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      9f336db3614e5105cd5c7b32de5d65e6

     

    Required Response Child-Elements for <params>
    Field Type Description
    balance int Current player balance.
    Important: amount must be in cents.

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>get_balance</method>
        <token>abc-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>3</error_code>
        <error_text>invalid token</error_text>
        <time>1423229288</time>
        <signature>9e784891fb366edcc8e4f6e85b5cd02e</signature>
    </root>
    
    • Signature calculation string:
      methodget_balancetokenabc-eba8-012f-596c-528c3f9e4820success0error_code3error_textinvalid tokentime14232292881JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      9e784891fb366edcc8e4f6e85b5cd02e

    Method transaction_bet_payin

    Description: Method for money withdrawals from Partners player account for making bets. If there are not enough money, then Partner API should return insufficient funds error.

    • We will not call get_balance (to check if player has enough funds to place a bet) before transaction_bet_payin for Speedy 7 game, so you need to ensure the balance checking is done properly on your side. In case the player does not have enough funds/balance you can return error response with error code 703 and a proper message "Insufficient balance" shall be displayed.

    Flowchart diagram:

    Webapi12.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payin</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <signature>a91c39b7028bde988d1a6858fafd545a</signature>
        <time>1423127617</time>
        <params>
            <amount>1234</amount>
            <currency>eur</currency>
            <bet_id>123456</bet_id>
            <transaction_id>246912</transaction_id>
            <retrying>0</retrying>
            <bet>Selected ball will be dropped with No. 1,...,42(1, 3, 10)</bet>
            <odd>5.70</odd>
            <bet_time>2015-02-05 09:13:37</bet_time>
            <game>1</game>
            <draw_code>71304050073</draw_code>
            <draw_time>2015-02-05 09:15:00</draw_time>
        </params>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payintokenc2696fe0-eba8-012f-596c-528c3f9e4820time1423127617amount1234currencyeurbet_id123456transaction_id246912retrying0betSelected ball will be dropped with No. 1,...,42(1, 3, 10)odd5.70bet_time2015-02-05 09:13:37game1draw_code71304050073draw_time2015-02-05 09:15:001JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      a91c39b7028bde988d1a6858fafd545a

     

    Required Request Child-Elements for <params>
    Field Type Description
    amount int Amount to withdraw from account.
    Important: amount is in cents.
    currency varchar Currency code from the ISO 4217 currency list.
    bet_id bigint unsigned Unique bet id on BetGames.TV server.
    transaction_id bigint unsigned Unique transaction id on BetGames.TV server. Partner is obliged to store processed transaction ids. If the request contains the same transaction id, Partner should return success status, but do not withdraw money from the balance again.
    retrying int Informational parameter. If it is equal 1, it means BetGames.TV server tries to resend request. For example, because of the network connection problems.

     

    Optional Request Child-Elements for <params> (enabled by default, could be disabled by Partner request)
    Field Type Description
    bet varchar Bet name on default Partner's language, encoding - UTF-8.
    odd decimal Outcome value.
    bet_time datetime Time when the bet has been placed. Timezone - UTC+0.
    game int or varchar By default is returned as Game ID (integer value). Can be returned as game name on default Partner's language (encoding - UTF-8) by Partner request.
    draw_code varchar Draw code number.
    draw_time datetime Scheduled start time of the draw. Timezone - UTC+0.
    is_mobile int Parameter to distinguish platform ("1"-mobile). This parameter appears in transaction_bet_payin requests only when you push it into iFrame JavaScript launch code.
    Note: this parameter isn't being used for desktop platform.

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payin</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423127617</time>
        <params>
            <balance_after>48766</balance_after>
            <already_processed>0</already_processed>
        </params>
        <signature>ebdb13dc9f8bbee7da1f322546b33d6a</signature>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payintokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423127617balance_after48766already_processed01JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      ebdb13dc9f8bbee7da1f322546b33d6a

     

    Required Response Child-Elements for <params>
    Field Type Description
    balance_after int Player balance after the transaction.
    Important: amount must be in cents.
    already_processed int Equals 1 if the transaction was already processed.

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payin</method>
        <token>abc-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>3</error_code>
        <error_text>invalid token</error_text>
        <time>1423229288</time>
        <signature>06a2d3c9d7448ee6b0fad54d00cdb946</signature>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payintokenabc-eba8-012f-596c-528c3f9e4820success0error_code3error_textinvalid tokentime14232292881JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      06a2d3c9d7448ee6b0fad54d00cdb946

    Method transaction_bet_payout

    Description: Method for money deposits to Partners player account – paying out the winnings.
    Important notes:

    • Transaction payout should return error with code 700, in case there were no payin with same bet_id before. This transaction should not affect the players balance.
    • Transaction payout should return success but do not change players balance, in case there were already payout been made with same bet_id, but different transaction_id.
    • If transaction_bet_payout method has validation that a payout amount must be equal to payin amount * odd value, then this validation for Speedy 7 game payout should not be used. It's because of the game logic - the odd value/coefficient might be different in payin and payout requests.

    Flowchart diagram:

    Transaction bet payout new2.png

     


     

    Request example:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payout</method>
        <token>-</token>
        <signature>a7112178a6d2e73fa6828be090c955d0</signature>
        <time>1423128560</time>
        <params>
            <player_id>150205</player_id>
            <amount>2034</amount>
            <currency>eur</currency>
            <bet_id>123456</bet_id>
            <transaction_id>246913</transaction_id>
            <retrying>0</retrying>
        </params>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payouttoken-time1423128560player_id150205amount2034currencyeurbet_id123456transaction_id246913retrying01JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      a7112178a6d2e73fa6828be090c955d0

     

    Required Request Child-Elements for <params>
    Field Type Description
    player_id varchar Player external code provided by partner in get_account_details method. This method uses player_id for player identification.
    amount int Amount to deposit to account.
    Important: 1) amount is in cents. 2) amount is 0 for lost bet.
    currency varchar Currency code from the ISO 4217 code list.
    bet_id bigint unsigned Unique bet id on BetGames.TV server.
    transaction_id bigint unsigned Unique transaction id on BetGames.TV server. Partner is obliged to store processed transaction ids. If the request contains the same transaction id, Partner should return success status, but do not deposit money to the balance again.
    retrying int Informational parameter. If it is equal 1, it means BetGames.TV server tries to resend request. For example, because of the network connection problems.

     


     

    Example of successful response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payout</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>1</success>
        <error_code>0</error_code>
        <error_text></error_text>
        <time>1423128560</time>
        <params>
            <balance_after>2092</balance_after>
            <already_processed>0</already_processed>
        </params>
        <signature>736782bf451def853bbad43e210d3787</signature>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payouttokenc2696fe0-eba8-012f-596c-528c3f9e4820success1error_code0error_texttime1423128560balance_after2092already_processed01JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      736782bf451def853bbad43e210d3787

     

    Required Response Child-Elements for <params>
    Field Type Description
    balance_after int Player balance after the transaction.
    Important: amount must be in cents.
    already_processed int Equals 1 if the transaction was already processed.

     


     

    Example of error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
        <method>transaction_bet_payout</method>
        <token>c2696fe0-eba8-012f-596c-528c3f9e4820</token>
        <success>0</success>
        <error_code>700</error_code>
        <error_text>there is no PAYIN with provided bet_id</error_text>
        <time>1423229288</time>
        <signature>a678ae382bce2edd151a40d6b470e257</signature>
    </root>
    
    • Signature calculation string:
      methodtransaction_bet_payouttokenc2696fe0-eba8-012f-596c-528c3f9e4820success0error_code700error_textthere is no PAYIN with provided bet_idtime14232292881JD4U-S7XB6-GKITA-DQXHP
    • Result after MD5 calculation:
      a678ae382bce2edd151a40d6b470e257

    Test token page

    The next step after you implemented all API methods is testing procedure from Betgames.TV side.

    To start testing procedure we need a simple page which outputs a newly generated token for some test player. You have to generate a token on each page load for logged in player and place it in that page. We need it for easier testing, so we could get new valid tokens by ourselves.

    Note: please make sure a test player has some money in account.

    Frequently asked questions

    1. Does each API method should be accessible by separate url?

    No, you have provide us single API url.

    Good example: https://partner-domain.com/betgames_api

    Bad example: https://partner-domain.com/betgames_api/ping, https://partner-domain.com/betgames_api/get_account_details, etc.;

    2. Can we use our internal error codes/error texts?

    Yes, you can use your internal error codes system. Only error code 404 is prohibited (being used by BetGames.TV in case of network connection problems) and error code's 700-799 are reserved for a specific cases. When Betgames server receives one of these error codes, specific error message will be shown inside of iFrame. Currently, following specific cases are registered:

    • 701 - We apologize, but bets for this game provider are restricted for you, please contact support for more details.
    • 702 - Your account requires identity validation.
    • 703 - Insufficient balance.
    • 704 - The game in the section is not available due to the active bonus. Details will be in your account.
    • 705 - Bet stake can not contain cents in your currency.

    3. How does Betgames.TV side behaves when our (Partner) server is unavailable?

    Request is timed out when Betgames.TV server doesn't get response from Partner's server in 15 seconds.

    Example:

    - a player places a bet and Partner's server becomes unavailable (doesn't respond in 10 seconds)

    - the player gets an error message 'Bet was not accepted'

    - this bet is being marked as failed on Betgames.TV side

    - Betgames.TV server waits 2 minutes (expecting Partner's server to become available) and sends transaction_bet_payout request for failed bet, so the player could receive bet amount back into his account

    - Betgames.TV server repeats current procedure every minute while Partner's server becomes available