Cancel Debit

/cancelDebit

The Cancel Debit API is used to revert a previously executed debit transaction. This typically occurs when a debit request fails due to technical issues (e.g. timeout, no response, or invalid response from the Merchant). In such cases, HPGames sends a cancel request to ensure the player’s balance is restored correctly.

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

---

Processing Rules

When the Merchant receives a cancel request:

• If the original debit transaction was successfully processed (balance decreased), the cancel request must be applied, and the balance must be increased.

• If the original debit transaction was NOT processed, the cancel request must be ignored, and the balance must remain unchanged.

In both cases, the endpoint must return a proper response.

---

Cancel Debit Request

Parameter	Type	Description	Required
merchantId	UUID	Merchant identifier	Yes
timestamp	Long	UNIX timestamp in milliseconds	Yes
betIdToCancel	UUID	HPGames debit bet identifier to be canceled	Yes
transactionIdToCancel	UUID	HPGames debit transaction identifier to be canceled	Yes
transactionId	UUID	Unique HPGames transaction identifier reference	Yes
created	DateTime	Bet creation timestamp (ISO 8601 format in UTC timezone (e.g. 2026-03-19T13:42:35.091483Z))	Yes
amount	Decimal	Amount to be credited to the player’s wallet	Yes
currency	String	Currency code (ISO 4217)	Yes
gameId	Integer	Unique HPGames game identifier	Yes
playerId	String	Merchant’s unique identification for each Player	Yes
authToken	String	Game session identifier	Yes
hash	String	HMAC SHA256 signature used to verify the request	Yes

Hash Fields

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

• merchantId
• transactionIdToCancel
• timestamp

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

Request Example

{
  "merchantId": "1387a6cc-3651-4473-ae52-e415caea3395",
  "timestamp": 1773941123456,
  "betIdToCancel": "6b1d3f8a-2c4e-4a9b-91c2-7e5d8f9a1b22",
  "transactionIdToCancel": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c55",
  "transactionId": "9f8e7d6c-5b4a-4321-9c8d-7e6f5a4b3c21",
  "created": "2026-03-19T16:38:43.456789Z",
  "amount": 3.75,
  "currency": "EUR",
  "gameId": 1,
  "playerId": "c8d9e0f1-2345-4a6b-8c9d-0e1f2a3b4c5d",
  "authToken": "5f6e7d8c-9b0a-4c3d-8e1f-2a3b4c5d6e7f",
  "hash": "5e2a7c9d1b3f4e6a8d0c2b1f3a5e7d9c4b6a8f0e1d3c5b7a9e2d4f6c8a0b1e3"
}

---

Cancel 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

Response Example

{
  "errorCode": 0,
  "errorText": "",
  "balance": 442.15,
  "currency": "EUR",
  "accountTransactionId": "3c930b71-1f97-4b2a-aba0-f62c36e0cd09",
  "transactionId": "9f8e7d6c-5b4a-4321-9c8d-7e6f5a4b3c21"
}

---

Bulk Cancel Debit

/bulkCancelDebit

Each cancel request within the bulk request must be signed individually.

Hash is calculated individually for each request object.

---

Bulk Cancel Debit Request

Parameter	Type	Description	Required
cancelDebitRequests	List<CancelDebitRequest>	List of Cancel Debit Requests	Yes

Request Example

{
  "cancelDebitRequests": [
    {
      "merchantId": "1387a6cc-3651-4473-ae52-e415caea3395",
      "timestamp": 1709289932725,
      "betIdToCancel": "2185a9a1-1497-41bd-937d-cbce3fae8961",
      "transactionIdToCancel": "1185a9a1-1497-41bd-937d-cbce3fae8961",
      "transactionId": "5f95f6d2-3e61-4434-96b8-07905f0fd557",
      "hash": "ee7aaaedbbb93d0e9c9db659a910be9b",
      "playerId": "d02b5979-6d2a-4830-80e2-bf3fa608a2f2",
      "gameId": 1,
      "currency": "EUR",
      "authToken": "6dc6c60a-d581-46a0-9ece-2a1765009128",
      "amount": 10
    }
  ]
}

---

Bulk Cancel Debit Response

Parameter	Type	Description	Required
cancelDebitResponses	List<CancelDebitResponse>	List of Cancel Debit Responses	Yes

Response Example

{
  "cancelDebitResponses": [
    {
      "errorCode": 0,
      "errorText": "",
      "balance": 1000.5,
      "currency": "EUR",
      "accountTransactionId": "3c930b71-1f97-4b2a-aba0-f62c36e0cd09",
      "transactionId": "5f95f6d2-3e61-4434-96b8-07905f0fd557"
    }
  ]
}