API Documentation

1. Integration overview

3. Authentication signatures

Sign the UTF-8 string with MD5 by concatenating fields in the exact order below, without dots, spaces or separators. Send the hexadecimal MD5 string; command must use lowercase exactly as documented.

hashlib.md5((partner_key + partner_id + command + request_id).encode("utf-8")).hexdigest()

Each Merchant may use only its registered API type (Charging, Recharge, Softcard or All). Authentication/IP errors may appear in JSON even when HTTP is 200.

4. Card exchange parameters and responses

POST /chargingws/v2

Submit cards with command=charging. Check using command=check with partner_id, request_id and sign as shown above; card details do not need to be resubmitted. The legacy MD5(partner_key + code + serial) signature is still supported when code and serial are included.

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "charging",
  "request_id": "CHARGE_DEMO_001",
  "telco": "VIETTEL",
  "amount": 100000,
  "code": "YOUR_CARD_CODE",
  "serial": "YOUR_CARD_SERIAL",
  "sign": "MD5_THEO_CONG_THUC_CHARGING"
}

Recheck transaction

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "check",
  "request_id": "CHARGE_DEMO_001",
  "sign": "MD5_PARTNER_KEY_CHECK_PARTNER_ID_REQUEST_ID"
}

Transaction response

{
  "trans_id": 123,
  "request_id": "CHARGE_DEMO_001",
  "status": 99,
  "message": "PENDING",
  "declared_value": 100000,
  "value": 0,
  "amount": 0,
  "telco": "VIETTEL",
  "code": "YOUR_CARD_CODE",
  "serial": "YOUR_CARD_SERIAL",
  "callback_sign": "MD5_PARTNER_KEY_CODE_SERIAL"
}

Merchant-specific fees

GET /chargingws/v2/getfee?partner_id=YOUR_PARTNER_ID. The response is a flat list containing telco, value, fees and penalty, compatible with Nappay. Existing integrations that need grouped objects can add format=grouped. fees is the customer fee for the account group; only enabled card types and denominations are returned. Do not hardcode the catalog or fees from the documentation examples.

[
  {
    "telco": "VIETTEL",
    "value": 100000,
    "fees": "18.5",
    "penalty": "50"
  }
]

The group fee is finalized per order when the card is accepted. For an incorrect denomination (status=2), a 50% penalty applies to the net amount after the group fee: credited amount = provider-confirmed denomination × (100 − group fee)% × 50%, rounded down to VND. For example, 10.000 VND with a 26,8% group fee credits 3.660 VND. Use amount from the final result to record the credit; do not recalculate it from the declared denomination. Orders routed to manual processing may remain at status 99 until an operator confirms them; lookup/callback results are the basis for the final update.

4. Top-up parameters and responses

POST /api/rechargews

1. Retrieve the catalog and required customer fields

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "productlist",
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_PRODUCTLIST"
}

Read status=success and data as a product list. Each product has service_code, name, options and items. options describes key, name and type; select fields include choices. For password/otp fields, keep values on the server and send them only over HTTPS.

{
  "status": "success",
  "data": [
    {
      "service_code": "DEMO_GAME",
      "name": "Sản phẩm minh họa",
      "options": [
        {
          "key": "game_id",
          "name": "ID nhân vật",
          "type": "text"
        }
      ],
      "amount_mode": "fixed",
      "amount_limits": null,
      "items": [
        {
          "value": 100000,
          "name": "Gói 100.000đ",
          "price": "92500",
          "discount": 7.5
        }
      ]
    }
  ]
}

price is the payment amount and value is the denomination. discount represents the account discount, calculated as (value − price) / value × 100. Do not add profit or deduct the discount again from price.

2. Fixed packages or customer-entered amounts

amount_mode=fixed: select a value from items. amount_mode=amount: read amount_limits.minimum, maximum and multiple; submit an amount within the allowed range and divisible by multiple. items may contain a technical package with value=1, price=1; this is not a 1 VND package for sale. Use amount_mode and amount_limits to build the form. Refresh the catalog when settings/prices change; the accepted order response contains the finalized price.

3. Submit an order

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "topup",
  "request_id": "TOPUP_DEMO_001",
  "service_code": "DEMO_GAME",
  "amount": 100000,
  "qty": 1,
  "account_info": {
    "game_id": "PLAYER_ID"
  },
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_TOPUP_REQUEST_ID"
}

In JSON, send account_info as an object. With form-urlencoded, send account_info as a JSON string or account_info[game_id]=PLAYER_ID; do not send conflicting formats. This game example is illustrative only: retrieve actual fields from productlist rather than assuming every game uses game_id.

