Thanh toán và rút tiền/Payment API

Payment API

Tạo và quản lý các phiên thanh toán tiền điện tử với Payment API của 2328.io.

Payment API cho phép bạn tạo phiên thanh toán, chuyển hướng khách hàng đến trang checkout được hosted và theo dõi trạng thái thanh toán.

Tạo thanh toán

Tạo một phiên thanh toán và trả về URL để khách hàng thanh toán.

Tham số yêu cầu

Field	Type	Required	Description
`amount`	decimal	yes	Số tiền thanh toán theo đơn vị tiền tệ, ví dụ `100.00`
`currency`	string	yes	Tiền pháp định (USD, EUR, RUB, …) hoặc tiền điện tử (USDT, TRX, BTC, …)
`order_id`	string	yes	ID đơn hàng của bạn, ví dụ `ORDER-12345` (tối đa 128 ký tự)
`to_currency`	string	no	Tiền điện tử được chọn trước
`network`	string	no*	Mã mạng (bắt buộc nếu `to_currency` được đặt hoặc `currency` là tiền điện tử)
`url_return`	string	no	URL chuyển hướng sau khi thanh toán, ví dụ `https://your-site.com/return`
`url_success`	string	no	Phương án thay thế cho `url_return`
`url_callback`	string	no	URL nhận thông báo webhook, ví dụ `https://your-site.com/webhook`
`invite_code`	string	no	Mã người giới thiệu
`fee_split`	decimal	no	Tỷ lệ phí merchant chuyển sang cho người trả, 0–100 (%). 0 = merchant trả toàn bộ, 100 = người trả gánh toàn bộ. Ghi đè cài đặt cấp project. Ví dụ: `30` (người trả gánh 30% phí).
`price_markup`	decimal	no	Phụ phí hoặc chiết khấu trên số tiền hóa đơn, −99 đến 100 (%). Ghi đè cài đặt cấp project. Ví dụ: `5` (+5%) hoặc `-10` (giảm 10%).
`description`	string	no	Mô tả hóa đơn tùy chọn (tối đa 200 ký tự). Hiển thị cho người trả trên trang thanh toán. Ví dụ: `Premium plan — Order #12345`.
`ttl_seconds`	int	no	Thời gian sống của hóa đơn tính bằng giây, từ `300` (5 phút) đến `86400` (24 giờ). Sau khoảng thời gian này hóa đơn hết hạn và không thể thanh toán được nữa. Mặc định: `3600` (1 giờ). Ví dụ: `3600`.

Phản hồi

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..."
  }
}

Chuyển hướng khách hàng đến result.url để hoàn tất thanh toán.
tg_deeplink — deeplink Telegram bot để thanh toán qua Telegram MiniApp.
qr — QR code mã hóa Base64 (data URI) của địa chỉ nạp tiền. Có giá trị khi địa chỉ đã được gán (khi network được đặt cùng với to_currency, hoặc khi currency là tiền điện tử); ngược lại là null.
txid, payment_amount — null cho đến khi khách hàng trả tiền. Được điền vào sau khi giao dịch được phát hiện trên chuỗi. Lắng nghe webhook payment_status: paid để biết thời điểm.
exchange_rate — null nếu việc quy đổi chưa áp dụng được (ví dụ tỷ giá fiat → crypto chưa được chốt). Được điền vào khi đã chọn được tiền của người trả.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Thông tin thanh toán

Lấy trạng thái thanh toán hiện tại theo uuid hoặc order_id.

Tham số yêu cầu

Field	Type	Required	Description	Values
`uuid`	string	yes*	UUID của thanh toán (lấy từ `result.uuid` khi tạo)
`order_id`	string	yes*	ID đơn hàng của bạn

Phải cung cấp ít nhất một trong uuid hoặc order_id.

RequestPOST/v1/payment/info

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Danh sách thanh toán

Lấy danh sách tất cả thanh toán có hỗ trợ lọc và phân trang.

Tham số yêu cầu

Field	Type	Required	Description
`status`	string	no	Lọc theo trạng thái thanh toán (xem References)
`date_from`	date	no	Ngày bắt đầu (YYYY-MM-DD), ví dụ `2026-01-01`
`date_to`	date	no	Ngày kết thúc (YYYY-MM-DD), ví dụ `2026-01-31`
`page`	int	no	Số trang, mặc định `1`
`per_page`	int	no	Số mục mỗi trang, mặc định `15`, tối đa `5000`

RequestPOST/v1/payment/list

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.