Testing

Two Ways to Test

Beexar provides two ways to validate your integration without involving real money:

Tool	What it tests	Wallet callbacks
Demo mode	Game UI, launch flow, embedding	None — virtual balance, no wallet calls
Integration Test Game	Your wallet implementation against the full SoftSwiss contract	Real calls to your callback URLs

Demo mode is launched via POST /api/v1/softswiss/launcher/demo (see Game Launch). The Integration Test Game is launched via the standard real launcher with game: "testgame" (see below).

Tip

Request a test operator and credentials from your Beexar account manager. You point your callback URLs at a staging wallet of your own so test bets never touch real player accounts.

---

Integration Test Game

Beexar includes a built-in Integration Test Game that validates your wallet implementation against 29 test scenarios. It covers the full SoftSwiss wallet API contract.

How It Works

1. Launch the test game via the standard launcher API
2. Select which tests to run (or run all)
3. The test game sends real wallet requests to your callback URLs
4. Each test validates request/response behavior and displays pass/fail results
5. You can inspect the actual HTTP request/response exchanged with your wallet

Test Categories

Category	Tests	What It Validates
Signature & Balance	2	HMAC signature validation, balance endpoint
Bets & Wins	8	Single bet, multiple bets, BetWin combined, win after finish, new params
No Funds	3	Insufficient funds (single bet, large win, two bets)
Idempotency	3	Duplicate bet, one duplicate in batch, duplicate win
Rollback	6	Normal rollback, win rollback, tombstone scenarios
SoftSwiss v2 Edge Cases	7	Win before bet, zero amount, BetWin response transactions, bonus amount, duplicate finish, rollback count

Running the Test Game

BODY='{"casino_id":"your-operator-slug","game":"testgame","account":{"id":"test_player","currency":"USD"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_api_secret" | awk '{print $2}')

curl -X POST https://gateway.beexar.com/api/v1/softswiss/launcher/real \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: $SIGNATURE" \
  -d "$BODY"

Open the returned launch_url in a browser. You will see the test game interface with checkboxes for each test.

Test Results

Each test run records:

• Pass/Fail status for each test
• Step-by-step execution log
• Actual HTTP request/response between Beexar and your wallet (the Operator Exchange)
• Summary badge: “Integration Ready” when all tests pass

Tip

Run all 29 tests before going to production. The “Integration Ready” badge confirms your wallet implementation is fully compatible.

Building the wallet from scratch? An SDK gives you signature verification, validation and the error envelope, so these tests are about your ledger rather than your plumbing.

---

Reference Wallet Implementation

Every Beexar SDK ships a complete, correct wallet in about 250 readable lines — in Node, PHP, Go and Python. Read it, run it, or copy the parts you need. See Reference wallet.

Each one implements all four endpoints, verifies the HMAC signature over the raw body, is idempotent on id_provider, records rollback tombstones, and answers in the SoftSwiss Twirp error format.

The same implementations are driven by a public conformance fixture set: exact request bytes, the signature over them, the ledger before and after, and the expected response. If you are integrating without an SDK, point your own tests at those fixtures and you get the coverage the official SDKs have.

---

Integration Checklist

Use this checklist to verify your integration is complete:

1. Signature validation

   • All requests validated with HMAC-SHA256 (X-REQUEST-SIGN header)
   • Invalid signatures return HTTP 400 with api_code 403

2. Balance endpoint

   • Returns current balance as decimal string
   • Handles unknown players gracefully (api_code 101)

3. BetWin endpoint

   • Processes all transactions atomically (in order)
   • Returns balance, round_id, and transactions array
   • Idempotent: duplicate id_provider returns original response
   • Insufficient funds returns HTTP 400 with api_code 100 and balance in meta
   • Tombstoned id_provider returns HTTP 400 with api_code 155
   • Handles finished: true to close the round

4. Rollback endpoint

   • Reverses original transactions
   • Creates tombstone if original transaction not found
   • Idempotent: duplicate rollback id_provider returns original response
   • Processes rollback even with insufficient funds

5. Finish endpoint

   • Acknowledges round completion with { "balance": "..." }
   • Handles duplicate finish calls idempotently

6. Error format

   • All errors use Twirp format: { "code": "...", "msg": "...", "meta": { "api_code": "...", "api_message": "..." } }
   • Only HTTP 400 and 500 status codes (no 403, 409, 412)
   • balance included in meta when api_code is 100, 105, or 106

---

Testing Scenarios

Happy Path: Dice Round

BODY='{"casino_id":"your-slug","game":"dice","account":{"id":"test_player","currency":"USD"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_api_secret" | awk '{print $2}')

curl -X POST https://gateway.beexar.com/api/v1/softswiss/launcher/real \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: $SIGNATURE" \
  -d "$BODY"

# Play the game in the returned launch_url
# Verify wallet callbacks were received:
#   - POST /balance (on game load)
#   - POST /betwin (bet + win, finished=true)

Happy Path: Crash Round

BODY='{"casino_id":"your-slug","game":"crash","account":{"id":"test_player","currency":"USD"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_api_secret" | awk '{print $2}')

curl -X POST https://gateway.beexar.com/api/v1/softswiss/launcher/real \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: $SIGNATURE" \
  -d "$BODY"

# Open the launch_url — join the next round, place a bet
# Cash out before the crash or let it ride
# Verify wallet callbacks:
#   - POST /betwin (bet only)
#   - POST /betwin (win, finished=true) — only if player cashed out
#   - POST /finish — only if the last BetWin did not set finished=true

Note

In crash, each player bet gets its own round_id. If a player uses both bet slots, you will receive two separate sequences with different round_id values.

Error Scenarios to Test

Scenario	Expected Behavior
Return HTTP 400 with api_code 100 on BetWin	Beexar shows “insufficient funds” to player
Return HTTP 500 on BetWin	Beexar retries (up to 3 times), then shows error
Timeout (no response) on BetWin	Beexar retries (up to 3 times), then shows error
Return invalid JSON	Beexar shows error to player
Duplicate id_provider on BetWin	Your wallet returns original response, no double processing
Rollback for non-existent transaction	Your wallet creates tombstone, returns 200