{
  "status": "success",
  "data": {
    "time": "2026-10-18 10:00:00",
    "request_id": "TOPUP_DEMO_001",
    "order_code": "R_DEMO_ORDER",
    "pay_amount": 92500,
    "discount": 7.5,
    "service_code": "DEMO_GAME",
    "amount": 100000,
    "status": "pending"
  }
}

4. Lookup and balance

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "getstatus",
  "request_id": "TOPUP_DEMO_001",
  "order_code": "R_DEMO_ORDER",
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_GETSTATUS_REQUEST_ID"
}

data.status: pending = processing; failed = unsuccessful. On success, order creation responses for the internal catalog may use success, while getstatus and callbacks use completed. Outer status=success only indicates that the API accepted/looked up the request. Check data.status to determine the order result. getstatus returns request_value as the denomination; amount for orders with internal quotes is the payment amount.

{
  "status": "success",
  "data": {
    "account": {
      "game_id": "PLAYER_ID"
    },
    "request_value": 100000,
    "amount": 92500,
    "request_id": "TOPUP_DEMO_001",
    "order_code": "R_DEMO_ORDER",
    "status": "completed"
  }
}

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "getbalance",
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_GETBALANCE"
}

{
  "status": "success",
  "data": {
    "balance": 1000000,
    "currency": "VND"
  }
}

4. Card purchase parameters and responses

POST /api/cardws

Catalog and stock

curl "https://toctoico.com/api/cardws/products?partner_id=YOUR_PARTNER_ID"

[
  {
    "name": "Thẻ minh họa",
    "service_code": "DEMO_CARD",
    "cardvalue": [
      {
        "service_code": "DEMO_CARD",
        "value": 100000,
        "id": "DEMO_SKU",
        "price": 97000
      }
    ]
  }
]

A stock check is only a snapshot at the time of the request and does not reserve stock; purchase orders still require processing and balance checks.

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "checkavailable",
  "service_code": "DEMO_CARD",
  "value": 100000,
  "qty": 1
}

{
  "stock_available": true,
  "message": "Còn hàng"
}

Purchase and retrieve

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "buycard",
  "request_id": "CARD_DEMO_001",
  "wallet_number": "YOUR_WALLET",
  "service_code": "DEMO_CARD",
  "value": 100000,
  "qty": 1,
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_BUYCARD_REQUEST_ID"
}

qty from 1 to 100, subject to stock and balance. value is the denomination, not the discounted price. service_code and prices come from the Merchant-specific catalog.

{
  "status": 1,
  "message": "Mua thẻ thành công",
  "data": {
    "request_id": "CARD_DEMO_001",
    "order_code": "S_DEMO_ORDER",
    "cards": [
      {
        "serial": "DEMO_SERIAL",
        "code": "DEMO_PIN",
        "expired": "2027-12-31"
      }
    ]
  }
}

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "redownload",
  "request_id": "CARD_DEMO_001",
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_REDOWNLOAD_REQUEST_ID"
}

While pending or disconnected, prefer redownload using the received order code. Do not change request_id and buy again. Some processing paths return duplicate-reference errors when buycard is retried, so redownload is the main reconciliation step. Store codes/PINs securely on your server.

{
  "partner_id": "YOUR_PARTNER_ID",
  "command": "getbalance",
  "wallet_number": "YOUR_WALLET",
  "sign": "MD5_PARTNER_KEY_PARTNER_ID_GETBALANCE"
}

{
  "balance": 1000000,
  "currency_code": "VND"
}

5. Callbacks and reconciliation

Register your callback URL in the Merchant on this website. The system sends card exchange/top-up results using POST JSON or GET according to the Merchant settings. Callbacks may be retried; handle repeats idempotently by order code and status.

Top-up callbacks use status=completed for successful orders; request_value is the requested top-up amount and amount is the payment amount if a finalized quote exists. Order lookups may return data.status=success for the same outcome. GET card exchange callbacks also include card_value.

{
  "status": "completed",
  "request_id": "TOPUP_DEMO_001",
  "order_code": "R_DEMO_ORDER",
  "request_value": 100000,
  "amount": 92500,
  "account": {
    "game_id": "PLAYER_ID"
  },
  "callback_sign": "MD5_PARTNER_KEY_ORDER_CODE"
}

1. Verify the signature using the corresponding Merchant key with a timing-safe comparison; verify that the order belongs to your system.
2. Call check/getstatus to confirm the status and verify the denomination/amount before recording a result. The compatible signature does not sign all status fields.
3. Record within a database transaction, prevent duplicate records/credits, then return HTTP 2xx promptly.
4. If callbacks are delayed or lost, look up the order periodically; do not treat disconnection as failure or create a new order.

The callback queue retries up to 12 times with increasing delays. Top-up callbacks also depend on the product's callback settings. Card purchase results are obtained through buycard/redownload.

