# Thông tin chung

> Đặc tả kỹ thuật để tích hợp xử lý thanh toán và rút tiền tiền điện tử với 2328.io.

Chào mừng bạn đến với tài liệu API của 2328.io. Tài liệu tham chiếu này mô tả cách tích hợp xử lý thanh toán và rút tiền điện tử vào ứng dụng của bạn.

## Bắt đầu

Để bắt đầu tích hợp:

1. Tạo tài khoản merchant và project tại [2328.io](https://2328.io)
2. Lấy **project UUID** và **API key** từ phần cài đặt project
3. Tạo riêng một **Payout API key** nếu bạn dự định sử dụng tính năng rút tiền
4. Đọc phần [Authentication](/docs/authentication) để tìm hiểu cách ký yêu cầu
5. Thực hiện cuộc gọi [Create Payment](/docs/payments) đầu tiên

## Base URL

Tất cả yêu cầu API trong môi trường production đều sử dụng base URL sau:

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

> **WARNING:** Tất cả yêu cầu phải được thực hiện qua **HTTPS**. Các yêu cầu không sử dụng HTTPS sẽ bị chặn.

## Bạn có thể làm gì

Với 2328.io API bạn có thể:

- **Nhận thanh toán bằng tiền điện tử** — tạo phiên thanh toán và chuyển hướng khách hàng đến trang checkout được hosted hoặc Telegram MiniApp
- **Rút tiền** — gửi rút tiền theo chương trình từ số dư merchant đến bất kỳ địa chỉ blockchain nào
- **Kiểm tra số dư** — xem số dư tài khoản merchant theo từng tiền tệ, giá trị tương đương USD và số tiền bị khóa do AML
- **Sử dụng ví tĩnh** — tạo địa chỉ nạp tiền vĩnh viễn gắn với một người dùng hoặc đơn hàng
- **Lấy tỷ giá** — lấy tỷ giá theo thời gian thực cho các cặp tiền pháp định và tiền điện tử
- **Nhận webhook** — được thông báo ngay lập tức khi trạng thái thanh toán thay đổi
## Giới hạn tần suất

API cho phép tối đa **10 yêu cầu mỗi giây cho mỗi project**. Các yêu cầu vượt quá giới hạn sẽ nhận phản hồi HTTP `429 Too Many Requests` — hãy chờ một chút (back off) và thử lại.

## Chọn mẫu tích hợp phù hợp

| Yêu cầu | Mẫu đề xuất | Tại sao |
|-------------|---------------------|-----|
| Để khách hàng chọn cách thanh toán | Thanh toán được lưu trữ | Tạo một khoản thanh toán và chuyển hướng tới `result.url`; 2328.io hiện đang trình bày các hướng dẫn có sẵn. |
| Giữ khách hàng bên trong trang thanh toán của bạn | Hóa đơn địa chỉ trực tiếp **H2H** | Gửi `to_currency` và `network` khi tạo khoản thanh toán; hiển thị `address`, `payer_amount` và `qr` được trả về. |
| Thu đúng `25 USDT` hoặc `0.001 BTC` | Hóa đơn định giá bằng tiền điện tử | Đặt tiền điện tử vào `currency` và số thập phân chính xác vào `amount`. |
| Cung cấp cho mỗi người dùng một địa chỉ gửi tiền có thể tái sử dụng | Ví tĩnh | Địa chỉ là vĩnh viễn và có thể nhận nhiều khoản tiền gửi độc lập. |
| Chuẩn hóa tài sản đến thành một loại tiền cân đối | Tự động chuyển đổi | Cấu hình quy tắc dự án trong bảng điều khiển và sử dụng kết quả `convert` khi chuyển đổi hoàn tất. |
| Chuyển đổi số dư thương nhân hiện có | Chuyển đổi thủ công | Xem trước với `/v1/convert/price`, sau đó thực hiện với `/v1/convert`. |
| Gửi quỹ đến địa chỉ blockchain | Chi trả | Sử dụng khóa API Chi trả riêng, tính toán trước và đối chiếu trạng thái chi trả. |

> **INFO:** Thanh toán lưu trữ (hosted checkout) và một đối một (H2H) là hai hình thức trình bày của cùng một API Thanh toán. H2H không tạo ra thanh toán yếu hơn hay không có chữ ký: backend vẫn tạo hóa đơn, 2328.io vẫn sở hữu địa chỉ và trạng thái, và các webhook đã ký vẫn là thẩm quyền cho việc thanh toán.

## Các bất biến tích hợp

Những quy tắc này áp dụng cho mọi tích hợp sản xuất:

- **Backend only** — giữ khóa API ngoài trình duyệt, ứng dụng di động, nhật ký, phân tích và các ảnh chụp màn hình hỗ trợ.
- **Decimal strings** — gửi và lưu trữ tiền dưới dạng chuỗi. Không bao giờ làm tròn tiền điện tử hoặc tỉ giá hối đoái bằng số thực dấu phẩy động nhị phân.
- **Immutable idempotency keys** — tạo `order_id` trước yêu cầu đầu tiên và lưu trữ toàn bộ yêu cầu cùng với nó. Một lần thử lại với cùng `order_id` có thể trả về đối tượng gốc thay vì áp dụng các trường đã thay đổi.
- **Webhook-first settlement** — chuyển hướng, polling của khách hàng, băm giao dịch do người dùng cung cấp và thời gian chờ HTTP không phải là bằng chứng thanh toán.
- **Verify, deduplicate, then mutate** — xác minh HMAC, yêu cầu ghi nhận idempotency một cách nguyên tử, cập nhật đơn hàng/số dư một lần, và trả lại HTTP 200 nhanh chóng.
- **Reconciliation** — định kỳ truy vấn trạng thái thanh toán, ví tĩnh và chi trả để webhook bị mất không thể dẫn đến bất đồng vĩnh viễn.
- **Dynamic availability** — xác thực các cặp tiền tệ/mạng với `/v1/directions`; một tài sản được hỗ trợ vẫn có thể tạm thời bị vô hiệu hóa một hướng nạp hoặc rút.
- **Explicit status policy** — quyết định cách sản phẩm của bạn xử lý thanh toán một phần, thanh toán quá mức, hết hạn, khóa AML, dự phòng chuyển đổi và timeout đầu nguồn không rõ ràng trước khi ra mắt.

## Dữ liệu được khuyến nghị lưu trữ

Đối với các khoản thanh toán, lưu ít nhất `uuid`, `order_id`, thân yêu cầu gốc, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, `payment_status` gần nhất, `txid`, `payment_amount`, `merchant_amount`, khối tùy chọn `convert` và payload webhook đã xác minh thô.

Đối với ví tĩnh, giữ ví `uuid`, địa chỉ, loại tiền, mạng lưới, tham chiếu khách hàng/tài khoản, trạng thái và URL callback riêng biệt với các hồ sơ nạp tiền. Mỗi khoản nạp cần có giao dịch riêng `uuid`, `txid`, trạng thái, số tiền nhận được, số tiền của thương nhân và kết quả chuyển đổi.