ឯកសារ API

ដាក់ការបញ្ជាទិញ Free Fire, Mobile Legends, Magic Chess: Go Go និង Blood Strike ពីកម្មវិធីរបស់អ្នកផ្ទាល់។ ការបញ្ជាទិញនីមួយៗបង់ដោយគណនីអ្នកផ្គត់ផ្គង់របស់អ្នកផ្ទាល់។

ចាប់ផ្តើម

ជ្រើសគណនីដែលបង់សម្រាប់ការបញ្ជាទិញតាម API៖ បើកទំព័ររបស់វា ហើយចុច “ប្រើសម្រាប់ការបញ្ជាទិញ API”។ Garena ត្រូវការមួយសម្រាប់តំបន់នីមួយៗ។ Garena · SmileOne
សួររកកូដទំនិញដែលហ្គេមមួយលក់ឥឡូវនេះ ដោយប្រើសំណើបញ្ជីទំនិញខាងក្រោម។
ផ្ញើការបញ្ជាទិញដំបូងរបស់អ្នកដោយប្រើសំណើខាងក្រោម។

ការផ្ទៀងផ្ទាត់

ផ្ញើសោ API របស់អ្នកនៅក្នុង header Authorization នៃរាល់សំណើ។

Authorization
Authorization: Bearer YOUR_API_KEY

រក្សាកូនសោនៅលើម៉ាស៊ីនមេរបស់អ្នក។ អ្នកណាដែលមានវា អាចចំណាយ Shell និង Smile Coin លើគណនីរបស់អ្នក ដូច្នេះកុំដាក់វាក្នុងគេហទំព័រ ឬកម្មវិធីទូរស័ព្ទ។

កូនសោ API ដំណើរការតែលើចំណុចបញ្ជាទិញ និងទំនិញនៅលើទំព័រនេះប៉ុណ្ណោះ។

បញ្ជីកូដទំនិញ

GET/api/items

ផ្ដល់នូវអ្វីដែលហ្គេមមួយលក់ឥឡូវនេះ អានផ្ទាល់តាមគណនីលំនាំដើមរបស់អ្នក ជាមួយកូដទំនិញដែលត្រូវផ្ញើក្នុងការបញ្ជាទិញ។

វាលកំណត់ចំណាំ
gamequery · ចាំបាច់ហ្គេម៖ freefire, mobilelegends, magicchessgogo ឬ bloodstrike។
regionquery · មិនចាំបាច់សម្រាប់ Free Fire តែប៉ុណ្ណោះ ហើយចាំបាច់នៅទីនោះ៖ KH, MY, SG, PH, VN ឬ TW។
ហ្គេមកំណត់ចំណាំ
freefireFree Fire។ កូដទំនិញរបស់វាមានតំបន់ហាង៖ freefire-KH-100។
mobilelegendsMobile Legends។ ផ្ញើ serverId (Zone ID) ជាមួយការបញ្ជាទិញ។
magicchessgogoMagic Chess: Go Go។ ផ្ញើ serverId ជាមួយការបញ្ជាទិញ។
bloodstrikeBlood Strike។ គ្មាន serverId និងគ្មាន region។
ឧទាហរណ៍សំណើ
curl "https://topupkit.com/api/items?game=freefire&region=KH" \
  -H "Authorization: Bearer YOUR_API_KEY"
ឧទាហរណ៍ចម្លើយ
{
  "ok": true,
  "data": [
    {
      "item": "freefire-KH-100",
      "name": "100 Diamonds",
      "price": "86 Shell",
      "costMinorUnits": 15652
    },
    {
      "item": "freefire-KH-weekly_membership",
      "name": "Weekly Membership",
      "price": "160 Shell",
      "costMinorUnits": null
    }
  ]
}

ដាក់ការបញ្ជាទិញ

POST/api/orders

ទទួលការបញ្ជាទិញ ហើយឆ្លើយភ្លាមៗដោយ status pending។ បន្ទាប់មកការទូទាត់ដំណើរការនៅពីក្រោយ ជាធម្មតាតិចជាងមួយនាទី ហើយយូរបំផុតប្រហែលបីនាទី។ យកលទ្ធផលដោយអានការបញ្ជាទិញ ឬពី callback។ ការបញ្ជាទិញដែលត្រូវបដិសេធនៅតែជាការបញ្ជាទិញ ដោយមានហេតុផលនៅលើវា។