import hashlib, hmac
expected = hashlib.md5((partner_key + payload["order_code"]).encode()).hexdigest()
valid = hmac.compare_digest(expected, str(payload.get("callback_sign", "")).lower())

6. Error codes and troubleshooting

Read the HTTP code, status, message and transaction status within data. Do not use one status table for all services: top-ups use strings, while card codes use numbers.

Space lookups at least a few seconds apart, increasing the delay while results are pending. Your server must generate and save request_id before sending. Do not use a real purchase to test connectivity; productlist/getbalance/getfee are read-only checks.

7. Code examples

Python example calling getbalance safely to test the connection (install requests using pip install requests). Use environment variables for private information; do not put keys in source code.

import os, hashlib, requests
BASE = "https://toctoico.com"
partner_id = os.environ["GACHTHE_PARTNER_ID"]
partner_key = os.environ["GACHTHE_PARTNER_KEY"]

def recharge(command, **fields):
    request_id = str(fields.get("request_id", "")) if command in ("topup", "getstatus") else ""
    sign = hashlib.md5((partner_key + partner_id + command + request_id).encode()).hexdigest()
    payload = {**fields, "partner_id": partner_id, "command": command, "sign": sign}
    response = requests.post(BASE + "/api/rechargews", json=payload, timeout=20)
    result = response.json()
    response.raise_for_status()
    return result

print(recharge("getbalance"))
# Lưu request_id trước khi gọi topup. Sau đó lưu order_code trả về.
# Khi timeout: tra cứu/đối soát, không tạo request_id mới để mua lại.

PHP: signature and JSON submission

<?php
$partnerId = getenv('GACHTHE_PARTNER_ID');
$partnerKey = getenv('GACHTHE_PARTNER_KEY');
$command = 'getbalance';
$payload = ['partner_id' => $partnerId, 'command' => $command,
    'sign' => md5($partnerKey . $partnerId . $command)];
$ch = curl_init('https://toctoico.com/api/rechargews');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_TIMEOUT => 20]);
$body = curl_exec($ch);
if ($body === false) { throw new RuntimeException('Chưa xác nhận được phản hồi API'); }
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
// Kiểm tra $status, $result['status'] và trạng thái đơn trong data nếu có.

cURL

curl --request POST 'https://toctoico.com/api/rechargews' \
  --header 'Content-Type: application/json' \
  --data '{"partner_id":"YOUR_PARTNER_ID","command":"getbalance","sign":"YOUR_COMPUTED_MD5"}' 

Card exchange uses the separate charging/check formulas in the signature table; the legacy MD5(partner_key + code + serial) formula remains supported. For card code purchases, use the concatenation rule in the signature table and the /api/cardws endpoint.

8. Serial lookup

POST /api/checkcard. Only use this when an administrator has enabled the feature and granted access to the Merchant. Lookup availability, limits and returned information depend on the approved configuration. Do not infer that a card is unused from an incomplete response.

{
  "partner_id": "YOUR_PARTNER_ID",
  "telco": "VIETTEL",
  "serial": "YOUR_CARD_SERIAL",
  "sign": "MD5_PARTNER_KEY_SERIAL"
}

Check status, message and the actual returned data. This is not a card top-up or PIN-check API; do not enable permissions yourself or run bulk lookups.

Tool Rejoin · Reseller API

1. Integration flow

This API sells, renews and resets Tool Rejoin VIP keys using your VND wallet on TOCTOICO. It is a separate REST protocol for Rejoin; do not send command or MD5 signatures from the three card/top-up services to this endpoint.

1. Sign in to website → API connections, create a Merchant of type Tool Rejoin, enable it and store the Partner ID/Partner Key on your backend.
2. Call GET /plans to retrieve plans on sale, prices and service_ready status. Use GET /balance to check your wallet balance.
3. Save your order reference, plan_id and quantity before sending POST /keys/purchase. Use that reference as the Idempotency-Key.
4. Read keys from a successful response or look up GET /orders/{request_id} after a lost response. Display keys securely to the purchaser.
5. Renew or reset using the UUID of a key owned by the Merchant account, with a separate Idempotency-Key for each operation.

VIP key validity starts upon the first valid activation on a device. Prices come from the database when a new transaction is processed, not from a price you submit. Prices and days in examples are illustrative; use GET /plans for actual plans. Free keys are issued through Discord and cannot be purchased or reset through this reseller API.

2. Authentication, permissions and format

Authorization: Bearer YOUR_PARTNER_KEY
X-Partner-ID: YOUR_PARTNER_ID
Accept: application/json
Content-Type: application/json
Idempotency-Key: shop_order_20261030_000001

