Skip to main content

Getting Started

Welcome to the accounting service API documentation. This guide will take you through the journey of managing users, accounts, and transactions within your betting application using our API. Let's get started!

Setting Up Your Betting Business

Imagine you are the owner of a new betting platform, and you need to set up an account to manage your finances and bet settlements. The first step is to create an account.

Creating an Account

To create an account, you need to send a POST request to our API with your betting business details. Here's how you can do it using different clients:

curl -X POST "$baseUrl/auth/register/account" \
-H "Content-Type: application/json" \
-d '{
"name": "My Betting Business",
"email": "owner@mybetting.com",
"password": "secure_password_here"
}'

Upon successful creation, the API will respond with your account details:

{
"message": "Account created successfully"
}

Authentication

Before creating users or performing other operations, you need to authenticate your account. There are two methods for authentication:

1. Token Authentication

You can log in with your account credentials to obtain a token:

curl -X POST "$baseUrl/auth/login/account" \
-H "Content-Type: application/json" \
-d '{
"email": "owner@mybetting.com",
"password": "secure_password_here"
}'

The API will respond with a token:

{
"data": {
"token": "OCFUBbMIX4PGXb4ROw5xKVC8kW8tGSBh"
},
"message": "Logged into account successfully"
}

This token should be included as a Bearer token in the Authorization header for all subsequent requests:

Authorization: Bearer OCFUBbMIX4PGXb4ROw5xKVC8kW8tGSBh

2. API Key Authentication

Alternatively, you can generate API keys for more secure, long-term authentication:

# First, log in to get a token
token=$(curl -X POST "$baseUrl/auth/login/account" \
-H "Content-Type: application/json" \
-d '{
"email": "owner@mybetting.com",
"password": "secure_password_here"
}' | jq -r '.data.token')

# Then use the token to generate API keys
curl -X POST "$baseUrl/auth/account/generate-keys" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json"

The API will respond with your API keys:

{
"data": {
"api_key": "api_key_k4rBSsfzj6SyJbsKOT3YXRXsmKRZuYT4",
"api_secret": "api_secret_80d6bx3NNRsqELP6in2eVS56jSGyVNhiUtRMeImnUoJWc8DQYgLnwm1gH45PISQN",
"base64_encoded": "YXBpX2tleV9rNHJCU3Nmemo2U3lKYnNLT1QzWVhSWHNtS1JadVlUNDphcGlfc2VjcmV0XzgwZDZieDNOTlJzcUVMUDZpbjJlVlM1NmpTR3lWTmhpVXRSTWVJbW5Vb0pXYzhEUVlnTG53bTFnSDQ1UElTUU4="
},
"message": "Api keys generated successfully"
}

You can use these API keys in one of two ways:

  1. Using the base64_encoded value directly:
Authorization: Basic YXBpX2tleV9rNHJCU3Nmemo2U3lKYnNLT1QzWVhSWHNtS1JadVlUNDphcGlfc2VjcmV0XzgwZDZieDNOTlJzcUVMUDZpbjJlVlM1NmpTR3lWTmhpVXRSTWVJbW5Vb0pXYzhEUVlnTG53bTFnSDQ1UElTUU4=
  1. Using the api_key as username and api_secret as password for Basic Auth.

Creating a User

Once you have authenticated, you can create users who will be placing bets on your platform. To create a user, you need to send a POST request to our API with the user's details. The reference field is optional and will be generated if not provided. The preferences field is also optional.

# Using token authentication
curl -X POST "$baseUrl/account/user" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
"reference": "danny_user", # Optional
"name": "User 3",
"preferences": {} # Optional
}'

# Or using API key authentication
curl -X POST "$baseUrl/account/user" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json" \
-d '{
"reference": "danny_user", # Optional
"name": "User 3",
"preferences": {} # Optional
}'

Upon successful creation, the API will respond with the user's details:

{
"data": {
"id": 2,
"reference": "a2_user_Xhwz442NTj74z6F0"
},
"message": "User created successfully"
}

Flow of Creating a User

Here is a visual representation of the flow for creating a user:

This diagram shows the complete sequence of API calls to create an account, authenticate, and then create a user.

Fund User Account

To fund a user account, you need to send a POST request to our API with the amount and either the user_id or user_reference. This request must be authenticated, either by token or API key.

Fund User Account

To fund a user account, you need to send a POST request to the /transactions/fund-user/ endpoint with the amount and either the user_id or user_reference.

# Using token authentication
curl -X POST "$baseUrl/transactions/fund-user/" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
"amount": 1000,
"user_id": 1
// "user_reference": "a1_user_dkjH6xmZzHHHgz5M" # Optional
}'

# Or using API key authentication
curl -X POST "$baseUrl/transactions/fund-user/" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json" \
-d '{
"amount": 1000,
"user_id": 1
// "user_reference": "a1_user_dkjH6xmZzHHHgz5M" # Optional
}'