សំណើ

វាលកំណត់ចំណាំ
Authorizationheader · ចាំបាច់Bearer បន្ទាប់មកសោ API របស់អ្នក។
Idempotency-Keyheader · មិនចាំបាច់ឈ្មោះមិនស្ទួនដែលអ្នកដាក់ឱ្យការបញ្ជាទិញនេះ រហូតដល់ ២៥៥ តួអក្សរ។ ណែនាំឱ្យប្រើយ៉ាងខ្លាំង។
itemstring · ចាំបាច់កូដទំនិញពីបញ្ជីទំនិញ៖ freefire-KH-100 សម្រាប់ Free Fire ដែលមានតំបន់ហាងនៅក្នុងកូដ ឬ mobilelegends-22590។ វាប្រាប់ថាការបញ្ជាទិញនេះសម្រាប់ហ្គេមណា។
playerIdstring · ចាំបាច់អ្នកលេងដែលទទួលទំនិញ។ លេខតែប៉ុណ្ណោះ រហូតដល់ ២០ ខ្ទង់។
serverIdstring · មិនចាំបាច់សម្រាប់តែហ្គេមដែលសួររកវា៖ Zone ID របស់ Mobile Legends ឬ Server ID របស់ Magic Chess: Go Go។ បើមិនដូច្នោះ កុំផ្ញើ។
accountIdstring · មិនចាំបាច់ស្រេចចិត្ត។ គណនីអ្នកផ្គត់ផ្គង់ដែលបង់ប្រាក់។ បើគ្មានទេ គណនីលំនាំដើមរបស់អ្នកសម្រាប់អ្នកផ្គត់ផ្គង់នោះ (និងតំបន់ សម្រាប់ Free Fire) ជាអ្នកបង់។
ឧទាហរណ៍សំណើ
curl -X POST "https://topupkit.com/api/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-order-1001" \
  -d '{
    "item": "freefire-KH-100",
    "playerId": "123456789"
  }'
ឧទាហរណ៍ body សម្រាប់ Mobile Legends
{
  "item": "mobilelegends-22590",
  "playerId": "123456789",
  "serverId": "2001"
}

201 សម្រាប់ការបញ្ជាទិញថ្មី។ 200 នៅពេល Idempotency-Key នេះធ្លាប់ប្រើរួច៖ អ្នកទទួលបានការបញ្ជាទិញដំបូងវិញ ហើយគ្មានការទូទាត់ម្តងទៀតទេ។

ឧទាហរណ៍ចម្លើយ
{
  "ok": true,
  "data": {
    "id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
    "supplier": "garena",
    "game": "freefire",
    "item": "freefire-KH-100",
    "region": "KH",
    "serverId": null,
    "playerId": "123456789",
    "status": "pending",
    "playerNickname": null,
    "itemName": null,
    "price": null,
    "providerReference": null,
    "supplierMessage": null,
    "failureReason": null,
    "createdAt": "2026-01-15T08:30:00.000Z",
    "settledAt": null
  }
}

វត្ថុការបញ្ជាទិញ