The Merchant must be active, have type Tool Rejoin or All, and belong to an unlocked account. If an IP allowlist is configured, requests must come from an allowed server public IP; do not add X-Forwarded-For or IP headers to bypass restrictions. Keep the Partner Key on the backend only, not in frontend JavaScript, URLs or logs.

Keys are scoped to the wallet owner, even when that account is an administrator on the website; only VIP keys purchased by that wallet owner through the website or API can be managed. API order lists belong only to the calling Merchant. Idempotency-Key is scoped per Merchant and shared across all operation types for that Merchant; do not reuse a purchase reference for renewal/reset. Different Merchants have separate request reference scopes, even if they share a wallet owner.

Response uses success boolean type, data is the result; errors contain success=false, message, code and data=null. Do not interpret status using the card API's numeric status table. Amounts are integer VND values; timestamps are returned in ISO 8601 UTC. The admin page may display UTC+7.

{
  "success": true,
  "data": {
    "balance": 500000,
    "currency": "VND",
    "discount_percent": 0,
    "discount_bps": 0
  }
}

3. Endpoint list

4. Balance and available plans

GET /balance returns balance, currency=VND and the Merchant account owner's discount_percent and discount_bps. This is the same wallet used for website transactions; do not deduct from an additional wallet for the same order without a reconciliation design.

{
  "success": true,
  "data": {
    "balance": 500000,
    "currency": "VND",
    "discount_percent": 0,
    "discount_bps": 0
  }
}

GET /plans returns data.items, currency, service_ready and the account's own key purchase discount. In each plan: base_price is the list price, price is the discounted unit price for a new purchase, and renew_price is the renewal price with the same account Rejoin discount applied. discount_bps is the percentage multiplied by 100 (2%=200 bps). Send only the plan_id of a plan currently on sale. service_ready=false means the VIP service is not ready; do not treat the listing as confirmation that keys can be sold.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "VIP 7 ngày",
        "days": 7,
        "base_price": 50000,
        "price": 50000,
        "renew_price": 50000,
        "discount_percent": 0,
        "discount_bps": 0,
        "reset_limit": 1,
        "featured": 1
      }
    ],
    "currency": "VND",
    "service_ready": true,
    "discount_percent": 0,
    "discount_bps": 0
  }
}

The discount applies to new purchases and renewals of Tool Rejoin VIP keys, through both the website and API of the same account owner. It does not apply to card exchange, card code purchases or service top-ups. For example, a list price of 50.000 VND with a 2% discount gives price=49.000 VND; buying 3 keys deducts 147.000 VND. Unit prices are rounded HALF_UP to the nearest VND before multiplying by quantity (a fractional amount of 0,5 VND or more rounds up). Do not apply the discount again to price. Prices and discounts are finalized at purchase or renewal; subsequent changes do not modify previous orders.

Admin: configure account discounts

Use a Tool Rejoin or All Merchant created by account active admin owns. The API rechecks admin permissions from the database within the transaction; ordinary resellers cannot view or modify this endpoint, even for themselves. Do not submit role, owner_id or admin permissions in the body.

{
  "discount_percent": 2
}

{
  "success": true,
  "data": {
    "user_id": 123,
    "discount_percent": 2,
    "discount_bps": 200
  }
}

GET and POST use the same path /api/rejoin/v1/users/123/discount. POST accepts only discount_percent, sets an absolute value and writes an admin audit entry. It does not accumulate discounts, change previous orders, create an order in /orders or require an Idempotency-Key. Sending the same value again keeps the same discount; if an admin subsequently changed the rate, a new POST still sets the submitted value. Errors: 403 permission_denied for non-admin users, 404 not_found if the account does not exist, and 400 invalid_request for invalid values or fields. Authentication, Merchant, IP and request-limit rules still apply.

curl --silent --show-error --include --request POST 'https://toctoico.com/api/rejoin/v1/users/123/discount' \
  --header 'Authorization: Bearer YOUR_ADMIN_PARTNER_KEY' \
  --header 'X-Partner-ID: YOUR_ADMIN_PARTNER_ID' \
  --header 'Content-Type: application/json' \
  --data '{"discount_percent":2}' 

5. Buy VIP keys

POST /api/rejoin/v1/keys/purchase

{
  "plan_id": 1,
  "quantity": 1
}

Do not submit price, discount_percent, discount_bps, charged, balance, duration_days or VIP entitlements to determine your own price/permissions. On success, wallet debit and key issuance occur in one transaction; on failure, neither partial key issuance nor partial wallet debit occurs. Save request_id, order_code, license_ids and charged for reconciliation.