Upon successful funding, the API will respond with the transaction details:

{
"data": {
"id": 1,
"user_id": 1,
"account_id": 2,
"reference": "TX_u6qGJ1A4qw0mV_5wMSJQ7dF5pe0S8HA3c4i1Z5YN7HD7loom",
"amount": 1000,
"description": "Balance funded",
"transaction_type": "credit",
"transaction_source": "funding",
"created_at": "2025-05-09T14:57:43.759Z"
},
"message": "Account funded successfully"
}

Check User Balance

To check a user's balance, you can use either the user_id or user_reference.

  • /account/user/:userId
  • /account/user/:reference/reference
# Using user_id
curl -X GET "$baseUrl/account/user/1" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json"

# Or using user_reference
curl -X GET "$baseUrl/account/user/a1_user_FclirLc2MJecJqsi/reference" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json"

The API will respond with the user's details:

{
"data": {
"id": 1,
"account_id": 2,
"reference": "a2_user_4lH6u7hayvaqs6Ix",
"name": "Jane Dodde",
"role": "user",
"preferences": {
"allow_negative_balance": true
},
"balance": 1000,
"exposure": 0
},
"message": "User fetched successfully"
}

Flow of Funding a User Account and Checking Balance

Here is a visual representation of the flow for funding a user account and checking the balance:

Placing a Bet Offer

To place a bet offer, you need to send a POST request to our API with the bet details. This request must be authenticated, either by token or API key.

Placing a Bet Offer

To place a bet offer, you need to send a POST request to the /bets/make-offer endpoint with the bet details. You can either use the user_id or user_reference to make a bet offer.

# Using token authentication
curl -X POST "$baseUrl/bets/make-offer" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
"requesting_user_reference": "a1_user_dkjH6xmZzHHHgz5M",
"requesting_odds": 3,
"requesting_amount": 300,
"wager_reference": "wager-4"
}'

# Or using API key authentication
curl -X POST "$baseUrl/bets/make-offer" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json" \
-d '{
"requesting_user_reference": "a1_user_dkjH6xmZzHHHgz5M",
"requesting_odds": 3,
"requesting_amount": 300,
"wager_reference": "wager-4"
}'

Upon successful bet offer, the API will respond with the bet details:

{
"data": {
"bet_id": 1,
"wager_reference": "wager-4",
"wager_id": 1
},
"message": "Bet offer placed successfully"
}

Viewing Open Bet Offers

To view open bet offers, you need to send a GET request to our API. This request must be authenticated, either by token or API key.

Viewing Open Bet Offers

To view open bet offers, you need to send a GET request to the /bets/open-bets endpoint.

# Using token authentication
curl -X GET "$baseUrl/bets/open-bets" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json"

# Or using API key authentication
curl -X GET "$baseUrl/bets/open-bets" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json"

The API will respond with the open bet offers:

{
"data": [
{
"id": 1,
"account_id": 1,
"offer_status": "requesting",
"wager_id": 1,
"wager_reference": "wager-4",
"requesting_user_id": 1,
"requesting_user_reference": "a1_user_FclirLc2MJecJqsi",
"requesting_odds": 3,
"requesting_amount": 300,
"created_at": "2025-03-06T02:49:52.080Z"
}
],
"per_page": 20,
"page": 1,
"total": 1,
"from": 1,
"to": 1,
"last_page": 1,
"total_requesting_amount": 300
}

Accepting Bet Offers

To accept a bet offer, you need to send a POST request to our API with the bet offer details. This request must be authenticated, either by token or API key.

Accepting Bet Offers

To accept a bet offer, you need to send a POST request to the /bets/accept-offer endpoint with the bet offer details. The requesting_user_id, requesting_user_reference, and meta are optional. If they are not provided, the system will determine the bets to be accepted. To define the accepting user, use either the accepting_user_id or the accepting_user_reference.

# Using token authentication
curl -X POST "$baseUrl/bets/accept-offer" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
"requesting_user_id": 1,
// "requesting_user_reference": "a1_user_dkjH6xmZzHHHgz5M", # Optional
"accepting_user_id": 2,
// "accepting_user_reference": "a1_user_4i0j18x3xN5BkB42", # Optional
"accepting_amount": 300,
"maximum_odds": 3,
"wager_reference": "wager-4"
// "meta": {"data": 12} # Optional
}'

# Or using API key authentication
curl -X POST "$baseUrl/bets/accept-offer" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json" \
-d '{
"requesting_user_id": 1,
// "requesting_user_reference": "a1_user_dkjH6xmZzHHHgz5M", # Optional
"accepting_user_id": 2,
// "accepting_user_reference": "a1_user_4i0j18x3xN5BkB42", # Optional
"accepting_amount": 300,
"maximum_odds": 3,
"wager_reference": "wager-4"
// "meta": {"data": 12} # Optional
}'

Upon successful acceptance of the bet offer, the API will respond with the bet details:

