Wallet
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.
Table of Content
- Authentication (Frontend - BetMakers)
- Wallet Integration (Betmakers - Wallet)
- On demand services (Wallet - BetMakers)
Authentication (Frontend - BetMakers)
We support two types of authentication methods. We recommend using JWT authentication; however, you are free to choose either one of them.
- JWT Authentication.
- Custom Authentication.
JWT Authentication.
JWT is employed for authentication between systems, and JWKS is utilised to validate the tokens in our integration processes. The diagram below outlines the fundamental flow for implementing authentication in the integration process.
JWT Specification
Following claims needs to be present on JWT body.
"client_id": "provided-client-id",
"aud": "user-uuid",
"token_use": "access",
"username": "user-uuid",
JWKS Specification.
The JWKS key sets must be configured using the RS256 standard for our integration.
Key sets should be made available through a publicly accessible endpoint. An example response body is provided below.
{
"keys": [
{
"kty": "RSA",
"use": "sig",
"alg": "RS256",
"kid": "64527lkxjcvnkawk11213a",
"n": "0oDGt_owqzVNAW4D0-LnJ7LwLK",
"e": "AQAB"
}
]
}
Custom Authentication.
With the Custom Authentication method, clients are permitted to generate any kind of encrypted token. Token verification is expected to be performed at the reserveFunds call (refer to the wallet integration section). User claims should be passed via the user metadata object (Refer host.state.user event documentation).
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.
- Confirm Transaction.
- Refund Bet Transaction.
- Settle Bet Transaction.
- Debit Transaction.
- Credit Transaction.
Reserve Transaction.
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 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,
"fixedOdds": 1.38,
"percentage": 2200,
"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
}
RefundBet Transactions.
The refund transaction call will only be triggered upon the successful reservation of funds.
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.
ExampleBet 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: cancelBets
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"}'