Matchup Game Callbacks
The Matchup Game involves fantasy matchups where participants make predictions on specific player comparisons. The following callbacks are used to place bets and settle outcomes for these matchups. This documentation explains the structure, idempotency requirements, and details needed for these interactions.
Place Bet Callback
The Place Bet callback is triggered when a user submits a new bet for a matchup. This callback notifies the client’s wallet API to deduct the appropriate amount from the user’s balance. It can contain multiple bets in a single request.
Endpoint and Authorization
- Endpoint: This callback is sent as a server-to-server HTTPS POST request to:
//{your_server}/bets
https: - Authorization: The request uses an admin_token in the
Authorization
header, formatted asBearer customer {admin_token}
. This token is a short-lived JWT generated by our system and should be verified for authenticity.
Request Structure
Each request includes details about the user, matchup pool, and specific bet being placed. This structure allows multiple bets to be included in a single callback.
Headers
"authorization": "Bearer customer {admin_token}"
}
{
Request Body Example
"bets": [
{
"user": {
"client": "string", // Client name (customer)
"uid": "number", // User ID in the client's system
"ip": "string" // User's IP address
},
"pool": {
"client": "string", // Client name (customer)
"currency": "string", // Currency for the bet slip
"game": "string", // Game type, always "player_matchups"
"uid": "number", // Unique ID of the coupon
"overdraw": "string" // Potential payout amount
},
"bet": {
"uid": "number", // Bet slip ID
"amount": "string", // Amount to deduct from the user
"odds": "string", // Odds the user is betting on
"rake": "number", // Always zero for this game
"extra": { // Extra metadata for reporting purposes
"uid": "number",
"lines": ["string"], // Array of matchup lines
"sport": "string", // Sport type, e.g., "football"
"selection": ["string"], // Selections the user has bet on
"description": "string" // Description of the matchup selections
}
}
}
]
}
{
Field Descriptions
User: Details of the user placing the bet.
- client (string): Client identifier.
- uid (number): Unique ID of the user within the client’s system.
- ip (string): User’s IP address.
Pool: Information about the matchup pool.
- client (string): Client identifier.
- currency (string): Currency of the bet.
- game (string): Always
"player_matchups"
. - uid (number): Unique ID for the coupon.
- overdraw (string): Potential payout.
Bet: Information specific to the bet.
- uid (number): Bet slip ID.
- amount (string): Amount to deduct from the user.
- odds (string): Betting odds for the user’s selection.
- rake (number): Always zero for this game.
- extra (object): Metadata for reporting.
- uid (number): Unique bet slip ID.
- lines (array of strings): List of matchup lines.
- sport (string): Sport type (e.g.,
"football"
). - selection (array of strings): User’s selections.
- description (string): Description of the matchup selections.
Idempotency and Reliability
This endpoint must be idempotent to prevent duplicate charges in case of retries. Each uid
in the bet object serves as a unique identifier, allowing the client system to detect and ignore duplicate requests if the same bet is submitted multiple times.
Settle Bet Callback
The Settle Bet callback finalizes results for each matchup bet, including both winners and losers. This callback also handles any refunds by marking a bet slip as lost
if a refund is due. The entire callback is sent when a tournament outcome is decided, including all bets under that matchup pool.
Endpoint and Authorization
- Endpoint: This callback is sent as a server-to-server HTTPS POST request to:
//{your_server}/winners
https: - Authorization: The request uses an admin_token in the
Authorization
header, formatted asBearer customer {admin_token}
. This token is a short-lived JWT generated by our system and should be verified for authenticity.
Request Structure
Each request includes details about the users and their respective bets in a matchup, including any payouts, refund amounts, and results.
Headers
"authorization": "Bearer customer {admin_token}"
}
{
Request Body Example
"pools": [
{
"pool": {
"client": "string", // Client name, typically "fanteam"
"game": "string", // Always "player_matchups"
"uid": "number", // Unique ID of the coupon
"currency": "string", // Base currency of the coupon
"overdraw": "number", // Total payout for the slip
"cost": "string", // User's stake, as a string
"guaranteed": true // Always true for this game
},
"bets": [
{
"user": {
"client": "string", // Client name
"uid": "string", // User's unique ID as a string
"name": "string" // Username
},
"bet": {
"uid": "number", // Bet transaction ID
"currency": "string", // Currency used for the bet
"amount": "string", // Amount deducted from the user, as a string
"odds": "number", // Betting odds
"rake": 0, // Always zero for this game
"payout": "number", // Amount won, can be zero if lost
"base_payout": "number", // Same as payout
"result": "string", // Status of the bet slip (e.g., "won", "lost")
"extra": { // Extra metadata about the bet slip (for reporting purposes)
"uid": "number",
"lines": ["string"],
"sport": "string",
"selection": ["string"]
}
}
}
]
}
]
}
{
Field Descriptions with Corrected Types
pools: Array of objects, each containing a
pool
object andbets
array.- pool: Information about the matchup pool.
- client (string): Client identifier.
- game (string): Always
"player_matchups"
. - uid (number): Unique ID for the coupon.
- currency (string): Currency of the bet.
- overdraw (number): Total payout for the slip.
- cost (string): Stake amount from the user, as a string.
- guaranteed (boolean): Always
true
for this game.
- pool: Information about the matchup pool.
bets: Array containing individual bet details.
- user:
- client (string): Client name.
- uid (string): Unique user ID as a string.
- name (string): Username.
- bet:
- uid (number): Transaction ID for the bet.
- currency (string): Currency used.
- amount (string): Amount deducted from the user, as a string.
- odds (number): Betting odds.
- rake (number): Always zero for this game.
- payout (number): Amount won;
0
if lost or refunded. - base_payout (number): Same as
payout
. - result (string): Status of the bet (e.g.,
"won"
,"lost"
). - extra (object): Metadata for reporting.
- uid (number): Unique ID for the bet slip.
- lines (array of strings): Matchup lines.
- sport (string): Type of sport.
- selection (array of strings): User’s selections.
- user:
Idempotency and Reliability
This endpoint must be idempotent. If any payout or refund fails, the entire request should be rejected, prompting a retry with the full set of bets. This ensures accurate payouts and consistent results.
For refunded bets, the "result"
field will typically be marked as "lost"
. A settled bet should be marked as complete and any retries should respond with idempotence.