SportAPI
Betting platforms

Automated Bet Settlement: How It Works and Where to Get an API That Settles Every Market in 1–2 Minutes

What an automated bet settlement API should handle, which markets are hardest to settle, and how SportAPI settles every outcome, from halves and corners to player stats, in 1–2 minutes and instantly in live.

A match timeline where each bet is settled right after a goal, a corner or the end of a half

Automated bet settlement means a service, not a person, decides how each bet ended. A bet settlement API determines whether a bet won, lost, was voided or half-won, and reports the result to your server. Without one, a sportsbook either keeps its own team of settlement staff or builds a settlement engine that understands hundreds of markets, cancellation rules and Asian handicaps.

At SportAPI that job is done by the Coupon API, our bet placement and settlement service. It settles every outcome automatically: main markets, halves and periods, corners, cards, player statistics, Asian totals and handicaps. A prematch bet is settled 1–2 minutes after the event ends, and a live market is settled the moment the event happens. Results reach your server by callback, and you can request them through the API whenever you like. Pricing starts at $300 a month.

Why settling a bet is harder than comparing scores

If every bet were on the match winner, settlement would fit in one line of code. In practice the result depends on the market, the rules and what happened to the match:

  • Total 2.25 at 1–1 isn’t a win or a loss but a half loss: half the stake comes back.
  • First-half corners are settled from first-half statistics, not the final score.
  • Player props such as goals, shots or assists need statistics for that specific player.
  • A cancelled or postponed match means a void, not a loss, and the player needs to know why.
  • A corrected result, for example after a review, means an already settled coupon has to be resettled.
  • An accumulator loses as soon as one leg loses, even while other matches are still in play.

Each case is a separate rule you’d have to build, test and maintain. A ready-made bet settlement API takes all of them off your hands.

Which bets are settled automatically

Market typeExampleWhat settlement needsAt SportAPI
Match result1X2, double chanceThe final scoreAutomatic
Totals and handicapsOver 2.5, handicap −1.5The score and market rulesAutomatic
Asian linesTotal 2.25, handicap −0.75Splitting the stake in twoAutomatic, with half wins and half losses
Halves, periods, setsFirst-half winner, third-period totalThe score by periodAutomatic
Match statisticsCorners, cards, foulsMatch and half statisticsAutomatic
Player propsPlayer to score, player runs, acesPlayer statisticsAutomatic
Live marketsNext goalThe moment of the eventInstantly, as soon as the event happens
AccumulatorsUp to 15 legs per couponThe result of every legAutomatic, an early loss is reported immediately

Bets are placed and settled on the SportAPI odds feed: 322 sports, prematch and live. So there’s no need to match team or market names between different systems: each selection is identified by an exact pointer from the feed, and the odds are checked when the bet is accepted.

How fast a bet is settled

  • Prematch bets and match results: 1–2 minutes after the event ends.
  • Live markets: instantly, as soon as the event happens, whether that’s a goal, a corner or the end of a half.
  • Sub-events such as a half, period, set or corners are settled as they finish, without waiting for the whole match.
  • An accumulator gets a losing status the moment one leg loses. You can see it straight away, even with other matches still running.

For the player, settlement speed is how quickly a win lands in their balance. The faster it is, the sooner the money is back in play and the fewer “where are my winnings?” tickets reach support.

Statuses and payouts

Each bet inside a coupon has its own status and settlement multiplier:

Bet statusMeaningMultiplier
1 WINWinThe bet’s odds
2 LOSELoss0
3 RETURNVoid1
21 HALF_WINHalf win(odds + 1) / 2
22 HALF_LOSEHalf loss0.5
23 PUSHStake returned on a tie1

A coupon’s final multiplier is the product of its bets’ multipliers, and the API returns the payout ready-made in real_win. Example: a stake of 10 on Over 2.25 at 1.90, and the match ends 1–1. Half the stake went on Over 2 and was returned, half on Over 2.5 and lost. Status HALF_LOSE, payout 5.

Coupons have statuses of their own: 0 active, 2 won, 4 lost, 8 fully voided, 15 returned for resettlement. We covered how singles and accumulators pay out in our article on single vs accumulator bets, and the full coupon lifecycle is in the settlement documentation.

Void reasons and resettlement

Every settled bet carries a reason code, settlement_reason_code, and an explanation. For example: match cancelled (MATCH_CANCELLED), match postponed (MATCH_POSTPONED), or market settled as a push (MARKET_PUSH). From the code you can show the player a clear message in their language instead of a bare “void”.

If a match result is corrected after settlement, the coupon moves to status 15 and then gets a new result. Your server receives both versions and adjusts the payout. Without this, a corrected result has to be handled by hand.

Players often want to check for themselves why a bet went the way it did: how many corners there were in the first half, or who got booked. Point them to SportAPI.net Stats, which has live scores, results, line-ups, head-to-head records and match statistics for 20 sports. Fewer support questions means fewer disputed settlements.

How results reach your server

There are two ways, and you can use them together.

Callbacks. As soon as a coupon is settled, the system sends a POST request with the result to your URL, with up to 100 coupons per request. Every request is signed with HMAC-SHA256, so a result can’t be forged. For accumulators you also get intermediate states showing which legs are settled and which aren’t yet.

