Refund Endpoint

This document describes the Refund endpoint for Klas Gaming Casino integration. This endpoint is used to refund funds to the player account when a player exits before the game starts or when an error occurs during the game. The refund is processed automatically by the system.

---

Endpoint

POST {WEBHOOK_URL}/refund

Note: {WEBHOOK_URL} is the webhook URL provided by the operator. Klas Gaming will send POST requests to this endpoint.

---

Headers

• X-Signature: HMAC signature for message integrity (generated from the request body)
• X-Timestamp: Timestamp of the request (milliseconds since epoch)
• Content-Type: application/json

---

Request Body

{
  "request_id": "string",        // Required. Unique request identifier.
  "timestamp": 1234567890123,   // Required. Timestamp of the request (milliseconds).
  "session_id": "string",        // Required. Unique session identifier.
  "player_id": "string",          // Required. Unique player identifier from operator system.
  "game_code": "string",         // Required. Game key of the active player's game.
  "transfer_id": "string",       // Required. Unique reference of the original transaction to be refunded.
  "round_id": "string",          // Required. Unique reference of the game round.
  "amount": "100",               // Required. Refund amount (string).
  "currency": "EUR",             // Required. Currency code (ISO-4217, e.g., EUR, USD).
  "reason": "string",            // Required. Reason for the refund.
  "reference_id": "string"       // Required. Reference identifier for the refund transaction.
}

Parameter	Type	Mandatory	Description
request_id	string	Yes	Unique request identifier.
timestamp	number	Yes	Timestamp of the request in milliseconds (Unix timestamp).
session_id	string	Yes	Unique identifier of the current player session.
player_id	string	Yes	Unique identifier of the player from the operator's system.
game_code	string	Yes	Game key of the active player's game.
transfer_id	string	Yes	Unique reference of the original transaction to be refunded.
round_id	string	Yes	Unique reference of the game round.
amount	string	Yes	Refund amount (must match the original transaction amount).
currency	string	Yes	Currency code (ISO-4217, e.g., EUR, USD).
reason	string	Yes	Reason for the refund (e.g., "player_exit", "game_error").
reference_id	string	Yes	Reference identifier for the refund transaction.

---

Response Body

{
  "balance": "30",                  // Player balance after refund (e.g., 30 EUR)
  "casino_transfer_id": "string",  // Unique reference of the refund transaction created in the operator's system
  "status_code": "OK"              // Status code of the execution
}

Parameter	Type	Mandatory	Description
balance	string	Yes	Player balance after refund (e.g., 30 EUR).
casino_transfer_id	string	Yes	Unique reference of the refund transaction created in the operator's system.
status_code	string	Yes	Status code of the execution.

---

Possible Status Codes

Status Code	Reason
OK	Request successful
ERR_INTEGRITY_CHECK_FAILED	Message integrity check failed
ERR_UNKNOWN	Internal server error
ERR_TIMEOUT	Timeout exception

---

Flow Description

1. Klas Gaming automatically sends a POST request to /refund when:
   • A player exits before the game starts
   • An error occurs during the game
2. The backend processes the request, refunds the funds to the player account, and returns the updated balance and transaction details.
3. The response includes the player's balance, refund transaction reference, and a status code indicating the result.

---

Example Request

curl -X POST https://<your-api>/refund \
  -H "Content-Type: application/json" \
  -H "User-Agent: Klas Integration" \
  -H "X-Signature: <hmac_signature>" \
  -H "X-Timestamp: 1710000000000" \
  -d '{
    "request_id": "1234-5678-90ab-cdef12345678",
    "timestamp": 1710000000000,
    "session_id": "1234-5678-90ab-cdef12345678",
    "player_id": "12001",
    "game_code": "DM-J1K2",
    "transfer_id": "original-transfer-1234-5678-90ab-cdef",
    "round_id": "round-1234-5678-90ab-cdef",
    "amount": "100",
    "currency": "EUR",
    "reason": "player_exit",
    "reference_id": "refund-ref-1234-5678-90ab-cdef"
  }'

---

Example Response

{
  "balance": "130",
  "casino_transfer_id": "operator_refund_tx_1234-5678-90ab-cdef12345678",
  "status_code": "OK"
}

---

Notes

• The refund is processed automatically by the system when a player exits before the game starts or when an error occurs during the game.
• The transfer_id must reference the original transaction that is being refunded.
• The amount should match the original transaction amount.
• The X-Signature header is generated using HMAC-SHA256 from the JSON request body using the operator's secret key.
• The X-Timestamp header must match the timestamp field in the request body.
• For more details, refer to the Klas Gaming integration documentation or contact your integration representative.

---