{
  "success": true,
  "data": {
    "request_id": "shop_order_20261030_000001",
    "operation": "purchase",
    "status": "completed",
    "order_code": "RJ_EXAMPLE_ORDER",
    "license_ids": [
      "11111111-2222-4333-8444-555555555555"
    ],
    "charged": 50000,
    "balance": 450000,
    "keys": [
      {
        "id": "11111111-2222-4333-8444-555555555555",
        "owner_id": 123,
        "plan_id": 1,
        "kind": "vip",
        "key": "RJ-DEMO0001-DEMO0002-DEMO0003-DEMO0004",
        "status": "inactive",
        "device": "",
        "expires_at": null,
        "duration_days": 7,
        "resets_remaining": 1,
        "created_at": "2026-10-30T02:00:00+00:00",
        "max_tabs": 4,
        "activated_at": null,
        "last_seen": null,
        "device_id": "",
        "generation": 1
      }
    ],
    "created_at": "2026-10-30T02:00:00+00:00",
    "pricing": {
      "base_unit_price": 50000,
      "unit_price": 50000,
      "quantity": 1,
      "discount_percent": 0,
      "discount_bps": 0
    }
  }
}

6. Key list and details

GET /api/rejoin/v1/keys?page=1&per_page=20. page starts at 1; set per_page between 1–100. status may be inactive, active, expired or revoked; q is used for search. Pagination returns page, per_page, total and pages. Keys are masked in the list; do not enter a masked value into the tool.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "11111111-2222-4333-8444-555555555555",
        "owner_id": 123,
        "plan_id": 1,
        "kind": "vip",
        "key": "RJ-DEMO••••••••00004",
        "status": "inactive",
        "device": "",
        "expires_at": null,
        "duration_days": 7,
        "resets_remaining": 1,
        "created_at": "2026-10-30T02:00:00+00:00",
        "max_tabs": 4,
        "activated_at": null,
        "last_seen": null,
        "device_id": "",
        "generation": 1
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1
  }
}

Call GET /api/rejoin/v1/keys/11111111-2222-4333-8444-555555555555 to retrieve data containing complete key details. Only VIP keys owned by the account are returned; invalid UUIDs or unauthorized keys are rejected. status=inactive means unactivated; active means currently valid; expired means validity ended; revoked means revoked.

{
  "success": true,
  "data": {
    "id": "11111111-2222-4333-8444-555555555555",
    "owner_id": 123,
    "plan_id": 1,
    "kind": "vip",
    "key": "RJ-DEMO0001-DEMO0002-DEMO0003-DEMO0004",
    "status": "inactive",
    "device": "",
    "expires_at": null,
    "duration_days": 7,
    "resets_remaining": 1,
    "created_at": "2026-10-30T02:00:00+00:00",
    "max_tabs": 4,
    "activated_at": null,
    "last_seen": null,
    "device_id": "",
    "generation": 1
  }
}

7. Renewal and device-transfer resets

POST /api/rejoin/v1/keys/{uuid}/renew with body {"plan_id":1}, with a new Idempotency-Key. Renewal uses renew_price, which already includes the account owner's Rejoin discount at the time of renewal. Do not apply the discount again. The pricing field records the price and rate finalized for the renewal order. For an activated key: new expiry = max(previous expiry, current time) + plan days. For an unactivated key: add pending days without starting the validity period. Add the plan's reset allowance while preserving the key string and device binding.

POST /api/rejoin/v1/keys/{uuid}/reset with body {}, with a new Idempotency-Key. A reset uses one allowance, removes the server-side device binding, increases generation and preserves the expiry date. A reset returns charged=0, order_code=null; an exhausted allowance returns an error. Force reset is not supported for resellers, Free keys or revoked keys.

A reset does not delete files on the phone, push an immediate disconnect or extend validity automatically. Stop the tool on the old device before resetting so it cannot reclaim the key; open the tool on the new device and enter the same key. Revocation of the old session depends on the tool's authentication cycle.

{
  "success": true,
  "data": {
    "request_id": "shop_reset_20261030_000001",
    "operation": "reset",
    "status": "completed",
    "order_code": null,
    "license_ids": [
      "11111111-2222-4333-8444-555555555555"
    ],
    "charged": 0,
    "balance": 450000,
    "keys": [
      {
        "id": "11111111-2222-4333-8444-555555555555",
        "owner_id": 123,
        "plan_id": 1,
        "kind": "vip",
        "key": "RJ-DEMO0001-DEMO0002-DEMO0003-DEMO0004",
        "status": "active",
        "device": "",
        "expires_at": "2026-11-06T02:00:00+00:00",
        "duration_days": 7,
        "resets_remaining": 0,
        "created_at": "2026-10-30T02:00:00+00:00",
        "max_tabs": 4,
        "activated_at": "2026-10-30T02:00:00+00:00",
        "last_seen": "2026-10-30T02:00:00+00:00",
        "device_id": "",
        "generation": 2
      }
    ],
    "created_at": "2026-10-30T02:00:00+00:00",
    "pricing": null
  }
}

