Debit API

This API is optional and only required when using features that involve debits (e.g., buy-in).

This API must be implemented by the client and must be server-to-server with IP whitelisting.

Certain gamification features require a participation fee, such as buy-in tournaments. This endpoint is used to debit the player for that fee.

Example debit request

POST [YOUR-SERVER-ENDPOINT] HTTP/1.1
Content-Type: application/json
X-API-Key: [ask from Codemodity]
 
{
    "debitRef": "0e17e833-a4db-41d0-83d1-adb539631864",
    "brandId": "brand-1",
    "playerId": "player-12345",
    "amount": 10.25,
    "currency": "EUR",
    "type": "BUYIN"
}

Request header

Header	Type	Mandatory?	Description
`X-API-Key`	string	Yes	All requests must be authorized with an API key sent in the `X-API-Key` header.

Request body

Field	Type	Mandatory?	Description
`debitRef`	string (format: UUID)	Yes	Unique reference for a call. Your system must use this to implement idempotency and prevent duplicate debits for the same attempt.
`brandId`	string	Yes	The unique ID of the brand the player belongs to (e.g., `HAPPYLUKE`). `brandId` and `playerId` together must be unique.
`playerId`	string	Yes	The ID of the player in your brand/PAM system. `brandId` and `playerId` together must be unique.
`amount`	decimal	Yes	The debit amount.
`currency`	string	Yes	Currency code of the `amount`.
`type`	string (enum)	Yes	Type of the debit. Currently, only `BUYIN` is used.

Response and Error Handling

Idempotency

Your endpoint must be idempotent. Gamity may send the same request multiple times due to network issues. To prevent duplicate debits, your system must store the debitRef of each successful request. If a new request arrives with a debitRef you have already processed, you must not debit the player again and should return a 200 OK response with the original transaction ID.

Response Codes and Retry Logic

Gamity’s automated retry system uses your API’s HTTP status codes to determine its behavior. It is critical that you return the correct status code for each scenario.

Status Code Range	Description
`200` (Success)	OK. The debit was successfully processed.
`429` (Too Many Requests)	Retryable Client Error. Your system is temporarily rate-limiting requests.
`4xx` (Other Client Errors)	Permanent Client Error. The request is invalid and will likely never succeed without a change. Examples: `400 Bad Request` (e.g., player not found, insufficient funds), `401 Unauthorized`.
`5xx` (Server Errors)	Temporary Server Error. Your server encountered an unexpected issue (`500`, `503`, etc.).
Request Timeout	Gamity’s request to your endpoint times out after 30 seconds.

Response Body

Response body in case of success

The success response should return a unique transaction identifier in your system.

{
    "transactionId": "4bba536-69a5-42b4-a66f-678bb61ae3f8"
}

Response body in case of error

{
    "error": {
        "code": "string", // e.g. "PLAYER_NOT_FOUND"
        "message": "string" // e.g. "Player with ID player-12345 is not found"
    }
}

Expected error codes:

INVALID_API_KEY
PLAYER_NOT_FOUND
INSUFFICIENT_FUNDS
BAD_REQUEST (fallback for errors with the request format or content)
TECHNICAL_ERROR (fallback for unexpected errors, if handled)

Test scenarios

This is a high risk endpoint. Implementing the security measures below are mandatory.

Idempotency: The endpoint must be idempotent using the payoutRef field. Sending a request again with the same payoutRef must not result in a duplicate transaction.
IP Allowlisting: The endpoint should have restricted access. Only IPs provided by Codemodity should be on the allowlist; all others should be blocked.
Authentication: The X-API-Key must be checked on every request. Requests with an invalid or missing API key should be rejected with a 401 Unauthorized status.
Data Validation: Your system is responsible for all business-level validation, such as detecting if a player’s currency has changed or if an account is blocked.

Payouts (API)Overview