Thông tin chung

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
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 để tìm hiểu cách ký yêu cầu
5. Thực hiện cuộc gọi Create Payment đầ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

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

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.