វាលកំណត់ចំណាំ
idstringលេខសម្គាល់ការបញ្ជាទិញ សម្រាប់អានវានៅពេលក្រោយ។
supplierstringអ្នកដែលបំពេញការបញ្ជាទិញ៖ garena ឬ smileone។
gamestringហ្គេម៖ freefire, mobilelegends, magicchessgogo ឬ bloodstrike។
itemstringកូដទំនិញពីបញ្ជីទំនិញ៖ freefire-KH-100 សម្រាប់ Free Fire ដែលមានតំបន់ហាងនៅក្នុងកូដ ឬ mobilelegends-22590។ វាប្រាប់ថាការបញ្ជាទិញនេះសម្រាប់ហ្គេមណា។
regionstring | nullតំបន់ហាងរបស់ Free Fire។ Null សម្រាប់ហ្គេមផ្សេង។
serverIdstring | nullServer ID ដែលបានផ្ញើជាមួយការបញ្ជាទិញ។ Null ពេលហ្គេមគ្មាន។
playerIdstringអ្នកលេងដែលទទួលទំនិញ។ លេខតែប៉ុណ្ណោះ រហូតដល់ ២០ ខ្ទង់។
statusstringសូមមើលស្ថានភាពការបញ្ជាទិញ។
playerNicknamestring | nullឈ្មោះអ្នកលេង នៅពេលអ្នកផ្គត់ផ្គង់ផ្ដល់ឱ្យ។
itemNamestring | nullឈ្មោះទំនិញតាមអ្នកផ្គត់ផ្គង់ផ្ទាល់។ Null សម្រាប់ Free Fire។
pricestring | nullអ្វីដែល Garena បានគិត ឬនឹងគិត ជាអក្សរ ដូចជា 13 Shell។ Null សម្រាប់ហ្គេមផ្សេង។
providerReferencestring | nullលេខប្រតិបត្តិការរបស់អ្នកផ្គត់ផ្គង់ ពេលណាវាផ្ដល់ឱ្យ។
supplierMessagestring | nullពាក្យរបស់អ្នកផ្គត់ផ្គង់ផ្ទាល់ ពេលវាបដិសេធការបញ្ជាទិញ។
failureReasonstring | nullមូលហេតុដែលការបញ្ជាទិញបរាជ័យ។ មានតែនៅពេល status ជា failed ប៉ុណ្ណោះ។
createdAtstringពេលដែលការបញ្ជាទិញត្រូវបានបង្កើត (កាលបរិច្ឆេទ ISO)។
settledAtstring | nullពេលចម្លើយរបស់អ្នកផ្គត់ផ្គង់ត្រូវបានរក្សាទុក (ISO date)។ Null ពេល pending។

ស្ថានភាពការបញ្ជាទិញ

ស្ថានភាពអត្ថន័យ
successអ្នកផ្គត់ផ្គង់បានទទួលការបញ្ជាទិញ ហើយបានយក Shell ឬ Smile Coin។
failedអ្នកផ្គត់ផ្គង់មិនបានយកអ្វីទេ។ failureReason ប្រាប់មូលហេតុ។
unknownចម្លើយបានបាត់ ដូច្នេះ Shell ឬ Smile Coin ប្រហែលបានចំណាយ ឬមិនទាន់។ ពិនិត្យប្រវត្តិគណនីរបស់អ្នក មុនបញ្ជាទិញម្ដងទៀត។
pendingបានទទួល ហើយកំពុងទូទាត់។ សូមអានការបញ្ជាទិញម្តងទៀត ឬរង់ចាំ callback។ បន្ទាប់ពី ១០ នាទី វាក្លាយជា unknown។

មូលហេតុនៃការបរាជ័យ

កំណត់លើការបញ្ជាទិញដែលបរាជ័យ។ គ្រប់ករណី អ្នកផ្គត់ផ្គង់មិនបានយកអ្វីទេ។

កូដអត្ថន័យ
player_not_foundGarena មិនស្គាល់លេខសម្គាល់អ្នកលេងនេះទេ។ មិនមាន Shell ត្រូវបានយកទេ។
player_region_not_allowedហាងនេះមិនអាចលក់ឱ្យតំបន់របស់អ្នកលេងនេះបានទេ។ មិនមាន Shell ត្រូវបានយកទេ។
item_not_availableទំនិញនេះមិនមានសម្រាប់អ្នកលេងនេះនៅពេលនេះទេ។ មិនមាន Shell ត្រូវបានយកទេ។
insufficient_shellគណនី Garena នេះមិនមាន Shell គ្រប់គ្រាន់ទេ។ មិនមាន Shell ត្រូវបានយកទេ។
otp_rejectedGarena មិនទទួលយកលេខកូដ authenticator ទេ។ សូមពិនិត្យលេខកូដសម្ងាត់ authenticator របស់គណនី។ មិនមាន Shell ត្រូវបានយកទេ។
garena_refusedGarena បានបដិសេធការបញ្ជាទិញនេះ។ មិនមាន Shell ត្រូវបានយកទេ។
garena_unavailableមិនអាចភ្ជាប់ទៅ Garena បានទេ។ សូមព្យាយាមម្តងទៀតបន្តិចទៀត។ មិនមាន Shell ត្រូវបានយកទេ។
smileone_account_expiredCookie របស់គណនីលែងដំណើរការ។ សូមបិទភ្ជាប់ cookie ថ្មី។ មិនបានបង់អ្វីទេ។
smileone_refusedSmileOne បានបដិសេធការបញ្ជាទិញនេះ។ មិនបានបង់អ្វីទេ។
smileone_unavailableមិនអាចភ្ជាប់ទៅ SmileOne បានទេ។ មិនបានបង់អ្វីទេ។