The tool requests authentication every 120 seconds, and leases last at most 300 seconds. This does not guarantee immediate disconnection of the old device or allow a full 300 seconds offline after every network failure; stop the old session before changing devices.

8. Order lookup and safe retries

GET /api/rejoin/v1/orders/{request_id} use the exact Idempotency-Key from the purchase/renewal/reset; do not substitute order_code or the key string into this path. Returns data in the same structure as the successful operation, including authorized complete keys. References not recorded by this Merchant return 404.

GET /api/rejoin/v1/orders?page=1&per_page=20&operation=purchase returns data.items, page, per_page, total and pages. operation accepts purchase, renew or reset; request_id can filter an exact reference. Keys in order lists are masked. The Rejoin API processes transactions immediately and does not use card/top-up callbacks.

1. Save the request reference + payload before calling the API, including calls from a queue.
2. Timeout or disconnection: do not conclude failure, refund or submit a new order with another ID. Look up GET /orders/{request_id}.
3. If a completed order is found, reuse its result; do not buy again. For 404, you may resend the same POST with the same Idempotency-Key and payload.
4. Retrying with the same reference/content returns the recorded result without another charge or reset. Reusing the same reference with a different payload or operation type returns 409.
5. 429/503: follow Retry-After if provided; look up the existing order and retry within limits using the same reference and payload. If the status is still uncertain, keep the order pending reconciliation.

Do not treat a browser timeout or HTTP error as proof that the wallet was not debited. Changing plan prices or account discounts after an order completes does not change its finalized charged and pricing values.

Order lookups/retries preserve request_id, order_code, charged, pricing, license_ids and the balance after that operation. pricing includes base_unit_price (list price), unit_price (discounted unit price), quantity, discount_percent and discount_bps from the order snapshot, not the current discount. Legacy orders without snapshots return pricing=null rather than an inferred discount. The keys field reflects the keys' current state: they may have been renewed, reset or bound to a device after the original transaction. Use GET /balance for the current balance. Retrying a reset after the key has been bound to a new device still returns the completed original operation and does not reset it again.

