ឯកសារ API
ដាក់ការបញ្ជាទិញ Free Fire, Mobile Legends, Magic Chess: Go Go និង Blood Strike ពីកម្មវិធីរបស់អ្នកផ្ទាល់។ ការបញ្ជាទិញនីមួយៗបង់ដោយគណនីអ្នកផ្គត់ផ្គង់របស់អ្នកផ្ទាល់។
ចាប់ផ្តើម
ការផ្ទៀងផ្ទាត់
ផ្ញើសោ API របស់អ្នកនៅក្នុង header 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។ |
| ហ្គេម | កំណត់ចំណាំ |
|---|---|
freefire | Free Fire។ កូដទំនិញរបស់វាមានតំបន់ហាង៖ freefire-KH-100។ |
mobilelegends | Mobile Legends។ ផ្ញើ serverId (Zone ID) ជាមួយការបញ្ជាទិញ។ |
magicchessgogo | Magic Chess: Go Go។ ផ្ញើ serverId ជាមួយការបញ្ជាទិញ។ |
bloodstrike | Blood Strike។ គ្មាន serverId និងគ្មាន region។ |
curl "https://topupkit.com/api/items?game=freefire®ion=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"
}'{
"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 | null | Server 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_found | Garena មិនស្គាល់លេខសម្គាល់អ្នកលេងនេះទេ។ មិនមាន Shell ត្រូវបានយកទេ។ |
player_region_not_allowed | ហាងនេះមិនអាចលក់ឱ្យតំបន់របស់អ្នកលេងនេះបានទេ។ មិនមាន Shell ត្រូវបានយកទេ។ |
item_not_available | ទំនិញនេះមិនមានសម្រាប់អ្នកលេងនេះនៅពេលនេះទេ។ មិនមាន Shell ត្រូវបានយកទេ។ |
insufficient_shell | គណនី Garena នេះមិនមាន Shell គ្រប់គ្រាន់ទេ។ មិនមាន Shell ត្រូវបានយកទេ។ |
otp_rejected | Garena មិនទទួលយកលេខកូដ authenticator ទេ។ សូមពិនិត្យលេខកូដសម្ងាត់ authenticator របស់គណនី។ មិនមាន Shell ត្រូវបានយកទេ។ |
garena_refused | Garena បានបដិសេធការបញ្ជាទិញនេះ។ មិនមាន Shell ត្រូវបានយកទេ។ |
garena_unavailable | មិនអាចភ្ជាប់ទៅ Garena បានទេ។ សូមព្យាយាមម្តងទៀតបន្តិចទៀត។ មិនមាន Shell ត្រូវបានយកទេ។ |
smileone_account_expired | Cookie របស់គណនីលែងដំណើរការ។ សូមបិទភ្ជាប់ cookie ថ្មី។ មិនបានបង់អ្វីទេ។ |
smileone_refused | SmileOne បានបដិសេធការបញ្ជាទិញនេះ។ មិនបានបង់អ្វីទេ។ |
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 ពិតប្រាកដ ដោយប្រើសោចុះហត្ថលេខារបស់អ្នក។
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 អាចផ្លាស់ប្តូរបាន។
{
"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 | មានបញ្ហានៅខាងប្រព័ន្ធ។ សូមព្យាយាមម្តងទៀតបន្តិចទៀត។ |