Skip to main content

Wallet Integration Overview

The Wallet is the core component that manages player authentication, balance, and financial transactions between the Merchant and HPGames.
All Wallet API endpoints must be integrated to ensure proper functionality and consistency across all game flows.

Wallet API Methods​

HPGames uses the following Merchant Wallet endpoints:

  • validateToken – authenticate the player session
  • getPlayerBalance – retrieve the player's current balance
  • debit – deduct funds for bets
  • credit – add funds for winnings
  • bulkCredit – apply multiple credit transactions in a single request
  • cancelDebit – reverse a previously debited transaction
  • bulkCancelDebit – reverse multiple debits in a single request

Transaction Types​

HPGames supports different transaction types, defined by the type field:

  • REGULAR

    • one debit request (bet placement)
    • one credit request (bet settlement)

  • JACKPOT

    • no debit request
    • one credit request (jackpot wins)

  • REWARD

    • one debit request with amount = 0
    • one credit request (reward settlement)
note

If the Merchant prefers not to receive debit for rewards, this must be agreed in advance.

Idempotency​

  • All Wallet API endpoints must be idempotent:
    • debit, credit, bulkCredit, cancelDebit, bulkCancelDebit
  • transactionId must be used as a unique identifier
  • Repeated requests with the same transactionId must not create duplicate transactions
  • If a transaction with the same identifier was already processed, the endpoint returns a successful response with the original transaction details

HTTP Response Handling​

  • All Wallet API endpoints always return HTTP 200 OK
  • In case of an error, the response body contains:
    • errorCode – a non-zero value indicates an error (use predefined Error Codes)
  • A successful response is indicated by: errorCode = 0

Example Response​

200 OK

{
  "errorCode": 1005,
  "errorText": "Insufficient balance"
}

Retry and Error Handling​

Retry Mechanism​

  • Behavior depends on the returned errorCode
  • Some errors indicate a final transaction state and stop further retries or cancel operations
  • If a debit request fails and the error does not trigger a cancel, no further action is performed
  • Refer to the Error Codes section for detailed behavior

Place Bet Failure​

  • If a debit request fails, the system will automatically attempt to reverse the transaction via the cancelDebit endpoint

Win/Lose Failure​

  • If a credit request fails, the system retries the same request until it is successfully processed

Retry Schedule​

  • First retry: after 5 minutes
  • Subsequent retries: every 5 minute for the next 24 hours
  • After 24 hours: manual intervention required

Settlement for Running Bets​

  • If a bet remains in progress, the system automatically attempts settlement after 3 days
  • Retry: every 5 minute for the next 24 hours
  • After that: manual intervention required