Guide

Redeem

Base: https://api.kabotapi.com · Auth: Authorization: Bearer pk_… (pk_ + 32 hex)

Idempotency — read this before you write any retry logic

Idempotency-Key: order-98213

A network timeout never tells you whether the redemption happened. Instead of making that your problem, we resolve it server-side:

Keys are remembered for 24 hours. Use your own order id, and reuse the same value across retries of the same order. Generating a fresh key per attempt defeats the entire guarantee.

When to use A vs B

Request body

Provide exactly one code source.

{
  "player_id": "5123456789",

  "codes": ["ABCD…"],                                // A) your own codes
  "uc": 120,                                         // B) we pick the packs
  "categories": ["60", "60"],                        // C) explicit packs
  "packs": [{ "denomination": 60, "quantity": 2 }],  // D) denomination × qty

  "async": false                                     // optional, see below
}

{ "player_id": "…", "denomination": 60, "quantity": 4 } is accepted as a single-pack shorthand for packs.

Response

200 when at least one code activated · 422 when none did. Both carry the same shape — always read the per-code array, never just the status line.

{
  "ok": true,
  "player_id": "5123456789",
  "player_name": "BLAKCMONSTER1",
  "requested": 2,
  "activated": 1,
  "failed": 1,
  "took_ms": 4130,
  "source": "stock",
  "codes": [
    { "code": "U3rSx…", "status": "activated", "disposition": "consumed", "billed": true },
    { "code": "U3rSx…", "status": "failed", "disposition": "returned", "billed": false,
      "error_code": "ACTIVATION_FAILED", "message": "Temporary issue. Retry later." }
  ],
  "billed_requests": 1,
  "refunded_requests": 1,
  "request_id": "req_9f2c…"
}

The player nickname comes back as player_name on every redeem, so you can show the customer who was topped up.

status — what happened to the activation

disposition — what happened to your copy of the code

Async mode

Activation can take tens of seconds — long enough for your own HTTP client to time out, and a timeout is exactly what makes people retry. "async": true answers in milliseconds:

// 202 Accepted
{
  "ok": true,
  "job_id": "job_46c8…",
  "state": "queued",
  "poll_url": "/v1/jobs/job_46c8…",
  "requested": 2,
  "request_id": "req_…"
}

Then poll GET /v1/jobs/{job_id} or — better — take a webhook. Job state is one of queued → running → done | failed. The completed job carries the same body as a synchronous redeem under result. If a job is interrupted by a server restart it lands in failed with error_code: job_interrupted — unused stock and quota are restored; start a new attempt with a new Idempotency-Key (see Errors).

{
  "ok": true,
  "job_id": "job_46c8…",
  "state": "done",
  "created_at": 1789000000,
  "updated_at": 1789000042,
  "result": { "…": "same shape as a sync redeem" }
}

Endpoints (cheat sheet)

Python

Call the HTTP API from your backend with any HTTP client. This example uses httpx and reuses the same Idempotency-Key across retries of the same order:

import httpx

BASE = "{{BASE}}"
H = {
    "Authorization": "Bearer pk_0123456789abcdef0123456789abcdef",
    "Content-Type": "application/json",
    # Your order id. Reuse it on every retry of THIS order.
    "Idempotency-Key": "order-98213",
}

r = httpx.post(
    f"{BASE}/v1/redeem",
    headers=H,
    json={"player_id": "5123456789", "uc": 120},
    timeout=120.0,
)

if r.status_code in (200, 422):          # business outcome — read the codes
    body = r.json()
    for c in body["codes"]:
        print(c["code"], c["status"], c["disposition"], c["billed"])
    print("billed:", body["billed_requests"],
          "refunded:", body.get("refunded_requests", 0))
elif r.status_code == 429:               # slow down, then retry the SAME key
    print("retry after", r.headers.get("Retry-After"), "s")
else:                                    # 4xx = fix the request; 5xx = retry
    print(r.status_code, r.json()["error_code"], r.json()["message"])

Polling an async job

Bounded — never poll in an unbounded loop from a checkout path:

import time, httpx

job = httpx.post(f"{BASE}/v1/redeem", headers=H,
                 json={"player_id": "5123456789", "uc": 120, "async": True},
                 timeout=30.0).json()

deadline = time.time() + 300             # give up after 5 minutes
delay = 1.5
while time.time() < deadline:
    j = httpx.get(f"{BASE}/v1/jobs/{job['job_id']}",
                  headers=H, timeout=30.0).json()
    if j["state"] in ("done", "failed"):
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 10)         # back off; do not hammer
else:
    raise TimeoutError("job still running — quote the job_id to support")

curl

# smoke
curl -sS "{{BASE}}/v1/me" -H "Authorization: Bearer pk_0123456789abcdef0123456789abcdef"

# A · your codes
curl -sS -X POST "{{BASE}}/v1/redeem" \
  -H "Authorization: Bearer pk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-98213" \
  -d '{"player_id":"5123456789","codes":["CODE1","CODE2"]}'

# B · our stock
curl -sS -X POST "{{BASE}}/v1/redeem" \
  -H "Authorization: Bearer pk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-98214" \
  -d '{"player_id":"5123456789","uc":120}'

Receipt / history

Every response carries request_id (and job_id in async mode). Store it on your order — it is what support asks for.

• GET /v1/jobs/{job_id} — async job state and result (free)
• In Telegram: /api_system → paste the id when support asks

No internal implementation details are exposed — only merchant-safe status and codes.