Redeeming codes

You can redeem codes in two ways:

• From the database: The API pulls a code from the database and redeems it for you. The database syncs with the bot, so you or your users can add codes there without worrying about storage.
• Directly: You provide the code with each request. This gives you full control over your codes, but adds complexity when errors occur since you need to decide what to do with failed codes.

Let’s start with the database method since it’s simpler. We’ll cover direct redemption afterward.

Making the request

Use the POST /redeem endpoint to redeem a code. Here’s how:

1
from kokos_activator_api import AsyncKokosApi
2
from kokos_activator_api.environment import KokosApiEnvironment
3
from kokos_activator_api.redeem import RedeemCodeFromDbRequest, ActivationErrorResponse
4
from kokos_activator_api.core.api_error import ApiError
5
6
client = AsyncKokosApi(
7
  token="YOUR_TOKEN",
8
  environment=KokosApiEnvironment.PRODUCTION,
9
)
10
11
try:
12
  result = await client.redeem.redeem_code(
13
    request=RedeemCodeFromDbRequest(
14
      player_id="51709255708",
15
      denomination=60,
16
      require_receipt=True,
17
      game_id="pubg_mobile",
18
    )
19
  )
20
21
  print("Activation successful! Player name:", result.name)
22
except ActivationErrorResponse as error:
23
  print("Activation error:", error.body.error_code)
24
  # handle error...
25
except ApiError as error:
26
  print("Unknown error:", error.body)
27
  # handle error...

Let’s break down the key parameters:

requireReceipt

This parameter used to control whether you would get an email/password when redeeming. Right now, this parameter affects nothing and should be left as true. It is kept only for backwards compatibility.

playerId

This is the player’s in-game character ID (a string of digits).

gameId

Currently, our service supports redeeming codes for 3 games:

• PUBG Mobile (pubg_mobile)
• Honor of Kings (honor_of_kings)
• Garena Free Fire (free_fire)

The API interface is basically identical, and you can switch between games easily.

Understanding the response

When redemption succeeds, you’ll get an ActivationReceipt object:

1
{
2
  "type": "ActivationReceipt",
3
  "id": 100407,
4
  "createdAt": "2026-09-13T08:27:18.520Z",
5
  "warning": false,
6
  "took": 6250,
7
  "playerId": "51709255708",
8
  "code": "r3h4xcJ72f2056g7h7",
9
  "openid": "0320648646774837",
10
  "name": "『NT』ярый",
11
  "gameId": "pubg_mobile",
12
  "userId": 42,
13
  "productName": "UC*600",
14
  "amount": 660,
15
  "uid": "U2463icbmr4k8h",
16
  "email": "[email protected]",
17
  "password": "KOKOS1_H1HA5CT1"
18
}

Here’s what each field means:

ID

Each receipt has a unique ID. You can retrieve it later with GET /history/{id}, or use the /receipt_{id} command in the bot to view it.

Email and password

You’ll get the Midasbuy account credentials used for redemption. You can use these to log in and verify the transaction yourself. It’s usually safe to share these with users, but remember that one account may have multiple redemptions.

For Gaerna games (Free Fire), email is an internal player account ID, and password is the session token used for the activation.

Warning

After redemption, we check if a “full receipt” appears on the account.

The warning field is true when We can’t find the full receipt for some reason. This happens rarely, but is still possible in some cases (usually network issues on the game provider or our side).

Amount

This shows how much UC/Diamonds/currency were redeemed. This field might not be present in some cases when we’re not able to detect the amount definitively.

Handling errors

We’ll cover all errors in detail later, but here are the basics.

When redemption fails, you’ll get an ActivationErrorResponse containing an ActivationError object with errorCode. errorCode is a specific error type from a fixed set of options. For example, CHARACTER_NOT_FOUND means the playerId is invalid or the player lookup failed.

See the Error handling guide for more information.

Direct redemption

If you prefer not to use the database, you can provide codes directly with each request.

Send a RedeemCodeDirectRequest instead of a RedeemCodeFromDbRequest. (In the HTTP API, omit denomination and use codeOverride instead.)

1
from kokos_activator_api.redeem import RedeemCodeDirectRequest
2
3
await client.redeem.redeem_code(
4
  request=RedeemCodeDirectRequest(
5
    require_receipt=True,
6
    player_id="51709255708",
7
    code_override="YMLKsXxG2B207euaK6",
8
    game_id="pubg_mobile",
9
  )
10
)

Next steps

Learn about all possible errors and how to handle them.