# Introduction
Betstack is a platform for FRICTIONLESS Betting across a variety of channels including Web, Mobile in-app, Messenger Bots, USSD, SMS and in retail outlets in cashier or betting terminals. In this developers portal you find documentation needed to setup Betstack to offer FRICTIONLESS Betting to your players.
Betstack services is easy to integrate with any Player Account Management (PAM) platforms and works alongside other game content such as Sportsbook, Casino games, Virtual Sports and Lotteries and other game systems.
In this Developer Portal we have prepared important information to get you quickly started with Betstack.
# Getting Started
Get started with Betstack learn about the differnet modules and simple steps to get started.
{% hint style="info" %}
Only authorized users can access the Betstack APIs. If you haven't received your account information please reach out to your account manager.
{% endhint %}
Betstack is a powerful and modular solution for managing Micro Bets. In simple steps you can offer different types of micro bets to your customers. This Getting started section provides an overview of the different modules and APIs you need to integrate Betstack to your platform.
There are 3 APIs developers need to get familiar with when working with Betstack.
API
Usage
Bet Cards API
Bet Cards contains information about the Micro Bet configuration, such as teams, odds, stake and other playable settings
Bet Engine API
Processing engine for Micro Bets
PAM API
Ticketing for Player Account Management (PAM) Platforms
# Signature
Generate HMAC hash signature to access Betstack APIs
Some APIs require signature in incoming requests (like BetEngine API).
The Signature is calculated based on the `timestamp`, `request body` and your `Secret Key` with HMAC hash using SHA256 Algorithm.
Here is an example on how to generate the Signature for create `/ticket` request with `Secret Key=12345ABCDE`, `timestamp=1706090303` and following request body:
```json
{
"operator": "site",
"token": "UnIqUe-ToKeN",
"price": 5000,
"currency": "KES",
"atag": "affiliate-1",
"source": "mobile",
"type": "superbet",
"event": 100001,
"bets": [101, 102, 103, 104, 105, 106]
}
```
In order to generate the Signature all spaces must be removed from the request body:
```json
{"operator":"site","token":"UnIqUe-ToKeN","price":5000,"currency":"KES","atag":"affiliate-1","source":"mobile","type":"superbet","event":100001,"bets":[101,102,103,104,105,106]}
```
{% hint style="info" %}
Please note that the order of the fields matters for calculating the signature. Fields must be in the same order they are listed on doc pages for requests.
{% endhint %}
{% hint style="info" %}
Please note that optional fields, like `atag` must also be included in signature generation, even if they have `null` values. For example, if `atag` field has `null` value then it must be included in signature generation like so:
```
{...,"atag":null,...}
```
{% endhint %}
Then message for HMAC algorithm has to be formed using following template:
```
{timestamp}{request body with removed spaces}
```
{% hint style="info" %}
Please note that for requests that have no body, like GET requests, above template will only consist of `{timestamp}`.
{% endhint %}
So the message should look like the following:
```
1706090303{"operator":"site","token":"UnIqUe-ToKeN","price":5000,"currency":"KES","atag":"affiliate-1","source":"mobile","type":"superbet","event":100001,"bets":[101,102,103,104,105,106]}
```
The computed Signature for this request is:
```
f99aee9f77eef1ee8b64c78e7f8612e3234f03cce5fecdebd7ea27f2b9081423
```
A free online HMAC Generator for testing is available on .
Here is how we calculated the Signature from above example using **Free Formatter**
{% hint style="info" %}
Your `Secret Key` is located on your API Settings page. Login to Betstack to access your `Secret Key`
{% endhint %}
Secret Key is locate in API Settings profile page
# Bet Card API
# Calculator
# Finance details
GET \`/bc/calculator/finance-details\` endpoint
Calculates detailed finance info: taxes and payouts.
Query parameters:
Parameter name
Data Type
Description
operator
string
Operator name. For example, for operator acme the value should be operator=acme
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value should be price=3500
odds
list of floats
List of event odds at time of ticket submission. Should be in decimal format with 2 digits after comma. For example, for odds 1.24 and 2.76 the value should be odds=1.24&odds=2.76
Operator name. For example, for operator acme the value should be operator=acme
rtag
string
rtag value
Response example:
```json
{
"rtag": "MzgwMjIxMjM0NTY3"
}
```
# Telegram deep link
GET \`bc/referral/tg-deep-link\` endpoint
Created valid telegram deep link
Query parameters:
Parameter name
Data Type
Description
operator
string
Operator name. For example, for operator acme the value should be operator=acme
rtag
string
rtag value
betcard_code
string
Code of the betcard which was used for ticket creation
Response example:
```json
{
"link": "https://t.me/bot_name?start=Yj1DT0RFMTImYXRhZz1Nemd3TWpJeE1qTTBOVFkz"
}
```
# Bet Engine API
Bet Engine service is called for ticket processing
API Endpoint :
Bet Engine service is responsible for processing the tickets. When tickets are submitted to Bet Engine, the service will invoke PAM API for integration with operator's platform.
The following sections are available in Bet Engine API:
[Headers](/bet-engine-api/headers)
[Create ticket endpoint](/bet-engine-api/create-ticket-endpoint)
[Reserve ticket endpoint](/bet-engine-api/reserve-ticket-endpoint)
[Paid ticket endpoint](/bet-engine-api/paid-ticket-endpoint)
[Get ticket endpoint](/bet-engine-api/get-ticket-endpoint)
[Get ticket list endpoint](/bet-engine-api/get-ticket-list-endpoint)
[Fields](/bet-engine-api/fields)
[Error codes](/bet-engine-api/error-codes)
# Headers
Access to Bet Engine API is authorized by the request headers. Please take timestamp and operator name and generate your request signature as described in [Signature](/signature)
Headers
Attribute
Description
timestamp
The unix time stamp
operator-name
Operator Name
signature
Signature of incoming request body and secret key (HMAC)
# Create ticket endpoint
POST \`/be/tickets\` endpoint
Currently we support 6 ticket types:
Details for creating `quicktip` ticket type are here - [Quicktip](/bet-engine-api/create-ticket-endpoint/quicktip)
Details for creating `smartbet` ticket type are here - [Smartbet](/bet-engine-api/create-ticket-endpoint/smartbet)
Details for creating `quickbet` ticket type are here - [Quickbet](/bet-engine-api/create-ticket-endpoint/quickbet)
Details for creating `quickbetx` ticket type are here - [QuickbetX](/bet-engine-api/create-ticket-endpoint/quickbetx)
Details for creating `superbet` ticket type are here - [Superbet](/bet-engine-api/create-ticket-endpoint/superbet)
Details for creating `jackpot` ticket type are here - [Jackpot](/bet-engine-api/create-ticket-endpoint/jackpot)
# Quicktip
POST \`/be/tickets\` endpoint
Create quicktip ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Specifies the max odds deviation when we still accept the request and create the ticket.
When the value is set to zero it means we don't allow any odds difference during ticket creation and will respond with "Ticket odds changed" Error response
events
list of objects
events id
integer
Event id
events bet
integer
Event bet id
events odds
float
Event odds at time of ticket submission. Should be in decimal format with 2 digits after comma
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 104,
"message": "Events list in ticket object can't be empty"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 108,
"message": "Bookmaker event for event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 109,
"message": "Market is blocked"
}
```
Error response (status=400):
```json
{
"code": 110,
"message": "Ticket odds changed"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
# Smartbet
POST \`/be/tickets\` endpoint
Create smartbet ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/create-ticket-endpoint/quicktip) ticket except ticket type must be `smartbet`.
# Quickbet
POST \`/be/tickets\` endpoint
Create quickbet ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/create-ticket-endpoint/quicktip) ticket except ticket type must be `quickbet`.
# QuickbetX
POST \`/be/tickets\` endpoint
Create quickbetx ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/create-ticket-endpoint/quicktip) ticket except ticket type must be `quickbetx`.
# Superbet
POST \`/be/tickets\` endpoint
Create superbet ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
Error response (status=400):
```json
{
"code": 116,
"message": "Market with `{market-id}` code is not allowed"
}
```
# Jackpot
POST \`/be/tickets\` endpoint
Create jackpot ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Specifies the max odds deviation when we still accept the request and create the ticket.
When the value is set to zero it means we don't allow any odds difference during ticket creation and will respond with "Ticket odds changed" Error response
events
list of objects
events id
integer
Event id
events bet
integer
Event bet id
events odds
float
Event odds at time of ticket submission. Should be in decimal format with 2 digits after comma
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 104,
"message": "Events list in ticket object can't be empty"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 108,
"message": "Bookmaker event for event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 109,
"message": "Market is blocked"
}
```
Error response (status=400):
```json
{
"code": 110,
"message": "Ticket odds changed"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
Error response (status=400):
```json
{
"code": 118,
"message": "Events list must contain at least {correct_amount} items."
}
```
# Reserve ticket endpoint
POST \`/be/tickets/reserve\` endpoint
Currently we support 6 ticket types:
Details for reserving `quicktip` ticket type are here - [Quicktip](/bet-engine-api/reserve-ticket-endpoint/quicktip)
Details for reserving `smartbet` ticket type are here - [Smartbet](/bet-engine-api/reserve-ticket-endpoint/smartbet)
Details for reserving `quickbet` ticket type are here - [Quickbet](/bet-engine-api/reserve-ticket-endpoint/quickbet)
Details for reserving `quickbetx` ticket type are here - [QuickbetX](/bet-engine-api/reserve-ticket-endpoint/quickbetx)
Details for reserving `superbet` ticket type are here - [Superbet](/bet-engine-api/reserve-ticket-endpoint/superbet)
Details for reserving `jackpot` ticket type are here - [Jackpot](/bet-engine-api/reserve-ticket-endpoint/jackpot)
# Quicktip
POST \`/be/tickets/reserve\` endpoint
Reserve quicktip ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Specifies the max odds deviation when we still accept the request and create the ticket.
When the value is set to zero it means we don't allow any odds difference during ticket creation and will respond with "Ticket odds changed" Error response
events
list of objects
events id
integer
Event id
events bet
integer
Event bet id
events odds
float
Event odds at time of ticket submission. Should be in decimal format with 2 digits after comma
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 104,
"message": "Events list in ticket object can't be empty"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 108,
"message": "Bookmaker event for event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 109,
"message": "Market is blocked"
}
```
Error response (status=400):
```json
{
"code": 110,
"message": "Ticket odds changed"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
# Smartbet
POST \`/be/tickets/reserve\` endpoint
Reserve smartbet ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/reserve-ticket-endpoint/quicktip) ticket except ticket type must be `smartbet`.
# Quickbet
POST \`/be/tickets/reserve\` endpoint
Reserve quickbet ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/reserve-ticket-endpoint/quicktip) ticket except ticket type must be `quickbet`.
# QuickbetX
POST \`/be/tickets/reserve\` endpoint
Reserve quickbetx ticket.
All request and response fields are the same as in [Quicktip](/bet-engine-api/reserve-ticket-endpoint/quicktip) ticket except ticket type must be `quickbetx`.
# Superbet
POST \`/be/tickets/reserve\` endpoint
Reserve superbet ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
Error response (status=400):
```json
{
"code": 116,
"message": "Market with `{market-id}` code is not allowed"
}
```
# Jackpot
POST \`/be/tickets/reserve\` endpoint
Reserve jackpot ticket.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
token
string
Player identification token
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
Specifies the max odds deviation when we still accept the request and create the ticket.
When the value is set to zero it means we don't allow any odds difference during ticket creation and will respond with "Ticket odds changed" Error response
events
list of objects
events id
integer
Event id
events bet
integer
Event bet id
events odds
float
Event odds at time of ticket submission. Should be in decimal format with 2 digits after comma
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 103,
"message": "Event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 104,
"message": "Events list in ticket object can't be empty"
}
```
Error response (status=400):
```json
{
"code": 105,
"message": "Team with `{team-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 106,
"message": "Market for bet with `{market-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 107,
"message": "Event with `{event-id}` identifier is not available for play because it has already started"
}
```
Error response (status=400):
```json
{
"code": 108,
"message": "Bookmaker event for event with `{event-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 109,
"message": "Market is blocked"
}
```
Error response (status=400):
```json
{
"code": 110,
"message": "Ticket odds changed"
}
```
Error response (status=400):
```json
{
"code": 111,
"message": "Duplicate key for code generation"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
Error response (status=400):
```json
{
"code": 114,
"message": "No webhook url for operator with `{operator-id}` name"
}
```
Error response (status=400):
```json
{
"code": 115,
"message": "Operators in request body and in request header are not identical"
}
```
Error response (status=400):
```json
{
"code": 118,
"message": "Events list must contain at least {correct_amount} items."
}
```
# Paid ticket endpoint
POST \`/be/tickets/{identifier}/paid\` endpoint
`identifier` - this could be either ticket id or ticket code.
Will set ticket status to `open`.
Response status codes:
Status Code
Interpretation
200
OK - Everything worked as expected
400
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
Error response (status=400):
```json
{
"code": 100,
"message": "{feature} feature not implemented yet"
}
```
Error response (status=400):
```json
{
"code": 102,
"message": "Ticket with `{ticket-id}` identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 117,
"message": "Ticket has to have `reserved` status in order to do this action"
}
```
# Get ticket endpoint
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Currently we support 6 ticket types:
Details for `quicktip` ticket type fields are here - [Quicktip](/bet-engine-api/get-ticket-endpoint/quicktip)
Details for `smartbet` ticket type fields are here - [Smartbet](/bet-engine-api/get-ticket-endpoint/smartbet)
Details for `quickbet` ticket type fields are here - [Quickbet](/bet-engine-api/get-ticket-endpoint/quickbet)
Details for `quickbetx` ticket type fields are here - [QuickbetX](/bet-engine-api/get-ticket-endpoint/quickbetx)
Details for `superbet` ticket type fields are here - [Superbet](/bet-engine-api/get-ticket-endpoint/superbet)
Details for `jackpot` ticket type fields are here - [Jackpot](/bet-engine-api/get-ticket-endpoint/jackpot)
Response status codes:
Status Code
Interpretation
200
OK - Everything worked as expected
400
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 100,
"message": "Feature not implemented yet"
}
```
Error response (status=400):
```json
{
"code": 102,
"message": "Ticket with {ticket-id} identifier is not found"
}
```
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
# Quicktip
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Response fields for `quicktip` ticket:
Attribute
Data Type
Description
id
string
Betstack ticket id
code
string
Betstack ticket code
psp
string or null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
stake
integer
Ticket amount. Should be in integer format (cents). For example, for stake 30.45 the value should be 3045
# Smartbet
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Response fields for `smartbet` ticket are the same as for [Quicktip](/bet-engine-api/get-ticket-endpoint/quicktip) ticket, except `type` field will contain `smartbet` value. All other fields are the same.
# Quickbet
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Response fields for `quickbet` ticket are the same as for [Quicktip](/bet-engine-api/get-ticket-endpoint/quicktip) ticket, except `type` field will contain `quickbet` value. All other fields are the same.
# QuickbetX
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Response fields for `quickbetx` ticket are the same as for [Quicktip](/bet-engine-api/get-ticket-endpoint/quicktip) ticket, except `type` field will contain `quickbetx` value. All other fields are the same.
# Superbet
GET \`/be/tickets/{identifier}\` endpoint
`identifier` - this could be either ticket id or ticket code.
Response fields for `superbet` ticket:
Attribute
Data Type
Description
id
string
Betstack ticket id
code
string
Betstack ticket code
psp
string ot null
Optional payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
stake
integer
Ticket amount. Should be in integer format (cents). For example, for stake 30.45 the value should be 3045
gross_payout
integer
Ticket gross payout. Should be in integer format (cents). For example, for gross payout 30.45 the value should be 3045
net_payout
integer
Ticket net payout. Should be in integer format (cents). For example, for net payout 30.45 the value should be 3045
wht_amount
integer
Player withholding tax amount. Should be in integer format (cents). For example, for tax 30.45 the value should be 3045
wht
float
Player withholding tax percentage. For example, for tax 20.0% the value should be 20.0
ext_amount
integer
Ticket exercise tax amount. Should be in integer format (cents). For example, for exercise tax 1.25 the value will be 125
ext
float
Ticket exercise tax percentage. For example, for tax 12.5% the value should be 12.5
Optional. Default = 10. Number of tickets to return
user_id
string
Optional. If presented - does filtration by ticket user_id field
skip_types
list of TicketType
Optional. List of Ticket Type (see Fields). If presented - does filtration by ticket type field. Excludes tickets with types from skip_type parameter. If you want to exclude tickets with multiple types - pass types like this: ...&skip_types=superbet&skip_types=jackpot&...
Response for this endpoint is a list of objects. Each object represents separate ticket. For each ticket type response fields are the same as in [Get ticket endpoint](/bet-engine-api/get-ticket-endpoint).
Sample response (status=200):
```json
[
{
"id": "6314704d686a9e8e5d68dca6",
"code": "E36E20",
"psp": null,
"price": 2000,
"stake": 1800,
"currency": "USD",
"gross_payout": 12000,
"net_payout": 10000,
"wht_amount": 1300,
"wht": 0.0,
"ext_amount": 200,
"ext": 10.0,
"ext_type": "inclusive",
"status": "open",
"result": "pending",
"approved": true,
"source": "desktop",
"type": "quicktip",
"atag": "atag_value",
"rtag": null,
"aff_instant_comm_amt": null,
"aff_instant_comm_pct": null,
"user_id": "1660986605374148608",
"psp": "mobile",
"created": "2022-09-04T09:30:53.000000",
"operator_time_created": "2022-09-04T11:30:53.000000",
"updated": "2022-09-04T09:30:53.000000",
"operator_time_updated": "2022-09-04T11:30:53.000000",
"events": [...],
"odds": 7.4
},
{
"id": "6314704d686a9e8e5d68dca6",
"code": "E36E20",
"price": 2000,
"stake": 1800,
"gross_payout": 0,
"net_payout": 0,
"wht_amount": 0,
"wht": 0.0,
"ext_amount": 200,
"ext": 10.0,
"ext_type": "inclusive",
"currency": "USD",
"status": "resulted",
"result": "lost",
"approved": true,
"source": "desktop",
"type": "superbet",
"atag": null,
"rtag": "44nnljrn4r",
"aff_instant_comm_amt": null,
"aff_instant_comm_pct": null,
"user_id": "1660986605374148608",
"psp": "mobile",
"created": "2022-09-04T09:30:53.000000",
"operator_time_created": "2022-09-04T11:30:53.000000",
"updated": "2022-09-04T09:30:53.000000",
"operator_time_updated": "2022-09-04T11:30:53.000000",
"event": {...},
"bets": [...]
},
...
]
```
Response status codes:
Status Code
Interpretation
200
OK - Everything worked as expected
400
Bad Request. Please check error code in response body (see Error codes)
403
Forbidden. You do not have access for such request
422
Validation Error. Please check response body for more details
Error response (status=400):
```json
{
"code": 112,
"message": "Operator with `{operator-id}` name is not found"
}
```
# Fields
Field values used in Bet Engine API
#### Ticket Fields
Attribute
Data Type
Description
result
string
pending / won / lost / void
status
string
new / *cancelled / reserved / open / calculating / resulted / closed
# Error codes
Full list of error codes for 400 response status code:
Error Code
Interpretation
100
{feature_name} feature not implemented yet
101
Error with incoming data
102
Ticket with {ticket-id} identifier is not found
103
Event with {event-id} identifier is not found
104
Events list in ticket object can't be empty
105
Team with {team-id} identifier is not found
106
Market for bet with {bet-id} identifier is not found
107
Event with {event-id} identifier is not available for play because it has already started
108
Bookmaker event for event with {event-id} identifier is not found
109
Market is blocked
110
Ticket odds changed
111
Duplicate key for code generation
112
Operator with {operator-name} name is not found
113
Error while request to PAM {action-name} action
114
No webhook url for operator with {operator-id} name
115
Operators in request body and in request header are not identical.
116
Market with {market-id} code is not allowed.
117
Ticket has to have {status} status in order to do this action.
118
Events list must contain at least {correct_amount} items.
# PAM Platform API
PAM Platform service is a backend integration calling operators PAM Platform
API Endpoint :
When tickets are submitted to Bet Engine, the service will invoke PAM API for integration with operator's platform.
{% hint style="info" %}
You can use our accept all proxy PAM API service on as your PAM endpoint in your API settings during development phase for acceptance of all requests.
{% endhint %}
Flowchart illustrating ticket process between Betengine and PAM Platform API when ticket is submitted from a Micro Bet:
{% file src="/files/IxsSFhyo6GemfyB8ebdE" %}
# Headers
In all requests for all actions (except `ping` action) two headers will be sent:
Attribute
Description
timestamp
The unix time stamp
signature
Signature of incoming request body and secret key (HMAC)
By checking signature in request you may confirm that the webhook came from us.
Detailed info about how to calculate signature may be found on [Signature](/pam-platform-api/signature) page.
# Signature
Generate HMAC hash signature to check that webhook is actually coming from BetEngine.
The Signature is calculated based on the `timestamp`, `request body` and your `Secret Key` with HMAC hash using SHA256 Algorithm.
Here is an example on how to generate the Signature for `ticket_create` action with `Secret Key=12345ABCDE`, `timestamp=1706191612` and following request body:
```json
{
"action": "ticket_create",
"data": {
"operator": "acme",
"ticket_id": "668ef666333180bba97f0c93",
"ticket_code": "CD4BDD",
"player_id": "sometokenvalue",
"price": 500,
"stake": 444,
"wht_amount": 240,
"wht": 10,
"ext_amount": 56,
"ext": 12.5,
"ext_type": "inclusive",
"gross_payout": 2842,
"net_payout": 2602,
"currency": "USD",
"atag": "atag_value",
"rtag": null,
"ticket_type": "quickbet"
}
}
```
In order to generate the Signature all spaces must be removed from the request body:
```json
{"action":"ticket_create","data":{"operator":"acme","ticket_id":"668ef666333180bba97f0c93","ticket_code":"CD4BDD","player_id":"sometokenvalue","price":500,"stake":444,"wht_amount":240,"wht":10,"ext_amount":56,"ext":12.5,"ext_type":"inclusive","gross_payout":2842,"net_payout":2602,"currency":"USD","atag":"atag_value","rtag":null,"ticket_type":"quickbet"}}
```
{% hint style="info" %}
Please note that the order of the fields matters for calculating the signature. It will always be `action` first then `data`. Fields in `data` must be in the same order they are listed on doc pages for actions.
{% endhint %}
{% hint style="info" %}
Please note that optional fields, like `atag` or `rtag` will also be included in signature generation, even if they have `null` values. For example, if `atag` field has `null` value then it will be included in signature generation like so:
```
{...,"atag":null,...}
```
{% endhint %}
Then message for HMAC algorithm has to be formed using following template:
```
{timestamp}{request body with removed spaces}
```
So the message should look like the following:
```
1706191612{"action":"ticket_create","data":{"operator":"acme","ticket_id":"668ef666333180bba97f0c93","ticket_code":"CD4BDD","player_id":"sometokenvalue","price":500,"stake":444,"wht_amount":240,"wht":10,"ext_amount":56,"ext":12.5,"ext_type":"inclusive","gross_payout":2842,"net_payout":2602,"currency":"USD","atag":"atag_value","rtag":null,"ticket_type":"quickbet"}}
```
The computed Signature for this request is:
```
3fe37f41ba6dc960fd2a7098bd4643f971ff1408a31bcea9f3ef8d03b3ba2d0a
```
A free online HMAC Generator for testing is available on .
Here is how we calculated the Signature from above example using **Free Formatter**
{% hint style="info" %}
Your `Secret Key` is located on your API Settings page. Login to Betstack to access your `Secret Key`
{% endhint %}
Secret Key is locate in API Settings profile page
# Ping
{% hint style="info" %}
`Signature` header will not be sent with this action.
{% endhint %}
Is used to verify the availability of API provided by the operator's platform Request:
```json
{
"action": "ping"
}
```
```
Response: 200
Doesn't require any payload
```
# Identify
Used to identify player using token generated by operator before.
In case of successful identification, PAM expects Response 200, otherwise return response with code 403 Request.
Request fields:
Sample `identify` response:
```json
Response: 200
{
"player_id": "1660986605374148608",
"lang": "en",
"balance": 1000,
"currency": "KES",
"feature_flags": {
"flag_name1": true,
"flag_name2": false
}
}
Response: 400
{
"code": 101,
"message": "User not found"
}
```
# Create a ticket
Is used when player creates a ticket (betslip). It takes money out of player's account. In case of not successful response a `ticket_discard` action will be called. In case of not successful call of `ticket_discard` action, call should be repeated after 30 mins.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket identification number
ticket_code
string
Ticket code
player_id
string
Player identification number or code
psp
string
Payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
stake
integer
Ticket stake. Should be in integer format (cents). For example, for stake 33.45 the value will be 3345
wht_amount
integer
Player withholding tax amount. Should be in integer format (cents). For example, for withholding tax amount 4.55 the value will be 455
wht
float
Player withholding tax percentage. For example, for withholding tax percentage 20.0% the value should be 20.0
ext_amount
integer
Ticket exercise tax amount. Should be in integer format (cents). For example, for exercise tax amount 1.25 the value will be 125
ext
float
Ticket exercise tax percentage. For example, for exercise tax percentage 12.5% the value should be 12.5
Sample request:
```json
{
"action": "ticket_create",
"data": {
"operator": "acme",
"ticket_id": "668ef666333180bba97f0c93",
"ticket_code": "CD4BDD",
"player_id": "sometokenvalue",
"psp": "mobile",
"price": 500,
"stake": 444,
"wht_amount": 240,
"wht": 10.0,
"ext_amount": 56,
"ext": 12.5,
"ext_type": "inclusive",
"gross_payout": 2842,
"net_payout": 2602,
"currency": "USD",
"atag": "atag_value",
"rtag": null,
"ticket_type": "quickbet",
},
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Reserve the ticket
Is used when player reserves a ticket (betslip). It creates a not wagered ticket. Once the player pays for the ticket its status is changed to open. In case of not successful response a `ticket_discard` action will be called. In case of not successful call of `ticket_discard` action, call should be repeated after 30 mins.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket identification number
ticket_code
string
Ticket code
player_id
string
Player identification number or code
psp
string
Payment service provider or method used to pay for the ticket. E.g mobile, brite, pawapay
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
stake
integer
Ticket stake. Should be in integer format (cents). For example, for stake 33.45 the value will be 3345
wht_amount
integer
Player withholding tax amount. Should be in integer format (cents). For example, for withholding tax amount 4.55 the value will be 455
wht
float
Player withholding tax percentage. For example, for withholding tax percentage 20.0% the value should be 20.0
ext_amount
integer
Ticket exercise tax amount. Should be in integer format (cents). For example, for exercise tax amount 1.25 the value will be 125
ext
float
Ticket exercise tax percentage. For example, for exercise tax percentage 12.5% the value should be 12.5
Sample request:
```json
{
"action": "ticket_update",
"data": {
"operator": "acme",
"ticket_id": "668ef666333180bba97f0c93",
"ticket_code": "CD4BDD",
"player_id": "sometokenvalue",
"price": 500,
"stake": 444,
"wht_amount": 240,
"wht": 10.0,
"ext_amount": 56,
"ext": 12.5,
"ext_type": "inclusive",
"gross_payout": 2842,
"net_payout": 2602,
"currency": "USD",
"atag": "atag_value",
"rtag": null,
"ticket_type": "quickbet",
},
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Close the ticket
Is used to notify Partner the ticket status is closed. Request is sent with 24 hours delay after `ticket_win` , `ticket_lost` , `ticket_void` , `ticket_refund` request. During this period rollbacks could be sent.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
Sample request:
```json
{
"action": "ticket_closed",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Refund the ticket
This request is needed when the ticket is declined after transaction is processed on Partner's side Request.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
reason
string
Reason for refund action
Sample request:
```json
{
"action": "ticket_refund",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608",
"reason": "some-reason"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Win the ticket
The request is made when player's ticket is won or cashed out.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
Sample request:
```json
{
"action": "ticket_win",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Lose the ticket
The request is made when ticket is lost.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
Sample request:
```json
{
"action": "ticket_lost",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Void the ticket
This request is made when ticket is voided.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
price
integer
Ticket price. Should be in integer format (cents). For example, for price 35.00 the value will be 3500
stake
float
Ticket stake. Should be in integer format (cents). For example, for stake 33.45 the value will be 3345
wht_amount
integer
Player withholding tax. Should be in integer format (cents). For example, for withholding tax amount 4.55 the value will be 455
wht
float
Player withholding tax percentage. For example, for withholding tax percentage 20.0% the value should be 20.0
ext_amount
integer
Ticket exercise tax. Should be in integer format (cents). For example, for exercise tax amount 1.25 the value will be 125
ext
float
Ticket exercise tax percentage. For example, for exercise tax percentage 12.5% the value should be 12.5
Ticket gross payout. Should be in integer format (cents). For example, for gross payout 30.45 the value will be 3045
net_payout
integer
Ticket net payout. Should be in integer format (cents). For example, for net payout 30.45 the value should be 3045
Sample request:
```json
{
"action": "ticket_void",
"data": {
"operator": "operator-code",
"ticket_id": "668ef666333180bba97f0c93",
"price": 500,
"stake": 444,
"wht_amount": 240,
"wht": 10.0,
"ext_amount": 56,
"ext": 12.5,
"ext_type": "inclusive",
"gross_payout": 2842,
"net_payout": 2602
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Discard the ticket
This method is triggered in case of fail during `ticket_create` procedure. Currently there could be two main reasons resulting in this method: connection lost or unsatisfactory result.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
reason
string
Reason for discard action
Sample request:
```json
{
"action": "ticket_discard",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608",
"reason": "some-reason"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# Rollback the ticket
The request is used in case Bet Engine made a ticket’s rollback.
Rollback happens when the ticket is originally set one way, but later (can be minutes or sometimes even days after) the results are changed and the ticket is set differently. A ticket’s rollback means that ticket status changes to the previous ticket status (open) and then it can be set to the opposite. After successful response Bet Engine should make a `ticket_win` / `ticket_lost` / `ticket_void` request.
Request fields:
Attribute
Data Type
Description
operator
string
Name of the operator as registered on the system
ticket_id
string
Ticket id
reason
string
Reason for rollback action
Sample request:
```json
[
"action": "ticket_rollback",
"data": {
"operator": "operator-code",
"ticket_id": "1330556611374148608",
"reason": "some-reason"
}
}
```
Sample response:
```
Response: 200
Doesn't require any payload
```
# SMS notifications
# Headers
In all requests for all types three headers will be sent:
Attribute
Description
timestamp
The unix time stamp
operator-name
Operator name
signature
Signature of incoming request body and secret key (HMAC)
By checking signature in request you may confirm that the notification came from us.
Detailed info about how to calculate signature may be found on [Signature](/sms-notifications/signature) page.
# Signature
Generate HMAC hash signature to check that SMS notification is actually coming from us.
The Signature is calculated based on the `timestamp`, `request body` and your `Secret Key` with HMAC hash using SHA256 Algorithm.
Here is an example on how to generate the Signature for `otp` type with `Secret Key=12345ABCDE`, `timestamp=1706191612` and following request body:
```json
{
"type": "otp",
"data": {
"code": "1234",
"msisdn": "+260977223120"
}
}
```
In order to generate the Signature all spaces must be removed from the request body:
```json
{"type":"otp","data":{"code":"1234","msisdn":"+260977223120"}}
```
{% hint style="info" %}
Please note that the order of the fields matters for calculating the signature. It will always be `type` first then `data`. Fields in `data` must be in the same order they are listed on doc pages for types.
{% endhint %}
Then message for HMAC algorithm has to be formed using following template:
```
{timestamp}{request body with removed spaces}
```
So the message should look like the following:
```
1706191612{"type":"otp","data":{"code":"1234","msisdn":"+260977223120"}}
```
The computed Signature for this request is:
```
46b1ec8d2a05129bb57c8256f2cdd3029b2cf72dbed57f0d3eedd6b156573433
```
A free online HMAC Generator for testing is available on .
Here is how we calculated the Signature from above example using **Free Formatter**
{% hint style="info" %}
Your `Secret Key` is located on your API Settings page. Login to Betstack to access your `Secret Key`
{% endhint %}
Secret Key is locate in API Settings profile page
# Notification types
We now support 2 notiifcation types:
* [otp](/sms-notifications/notification-types/otp) - this notifications will always be sent and can not be turned off.
* [ticket\_status](/sms-notifications/notification-types/ticket_status) - this notifications can be turned on/off on `Notifications` page in Betstack.
# otp
Request fields:
Ticket Result. Can be one of: pending, won, lost, void
Sample `ticket_status` request:
```json
{
"type": "ticket_status",
"data": {
"ticket_code": "AB1234",
"ticket_id": "66a62424b1770731244c1f3f",
"msisdn": "213456451",
"status": "open",
"result" : "pending"
}
}
```
{% hint style="info" %}
`open` status will be sent only for tickets which were initially reserved.
{% endhint %}
Response fields:
