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

ขั้นตอนเชื่อม Neo API แบบ Seamless ตั้งแต่ Private Key, Callback URL, /check-balance, /update-balance, get-games, init-session ถึง checklist ก่อนเปิดจริง

การเชื่อม 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](/docs/seamless) ถ้ายังไม่แน่ใจว่าควรใช้ Seamless หรือ Transfer อ่าน [Seamless กับ Transfer ต่างกันยังไง](/blog/seamless-vs-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](/blog/callback-403-cloudflare)

## ขั้นที่ 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](/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"}'
```

2. เปิดหน้า **Callback Test** ในหลังบ้าน Neo กรอก Callback URL, Agent ID, Private Key และ Username ของผู้เล่นทดสอบ แล้วกด **Run Tests** ระบบจะทดสอบทั้ง `/check-balance` และ `/update-balance` แล้วแสดงว่า response ตรงรูปแบบหรือไม่
3. ทดสอบกรณีผิดปกติให้ครบ: 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](/blog/plus-provider-rtp-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](/blog/integrate-with-ai)

## 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 วันนับจากเวลาที่เดิมพัน

---
Source: https://neoapihub.com/blog/seamless-integration-guide
