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

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

ต่างกันที่ว่าใครถือยอดเงินของผู้เล่น แบบ Seamless (Single Wallet) ยอดอยู่ในระบบของคุณ และ Neo API เรียก callback มาหักหรือจ่ายเงินทุกครั้งที่มีการเดิมพัน แบบ Transfer (Two Wallet) ยอดสำหรับเล่นเกมอยู่ในระบบ Neo API คุณโยกเงินเข้าด้วย `transfer-in` ก่อนเล่นและโยกออกด้วย `transfer-out` หลังเล่น โดยไม่มี callback รายตา เลือก Seamless เมื่อระบบของคุณรับโหลดสูงได้และอยากให้ผู้เล่นเห็นยอดเดียว เลือก Transfer เมื่อเพิ่งเริ่มทำระบบหรือไม่อยากรับ callback แบบ real-time

## ใครถือกระเป๋าเงิน

**Seamless** ค่ายเกมไม่ถือเงินผู้เล่นเอง (หรือถือแค่ชั่วคราว) ทุกการเดิมพันและการจ่ายรางวัลจะวิ่งเป็น callback มาที่เซิร์ฟเวอร์ของคุณ คุณเป็น source of truth ของยอดเงิน ผู้เล่นเปลี่ยนเกมหรือเปลี่ยนค่ายได้ทันทีโดยไม่ต้องโยกเงิน

**Transfer** ผู้เล่นแต่ละคนมียอดอีกก้อนหนึ่งในระบบ Neo API ก่อนเข้าเล่นต้องโยกเงินเข้ากระเป๋านี้ และเมื่อจบ session หรือออกจากเกมต้องโยกกลับ ระหว่างเล่นการตัดสินผลและการ settle เกิดฝั่งผู้ให้บริการ ไม่มี callback กลับมาหาคุณทุกตา

## Seamless: สิ่งที่ต้องสร้าง

1. ตั้ง Callback URL เป็นโฮสต์สาธารณะที่เซิร์ฟเวอร์ของ Neo เรียกถึง
2. Endpoint `/check-balance` ตอบ `username`, `balance`, `status_code`
3. Endpoint `/update-balance` รับ `transferIn` (หัก) และ `transferOut` (จ่าย) แล้วตอบ `balanceBefore`, `balanceAfter`, `status_code`
4. กันรายการซ้ำด้วย `providerTransactionId` เพราะถ้าตอบช้า Neo API จะส่ง request เดิมซ้ำ
5. รองรับ `ableNegativeBalance` และการยกเลิกรายการผ่าน `toCancelProviderTransactionId`
6. ทุก callback ต้องเป็นแบบ transactional และ idempotent พร้อม ledger และ audit log ของทุกรายการ

ขั้นตอนเต็มพร้อมโค้ดอยู่ใน [เชื่อม Neo API แบบ Seamless ทีละขั้น](/blog/seamless-integration-guide)

## Transfer: สิ่งที่ต้องสร้าง

ไม่ต้องเขียน callback ใช้วิธีเรียก API จัดการผู้เล่นและยอดเงิน ทุกเส้นเป็น `POST` ที่ `https://api.neoapihub.com/api/external-transfer/` และแนบ Private Key ใน header `Authorization`

| เส้น | Body | ทำอะไร |
|---|---|---|
| `create-user` | `username`, `initialBalance` (optional) | สร้างผู้เล่น ไม่ส่ง `initialBalance` ถือว่า 0 |
| `transfer-in` | `username`, `amount` | เพิ่มยอด เช่น มี 100 ส่ง 50 ได้ 150 |
| `transfer-out` | `username`, `amount` | ลดยอด เช่น มี 100 ส่ง 50 เหลือ 50 |
| `get-balance` | `username` | ดูยอดปัจจุบัน |
| `set-balance` | `username`, `amount` | ตั้งยอดสุดท้ายตรงๆ เช่น มี 100 ส่ง 150 ได้ 150 |
| `get-transfer-history` | `username`, `startDate`, `endDate`, `page`, `limit` | ประวัติเติม ถอน ปรับยอด แบบแบ่งหน้า |