អានការបញ្ជាទិញមួយ

GET/api/orders/{id}

ផ្តល់ការបញ្ជាទិញដែលមានលេខសម្គាល់នេះ។ សូមសួររៀងរាល់ប៉ុន្មានវិនាទី រហូតដល់ status លែងជា pending។

បញ្ជីការបញ្ជាទិញ

GET/api/orders

ត្រឡប់ការបញ្ជាទិញរបស់អ្នក ថ្មីបំផុតមុន ចំនួន 20 ក្នុងមួយទំព័រ។ បន្ថែម ?supplier=garena ឬ ?supplier=smileone សម្រាប់អ្នកផ្គត់ផ្គង់មួយ ?search= ដើម្បីផ្គូផ်ရាយលេខការបញ្ជាទិញ លេខអ្នកលេង ឬឯកសារយោង និង ?page= ដើម្បីអានទៅមុខទៀត។

Callback

Callback (ហៅម្យ៉ាងទៀតថា webhook) ជាសំណើដែលយើងផ្ញើទៅម៉ាស៊ីនមេរបស់អ្នក នៅពេលការបញ្ជាទិញដោយសោ API របស់អ្នកចប់ ដូច្នេះអ្នកមិនចាំបាច់សួរជានិច្ចទេ។ វាប្រើវត្ថុការបញ្ជាទិញដូចគ្នា ហើយមកតែនៅពេល status ជា success, failed ឬ unknown ប៉ុណ្ណោះ។ ការអានការបញ្ជាទិញក៏នៅតែប្រើបានដែរ។

នៅទំព័រសោ API ចុច Callback លើសោរបស់អ្នក ហើយបញ្ចូលអាសយដ្ឋាន https://។ អ្នកទទួលបានសោចុះហត្ថលេខាតែម្តងគត់។ ចុចផ្ញើសាកល្បង ដើម្បីពិនិត្យម៉ាស៊ីនមេរបស់អ្នក៖ ការសាកល្បងមាន header X-Callback-Event: test និងការបញ្ជាទិញគំរូ។

អ្វីដែលម៉ាស៊ីនមេរបស់អ្នកទទួលបាន
POST /your-callback-url
Content-Type: application/json
X-Callback-Event: order.settled
X-Callback-Timestamp: 1768465804
X-Callback-Signature: sha256=5f8d0c…

{
  "id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
  "supplier": "garena",
  "game": "freefire",
  "item": "freefire-KH-100",
  "region": "KH",
  "serverId": null,
  "playerId": "123456789",
  "status": "success",
  "playerNickname": "FF_Player",
  "itemName": null,
  "price": "86 Shell",
  "providerReference": "GARENA_TRANSACTION_ID",
  "supplierMessage": null,
  "failureReason": null,
  "createdAt": "2026-01-15T08:30:00.000Z",
  "settledAt": "2026-01-15T08:30:04.000Z"
}

សូមពិនិត្យហត្ថលេខា មុននឹងទុកចិត្ត callback។ វាជា HMAC-SHA256 នៃ timestamp សញ្ញាចុច និង body ពិតប្រាកដ ដោយប្រើសោចុះហត្ថលេខារបស់អ្នក។

Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before JSON.parse.
const expected = Buffer.from(
  "sha256=" +
    createHmac("sha256", SIGNING_SECRET)
      .update(`${headers["x-callback-timestamp"]}.${rawBody}`)
      .digest("hex"),
);
const received = Buffer.from(headers["x-callback-signature"] ?? "");
const age = Date.now() / 1000 - Number(headers["x-callback-timestamp"]);