API requests, whenever you want. You can fetch the state of any coupon at any time: one coupon by code, a list of up to 100, all active coupons, or everything settled in the last N minutes. That’s handy for support, reconciliation and recovering after an outage.

A callback handler in Node.js:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/coupon-result', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = Buffer.from(req.get('X-Coupon-Signature') || '');
  const expected = Buffer.from(
    'sha256=' + crypto.createHmac('sha256', process.env.CALLBACK_SECRET).update(req.body).digest('hex'),
  );
  if (signature.length !== expected.length || !crypto.timingSafeEqual(signature, expected)) {
    return res.sendStatus(401); // signature mismatch: don't touch balances
  }

  const batch = JSON.parse(req.body.toString('utf8'));
  await db.transaction(async (tx) => {
    if (!(await tx.saveBatchOnce(batch.batchId))) return; // this batch was already processed
    for (const coupon of batch.coupons) {
      await tx.upsertCoupon(coupon); // look the coupon up by coupon_code
      if ([2, 4, 8].includes(coupon.status)) {
        await tx.payOnce(coupon.coupon_code, coupon.realWin); // pay out exactly once
      }
    }
  });
  res.sendStatus(200);
});

Three rules keep a settlement integration from breaking: verify the signature against the raw request bytes before parsing the JSON; tell a repeated delivery of the same batch (same batchId) from a new coupon state (new batchId); and pay out once, even if a coupon’s final result arrives several times.

Choosing a bet settlement API: questions for the provider

QuestionWhy it mattersSportAPI’s answer
Which markets are settled automatically?Every manual market costs money and invites mistakesEvery outcome in the feed, including halves, corners and players
How fast does a result arrive?It decides when the player gets paid1–2 minutes, live instantly
Are Asian lines settled with half wins?Otherwise totals of 2.25 and handicaps of 0.75 are settled wrongYes, HALF_WIN and HALF_LOSE statuses
Is the void reason provided?Players need to know why a bet was voidedYes, a code and a text reason
What happens when a result is corrected?Without resettlement the mistake stays foreverA resettlement status and a new result
How are result notifications protected?A forged callback is a forged payoutHMAC-SHA256 signature
Can I request a result myself?A callback can fail to arriveYes, any time through the API
Where are player balances held?Money should stay with the operatorIn your system

Mistakes when integrating bet settlement

  • Paying out from potential_win. That’s the possible win before settlement. Pay real_win after a final status.
  • Treating an intermediate state as a loss. In an intermediate accumulator callback the payout is 0, but the coupon is still active. Check the coupon status.
  • Deduplicating by coupon_code. One coupon can arrive several times with different states. Drop repeats by batchId.
  • No polling fallback. If your server was down, some callbacks may arrive late. Every few minutes, request coupons settled in the last 10 minutes.
  • The signing secret in client code. It belongs on the server only.

How this differs from “send us a bet, get a result” services

Some services settle bets placed anywhere: you send the match, market and line, and the service looks up the result. That suits bets already taken in another system, but it’s easy to go wrong on matching: a team, competition or market name doesn’t line up, and the bet gets stuck.

At SportAPI a bet is placed and settled in the same system as the odds feed. The selection is identified by an exact pointer from the feed, the odds are checked at acceptance, and “market not found” can’t happen at settlement. If you’re launching betting or moving to a new odds feed, that’s the more reliable setup.

If you need match results rather than bet results, for a website, statistics or checking predictions, see our article on final match results in JSON.

How much it costs

What you needPrice
Bet placement and automated settlement (Coupon API)from $300 a month, billed by settled selections
Odds feed for one sportfrom $30 a month
Player balances and paymentsin your system

FAQ

What is automated bet settlement?

A service decides how each bet ended (won, lost, voided or half-won) and passes the result to your system automatically. Your server then pays the player based on that result.

How fast are bets settled?

Prematch bets are settled 1–2 minutes after the event ends. Live markets are settled as soon as the event happens. An accumulator gets a losing status as soon as one of its legs loses.

Are corners, cards and player props settled?

Yes. Every outcome in the feed is settled automatically: halves and periods, corners, cards, fouls, player statistics, Asian totals and handicaps.

How do I get results: callback or request?

Whichever suits you. A callback arrives on its own as soon as a coupon is settled. Through the API you can request a result at any time, by coupon code, as a list or for the last few minutes. Using both is the most reliable option.

Can you settle bets placed in another system?

The Coupon API settles bets placed on the SportAPI odds feed, where the selection and odds are checked at acceptance. If you’re moving from another system, place new bets through the Coupon API and settlement becomes fully automatic.

Where are player balances held?

In your system. SportAPI accepts and settles bets, while deposits, withdrawals and payouts are run by your server based on the result from the API.

What to do next

  1. Check which markets and sports your project needs.
  2. Get test access and place a few bets on live matches to see how fast the results arrive.
  3. Set up a callback handler with signature checks, plus a polling fallback.

Tell the SportAPI manager on Telegram you need automated bet settlement. You’ll get access to the Coupon API and can test settlement on real matches.

← All articles