MTS API
Overview
This service facilitates the integration of your wallet with our betting system, and the accompanying documents provide specifications for authentication, betting & wallet transaction handling, and communication with our API. The diagram below outlines the general flow of the implementation.
Reserve and confirm calls can be ignored if you are using your own widget component and debit the funds before sending a bet placement request.
Table of Content.
- Authentication (BetMakers APIs)
- Bet Placement API
- Wallet Integration (Betmakers - Wallet)
- On demand services (Wallet - BetMakers)
Authentication (BetMakers APIs)
Betmakers utilizes the OAuth 2.0 client credentials flow to authorize APIs. You will be provided with a token endpoint. Please refer to the example request below to learn how to generate a token.
POST {BetMakersTokenEndpoint}/oauth2/token
Content-Type: application/x-www-form-urlencoded
Request body:
grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET_KEY
Response:
{
"access_token": "ACCESS_TOKEN",
"expires_in": 3600,
"token_type": "Bearer"
}
Bet Placement API
BetMakers (BM) offers a set of Bet GraphQL mutations, queries, and subscriptions for both client and server applications. The bet endpoint allows placing bets from your server with mutations and fetching bet data with queries. Bet subscriptions, accessible to both client and server applications, enable real-time updates. For optimal user interface experience, it is recommended to integrate frontend Bet components directly with Bet GraphQL subscriptions to receive timely bet updates.
Mutation: createBet
This mutation allows you to place bets on BetMakers backend.
Pass the user information in the user metadata object for us to identify the punter.
Example Request:
mutation createBet($input: BetList!, $metadata: Metadata) {
createBet(input: $input, metadata: $metadata) {
bet_id
status
}
}
Headers:
{
"X-API-Key": "3djdnk70ru7c7uhgpjt2atnh1v",
"Authorization": "Bearer Token"
}
Variables:
{
"input": {
"ticket_id": "1d3d0672-76bd-457e-8046-51e534726124",
"bets": [
{
"id": "8be4d4d1-0847-4392-98ed-da33c968e20e",
"bet_type": "win",
"currency": "ZAR",
"is_bonus_bet": false,
"is_boxed": false,
"legs": [
{
"bet_type_id": "win" // Required for Multi's to detect leg betTypes.
"event_id": "4d35fbec-63f5-50c5-b37c-51238d5c4ee8",
"leg_type": "Racing",
"product_keyword": "TBF",
"selections": [
{
"position": 0, // The position field is used to specify the order of selections for non-boxed exotic bets, and should be set to 1 for boxed exotic bets. For other bet types, you can pass 0.
"selection_odds": "3.50" // Required for Fixed Odd Product Bets (TBF) not for Tote products.
"selection_id": [
"725e586e-704c-519b-8c32-61440436257c"
]
}
]
}
],
"original_amount": 100,
}
],
"account_type": "Wallet",
"source": "Mts_Api"
},
"metadata": {
"brand_name": "betmakers",
"brand_user_id": "a48bd243-9a18-4b64-a1ec-292e88b924da",
"user_id": "a48bd243-9a18-4b64-a1ec-292e88b924da",
"data": ""
}
}
Response:
{
"data": {
"createBet": [
{
"bet_id": "88b855cf-357e-467e-bf29-43e02e0603ba",
"status": "Processing"
}
]
}
}
Subscription: betEventUpdates
The following subscription provides a means to listen to bet status updates through the BetStatusUpdated event, offering information related to status updates on bets. This event is optional and generally does not involve any wallet transactions.
Example Request:
Headers:
{
"X-API-Key": "token"
"Authorization": "Bearer Token"
}
Subscription:
subscription betEventUpdates {
betEventUpdates {
... on BetAccepted {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
amount
liability_percentage
is_partial
percentage
status
old_status
}
... on BetPriceAdjusted {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
price
old_price
}
... on BetReferred {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
}
... on BetResultUpdated {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
amount
status
old_status
}
... on BetRefundUpdated {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
amount
status
old_status
}
... on BetPartialRefundUpdated {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
amount
status
old_status
}
... on BetStatusUpdated {
bet_id
version
event_id
event_type
aggregate_type
time_stamp
status
old_status
}
}
}
Racing Query Service
BetMakers (BM) offers a collection of Racing GraphQL queries and subscriptions for seamless integration with your applications. The racing GraphQL endpoint supplies content, encompassing Meetings, Races, Runners, Deductions, Scratchings, Futures, and Results. To optimise the user interface, it is recommended to directly integrate frontend components with Racing GraphQL queries and subscriptions. Use the provided Racing GraphQL endpoint to query the data.
Subscription: RaceUpdates
Updates related to the races flow through this subscription.
Example Request:
Headers:
{
"X-API-Key": "token"
}
Subscription:
subscription RaceUpdates {
raceUpdates(race_id: "69f89398-0357-5d4d-b21a-316e250a4f98") {
price {
bet_type
fluctuations
display_price
price
updated_at
product {
keyword
name
type
available
updated_at
}
}
}
}
Query Sample: Meetings
This query allows the retrieval of all meeting-related data, including the option to retrieve child elements such as races if needed.
Example Request:
Headers:
{
"X-API-Key": "token"
}
Query:
query Meetings {
meetings(meeting_ids: ["69f89398-0357-5d4d-b21a-316e250a4f98"]) {
id
start_date
first_race_time
updated_at
races {
id
}
type
}
}
Response:
{
"data": {
"meetings": [
{
"id": "69f89398-0357-5d4d-b21a-316e250a4f98",
"start_date": "2024-02-07T00:00:00Z",
"first_race_time": "2024-02-06T23:07:00Z",
"updated_at": "2024-02-06T20:32:15Z",
"races": [
{
"id": "624207f2-d9b3-5c24-989a-2e47fe150566"
},
...
],
"type": "HARNESS"
}
]
}
}
Sample Query: Races
This query facilitates the retrieval of racing and runner related data.
Getting Runner/Selection Prices. Prices for runners/selections can be obtained by querying the GraphQL race query. The prices object is nested within the structure of races -> runners -> prices.
Example Request:
Headers:
{
"X-API-Key": "token"
}
Query:
{
races(race_ids: "6ed94d9f-6adf-5695-92a8-a1102765fcb0") {
id
name
distance
track_condition
class
result_prices {
bet_type
dividend
tab_no
jackpot
pool_size
updated_at
product {
name
type
available
updated_at
}
}
exotic_result_prices {
bet_type
result_string
dividend
jackpot
pool_size
updated_at
product {
name
type
available
updated_at
}
}
race_comment {
comment
updated_at
}
results {
position
source
tab_no
updated_at
}
deductions {
id
win_deduction
updated_at
type
}
fav_runner_id
has_speed_maps
surface_type
market_id
market_name
fixed_odds_enabled
tote_enabled
tote_products {
race_id
source
tote_product_bet_types {
bet_type
max_combos
min_combos
increment
max_bet_amount
min_bet_amount
max_bet_cost
min_bet_cost
min_stake
updated_at
}
tote_selections {
runner_id
source
selection_id
}
}
bet_status
status
weather
start_at
runners {
id
tab_no
name
barrier
weight_total
jockey
trainer
status
silk_url
silk_url_sixtyfour
last_ten_starts
scratched_time
speed_map_position
updated_at
runner_comment {
comment
updated_at
}
prices {
bet_type
fluctuations
display_price
price
updated_at
product {
keyword
name
type
available
updated_at
bet_types {
bet_type
core_bet_type
is_fixed
is_multi_available
is_custom
custom_bet_type
}
}
}
}
race_products {
keyword
name
type
available
updated_at
bet_types {
bet_type
core_bet_type
is_fixed
is_multi_available
is_custom
custom_bet_type
}
}
}
}
Response:
{
"data": {
"races": [
{
"id": "6ed94d9f-6adf-5695-92a8-a1102765fcb0",
"name": "Toora Royal Standard Hotel Mdn Plate",
"distance": 1700,
"track_condition": "GOOD4",
"class": "MDN-SW,Maiden",
"result_prices": null,
"exotic_result_prices": null,
"race_comment": {
"comment": ".....",
"updated_at": "2024-02-06T06:34:26Z"
},
"results": [
{
"position": 1,
"source": "OP",
"tab_no": 14,
"updated_at": "2024-02-06T03:41:29Z"
}
...
],
"deductions": null,
"fav_runner_id": null,
"has_speed_maps": null,
"surface_type": null,
"market_id": null,
"market_name": null,
"fixed_odds_enabled": true,
"tote_enabled": true,
"tote_products": [
{
"race_id": "6ed94d9f-6adf-5695-92a8-a1102765fcb0",
"source": "INT2",
"tote_product_bet_types": [
{
"bet_type": "Place",
"max_combos": null,
"min_combos": null,
"increment": 100,
"max_bet_amount": 5000000,
"min_bet_amount": 100,
"max_bet_cost": null,
"min_bet_cost": null,
"min_stake": 100,
"updated_at": "2024-02-05T10:22:23Z"
},
...
],
"tote_selections": [
{
"runner_id": "178a876c-b899-50b8-ae55-c7f6edae2897",
"source": "INT2",
"selection_id": "216:888:2:216:888:7"
}
...
]
}
],
"bet_status": "",
"status": "FINAL",
"weather": "FINE",
"start_at": "2024-02-06T03:30:00Z",
"runners": [
{
"id": "178a876c-b899-50b8-ae55-c7f6edae2897",
"tab_no": 7,
"name": "Atteindre",
"barrier": 7,
"weight_total": 57.5,
"jockey": "Luke Cartwright",
"trainer": "E Jusufovic",
"status": "STARTER",
"silk_url": "https://d36frgpkvm82k8.cloudfront.net/273494_2_7_32x32.png",
"silk_url_sixtyfour": "https://d36frgpkvm82k8.cloudfront.net/273494_2_7_64x64.png",
"last_ten_starts": null,
"scratched_time": null,
"speed_map_position": null,
"updated_at": "2024-02-06T06:51:59Z",
"runner_comment": {
"comment": "Wasn't far away before a spell at Pakenham in a Maiden race when 6.70L from the winner as a $7 chance. One of the toughest to beat.",
"updated_at": "2024-02-06T06:34:25Z"
},
"prices": null
}
...
],
"race_products": [
{
"keyword": "SUP",
"name": "SuperTAB",
"type": "Standard",
"available": true,
"updated_at": "2024-01-12T04:18:48.624719Z",
"bet_types": [
{
"bet_type": "",
"core_bet_type": "TRIFECTA",
"is_fixed": false,
"is_multi_available": false,
"is_custom": false,
"custom_bet_type": null
}
...
]
}
...
]
}
]
}
}
Sample Query: NextToJumpRaces
This call provides information about races that are about to start.
Example Request:
Headers:
{
"X-API-Key": "token"
}
Query:
query NextToJumpRaces {
nextToJumpRaces {
race_name
race_number
meeting_id
meeting_name
distance
meeting_type
prize_money
state
country
start_datetime
fixed_odds_enabled
}
}
Response
{
"data": {
"nextToJumpRaces": [
{
"race_name": "Greyhounds Make Great Pets",
"race_number": 5,
"meeting_id": "3f917f35-b8b5-5830-af4d-e63d8d7383ba",
"meeting_name": "Ipswich",
"distance": 431,
"meeting_type": "GREYHOUND",
"prize_money": 3400,
"state": "QLD",
"country": "AUS",
"start_datetime": "2024-02-16T05:12:00Z",
"fixed_odds_enabled": true
}
]
}
}
Wallet Integration (Betmakers - Wallet)
Implementing Auth.
We utilise REST endpoints for posting data to external client wallets. Betmakers provide two authentication types for machine-to-machine communication. You must implement one of these authentication methods according to the given specification.
- Client Credentials Auth.
- API Key Auth.
Implementing Client Credentials Authentication.
In order to implement Client Credentials based auth you need to implement authentication endpoint (/auth/token). The token endpoint will be called with provided client_id and client_secret to obtain the token, which will then serve as a bearer token for authorising calls to the external wallet, as illustrated in the accompanying diagram depicting the basic flow.
POST {ExternalWalletEndpoint}/auth/token
Request body:
{
"grant_type": "client_credentials",
"client_id": "TestClient",
"client_secret": "TestSecret"
}
Response:
{
"access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
"expires_in": 3600,
"token_type": "bearer",
"scope": null
}
Implementing API Key Authentication.
Two parties will utilize a shared API Key for authentication purposes between betmakers and wallets. This method necessitates the implementation of an authentication endpoint.
Wallet Transactions.
Our system supports four transactions, and clients are required to implement them based on the provided specifications. The minimum payloads to be sent to the wallet are outlined below, with the possibility of additional data being included.
All HTTP requests are configured with a 10-second timeout.
- Reserve Transaction. - OPTIONAL
- Confirm Transaction. - OPTIONAL
- Refund Bet Transaction.
- Settle Bet Transaction.
- Debit Transaction.
- Credit Transaction.
Reserve Transaction.
This call is optional and can be ignored if you are using your own widget component and debit the funds before sending a bet placement request.
This transaction will be used to reserve funds from the user's account and will be sent at the time of bet placement. We forward the token and metadata from the bet placement. Please utilize these details to conduct server-side validation.
Example Request:
POST {ExternalWalletEndpoint}/reserve
Request body:
{
"transactionId": "transaction-uuid",
"betId": "bet-uuid",
"userId": "user-uuid",
"bonusFlag": false, // True for bonus bets.
"amount": 1000,
"token": "token", // Token used on placement.
"metadata": {
"userId": "user-id",
"brandName": "betmakers",
"brandUserId": "brand-user-id",
"data": ""
}
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
Confirm Transaction.
This call is optional and can be ignored if you are using your own widget component and debit the funds before sending a bet placement request.
This request serves to confirm the reserved funds are accepted along with the bet. Accepted amount will be reflected on the amount field which needs to be debited from either the bonus account or cash account based on the bonus flag.
Example Request:
POST {ExternalWalletEndpoint}/confirm
Request body:
{
"transactionId": "transaction-uuid",
"userId": "user-uuid",
"betId": "bet-uuid",
"bonusFlag": false, // True for bonus bets.
"amount": 2200,
"betMetadata": {
"id": "bet-uuid",
"ticketId": "ticket-uuid",
"tenantId": "tenant-uuid",
"userId": "user-uuid",
"betTypeId": 2,
"statusId": 7,
"createdAt": "2024-10-31T08:36:09Z",
"amount": 2200,
"percentage": 2200,
"fixedOdds": 1.38,
"legs": [
{
"betTypeId": 2,
"eventId": "b7137ff3-92a8-58e3-8d0c-7006feb154ab",
"productKeyword": "TBF",
"processedDividend": 0,
"legType": "Racing",
"marketId": null,
"selection": [
{
"statusId": 1,
"fixedOdds": 1.38,
"margin": 0,
"position": 0,
"selectionId": [
"257ec2f2-b7be-5058-9b8d-94ca94c3744c"
],
"lineTypeId": 0,
"line": 0
}
]
}
]
}
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
Refund Transactions.
Refunds or partial refunds to the bet will be conveyed through this endpoint. It is required to credit the provided amount into the client's cash or bonus balance based on the bonus flag.
Example Request:
POST {ExternalWalletEndpoint}/refundBet
Request body:
{
"transactionId": "transaction-uuid",
"betId": "bet-uuid",
"userId": "user-uuid",
"bonusFlag": false, // True for bonus bets.
"amount": 200
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
Settle Transactions.
The settle request is employed to convey that the bet has been settled. In the case of a winning bet, the payout will be passed through the amount field, and it is necessary to credit that amount to the client's cash balance.
In the event of a failure while handling the settleBet request, the system will automatically retry up to five times with the same details. The retry intervals will be as follows: after 5 minutes, 10 minutes, 20 minutes, and then hourly. The transactionId can be used to check if the transaction has already been processed on your end.
Example Request:
POST {ExternalWalletEndpoint}/settleBet
Request body:
{
"transactionId": "transaction-uuid",
"betId": "bet-uuid",
"userId": "user-uuid",
"bonusFlag": false, // True for bonus bets.
"amount": 2590 // Winnings if available.
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
Debit Transaction.
Additional transactions, such as reverted winnings, will be posted to this endpoint. It is essential to debit the specified amount from the client's cash or bonus balance based on the bonus flag.
Expected Transaction Types:
| Code | Description |
|---|---|
deductbetwin | Reversing winnings of the bet. |
betwincancelled | Reversing winnings of the bet. |
Example Request:
POST {ExternalWalletEndpoint}/debit
Request body:
{
"transactionId": "transaction-uuid",
"betId": "bet-uuid",
"userId": "user-uuid",
"bonusFlag": false, // True for bonus bets.
"transactionType": "betwincancelled",
"amount": 100,
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
Credit Transactions.
Additional transactions, such as manual adjustments, will be posted to this endpoint. It is essential to credit the specified amount to the client's cash or bonus balance based on the bonus flag.
Expected Transaction Types:
| Code | Description |
|---|---|
adjustreversetransaction | Manual adjusted transactions. |
cashout | Cash out transactions. |
betpartialrefund | Partial refunds for the bet. |
Example Request:
POST {ExternalWalletEndpoint}/credit
Request body:
{
"transactionId": "transaction-uuid",
"betId": "bet-uuid",
"userId": "user-uuid",
"bonusFlag": false, // True for bonus bets.
"transactionType": "betwincancelled",
"amount": 100, // Refunded amount.
}
Success Response:
{
"success": true
}
Error Response:
{
"message": "Readable message.",
"code": "ErrCode",
"statusCode": 401
}
On-Demand Services (BackOffice APIs)
On-demand query services operate as an open endpoint, requiring only the inclusion of the x-api-key in the request headers. For user-related queries or subscriptions, the access token needs to be passed in the header. Components designed for the tenant frontend can access both bet subscriptions and query data.
Getting Access Token
Access token can be aquired by calling provide oAuth endpoint
Example Request:
POST {BackOffice_TokenEndpoint}
Request body:
{
"grant_type": "client_credentials",
"client_id": "{BackOffice_ClientID}",
"client_secret": "{BackOffice_ClientSecret}"
}
Response:
{
"access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
"expires_in": 3600,
"token_type": "bearer",
"scope": null
}
Example Curl:
curl --location '<BackOffice_TokenEndpoint>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: XSRF-TOKEN=efa6365e-c468-4fc3-aba0-0b364be0c8b9' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<BackOffice_ClientID>' \
--data-urlencode 'client_secret=<BackOffice_ClientSecret>'
Available APIs
Query: GetBets
This query retrieves all bets for a for given ids for tenant(s).
Example Schema:
Headers:
{
"X-API-Key": "<BackOffice_ClientID>",
"Authorization": "Bearer <ACCESS_TOKEN>"
}
Query:
query GetBets {
getBets(
input: {
tenant: {
ids: ["<tenant-uuid>"]
bet_ids: ["<bet-uuid>"]
}
}
) {
bets {
id
created_at
legs {
bet_type
dividend
event_id
...
}
metadata {
created_at
tenant_id
user_id
...
}
}
pagination {
last_id
count
}
}
}
Example Curl:
curl '<BackOffice_Endpoint>/query' \
-H 'accept: */*' \
-H 'content-type: application/json' \
-H 'authorization: bearer <ACCESS_TOKEN>' \
-H 'x-api-key: <BackOffice_ClientID>' \
--data-raw '{"query":"query GetBets {\n getBets(\n input: {\n tenant: {\n ids: [\"<tenant-uuid>\"]\n bet_ids: [\"1f2eeaff-0f79-40fa-92d6-b1ffbd9ce8ba\"]\n }\n }\n ) {\n bets {\n id\n created_at\n legs {\n bet_type\n dividend\n event_id\n event_name\n event_time\n leg_type\n meeting_id\n meeting_name\n postions_paid\n product_keyword\n sport_id\n sport_name\n race_number\n }\n metadata {\n created_at\n tenant_id\n user_id\n account_id\n account_type\n ticket_id\n fixed_odds\n original_odds\n amount\n original_amount\n percentage\n original_percentage\n is_partial\n status\n source\n medium\n bet_limit_id\n reason\n reason_id\n message\n action_id\n liability_percentage\n liability\n is_fixed\n is_flexi\n is_boxed\n bet_type\n teller_id\n is_cashout\n is_livebet\n ip_address\n }\n }\n pagination {\n last_id\n count\n }\n }\n}\n","operationName":"GetBets"}'
Mutation: CancelBet
The following mutation lets the client cancel the bets.
Example Schema:
Headers:
{
"X-API-Key": "<BackOffice_ClientID>",
"Authorization": "<ACCESS_TOKEN>"
}
Query:
mutation CancelBet {
cancelBet(
bet: {
id: "<bet-uuid>"
tenant_id: "<tenant-uuid>"
}
)
}
Example Curl:
curl '<BackOffice_Endpoint>/query' \
-H 'accept: */*' \
-H 'content-type: application/json' \
-H 'authorization: bearer <ACCESS_TOKEN>' \
-H 'x-api-key: <BackOffice_ClientID>' \
--data-raw '{"query":"mutation CancelBet {\n cancelBet(\n bet: {\n id: \"1f2eeaff-0f79-40fa-92d6-b1ffbd9ce8ba\"\n tenant_id: \"<tenant-uuid>\"\n }\n )\n}\n","operationName":"CancelBet"}'