const genuine =
  received.length === expected.length &&
  timingSafeEqual(received, expected) &&
  Math.abs(age) < 300;

អ្នកណាដែលរកឃើញអាសយដ្ឋានរបស់អ្នក អាចផ្ញើ “success” ក្លែងក្លាយមកបាន។ បើគ្មានការពិនិត្យនេះ ពួកគេអាចទទួលបានទំនិញដោយឥតគិតថ្លៃ។

សូមឆ្លើយដោយ status 2xx ក្នុងរយៈពេល ១០ វិនាទី។ ចម្លើយផ្សេងទៀតនឹងត្រូវសាកម្តងទៀត រហូតដល់ប្រាំដងទៀត ក្នុងរយៈពេលប្រហែលប្រាំមួយម៉ោង។ អ្នកអាចទទួលការបញ្ជាទិញដដែលពីរដង ដូច្នេះសូមប្រើ id របស់ការបញ្ជាទិញ ដើម្បីរំលងការផ្ញើស្ទួន។ យើងមិនតាម redirect ទេ ហើយអាសយដ្ឋានលើបណ្តាញឯកជនត្រូវបានបដិសេធ។

សាកល្បងម្តងទៀតដោយសុវត្ថិភាព

ប្រសិនបើសំណើអស់ពេល អ្នកមិនអាចដឹងថាវាបានទូទាត់ឬអត់។ ផ្ញើម្តងទៀតជាមួយ Idempotency-Key ដដែល៖ ការបញ្ជាទិញដំបូងនឹងត្រឡប់មកវិញ ហើយគ្មានការទូទាត់ពីរដងទេ។ បើគ្មាន header នេះ រាល់សំណើគឺជាការបញ្ជាទិញថ្មី ហើយអាចទូទាត់ម្តងទៀត។

ទម្រង់ចម្លើយ

រាល់ចម្លើយជា JSON ដែលមានវាល ok។ នៅពេល ok ជា true លទ្ធផលនៅក្នុង data។ នៅពេលជា false សូមសម្រេចតាម error.code ព្រោះ error.message អាចផ្លាស់ប្តូរបាន។

error
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "…"
  }
}

កំហុស

ការបញ្ជាទិញដែលត្រូវបដិសេធមិនមែនជាកំហុសទេ៖ វាត្រឡប់មកវិញជាមួយ status failed។ កូដទាំងនេះមានន័យថាសំណើខ្លួនឯងមិនអាចដំណើរការបាន។

កូដអត្ថន័យ
400INVALID_JSONមានបញ្ហាក្នុងការផ្ញើ។ សូមផ្ទុកទំព័រឡើងវិញ ហើយព្យាយាមម្តងទៀត។
400VALIDATION_ERRORវាលមួយបាត់ ឬខុស។ error.message ប្រាប់បញ្ហា។
401UNAUTHORIZEDសោ API បាត់ ខុស ឬត្រូវបានលុប។
404NOT_FOUNDការបញ្ជាទិញនេះមិនមាន ឬមិនមែនជារបស់អ្នក។
409NO_DEFAULT_ACCOUNTមិនទាន់ជ្រើសគណនីដើម្បីបង់សម្រាប់ការបញ្ជាទិញ API នៃហ្គេមនេះទេ។ បើកទំព័រ Garena ឬ SmileOne ហើយចុច “ប្រើសម្រាប់ការបញ្ជាទិញ API” លើគណនីមួយ។
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERSគណនី Garena នេះមិនទាន់រៀបចំសម្រាប់ការបញ្ជាទិញនៅឡើយទេ។ សូមបញ្ចូល UID និងលេខកូដសម្ងាត់ authenticator ជាមុនសិន។
413PAYLOAD_TOO_LARGEទិន្នន័យនេះធំពេកមិនអាចផ្ញើបានទេ។ សូមកាត់ខ្លីកំណត់សម្គាល់ ឬវាលវែងៗ ហើយព្យាយាមម្តងទៀត។
500INTERNAL_ERRORមានបញ្ហានៅខាងប្រព័ន្ធ។ សូមព្យាយាមម្តងទៀតបន្តិចទៀត។