neo.api

เชื่อม Neo API แบบ Seamless ทีละขั้น พร้อม checklist go-live

อ่านแบบ Markdown

การเชื่อม 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

ผู้เล่นเกมNeo APIกระเป๋าของคุณcallbackยอดเงิน
ทุกเดิมพัน Neo API เรียก /check-balance และ /update-balance ที่ Callback URL ของคุณ

บทความนี้เรียงตามลำดับที่ควรทำจริง ฟิลด์และ 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

  1. ล็อกอินหลังบ้าน Neo แล้วเปิดหน้า บัญชีของฉัน จะเห็น Agent ID และ Private Key ถ้ายังไม่มีบัญชี ติดต่อ Neo Support ทาง Telegram https://t.me/neosuperapi
  2. เก็บ Private Key ไว้ใน environment variable ของเซิร์ฟเวอร์ ไม่เขียนลงในโค้ด และไม่ commit ขึ้น repository
  3. แนบ Private Key ใน header Authorization ทุกครั้งที่เรียก Neo API
  4. ขากลับใช้ค่าเดียวกัน ทุก 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 มา คุณตอบยอดเงินปัจจุบันกลับไป

http
POST /check-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{ "username": "player123", "agentId": "agent_123" }
json
{ "username": "player123", "balance": 1000.00, "status_code": 0 }

ถ้าไม่พบผู้เล่น ตอบ status_code: 1 (USER_NOT_FOUND)

ขั้นที่ 4: เขียน /update-balance

เส้นนี้คือที่เงินขยับจริง Neo API ส่งรายการเล่นมา คุณปรับยอดแล้วตอบยอดก่อนและหลังทำรายการ

http
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
}
json
{ "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

กติกาที่ต้องทำให้ครบ

  1. ยอดหลังรายการ = ยอดก่อน − transferIn + transferOut
  2. ถ้า transferIn มากกว่ายอดที่มี และ ableNegativeBalance ไม่ใช่ true ให้ตอบ 2 โดยไม่ขยับยอด
  3. ถ้าได้ providerTransactionId ที่เคยประมวลผลแล้ว ห้ามคิดเงินซ้ำ ให้ตอบ 7 พร้อมยอดปัจจุบัน กรณีนี้เกิดเมื่อเซิร์ฟเวอร์ของคุณตอบช้า แล้ว Neo API ส่ง request เดิมซ้ำด้วย id เดิม
  4. ถ้า toCancelProviderTransactionId มีค่า ให้ยกเลิกรายการนั้น หาไม่เจอให้ตอบ 8
  5. ฟิลด์ผลลัพธ์ต้องชื่อ status_code เท่านั้น Neo API ใช้ฟิลด์นี้ตัดสินว่ารายการสำเร็จหรือไม่
  6. ตอบ 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

javascript
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

  1. ยิง request ใส่ endpoint ของตัวเองจากเครื่องที่อยู่นอกเครือข่ายของเซิร์ฟเวอร์ เพื่อให้แน่ใจว่าเข้าถึงได้จากอินเทอร์เน็ต
bash
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"}'
  1. เปิดหน้า Callback Test ในหลังบ้าน Neo กรอก Callback URL, Agent ID, Private Key และ Username ของผู้เล่นทดสอบ แล้วกด Run Tests ระบบจะทดสอบทั้ง /check-balance และ /update-balance แล้วแสดงว่า response ตรงรูปแบบหรือไม่
  2. ทดสอบกรณีผิดปกติให้ครบ: username ที่ไม่มีอยู่, ยอดเงินไม่พอ และ providerTransactionId ซ้ำ

Test Runner ยิง request จาก browser โดยตรง callback server จึงต้องเปิด CORS ระหว่างทดสอบ ส่วนของจริง Neo API เรียกแบบ server-to-server ไม่เกี่ยวกับ CORS

ขั้นที่ 6: ดึงรายการเกม

bash
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

javascript
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) ห้ามฝังใน iframe
  • html: 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 วันนับจากเวลาที่เดิมพัน

บทความอื่น

Seamless กับ Transfer ต่างกันยังไง เลือกแบบไหนกับ Neo API

เทียบการเชื่อม Neo API แบบ Seamless (Single Wallet) กับ Transfer (Two Wallet) ว่าใครถือกระเป๋าเงิน ต้องสร้างอะไรบ้าง ใช้ endpoint ไหน ข้อดีข้อเสีย และวิธีเลือก

ใช้ AI ช่วยเชื่อม Neo API กับ Claude Code, Cursor, ChatGPT

วิธีให้ AI เขียนโค้ดเชื่อม Neo API ให้ถูกตั้งแต่รอบแรก ส่งเอกสาร Markdown, prompt พร้อมใช้, จุดที่ต้องตรวจในโค้ด callback และการเก็บ Private Key ให้พ้นแชท

Callback โดน Cloudflare บล็อก 403 ทุกค่ายเล่นไม่ได้ แก้ยังไง

init-session สำเร็จแต่ทุกค่ายเดิมพันไม่ได้ ให้เช็ค Cloudflare หรือ WAF หน้า Callback URL ก่อน วิธียืนยันอาการ ตั้ง Skip rule หรือแยก subdomain และทดสอบซ้ำ

ปรับ RTP ค่าย _plus ผ่าน API ด้วย set-rtp และ init-session

ค่าย _plus ไหนปรับ RTP ได้ ไหนไม่ได้ เช็คด้วย canSetRtp และ canSetPreset แล้วตั้งด้วย set-rtp หรือส่ง rtp กับ init-session พร้อมตัวอย่าง request และ error