{
  "success": true,
  "data": {
    "items": [
      {
        "request_id": "shop_order_20261030_000001",
        "operation": "purchase",
        "status": "completed",
        "order_code": "RJ_EXAMPLE_ORDER",
        "license_ids": [
          "11111111-2222-4333-8444-555555555555"
        ],
        "charged": 50000,
        "balance": 450000,
        "keys": [
          {
            "id": "11111111-2222-4333-8444-555555555555",
            "owner_id": 123,
            "plan_id": 1,
            "kind": "vip",
            "key": "RJ-DEMO••••••••00004",
            "status": "inactive",
            "device": "",
            "expires_at": null,
            "duration_days": 7,
            "resets_remaining": 1,
            "created_at": "2026-10-30T02:00:00+00:00",
            "max_tabs": 4,
            "activated_at": null,
            "last_seen": null,
            "device_id": "",
            "generation": 1
          }
        ],
        "created_at": "2026-10-30T02:00:00+00:00",
        "pricing": {
          "base_unit_price": 50000,
          "unit_price": 50000,
          "quantity": 1,
          "discount_percent": 0,
          "discount_bps": 0
        }
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1
  }
}

9. HTTP and errors

{
  "success": false,
  "data": null,
  "code": "insufficient_balance",
  "message": "Số dư không đủ. Vui lòng nạp thêm tiền."
}

Current limits: 100 requests/minute per Merchant and 120 requests/minute per IP on the Rejoin API; every request counts toward both. HTTP 429 requires waiting at least until the next minute window. Read both HTTP and success/code/message. Do not apply chargingws/cardws numeric error codes to Rejoin. Do not log Authorization, Partner Key or full VIP keys in support logs.

Account/group purchase limits also apply to the API: per-transaction value, daily purchase total and limits for accounts without two-factor authentication. Exceeding a limit returns HTTP 403, code=purchase_limit. This does not require submitting a 2FA code to the API; check account settings/limits before retrying. Unauthorized actions, such as resetting a revoked key, may return permission_denied (403).

Success returns HTTP 200. Responses containing complete keys use Cache-Control: no-store; do not cache them publicly or store raw keys in localStorage or logs. Keep key issuance data on the backend and display it only to the authenticated purchaser.

10. Complete code examples

Run this from the reseller's backend with HTTPS verification enabled by default. Set environment variables using a Merchant from this website. Do not use the tool's client API challenge/activate endpoints instead of the sales API. The purchase/renewal POST examples deduct wallet funds when real credentials are used; resets consume the reset allowance.

cURL: catalog, purchase and lookup after timeout

export REJOIN_PARTNER_ID='YOUR_PARTNER_ID'
export REJOIN_PARTNER_KEY='YOUR_PARTNER_KEY'
API='https://toctoico.com/api/rejoin/v1'
REQUEST_ID='shop_order_20261030_000001' # Persist before submitting.

curl --silent --show-error --include "$API/plans" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"

curl --silent --show-error --include --request POST "$API/keys/purchase" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data '{"plan_id":1,"quantity":1}'

# On timeout, look up the original request ID. Never create a replacement ID.
curl --silent --show-error --include "$API/orders/$REQUEST_ID" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"

cURL: key details, history, renewal and reset

Reuse the API/Partner variables from the example above. Replace KEY_ID with the UUID returned in license_ids; use a new operation reference for each POST below and save that reference before sending the request.

KEY_ID='UUID_FROM_LICENSE_IDS'

curl --silent --show-error --include "$API/balance" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"
curl --silent --show-error --include "$API/keys?page=1&per_page=20&status=inactive" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"
curl --silent --show-error --include "$API/keys/$KEY_ID" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"
curl --silent --show-error --include "$API/orders?page=1&per_page=20&operation=purchase" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID"

# Renewal debits the wallet using the selected plan price.
curl --silent --show-error --include --request POST "$API/keys/$KEY_ID/renew" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: shop_renew_20261030_000001" \
  --data '{"plan_id":1}'

# Stop the tool on the old device first. Reset consumes one allowance.
curl --silent --show-error --include --request POST "$API/keys/$KEY_ID/reset" \
  --header "Authorization: Bearer $REJOIN_PARTNER_KEY" \
  --header "X-Partner-ID: $REJOIN_PARTNER_ID" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: shop_reset_20261030_000001" \
  --data '{}' 

Python 3: purchase, order lookup and retry with the same reference

Uses the standard library; requests does not need to be installed. Save REJOIN_ORDER_ID linked to your order before sending the request.

import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request

BASE = os.environ.get("REJOIN_API_BASE", "https://toctoico.com/api/rejoin/v1").rstrip("/")
PARTNER_ID = os.environ["REJOIN_PARTNER_ID"]
PARTNER_KEY = os.environ["REJOIN_PARTNER_KEY"]

class APIError(Exception):
    def __init__(self, status, result):
        if not isinstance(result, dict):
            result = {"message": "HTTP error without a valid API object"}
        super().__init__(result.get("message", "API request failed"))
        self.status, self.result = status, result

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        return None  # Never forward API credentials to a redirected host.

OPENER = urllib.request.build_opener(NoRedirect())

def api(method, path, payload=None, request_id=None):
    headers = {"Authorization": "Bearer " + PARTNER_KEY,
               "X-Partner-ID": PARTNER_ID, "Accept": "application/json"}
    if request_id is not None:
        headers["Idempotency-Key"] = request_id
    data = None
    if payload is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(payload).encode("utf-8")
    request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
    try:
        with OPENER.open(request, timeout=20) as response:
            try:
                result = json.load(response)
            except (ValueError, UnicodeError):
                raise urllib.error.URLError("Invalid API response; outcome not confirmed") from None
    except urllib.error.HTTPError as error:
        try:
            result = json.load(error)
        except (ValueError, UnicodeError):
            result = {"message": "HTTP error without a valid JSON body"}
        raise APIError(error.code, result) from None
    if not isinstance(result, dict):
        raise urllib.error.URLError("Invalid API response; outcome not confirmed")
    if result.get("success") is not True:
        raise APIError(200, result)
    if not isinstance(result.get("data"), dict):
        raise urllib.error.URLError("Invalid API response; outcome not confirmed")
    return result["data"]

def order(request_id):
    return api("GET", "/orders/" + urllib.parse.quote(request_id, safe=""))

def purchase(plan_id, quantity, request_id):
    # Save request_id + payload in your database BEFORE calling this function.
    payload = {"plan_id": plan_id, "quantity": quantity}
    try:
        return api("POST", "/keys/purchase", payload, request_id)
    except APIError as error:
        if error.status not in (429, 503):
            raise  # Never replace a rejected 409 payload with a new request ID.
        time.sleep(60 if error.status == 429 else 2)
    except (urllib.error.URLError, TimeoutError):
        pass
    # A lost response does not mean the purchase failed. Look up the SAME ID.
    try:
        return order(request_id)
    except APIError as error:
        if error.status != 404:
            raise
    # Only one bounded retry, with exactly the same payload and request ID.
    # If this also times out, persist "needs reconciliation" and poll order().
    return api("POST", "/keys/purchase", payload, request_id)

if __name__ == "__main__":
    # Use a plan_id returned by GET /plans, never infer it from a display name.
    result = purchase(int(os.environ["REJOIN_PLAN_ID"]), 1, os.environ["REJOIN_ORDER_ID"])
    # Store/show result["keys"] only through a protected customer flow, not logs.
    print(json.dumps({name: result[name] for name in
                      ("request_id", "order_code", "charged", "license_ids")}, ensure_ascii=False))

PHP 8 + cURL: the same contract and retry reference

<?php
$base = rtrim(getenv('REJOIN_API_BASE') ?: 'https://toctoico.com/api/rejoin/v1', '/');
$partnerId = getenv('REJOIN_PARTNER_ID');
$partnerKey = getenv('REJOIN_PARTNER_KEY');

class RejoinApiError extends RuntimeException {
    public int $httpStatus;
    public function __construct(int $status, array $result) {
        parent::__construct($result['message'] ?? 'API request failed');
        $this->httpStatus = $status;
    }
}
class RejoinTransportError extends RuntimeException {}

function rejoinApi(string $method, string $path, ?array $payload = null,
                   ?string $requestId = null): array {
    global $base, $partnerId, $partnerKey;
    $headers = ['Authorization: Bearer ' . $partnerKey,
                'X-Partner-ID: ' . $partnerId, 'Accept: application/json'];
    if ($requestId !== null) $headers[] = 'Idempotency-Key: ' . $requestId;
    $ch = curl_init($base . $path);
    $options = [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true,
                CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 20,
                CURLOPT_FOLLOWLOCATION => false];
    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
        // Empty reset payload must be a JSON object {}, never an array [].
        $options[CURLOPT_POSTFIELDS] = json_encode($payload === [] ? new stdClass() : $payload,
                                                  JSON_THROW_ON_ERROR);
    }
    $options[CURLOPT_HTTPHEADER] = $headers;
    curl_setopt_array($ch, $options);
    $body = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($body === false) throw new RejoinTransportError('Response not confirmed');
    try {
        $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    } catch (JsonException $error) {
        if ($status < 200 || $status >= 300) {
            throw new RejoinApiError($status, ['message' => 'HTTP error without valid JSON']);
        }
        throw new RejoinTransportError('Invalid JSON; outcome not confirmed');
    }
    if (!is_array($result)) {
        if ($status < 200 || $status >= 300) {
            throw new RejoinApiError($status, ['message' => 'HTTP error without a valid API object']);
        }
        throw new RejoinTransportError('Invalid API object; outcome not confirmed');
    }
    if ($status < 200 || $status >= 300 || ($result['success'] ?? false) !== true) {
        throw new RejoinApiError($status, $result);
    }
    if (!is_array($result['data'] ?? null)) {
        throw new RejoinTransportError('Invalid API data; outcome not confirmed');
    }
    return $result['data'];
}

function rejoinOrder(string $requestId): array {
    return rejoinApi('GET', '/orders/' . rawurlencode($requestId));
}

function rejoinPurchase(int $planId, int $quantity, string $requestId): array {
    // Persist the request ID and payload in your database before sending.
    $payload = ['plan_id' => $planId, 'quantity' => $quantity];
    try {
        return rejoinApi('POST', '/keys/purchase', $payload, $requestId);
    } catch (RejoinApiError $error) {
        if (!in_array($error->httpStatus, [429, 503], true)) throw $error;
        sleep($error->httpStatus === 429 ? 60 : 2);
    } catch (RejoinTransportError $error) {
        // Continue with order lookup; never generate a replacement ID here.
    }
    try {
        return rejoinOrder($requestId);
    } catch (RejoinApiError $error) {
        if ($error->httpStatus !== 404) throw $error;
    }
    // One retry with the identical payload and request ID.
    // If still uncertain, keep the order for reconciliation using rejoinOrder().
    return rejoinApi('POST', '/keys/purchase', $payload, $requestId);
}

$requestId = getenv('REJOIN_ORDER_ID'); // Stable business order ID, saved before I/O.
$planId = (int) getenv('REJOIN_PLAN_ID'); // Read from GET /plans.
$result = rejoinPurchase($planId, 1, $requestId);
// Reset example: stop the old tool first, then persist a NEW reset request ID.
// $uuid = $result['license_ids'][0];
// $reset = rejoinApi('POST', '/keys/' . $uuid . '/reset', [], 'shop_reset_20261030_000001');
// Store/show $result['keys'] only through a protected customer flow, not logs.
$summary = array_intersect_key($result, array_flip(['request_id', 'order_code', 'charged', 'license_ids']));
echo json_encode($summary, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);