# Payment API

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

Payment API ให้คุณสร้างเซสชันการชำระเงิน นำลูกค้าไปยังหน้า checkout ที่โฮสต์ไว้ และติดตามสถานะการชำระเงินได้

## สร้างการชำระเงิน

<TwoCol>

สร้างเซสชันการชำระเงินและคืน URL สำหรับให้ลูกค้าชำระเงิน

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `amount` | decimal | yes | จำนวนเงินที่ชำระในสกุลเงินนั้น เช่น `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | yes | สกุลเงิน fiat (USD, EUR, RUB, …) หรือคริปโตเคอร์เรนซี (USDT, TRX, BTC, …) | <EnumValues name="currency" values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" /> |
| `order_id` | string | yes | order ID ของคุณ เช่น `ORDER-12345` (สูงสุด 128 ตัวอักษร) | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | no | คริปโตเคอร์เรนซีที่เลือกไว้ล่วงหน้า | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | no\* | รหัสเครือข่าย (ต้องระบุเมื่อตั้งค่า `to_currency` หรือ `currency` เป็นคริปโตเคอร์เรนซี) | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | no | URL redirect หลังการชำระเงิน เช่น `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | no | ทางเลือกแทน `url_return` | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | no | URL สำหรับการแจ้งเตือน Webhook เช่น `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | no | โค้ดผู้แนะนำ | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `fee_split` | decimal | no | สัดส่วนค่าธรรมเนียมผู้ค้าที่ส่งต่อให้ผู้ชำระ 0–100 (%) 0 = ผู้ค้าจ่ายเต็ม, 100 = ผู้ชำระจ่ายเต็ม ค่านี้จะลบล้างการตั้งค่าระดับโปรเจกต์ **ตัวอย่าง: `30`** (ผู้ชำระรับภาระ 30% ของค่าธรรมเนียม) | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `price_markup` | decimal | no | บวกเพิ่มหรือส่วนลดบนยอดใบแจ้งหนี้ −99 ถึง 100 (%) ค่านี้จะลบล้างการตั้งค่าระดับโปรเจกต์ **ตัวอย่าง: `5`** (+5%) หรือ `-10` (ส่วนลด 10%) | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `description` | string | no | คำอธิบายใบแจ้งหนี้ (สูงสุด 200 ตัวอักษร) แสดงให้ผู้ชำระเห็นบนหน้าชำระเงิน **ตัวอย่าง: `Premium plan — Order #12345`** | <InputValue name="description" placeholder="Premium plan — Order #12345" /> |
| `ttl_seconds` | int | no | อายุของใบแจ้งหนี้เป็นวินาที ตั้งแต่ `300` (5 นาที) ถึง `86400` (24 ชั่วโมง) เมื่อพ้นเวลานี้ใบแจ้งหนี้จะหมดอายุและชำระไม่ได้อีก ค่าเริ่มต้น: `3600` (1 ชั่วโมง) **ตัวอย่าง: `3600`** | <InputValue name="ttl_seconds" type="integer" placeholder="3600" /> |

### การตอบกลับ

```json
{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- นำลูกค้าไปยัง `result.url` เพื่อดำเนินการชำระเงินให้เสร็จสมบูรณ์
- `tg_deeplink` — ดีพลิงก์บอท Telegram สำหรับชำระเงินผ่าน Telegram MiniApp
- `qr` — QR code ที่เข้ารหัส base64 (data URI) ของที่อยู่ฝากเงิน จะปรากฏเมื่อมีการกำหนดที่อยู่แล้ว (เมื่อตั้งค่า `network` ร่วมกับ `to_currency` หรือเมื่อ `currency` เป็นคริปโตเคอร์เรนซี); ในกรณีอื่นจะเป็น `null`
- `txid`, `payment_amount` — เป็น `null` จนกว่าลูกค้าจะชำระเงิน จะถูกเติมค่าเมื่อระบบตรวจพบธุรกรรมบนเชน รับฟัง Webhook `payment_status: paid` เพื่อรู้เวลา
- `exchange_rate` — เป็น `null` หากยังใช้การแปลงสกุลไม่ได้ (เช่น ยังไม่ล็อกอัตรา fiat → crypto) จะถูกเติมค่าเมื่อเลือกสกุลเงินผู้ชำระแล้ว

<TwoColAside>

<Credentials />

<TryIt endpoint="POST /v1/payment">
  <Param name="amount" type="decimal" required />
  <Param name="currency" type="enum" required values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="order_id" type="string" required />
  <Param name="to_currency" type="enum" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="network" type="enum" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" />
  <Param name="url_return" type="string" />
  <Param name="url_success" type="string" />
  <Param name="url_callback" type="string" />
  <Param name="invite_code" type="string" />
  <Param name="fee_split" type="decimal" />
  <Param name="price_markup" type="decimal" />
  <Param name="description" type="string" />
  <Param name="ttl_seconds" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>

## ข้อมูลการชำระเงิน

<TwoCol>

ดูสถานะการชำระเงินปัจจุบันด้วย `uuid` หรือ `order_id`

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `uuid` | string | yes\* | UUID ของการชำระเงิน (จาก `result.uuid` ตอนสร้าง) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | yes\* | order ID ของคุณ | <InputValue name="order_id" placeholder="ORDER-12345" /> |

> **INFO:** ต้องระบุ `uuid` หรือ `order_id` อย่างน้อยหนึ่งค่า

<TwoColAside>

<TryIt endpoint="POST /v1/payment/info">
  <Param name="uuid" type="string" />
  <Param name="order_id" type="string" />
</TryIt>

</TwoColAside>

</TwoCol>

## รายการการชำระเงิน

<TwoCol>

ดูรายการการชำระเงินทั้งหมดพร้อมการกรองและแบ่งหน้า

### พารามิเตอร์ของคำขอ

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `status` | string | no | กรองตามสถานะการชำระเงิน (ดู [References](/docs/references)) | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | no | วันที่เริ่มต้น (YYYY-MM-DD) เช่น `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | no | วันที่สิ้นสุด (YYYY-MM-DD) เช่น `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | no | หมายเลขหน้า ค่าเริ่มต้น `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | no | จำนวนรายการต่อหน้า ค่าเริ่มต้น `15` สูงสุด `5000` | <InputValue name="per_page" type="integer" example="15" /> |

<TwoColAside>

<TryIt endpoint="POST /v1/payment/list">
  <Param name="status" type="enum" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" />
  <Param name="date_from" type="string" />
  <Param name="date_to" type="string" />
  <Param name="page" type="integer" />
  <Param name="per_page" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>