{
"data": [
{
"bet_id": 1,
"requesting_user_reference": "a1_user_FclirLc2MJecJqsi",
"requesting_user_id": 1,
"accepted_amount": 300,
"accepted_odds": 3,
"wager_reference": "wager-4",
"wager_id": 1
}
],
"message": "Bet offer accepted successfully"
}

Flow of Placing a Bet Offer, Viewing Open Bet Offers, and Accepting Bet Offers

Here is a visual representation of the flow for placing a bet offer, viewing open bet offers, and accepting bet offers:

Update Wager Outcome

To update a wager outcome, you need to send a POST request to our API with the wager reference and the outcome. This request must be authenticated, either by token or API key.

Update Wager Outcome

To update a wager outcome, you need to send a POST request to the /bets/update-wager-outcome endpoint with the wager reference and the outcome. The outcome can be one of the following: win, loss, half-win, half-loss, push, or void.

# Using token authentication
curl -X POST "$baseUrl/bets/update-wager-outcome" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
"reference": "wager-4",
"outcome": "half-win"
}'

# Or using API key authentication
curl -X POST "$baseUrl/bets/update-wager-outcome" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json" \
-d '{
"reference": "wager-4",
"outcome": "half-win"
}'

Upon successful update, the API will respond with a message:

{
"message": "Wager outcome updated successfully"
}

Get Bet History

To get bet history, you need to send a GET request to our API. This request must be authenticated, either by token or API key.

Get Bet History

To get bet history, you need to send a GET request to the /bets/history endpoint.

# Using token authentication
curl -X GET "$baseUrl/bets/history" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json"

# Or using API key authentication
curl -X GET "$baseUrl/bets/history" \
-H "Authorization: Basic $base64_encoded" \
-H "Content-Type: application/json"

The API will respond with the bet history:

[
{
"id": 1,
"requesting_user_id": 1,
"requesting_user_reference": "a1_user_FclirLc2MJecJqsi",
"accepting_user_id": 2,
"accepting_user_reference": "a1_user_oNOxm0ZuRJsgySMZ",
"offer_status": "accepted",
"effective_amount": 300,
"effective_odds": 3,
"created_at": "2025-03-06T02:49:52.080Z",
"wager": {
"id": 1,
"reference": "wager-4",
"outcome": "half-win",
"account_id": 1,
"created_at": "2025-03-06T02:49:52.080Z",
"updated_at": "2025-03-06T02:54:48.405Z"
},
"bet_trails": [
{
"id": 1,
"bet_id": 1,
"account_id": 1,
"wager_id": 1,
"offer_status": "requesting",
"description": "Requesting for bet",
"outcome": "undecided",
"requesting_odds": 3,
"requesting_amount": 300,
"accepting_odds": null,
"accepting_amount": null,
"effective_odds": null,
"effective_amount": null,
"created_at": "2025-03-06T02:49:52.080Z",
"transactions": []
},
{
"id": 2,
"bet_id": 1,
"account_id": 1,
"wager_id": 1,
"offer_status": "accepted",
"description": "Bet offer accepted",
"outcome": "undecided",
"requesting_odds": 3,
"requesting_amount": 300,
"accepting_odds": 3,
"accepting_amount": 300,
"effective_odds": null,
"effective_amount": null,
"created_at": "2025-03-06T02:53:36.773Z",
"transactions": []
},
{
"id": 3,
"bet_id": 1,
"account_id": 1,
"wager_id": 1,
"offer_status": "accepted",
"description": "Bet offer accepted",
"outcome": "half-win",
"requesting_odds": 3,
"requesting_amount": 300,
"accepting_odds": 3,
"accepting_amount": 300,
"effective_odds": null,
"effective_amount": null,
"created_at": "2025-03-06T02:54:48.403Z",
"transactions": [
{
"id": 2,
"account_id": 1,
"bet_trail_id": 3,
"user_id": 1,
"user_reference": "a1_user_FclirLc2MJecJqsi",
"reference": "TX_-6EaRcGbweZFLlvy-FqYsjBd_9SGbw2chQqswJNNi1Vf0v0m",
"amount": 300,
"description": "Won 300 from wager wager-4",
"transaction_type": "credit",
"transaction_source": "bet",
"created_at": "2025-03-06T02:54:48.403Z"
},
{
"id": 3,
"account_id": 1,
"bet_trail_id": 3,
"user_id": 2,
"user_reference": "a1_user_oNOxm0ZuRJsgySMZ",
"reference": "TX_fWFFLUU8T1mRDvP60U5YZDtMK-r8yaU1Oh11976vMWoLn8h4",
"amount": 300,
"description": "Lost 300 on wager wager-4",
"transaction_type": "debit",
"transaction_source": "bet",
"created_at": "2025-03-06T02:54:48.403Z"
}
]
}
]
}
]

Flow of Updating Wager Outcome and Getting Bet History

Here is a visual representation of the flow for updating a wager outcome and getting bet history: