Mobile API Service (MaS)
Mobile API Service or MaS is our middleware API, enabling communication between mobile devices and server endpoints. Many of our clients use our standard XML API, some of which is defined below.
Generic Concepts
Anonymous vs Authenticated
There are two categories of requests available in the MaS system: Anonymous and Authenticated. Authenticated requests require a valid session to have been instantiated with a login request and will return an error if a valid session id is not included in the request. Anonymous requests do not provide any private data, and can thus be sent without a proper login. An example of this is a generic list of odds on a betting platform. These are usually published publicly, and are thus available without a login.
Errors
If, for some reason, a request fails, it will return an error message in the response. Error messages all follow the same format, consisting of an errors element, with nested error elements detailing the error that occured. As an example, here is a failed location response:
<?xml version="1.0" encoding="UTF-8"?>
<response timestamp="1291115364342" type="service-ma" version="0.1.0.0">
<errors>
<error code="4" field="location">Location 23434.4564, 23434.4564 forbidden</error>
</errors>
</response>
The descriptions of request/response pairs listed below will generally include a list of error elements that can occur. However, there are also generic error messages that can occur on many messages, and they are listed here:
<error code="1" field="fieldname">Malformed request: xml body required for {method name} method</error>
<error code="2" field="fieldname">Missing field: session element and valid session id required for {method name} method</error>
<error code="3" field="fieldname">IO Communication Error {method name} method failed</error>
<error code="4" field="fieldname">No matching session. Login required.</error>
Error code 1 is used for invalidly formed XML. Error code 2 is used for requests that require a session attribute but do not include one. Error code 3 is used for communications error, such as a loss of connectivity. Error code 4 is used for any other type of error, generally meaning a semantic error (such as an invalid session, or incorrect account details).
Wallet
Wallet transactions are any transactions that involve updating or requesting information regarding a user's account. Since this usually requires dealing with sensitive information, almost all wallet transaction require the client to be logged in and to supply a valid session ID within their requests.
login
This is the first call for any transaction that requires authentication. The user supplies their login information and are returned a session id. This session id needed during authenticated requests, as is shown in later examples.
Example request:
<request type="service-ma" version="0.1.0.0" method="login"> <login> <user>username</user> <password>password</password> </login> </request>
Example successful response:
<?xml version="1.0" encoding="UTF-8"?> <response timestamp="1286290078803" type="service-ma" version="0.1.0.0"> <session>424295022076241764</session> </response>
Example error elements:
<error code="4">209: invalid combination of customer credentials</error>
logout
This request terminates the session. Any further calls requiring authentication will fail and return an error message advised that login is required until another login occurs.
Example request:
<request type="service-ma" version="0.1.0.0" method="logout"> <session>424295022076241764</session> </request>
Example successful response:
<?xml version="1.0" encoding="UTF-8"?> <response timestamp="1286290078803" type="service-ma" version="0.1.0.0"> <logout/> </response>
location
Location advices whether the supplied longitude (x) and lattitude (y) coordinates are within a specified area. This area is adjustable, and is often used to determine if the device is in a jurisdiction in which a particular application, such as gambling, is legal. It is an anonymous call, and does not require a previous login call.
Example request:
<request type="service-ma" version="0.1.0.0" method="location"> <location xPosition="8" yPosition="8" /> </request>
Example response:
<?xml version="1.0" encoding="UTF-8"?> <response timestamp="1291125829061" type="service-ma" version="0.1.0.0"> <location /> </response>
Example location errors:
<error code="2" field="xPosition">Missing field: location element and valid xPosition attribute required for location api</error> <error code="4" field="location">Location 23434.4564, 23434.4564 forbidden</error>
The first error message is invalid xml or field values, the second is a location outside of the valid region.
transactions
This request provides a list of transactions that have occured on a particular user's account. It requires previous authentication. The opType attribute contains a fixed list of possible options, which are detailed after the example request/response pairings.
Example request:
<request type="service-ma" version="0.1.0.0" method="transactions"> <session>2969234988250759039</session> </request>
Example response:
<?xml version="1.0" encoding="UTF-8"?>
<response timestamp="1286392053232" type="service-ma" version="0.1.0.0">
<transactions id="23443432" page="0">
<transaction id="2000652159" date="2010-07-19 11:48:47" amount="-1.00" balance="88.10" opType="BSTK"></transaction>
<transaction id="1992204283" date="2010-07-15 14:07:08" amount="3.00" balance="89.10" opType="BSTL"></transaction>
<transaction id="1991589997" date="2010-07-15 05:45:15" amount="-1.00" balance="86.10" opType="BSTK"></transaction>
<transaction id="1954721823" date="2010-06-27 16:50:51" amount="2.75" balance="87.10" opType="BSTL"></transaction>
<transaction id="1950388106" date="2010-06-25 14:10:56" amount="-1.00" balance="84.35" opType="BSTK"></transaction>
<transaction id="1946521636" date="2010-06-23 17:02:08" amount="-0.20" balance="85.35" opType="BSTK"></transaction>
<transaction id="1946518758" date="2010-06-23 17:00:30" amount="2.80" balance="85.55" opType="BSTL"></transaction>
<transaction id="1946375630" date="2010-06-23 15:27:26" amount="-1.00" balance="82.75" opType="BSTK"></transaction>
<transaction id="1946337883" date="2010-06-23 15:00:56" amount="-2.00" balance="83.75" opType="BSTK"></transaction>
<transaction id="1944309118" date="2010-06-22 13:40:41" amount="-0.70" balance="85.75" opType="BSTK"></transaction>
</transactions>
</response>
Example request 2 (This one contains a limiter on how many transactions are returned):
<request type="service-ma" version="0.1.0.0" method="transactions"> <session>2969234988250759039</session> <transactions id="23443432" page="1"/> </request>
| opType code mappings | |
| code | description |
| DEP | Deposit |
| WTD | Withdrawal |
| BSTK | Stake |
| BSTL | Returns |
| BCAN | Void |
| MAN | Manual Adj. |
| XFER | Transfer |
| XSOT | Description |
| DDEP | Draw-down Dep |
| RDEP | Dep. pending referral |
| DCAN | Dep. cancellation |
| RWTD | Refunded Withdrawal |
| RBAL | Rolled-up balance |
| ERLY | Early settlement |
| COMM | Commision |
| XSIN | Transfer in |
| XSOT | Transfer out |
user summary and user details
These two methods return the user's details from the 3rd party wallet. They require authentication, and are very similarly structured. The difference is that the summary method supports an optional time out, and will respect that time out, while the details method will not. Other than this, the structure is the same.
Example user summary request:
<request type="service-ma" version="0.1.0.0" method="userSummary"> <session>9011798213141826773</session> </request>
Example user summary response:
<?xml version="1.0" encoding="UTF-8"?>
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0">
<userDetails>
<accountNo>123456789</accountNo>
<userName>username</userName>
<firstName>firstname</firstName>
<lastName>lastname</lastName>
<title>Dr</title>
<email>1306658</email>
<mobile>1306658</mobile>
<currency>GBP</currency>
<oddsDisplay>ODDS</oddsDisplay>
<address>
<houseName></houseName>
<houseNo></houseNo>
<flatNo></flatNo>
<city></city>
<postcode></postcode>
<country>United Kingdom</country>
</address>
</userDetails>
</response>
Example user details request:
<request type="service-ma" version="0.1.0.0" method="userDetails"> <session>9011798213141826773</session> </request>
Example user details response:
<?xml version="1.0" encoding="UTF-8"?>
<response timestamp="1286462613110" type="service-ma" version="0.1.0.0">
<userDetails>
<accountNo>123456789</accountNo>
<userName>username</userName>
<firstName>firstname</firstName>
<lastName>lastname</lastName>
<title>Dr</title>
<email>1306658</email>
<mobile>1306658</mobile>
<currency>GBP</currency>
<oddsDisplay>FRACTION</oddsDisplay>
<address>
<city></city>
<postcode></postcode>
<country>GB</country>
</address>
</userDetails>
</response>
MAKE PAYMENT
Example make payment request
<request type="service-ma" version="0.1.0.0" method="makePayment"> <payment password="somePassword" payMethodId="" sort="" amount="" cvv="" /> <session>123456789</session> </request>
Example make payment response
<?xml version="1.0" encoding="UTF-8"?> <response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <session>123456789</session> <payment id=""/> </response>
BALANCE
Example balance request, no show items
<request type="service-ma" version="0.1.0.0" method="balance"> <session>123456789</session> </request>
Example balance response, no show items
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <session>123456789</session> <balance currency="" balance="" availableFunds="" withdrawableFunds=""/> </response>
Example balance request, with show items
<request type="service-ma" version="0.1.0.0" method="balance"> <balance showItems="true"> <session>123456789</session> </request>
Example balance response, with show items
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <balance currency="" balance="" availableFunds="" withdrawableFunds=""/> <wallet currency="" balance="" withdrawableFunds=""> <session>123456789</session> </response>
PAY METHOD
Returns individual pay method specified
Example pay method request
<request type="service-ma" version="0.1.0.0" method="payMethod"> <payMethod>123456789</payMethod> <session>123456789</session> </request>
Example pay method response
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <payMethod id="" type="" canWithdraw="" canDeposit=""> <card no="" [start=""] [expiry=""] [issueNo=""] [minDepositLimit=""] [maxDepositLimit=""] [minWithdrawalLimit=""] [maxWithdrawalLimit=""]/> </payMethod> <session>123456789</session> </response>
PAY METHODS
Returns a list of all pay methods
Example pay methods request
<request type="service-ma" version="0.1.0.0" method="payMethods"> <session>123456789</session> </request>
Example pay methods response
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0">
<payMethods>
<payMethod id="" type="" canWithdraw="" canDeposit="">
<card cardNo="" [start=""] [expiry=""] [issueNo=""] [minDepositLimit=""] [maxDepositLimit=""] [minWithdrawalLimit=""] [maxWithdrawalLimit=""]/>
</payMethod>
<payMethod id="" type="" canWithdraw="" canDeposit="">
<card cardNo="" [start=""] [expiry=""] [issueNo=""] [minDepositLimit=""] [maxDepositLimit=""] [minWithdrawalLimit=""] [maxWithdrawalLimit=""]/>
</payMethod>
</payMethods>
</response>
ADD PAY METHOD
Example add pay method request
<request type="service-ma" version="0.1.0.0" method="addPayMethod"> <addPayMethod> <card cardNo="" expiryMonth="" expiryYear="" [issueNo=""] [startMonth="" startYear=""] /> </addPayMethod> <session>123456789</session> </request>
Example add pay method response
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <payMethod id="" /> </response>
FUNDS TRANSFER
Funds transfer allows funds to be transfered from any one source to the wallet and vice versa. Examples of the xml are demonstrated below.
The request requires the following elements:
amount: which details the amount of the transfer action: What type of funds transfer is occurring, for example, a refund. transactionId: a unique identifier for the transaction description: A brief text field detailing the transfer session: the logged in identifier returned from a previous login request.
It also allows the optional element:
currency: what currency the amount is listed in. If not included, this defaults to GBP.
Example funds transfer request
<request type="service-ma" version="0.1.0.0" method="fundsTransfer"> <amount>100.25</amount> [<currency>GBP</currency>] optional, defaults to GBP <action>Refund/Transfer/Stake</action> <transactionId>987654321</transactionId> <description>winnings transfer</description> <session>123456789</session> </request>
Example funds transfer response
The response, if successful, will return the currency, updated balance, and a unique transaction record which can be used to look up the transaction in the future.
<response timestamp="1286369323940" type="service-ma" version="0.1.0.0"> <success>true</success> <currency>GBP</currency> <balance>100.75</balance> <transactionRecord>111111111</transactionRecord> </response>