ลำดับใช้งานปกติ

```text
create-user → transfer-in → init-session → ผู้เล่นเล่น → transfer-out → get-transfer-history
```

ตัวอย่างโยกเงินเข้าก่อนเปิดเกม

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/transfer-in \
  -H "Authorization: $NEO_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"player123","amount":50}'
```

```json
{
  "id": "string",
  "agentId": "string",
  "agentUserId": "string",
  "transferAmount": 50,
  "transferType": "IN",
  "balanceBefore": 100,
  "balanceAfter": 150,
  "createdAt": "2026-01-04T08:34:27.438Z"
}
```

กติกาที่ต้องรู้: `username` ต้องไม่ซ้ำภายใน agent, `amount` และ `initialBalance` ต้องไม่ติดลบ (`transfer-in` และ `transfer-out` ต้องมากกว่า 0) เวลาใช้รูปแบบ ISO 8601 Error ที่เจอบ่อยคือ `INVALID_PRIVATE_KEY`, `USERNAME_ALREADY_EXISTS`, `USERNAME_NOT_FOUND` และ `INSUFFICIENT_BALANCE` (ถอนเกินยอด)

ฝั่งคุณยังต้องมี ledger ของตัวเอง ทุกครั้งที่หักเงินจากกระเป๋าหลักของเว็บเพื่อ `transfer-in` และทุกครั้งที่ `transfer-out` กลับมา ต้องบันทึกคู่กันพร้อม `id` ที่ได้จาก response เพื่อกระทบยอดกับ `get-transfer-history` ได้

## ตารางเปรียบเทียบ

| หัวข้อ | Seamless (Single Wallet) | Transfer (Two Wallet) |
|---|---|---|
| ยอดเงินระหว่างเล่นอยู่ที่ | ระบบของคุณ | ระบบ Neo API |
| Callback รายตา | มี ทุกการเดิมพันและการจ่าย | ไม่มี |
| Callback URL | ต้องตั้ง | ไม่ต้องตั้ง |
| โหลดที่ระบบคุณต้องรับ | สูง (high QPS) และต้องตอบเร็ว | เฉพาะตอนโยกเงิน |
| สิ่งที่ต้องเขียน | 2 callback + idempotency + ledger | เรียก API โยกเงิน + ledger ฝั่งเว็บ |
| ประสบการณ์ผู้เล่น | เห็นยอดเดียว เปลี่ยนเกมได้ทันที | อาจเห็นยอดแยก เงินอาจโยกช้าหรือค้าง |
| ความเสี่ยงหลัก | คิดเงินซ้ำถ้ากันรายการซ้ำไม่ดี | เงินค้างเมื่อ session ค้างหรือ error |
| เหมาะกับ | ระบบที่เสถียรและพร้อมทำ idempotency, ledger, audit | ผู้เริ่มพัฒนาระบบ หรือไม่ต้องการรับโหลดแบบ real-time |

## Endpoint ที่ใช้ของแต่ละแบบ

| Endpoint | Seamless | Transfer |
|---|---|---|
| `/check-balance`, `/update-balance` (Neo เรียกคุณ) | ใช้ | ไม่ใช้ |
| `/api/external-transfer/*` (6 เส้นข้างบน) | ไม่ใช้ | ใช้ |
| `/api/external/get-games` | ใช้ | ใช้ |
| `/api/external/init-session` | ใช้ | ใช้ |
| `/api/external/get-sub-agent-quota-summary` | ใช้ | ใช้ |
| `/api/external/get-transaction-by-username` | ใช้ | ใช้ |
| `/api/external/get-bet-detail-url` | ใช้ | ใช้ |
| `/api/external/get-poy-group-history-by-user` | ใช้ | ใช้ |

ส่วนเปิดเกมเหมือนกันทั้งสองแบบ ใช้ `init-session` ตัวเดียวกัน ฟิลด์เดียวกัน (`gameId`, `username`, `hrefBackUrl`, `agentId`, `language`, `isDesktop`, `rtp`, `clientIp`) และจัดการ response `type` (`url`, `html`, `redirect`) แบบเดียวกัน เอกสารแยกตามแบบอยู่ที่ [/docs/seamless](/docs/seamless) และ [/docs/transfer](/docs/transfer)

## เลือกยังไง

ตอบคำถามเหล่านี้ก่อน

1. **เว็บของคุณมีกระเป๋าเงินผู้เล่นและ ledger ที่เชื่อถือได้อยู่แล้วหรือยัง** ถ้ามี Seamless ต่อเข้าได้ตรงๆ ถ้ายังไม่มี Transfer เริ่มได้เร็วกว่า
2. **เซิร์ฟเวอร์รับ request ทุกตาเดิมพันได้ไหม** Seamless หมายถึง callback ทุกครั้งที่ผู้เล่นหมุนหรือวางเดิมพัน ต้องตอบเร็วและไม่ล่มช่วงคนเล่นเยอะ
3. **ผู้เล่นสลับค่ายบ่อยไหม** ถ้าบ่อย Seamless ไม่ต้องโยกเงินทุกครั้งที่เปลี่ยนเกม
4. **ทีมพร้อมดูแลเงินค้างหรือไม่** แบบ Transfer ต้องมีขั้นตอนตรวจเมื่อ `transfer-out` ไม่สำเร็จหรือผู้เล่นปิดเกมกลางคัน

ถ้าจะใช้ AI ช่วยเขียนส่วนเชื่อมต่อของแบบที่เลือก ดู [ใช้ AI ช่วยเชื่อม Neo API](/blog/integrate-with-ai)

## เปลี่ยนแบบภายหลังได้ไหม

ประเภทการเชื่อมต่อ (Callback Type) ผูกกับบัญชี กำหนดตอนสร้างบัญชี หัวสายแก้ให้ลูกสายชั้นถัดไปได้ผ่าน `POST /api/external/update-sub-agent` ด้วยฟิลด์ `callbackType` (`SEAMLESS` หรือ `TRANSFER`) และ `callbackUrl` ถ้าเปลี่ยนมาเป็น Seamless กฎของ Callback URL มีผลทันที ต้องเป็นโฮสต์สาธารณะ ไม่ใช่ `localhost` หรือ IP วงภายใน

ก่อนสลับ ให้ตรวจว่าไม่มีรายการค้าง และเตรียมรับผลจ่ายหรือการยกเลิกที่อาจมาช้าของรายการเดิม ถ้าบัญชีของคุณเป็นหัวสายบนสุด ติดต่อ Neo Support ทาง https://t.me/neosuperapi

## FAQ

### แบบ Transfer ต้องตั้ง Callback URL ไหม

ไม่ต้อง Callback URL ใช้กับแบบ Seamless เท่านั้น ตอนสร้างลูกสายแบบ Transfer ปล่อยช่องนี้ว่างได้

### `set-balance` ต่างจาก `transfer-in` อย่างไร

`transfer-in` บวกจำนวนที่ส่งเข้าไปในยอดเดิม ส่วน `set-balance` ตั้งยอดเป็นจำนวนที่ส่งมาตรงๆ เหมาะกับการ sync ยอดให้ตรงกับระบบภายนอก อย่าใช้ `set-balance` แก้เงินค้างก่อนตรวจประวัติ `get-transfer-history` และ `get-transaction-by-username` ว่ารายการไหนสำเร็จแล้ว

### ดูประวัติเดิมพันรายตาได้ทั้งสองแบบไหม

ได้ `get-transaction-by-username` คืนรายการเดิมพันพร้อม `betAmount`, `settleAmount`, `turnOver` และ `status` ส่วน `get-bet-detail-url` คืนลิงก์ดูรายละเอียดตานั้น ใช้ได้ทั้ง Seamless และ Transfer

### ดูค่าบริการได้ที่ไหน

ดูอัตราค่าบริการล่าสุดที่ https://neoapihub.com/rate ส่วนคำถามเรื่องบัญชีหรือการเปิดใช้งาน ติดต่อ Neo Support ทาง https://t.me/neosuperapi

---
Source: https://neoapihub.com/blog/seamless-vs-transfer
