Wallet Callbacks

Three seamless-wallet callbacks the operator implements at their wallet base URL. Oddyne calls them to move money on the operator's ledger. See the Callbacks guide for the full walkthrough.

Endpoints

POST <WALLET_URL>/bet        # debit stake on bet placed
POST <WALLET_URL>/win        # credit winnings on settlement
POST <WALLET_URL>/rollback   # reverse a prior debit/credit

Request fields are snake_case.

Idempotency

Every request carries a unique transaction_ref. The operator MUST be idempotent — a repeated transaction_ref returns the same result and does not double-apply. rollback references the reversed txn via original_transaction_ref.

POST <WALLET_URL>/bet

{
  "transaction_ref": "unique-tx-id",
  "operator_id": "<SITE_ID>",
  "ticket_id": 123456,
  "user_id": "<PLAYER_ID>",
  "stake": 10.00,
  "currency": "USD",
  "total_odds": 2.5,
  "potential_win": 25.00,
  "bet_type": "single",
  "selections": [
    { "event_id": 1001, "market_id": 1, "outcome_id": 3, "price_version": "v2", "odds": 2.5 }
  ],
  "created_at": "2026-08-09T12:00:00Z"
}

POST <WALLET_URL>/win

{
  "transaction_ref": "unique-tx-id",
  "operator_id": "<SITE_ID>",
  "ticket_id": 123456,
  "user_id": "<PLAYER_ID>",
  "win_amount": 25.00,
  "currency": "USD",
  "total_odds": 2.5,
  "bet_type": "single",
  "selections": [
    { "event_id": 1001, "market_id": 1, "outcome_id": 3, "price_version": "v2", "odds": 2.5 }
  ],
  "settled_at": "2026-08-09T13:00:00Z"
}

POST <WALLET_URL>/rollback

{
  "transaction_ref": "unique-tx-id",
  "original_transaction_ref": "the-tx-id-being-reversed",
  "operator_id": "<SITE_ID>",
  "ticket_id": 123456,
  "user_id": "<PLAYER_ID>",
  "amount": 10.00,
  "currency": "USD",
  "selections": [
    { "event_id": 1001, "market_id": 1, "outcome_id": 3, "price_version": "v2", "odds": 2.5 }
  ]
}

selections[] item

{ "event_id": 1001, "market_id": 1, "outcome_id": 3, "price_version": "v2", "odds": 2.5 }

Field	Type
event_id	integer
market_id	integer
outcome_id	integer
price_version	string
odds	number

Expected response

The operator returns this from every callback.

Success:

{ "status": "ok", "transaction_id": "operator-side-tx-id" }

Failure:

{ "status": "error", "error_code": "INSUFFICIENT_FUNDS", "error_message": "..." }

Field	Notes
status	"ok" or "error".
transaction_id	Operator's own ledger txn id (on success).
error_code	Machine-readable code, e.g. INSUFFICIENT_FUNDS (on error).
error_message	Human-readable message (on error).