# ข้อมูลทั่วไป

> ข้อกำหนดทางเทคนิคสำหรับการประมวลผลการชำระเงินด้วยคริปโตเคอร์เรนซีและการถอนเงินผ่าน 2328.io

ยินดีต้อนรับสู่เอกสารประกอบ API ของ 2328.io เอกสารอ้างอิงนี้อธิบายวิธีรวมการประมวลผลการชำระเงินด้วยคริปโตเคอร์เรนซีและการถอนเงินเข้ากับแอปพลิเคชันของคุณ

## เริ่มต้นใช้งาน

ขั้นตอนการเริ่มต้นรวม API:

1. สร้างบัญชีผู้ค้าและโปรเจกต์ที่ [2328.io](https://2328.io)
2. รับ **project UUID** และ **API key** จากการตั้งค่าโปรเจกต์
3. สร้าง **Payout API key** แยกต่างหากหากคุณวางแผนใช้งานการถอนเงิน
4. อ่านส่วน [Authentication](/docs/authentication) เพื่อเรียนรู้วิธีลงลายเซ็นคำขอ
5. เรียกใช้ [Create Payment](/docs/payments) เป็นครั้งแรก

## Base URL

คำขอ API ในระบบโปรดักชันทั้งหมดใช้ base URL ต่อไปนี้:

```
https://api.2328.io/api
```

> **WARNING:** คำขอทั้งหมดต้องส่งผ่าน **HTTPS** เท่านั้น คำขอที่ไม่ใช้ HTTPS จะถูกบล็อก

## สิ่งที่คุณทำได้

ด้วย 2328.io API คุณสามารถ:

- **รับการชำระเงินด้วยคริปโต** — สร้างเซสชันการชำระเงินและนำลูกค้าไปยังหน้า checkout ที่โฮสต์ไว้หรือ Telegram MiniApp
- **ถอนเงิน** — ส่งการถอนจากยอดคงเหลือของผู้ค้าไปยังที่อยู่บล็อกเชนใด ๆ ผ่านโปรแกรม
- **ตรวจสอบยอดคงเหลือ** — ดูยอดคงเหลือบัญชีผู้ค้าตามสกุลเงิน ค่าเทียบเท่า USD และจำนวนที่ถูกล็อกโดย AML
- **ใช้กระเป๋าเงินคงที่** — สร้างที่อยู่ฝากเงินถาวรที่ผูกกับผู้ใช้หรือคำสั่งซื้อ
- **ดึงอัตราแลกเปลี่ยน** — รับอัตราแลกเปลี่ยนแบบเรียลไทม์สำหรับคู่สกุลเงิน fiat และคริปโต
- **รับ Webhook** — รับการแจ้งเตือนทันทีเมื่อสถานะการชำระเงินเปลี่ยนแปลง
## ข้อจำกัดอัตราคำขอ

API อนุญาตสูงสุด **10 คำขอต่อวินาทีต่อโปรเจกต์** คำขอที่เกินขีดจำกัดจะได้รับการตอบกลับ HTTP `429 Too Many Requests` — ให้ถอยและลองใหม่

## เลือกแบบแผนการรวมที่เหมาะสม

| ข้อกำหนด | แบบแผนที่แนะนำ | เหตุผล |
|-------------|---------------------|-----|
| ให้ลูกค้าเลือกวิธีการชำระเงิน | การจ่ายเงินผ่านโฮสต์ | สร้างการชำระเงินและเปลี่ยนเส้นทางไปยัง `result.url`; 2328.io จะแสดงทิศทางที่มีอยู่ในปัจจุบัน |
| เก็บลูกค้าให้อยู่ภายในหน้าชำระเงินของคุณเอง | ออกใบแจ้งหนี้ **H2H** โดยตรง | ส่ง `to_currency` และ `network` เมื่อสร้างการชำระเงิน; แสดง `address`, `payer_amount` และ `qr` ที่กลับมา |
| เรียกเก็บเงินเท่ากับ `25 USDT` หรือ `0.001 BTC` | ใบแจ้งหนี้ที่ระบุเป็นสกุลเงินดิจิทัล | ใส่สกุลเงินดิจิทัลใน `currency` และจำนวนทศนิยมที่แน่นอนใน `amount` |
| ให้ผู้ใช้แต่ละคนมีที่อยู่ฝากซ้ำได้ | กระเป๋าสตางค์แบบคงที่ | ที่อยู่นี้เป็นถาวรและสามารถรับการฝากเงินหลายครั้งได้ |
| ปรับสินทรัพย์ที่เข้ามาให้อยู่ในสกุลเงินยอดเงินเดียว | แปลงอัตโนมัติ | กำหนดกฎของโครงการในแดชบอร์ดแล้วใช้ผลลัพธ์ของ `convert` เมื่อการแปลงเสร็จสิ้น |
| แลกเปลี่ยนยอดคงเหลือของผู้ขายที่มีอยู่ | แปลงด้วยตนเอง | พรีวิวด้วย `/v1/convert/price` จากนั้นดำเนินการด้วย `/v1/convert` |
| ส่งเงินไปยังที่อยู่บล็อกเชน | การจ่ายเงิน | ใช้คีย์ API การจ่ายเงินแยกต่างหาก คำนวณก่อน และปรับสถานะการจ่ายเงินให้ตรงกัน |

> **INFO:** การชำระเงินแบบโฮสต์เช็คเอาต์และ H2H เป็นสองรูปแบบของ API การชำระเงินเดียวกัน H2H ไม่ได้สร้างการชำระเงินที่อ่อนแอหรือไม่มีลายเซ็น: ระบบหลังบ้านยังคงสร้างใบแจ้งหนี้ 2328.io ยังคงเป็นเจ้าของที่อยู่และสถานะ และเว็บฮุกที่ลงลายเซ็นยังคงมีอำนาจในการชำระเงิน

## ตัวแปรการรวม

กฎเหล่านี้ใช้กับการรวมทุกผลิตภัณฑ์ในการผลิต:

- **Backend only** — อย่าเก็บคีย์ API ไว้ในเบราว์เซอร์ แอปพลิเคชันมือถือ บันทึก สถิติ หรือภาพหน้าจอการสนับสนุน
- **Decimal strings** — ส่งและเก็บเงินเป็นสตริง อย่าปัดเศษคริปโตเคอร์เรนซีหรืออัตราแลกเปลี่ยนด้วยการคำนวณทศนิยมแบบทวิภาค
- **Immutable idempotency keys** — สร้าง `order_id` ก่อนคำขอครั้งแรกและเก็บคำขอทั้งหมดด้วยมัน การลองใหม่ด้วย `order_id` เดิมสามารถส่งกลับวัตถุเดิมแทนที่จะปรับฟิลด์ที่เปลี่ยน
- **Webhook-first settlement** — การเปลี่ยนเส้นทาง การpollของไคลเอนต์ แฮชธุรกรรมที่ผู้ใช้ให้มา และเวลาหมด HTTP ไม่ใช่หลักฐานการชำระเงิน
- **Verify, deduplicate, then mutate** — ตรวจสอบ HMAC เรียกร้องบันทึกความเป็นเอกลักษณ์แบบอะตอม ปรับปรุงคำสั่งซื้อ/ยอดคงเหลือครั้งเดียว และส่งกลับ HTTP 200 อย่างรวดเร็ว
- **Reconciliation** — ตรวจสอบสถานะการชำระเงิน สถานะกระเป๋าสตางค์คงที่ และสถานะการจ่ายเงินเป็นระยะๆ เพื่อไม่ให้เว็บฮุกที่หายไปสร้างความไม่ตรงกันถาวร
- **Dynamic availability** — ตรวจสอบความถูกต้องของคู่สกุลเงิน/เครือข่ายกับ `/v1/directions`; สินทรัพย์ที่ได้รับการสนับสนุนยังสามารถมีทิศทางการฝากหรือถอนที่ถูกปิดใช้ชั่วคราวได้
- **Explicit status policy** — ตัดสินใจว่าผลิตภัณฑ์ของคุณจะจัดการกับการชำระเงินบางส่วน การจ่ายเกิน เวลาหมดอายุ การล็อก AML การสำรองการแปลง และการหมดเวลาในทางที่ไม่ชัดเจนจากระบบภายนอกอย่างไร ก่อนที่จะเปิดใช้งาน

## ข้อมูลที่แนะนำให้เก็บไว้

สำหรับการชำระเงิน เก็บไว้อย่างน้อย `uuid`, `order_id`, ตัวคำขอต้นฉบับ `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, ล่าสุด `payment_status`, `txid`, `payment_amount`, `merchant_amount`, บล็อกตัวเลือก `convert` และ payload ของ webhook ที่ตรวจสอบแล้วแบบดิบ

สำหรับกระเป๋าสตางค์แบบคงที่ ให้เก็บกระเป๋าสตางค์ `uuid` ที่อยู่ สกุลเงิน เครือข่าย การอ้างอิงลูกค้า/บัญชี สถานะ และ URL การเรียกกลับ แยกจากบันทึกการฝาก แต่ละการฝากต้องมีธุรกรรมของตัวเอง `uuid`, `txid`, สถานะ จำนวนที่ได้รับ จำนวนของร้านค้า และผลลัพธ์การแปลง