เชื่อม Neo API แบบ Seamless ทีละขั้น พร้อม checklist go-live
การเชื่อม Neo API แบบ Seamless คือการให้กระเป๋าเงินของผู้เล่นอยู่ที่ระบบของคุณ แล้ว Neo API เรียก callback มาที่เซิร์ฟเวอร์ของคุณทุกครั้งที่ผู้เล่นเดิมพันหรือได้รับเงิน งานฝั่งคุณมีสองส่วน คือเขียน endpoint ให้ Neo API เรียก 2 เส้น (/check-balance และ /update-balance) และเรียก API ของ Neo 2 เส้น (get-games และ init-session) ที่ https://api.neoapihub.com ทุก request ทั้งขาไปและขากลับยืนยันตัวตนด้วย Private Key ใน header Authorization
บทความนี้เรียงตามลำดับที่ควรทำจริง ฟิลด์และ status code ทั้งหมดมาจากเอกสาร /docs/seamless ถ้ายังไม่แน่ใจว่าควรใช้ Seamless หรือ Transfer อ่าน Seamless กับ Transfer ต่างกันยังไง ก่อน
ภาพรวม: ใครเรียกใคร
| ทิศทาง | เส้น | ใช้ทำอะไร |
|---|---|---|
| คุณ → Neo API | POST /api/external/get-games |
ดึงรายการค่ายและเกม เพื่อเอา gameId |
| คุณ → Neo API | POST /api/external/init-session |
ขอ URL หรือ HTML สำหรับเปิดเกมให้ผู้เล่น |
| Neo API → คุณ | POST /check-balance |
ถามยอดเงินปัจจุบันของผู้เล่น |
| Neo API → คุณ | POST /update-balance |
หักเงินเดิมพัน (transferIn) และจ่ายเงิน (transferOut) |
ลำดับตอนผู้เล่นเข้าเกม: ผู้เล่นกดเกมในเว็บของคุณ → backend ของคุณเรียก init-session → ได้ลิงก์เกมกลับมา → ผู้เล่นเล่น → Neo API เรียก /check-balance และ /update-balance ที่เซิร์ฟเวอร์ของคุณ → คุณตอบยอดเงินกลับไป
ขั้นที่ 1: Agent ID และ Private Key
- ล็อกอินหลังบ้าน Neo แล้วเปิดหน้า บัญชีของฉัน จะเห็น Agent ID และ Private Key ถ้ายังไม่มีบัญชี ติดต่อ Neo Support ทาง Telegram https://t.me/neosuperapi
- เก็บ Private Key ไว้ใน environment variable ของเซิร์ฟเวอร์ ไม่เขียนลงในโค้ด และไม่ commit ขึ้น repository
- แนบ Private Key ใน header
Authorizationทุกครั้งที่เรียก Neo API - ขากลับใช้ค่าเดียวกัน ทุก callback ที่ Neo API ส่งมาจะมี Private Key ของคุณใน header
Authorizationให้เทียบค่านี้ก่อนประมวลผลทุกครั้ง
ถ้า Private Key หลุด ให้กด Reset Private Key ในหน้าเดียวกันทันที แล้วอัปเดต environment variable ทุกเครื่อง ถ้าต้องการจำกัด IP ที่เรียก callback ได้ ขอรายการ IP Whitelist จากหัวสายหรือ Neo Support
ขั้นที่ 2: ตั้ง Callback URL
ในหน้า บัญชีของฉัน เลื่อนลงมาที่ จัดการ Callback URL แล้วใส่ URL ฐานของเซิร์ฟเวอร์ที่รับ callback ระบบจะต่อชื่อเส้นท้าย URL นี้ เช่น ตั้งไว้เป็น https://wallet.example.com/neo Neo API จะเรียก https://wallet.example.com/neo/check-balance และ https://wallet.example.com/neo/update-balance
ระบบตรวจ URL ตั้งแต่ตอนกดบันทึก ถ้าไม่ผ่านจะได้ CALLBACK_URL_NOT_ALLOWED เงื่อนไขคือ
- ขึ้นต้นด้วย
httpหรือhttpsและใน production ควรเป็น HTTPS - เป็นโฮสต์สาธารณะ ใช้
localhost,127.0.0.1หรือ IP วงภายใน (10.x,172.16–31.x,192.168.x,169.254.x) ไม่ได้ โดเมนที่ resolve ไปเป็น IP ภายในก็ไม่ผ่าน - โดเมนที่ DNS ยังไม่ขึ้นบันทึกได้ แต่ callback จะยังไม่ทำงานจนกว่า DNS ชี้มาที่เซิร์ฟเวอร์
- ห้ามใส่ username/password ไว้ใน URL ให้ยืนยันตัวตนด้วย header
Authorizationแทน
ถ้าโดเมน callback อยู่หลัง Cloudflare หรือ WAF ตัวอื่น ให้กันไม่ให้มี bot challenge บนสองเส้นนี้ตั้งแต่แรก วิธีตั้งอยู่ใน callback โดน Cloudflare บล็อก 403
ขั้นที่ 3: เขียน /check-balance
Neo API ส่ง username (ชื่อเดียวกับที่คุณส่งตอน init-session) และ agentId มา คุณตอบยอดเงินปัจจุบันกลับไป
POST /check-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY
{ "username": "player123", "agentId": "agent_123" }{ "username": "player123", "balance": 1000.00, "status_code": 0 }ถ้าไม่พบผู้เล่น ตอบ status_code: 1 (USER_NOT_FOUND)
ขั้นที่ 4: เขียน /update-balance
เส้นนี้คือที่เงินขยับจริง Neo API ส่งรายการเล่นมา คุณปรับยอดแล้วตอบยอดก่อนและหลังทำรายการ
POST /update-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY
{
"agentId": "agent_123",
"username": "player123",
"providerTransactionId": "txn_123456",
"transferIn": 0.00,
"transferOut": 50.00,
"ableNegativeBalance": false,
"toCancelProviderTransactionId": null
}{ "username": "player123", "balanceBefore": 1000.00, "balanceAfter": 1050.00, "status_code": 0 }| ฟิลด์ | ความหมาย |
|---|---|
transferIn |
เงินที่ผู้เล่นเอาเข้าเกม คล้ายการวางเดิมพัน ให้หักออกจากยอด |
transferOut |
เงินที่จ่ายให้ผู้เล่น คล้ายการ settle ให้บวกเข้ายอด |
providerTransactionId |
id ของรายการ ใช้กันการคิดเงินซ้ำ |
ableNegativeBalance |
ถ้าเป็น true ต้องยอมให้ยอดผู้เล่นติดลบได้ |
toCancelProviderTransactionId |
มีค่าเมื่อค่ายเกมขอยกเลิกรายการเดิม ต้องยกเลิกรายการนั้นออกจากระบบ |
isBuyFeature, isFreeSpin |
optional ส่งมาเฉพาะเมื่อเป็น true เป็นข้อมูลประกอบรายงาน การคิดเงินยังใช้ transferIn / transferOut |
กติกาที่ต้องทำให้ครบ
- ยอดหลังรายการ = ยอดก่อน −
transferIn+transferOut - ถ้า
transferInมากกว่ายอดที่มี และableNegativeBalanceไม่ใช่trueให้ตอบ2โดยไม่ขยับยอด - ถ้าได้
providerTransactionIdที่เคยประมวลผลแล้ว ห้ามคิดเงินซ้ำ ให้ตอบ7พร้อมยอดปัจจุบัน กรณีนี้เกิดเมื่อเซิร์ฟเวอร์ของคุณตอบช้า แล้ว Neo API ส่ง request เดิมซ้ำด้วย id เดิม - ถ้า
toCancelProviderTransactionIdมีค่า ให้ยกเลิกรายการนั้น หาไม่เจอให้ตอบ8 - ฟิลด์ผลลัพธ์ต้องชื่อ
status_codeเท่านั้น Neo API ใช้ฟิลด์นี้ตัดสินว่ารายการสำเร็จหรือไม่ - ตอบ
0หลังบันทึกลงฐานข้อมูลสำเร็จแล้วเท่านั้น และตอบ7เฉพาะรายการที่ตรวจแล้วว่าซ้ำจริง
Status code
status_code |
ชื่อ | ใช้เมื่อ |
|---|---|---|
| 0 | SUCCESS | ทำรายการสำเร็จ |
| 1 | USER_NOT_FOUND | หา username ไม่เจอ |
| 2 | INSUFFICIENT_BALANCE | เงินผู้เล่นไม่พอสำหรับ transferIn |
| 3 | INVALID_REQUEST | request ผิด format |
| 4 | UNAUTHORIZED | agent id ไม่ถูกต้อง |
| 5 | FORBIDDEN | private key ไม่ถูกต้อง |
| 6 | INTERNAL_SERVER_ERROR | เซิร์ฟเวอร์ของคุณมีปัญหาอื่น |
| 7 | TRANSACTION_ALREADY_EXISTS | providerTransactionId ซ้ำ |
| 8 | TO_CANCEL_TRANSACTION_NOT_FOUND | หารายการที่ต้องยกเลิกไม่เจอ |
ตัวอย่างโค้ดในเอกสารตอบ 4 ที่ /check-balance และตอบ 5 ที่ /update-balance เมื่อ header Authorization ไม่ตรง
ตัวอย่าง: Node.js (Express) + PostgreSQL
import crypto from 'node:crypto';
import express from 'express';
import pg from 'pg';
const app = express();
app.use(express.json());
const pool = new pg.Pool({ connectionString: process.env.WALLET_DB_URL });
const PRIVATE_KEY = process.env.NEO_PRIVATE_KEY;
function authorized(req) {
const got = Buffer.from(req.get('Authorization') ?? '');
const want = Buffer.from(PRIVATE_KEY);
return got.length === want.length && crypto.timingSafeEqual(got, want);
}
app.post('/neo/check-balance', async (req, res) => {
const { username } = req.body;
if (!authorized(req)) return res.status(401).json({ username, balance: 0, status_code: 4 });
const { rows } = await pool.query('SELECT balance FROM wallets WHERE username = $1', [username]);
if (rows.length === 0) return res.json({ username, balance: 0, status_code: 1 });
return res.json({ username, balance: Number(rows[0].balance), status_code: 0 });
});
app.post('/neo/update-balance', async (req, res) => {
const b = req.body;
const send = (status_code, before = 0, after = before) =>
res.json({ username: b.username, balanceBefore: before, balanceAfter: after, status_code });
if (!authorized(req)) return res.status(401).json({ username: b.username, balanceBefore: 0, balanceAfter: 0, status_code: 5 });
if (!b.username || !b.providerTransactionId) return send(3);
const db = await pool.connect();
try {
await db.query('BEGIN');
// ล็อกแถวกระเป๋า กันสอง callback ของผู้เล่นคนเดียวกันแก้ยอดพร้อมกัน
const w = await db.query('SELECT balance FROM wallets WHERE username = $1 FOR UPDATE', [b.username]);
if (w.rowCount === 0) { await db.query('ROLLBACK'); return send(1); }
const before = Number(w.rows[0].balance);
// รายการซ้ำ: ตอบ 7 พร้อมยอดปัจจุบัน ไม่คิดเงินซ้ำ
const seen = await db.query('SELECT 1 FROM neo_tx WHERE provider_transaction_id = $1', [b.providerTransactionId]);
if (seen.rowCount > 0) { await db.query('ROLLBACK'); return send(7, before); }
if (b.toCancelProviderTransactionId) {
// cancelTransaction: ยกเลิกรายการเดิมออกจากระบบตามเอกสาร คืน false ถ้าหาไม่เจอ
const found = await cancelTransaction(db, b.toCancelProviderTransactionId);
if (!found) { await db.query('ROLLBACK'); return send(8, before); }
}
const transferIn = Number(b.transferIn || 0);
const transferOut = Number(b.transferOut || 0);
if (transferIn > before && b.ableNegativeBalance !== true) {
await db.query('ROLLBACK'); return send(2, before);
}
const after = before - transferIn + transferOut;
await db.query('UPDATE wallets SET balance = $1 WHERE username = $2', [after, b.username]);
await db.query(
'INSERT INTO neo_tx (provider_transaction_id, username, transfer_in, transfer_out, payload) VALUES ($1, $2, $3, $4, $5)',
[b.providerTransactionId, b.username, transferIn, transferOut, b],
);
await db.query('COMMIT');
return send(0, before, after); // ตอบ 0 หลัง COMMIT เท่านั้น
} catch (err) {
await db.query('ROLLBACK').catch(() => {});
return send(6);
} finally {
db.release();
}
});
app.listen(3000);ตาราง neo_tx ควรมี unique constraint ที่ provider_transaction_id เป็นด่านสุดท้ายกันรายการซ้ำ และในงานจริงควรเก็บและคำนวณเงินด้วยชนิด decimal แทน float ตัวอย่างภาษา Python, PHP และ Go อยู่ใน /docs/seamless
ขั้นที่ 5: ทดสอบ callback
- ยิง request ใส่ endpoint ของตัวเองจากเครื่องที่อยู่นอกเครือข่ายของเซิร์ฟเวอร์ เพื่อให้แน่ใจว่าเข้าถึงได้จากอินเทอร์เน็ต
curl -i -X POST https://wallet.example.com/neo/check-balance \
-H "Content-Type: application/json" \
-H "Authorization: $NEO_PRIVATE_KEY" \
-d '{"username":"testplayer01","agentId":"YOUR_AGENT_ID"}'- เปิดหน้า Callback Test ในหลังบ้าน Neo กรอก Callback URL, Agent ID, Private Key และ Username ของผู้เล่นทดสอบ แล้วกด Run Tests ระบบจะทดสอบทั้ง
/check-balanceและ/update-balanceแล้วแสดงว่า response ตรงรูปแบบหรือไม่ - ทดสอบกรณีผิดปกติให้ครบ: username ที่ไม่มีอยู่, ยอดเงินไม่พอ และ
providerTransactionIdซ้ำ
Test Runner ยิง request จาก browser โดยตรง callback server จึงต้องเปิด CORS ระหว่างทดสอบ ส่วนของจริง Neo API เรียกแบบ server-to-server ไม่เกี่ยวกับ CORS
ขั้นที่ 6: ดึงรายการเกม
curl -X POST https://api.neoapihub.com/api/external/get-games \
-H "Authorization: $NEO_PRIVATE_KEY" \
-H "Content-Type: application/json" \
-d '{"agentId":"YOUR_AGENT_ID","providerList":["PROVIDER_ID"]}'providerList เป็น optional ถ้าไม่ส่งจะได้ทุกค่าย response เป็น providers[] แต่ละรายการมี provider (id, name, isRedirect, logoUrl) และ games[] (id, name, code, imageUrl, type, isRecommend, isNew, providerId) ใช้ id ของเกมเป็น gameId ตอนเปิดเกม
เก็บรายการไว้ในระบบของคุณและ sync ใหม่เป็นระยะ ตัวอย่างที่เกิดขึ้นแล้ว: เดือนกรกฎาคม 2026 ค่าย JILI_plus, SA_plus, NOLIMITCITY_plus, EVOPLAY_plus และ FACHAI_plus ย้ายระบบ ชื่อค่ายเหมือนเดิมแต่ providerId และ gameId เปลี่ยนทั้งหมด gameId ชุดเดิมเปิดได้แค่ช่วงเปลี่ยนผ่าน
ขั้นที่ 7: เปิดเกมด้วย init-session
เรียกจาก backend เท่านั้น เพราะต้องแนบ Private Key
app.post('/play', async (req, res) => {
const r = await fetch('https://api.neoapihub.com/api/external/init-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: process.env.NEO_PRIVATE_KEY },
body: JSON.stringify({
agentId: process.env.NEO_API_AGENT_ID,
username: req.user.username, // ชื่อนี้จะกลับมาใน /check-balance และ /update-balance
gameId: req.body.gameId,
hrefBackUrl: 'https://www.example.com/lobby',
language: 'th', // en, cn, jp, th, vn, kr
isDesktop: !req.body.isMobile,
clientIp: req.ip, // จำเป็นสำหรับเกมค่าย PG
}),
});
if (!r.ok) return res.status(502).json({ error: 'init-session failed', status: r.status });
return res.json(await r.json()); // { type: 'url' | 'html' | 'redirect', url?, html? }
});จัดการ response ตาม type
urlหรือredirect: เปิดurlให้ผู้เล่นใน tab ใหม่ ถ้าเป็นredirect(เช่น HuayDragon) ห้ามฝังใน iframehtml: render ค่าในhtmlให้ผู้เล่น
จุดที่มักพลาด: ไม่ส่ง clientIp ตอนเปิดเกมค่าย PG จะได้ 400 และเกมไม่เปิด ถ้าเว็บอยู่หลัง proxy หรือ CDN ต้องส่ง IP จริงของผู้เล่น ไม่ใช่ IP ของ proxy ถ้ามีหลายเว็บใน Agent เดียว ให้ต่อท้าย username ด้วยชื่อเว็บกันชื่อชนกัน ฟิลด์ rtp เป็น optional ใช้กับค่ายที่ตั้ง RTP ได้ อ่านต่อใน ปรับ RTP ค่าย _plus ผ่าน API
Checklist ก่อน go-live
- Callback URL เป็นโดเมนสาธารณะ ใช้ HTTPS และเรียกถึงได้จากนอกเครือข่าย
- ไม่มี bot challenge, JS challenge หรือ rate limit ที่บล็อก
/check-balanceและ/update-balance - ทุก callback ตรวจ header
Authorizationก่อนแตะฐานข้อมูล -
/update-balanceกันproviderTransactionIdซ้ำ ทั้งในโค้ดและด้วย unique constraint - รองรับ
ableNegativeBalanceและtoCancelProviderTransactionId - ตอบด้วยฟิลด์
status_codeและใช้รหัสตามตาราง - ผ่านหน้า Callback Test ทั้งกรณีปกติและกรณีผิดพลาด
- Private Key อยู่ใน environment variable ไม่อยู่ในโค้ด log หรือ frontend
-
init-sessionส่งclientIpและisDesktopตรงกับอุปกรณ์ และเปิดtype: redirectใน tab ใหม่ - มีงาน sync
get-gamesเป็นระยะ - เช็คเครดิตด้วย
get-sub-agent-quota-summaryเพราะเมื่อเครดิตหมดผู้เล่นจะเล่นเกมไม่ได้
ถ้าใช้ AI ช่วยเขียนโค้ดส่วนนี้ ดูวิธีให้เอกสารและวิธีตรวจผลลัพธ์ใน ใช้ AI ช่วยเชื่อม Neo API
FAQ
Neo API ส่ง /update-balance ซ้ำด้วย providerTransactionId เดิมเมื่อไร
เมื่อเซิร์ฟเวอร์ของคุณตอบช้า Neo API จะส่ง request เดิมมาอีกครั้งด้วย id เดิม ให้ตอบ status_code: 7 พร้อมยอดปัจจุบัน และห้ามคิดเงินรอบนั้นซ้ำ
ต้องตอบ HTTP status อะไรถ้าเงินไม่พอหรือหาผู้เล่นไม่เจอ
Neo API ตัดสินผลจากฟิลด์ status_code ใน body ตัวอย่างโค้ดในเอกสารตอบ HTTP 200 พร้อม status_code ที่ตรงกับกรณี และตอบ 401 เฉพาะเมื่อ Authorization ไม่ถูกต้อง
ทดสอบ callback กับ localhost ได้ไหม
ไม่ได้ Callback URL ต้องเป็นโฮสต์สาธารณะ ระบบไม่รับ localhost, 127.0.0.1 หรือ IP วงภายใน ให้ใช้เซิร์ฟเวอร์ทดสอบที่มีโดเมนสาธารณะแทน
ข้อมูลประวัติการเล่นดึงจากไหน
ใช้ POST /api/external/get-transaction-by-username ดึงประวัติรายผู้เล่นหรือทั้งสาย และใช้ POST /api/external/get-bet-detail-url ขอลิงก์ดูรายละเอียดรายตา ซึ่งดูย้อนหลังได้ภายใน 7 วันนับจากเวลาที่เดิมพัน



