Debit

/debit

The Debit API enables the HPGames platform to withdraw funds from the Player’s wallet via the Merchant system. This transaction is performed when a bet is placed.

The sequence diagram below illustrates the communication flow between HPGames and the Merchant for debit and credit operations.

---

Debit Request

Parameter	Type	Description	Required
merchantId	UUID	Merchant identifier	Yes
timestamp	Long	UNIX timestamp in milliseconds	Yes
betId	UUID	Unique HPGames bet identifier	Yes
transactionId	UUID	Unique HPGames transaction identifier	Yes
amount	Decimal	Amount to withdraw from the player’s wallet	Yes
currency	String	Currency code (ISO 4217)	Yes
created	DateTime	Bet creation timestamp (ISO 8601 format in UTC timezone (e.g. 2026-03-19T13:42:35.091483Z))	Yes
gameId	Integer	Unique HPGames game identifier	Yes
type	String	Defines the type of the transaction [REGULAR, REWARD, JACKPOT]	Yes
authToken	String	Game session identifier	Yes
hash	String	HMAC SHA256 signature used to verify the request	Yes
rewardId	String	Reward identifier assigned to the Player	No
rewardType	String	Reward type [FREE_BET]	No
playerId	String	Merchant’s unique identification for the Player	Yes

Hash Fields

The hash is calculated by concatenating the following fields in the exact order:

• merchantId
• betId
• amount
• transactionId
• timestamp

For details on how the hash is generated, see Hash Algorithm.

Request Example

{
  "merchantId": "1387a6cc-3651-4473-ae52-e415caea3395",
  "timestamp": 1773940012345,
  "betId": "8a2d1c4b-7e6f-4a9b-91c2-3d5e7f8a9b33",
  "transactionId": "2c7e5a9d-1b3f-4d8a-9c6e-7f1a2b3c4d55",
  "amount": 3.75,
  "currency": "EUR",
  "created": "2026-03-19T16:20:12.987654Z",
  "gameId": 1,
  "type": "REGULAR",
  "authToken": "5f6e7d8c-9b0a-4c3d-8e1f-2a3b4c5d6e7f",
  "playerId": "c8d9e0f1-2345-4a6b-8c9d-0e1f2a3b4c5d",
  "hash": "c1a4e9b27d6f3c8a5e0b2d1f4a7c9e3d6b8f0a2c5d7e9b1c3f4a6d8e0b2c4f6a"
}

---

Debit Response

Parameter	Type	Description	Required
errorCode	Integer	Error code (default 0, indicates success)	No
errorText	String	Error message	No
balance	Decimal	Player’s wallet balance	Yes
currency	String	Currency code (ISO 4217)	Yes
accountTransactionId	String	Merchant's internal transaction identifier	Yes
transactionId	UUID	Unique HPGames transaction identifier	Yes (must be returned in both success and error cases)

Response Example

{
  "errorCode": 0,
  "errorText": "",
  "balance": 990.59,
  "currency": "EUR",
  "accountTransactionId": "0bd7bb93-68f2-4fb0-864d-7156a768922d",
  "transactionId": "2c7e5a9d-1b3f-4d8a-9c6e-7f1a2b3c4d55"
}