Payment API

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

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

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"

Thanh toán được lưu trữ, H2H, và số lượng tiền điện tử chính xác

Cùng một điểm cuối hỗ trợ ba kiểu hóa đơn khác nhau. Chọn một cách có chủ đích; không trộn lẫn ngữ nghĩa số lượng của chúng.

Thanh toán được lưu trữ với lựa chọn người thanh toán

Gửi amount, currency, order_id, và url_callback, nhưng bỏ qua to_currency và network. Phản hồi chứa result.url; address, qr, và đôi khi các trường người thanh toán vẫn null cho đến khi người thanh toán chọn hướng trên trang được lưu trữ.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Hóa đơn H2H trực tiếp

Gửi cả to_currency và network. 2328.io tạo hóa đơn blockchain trong quá trình gọi API, vì vậy một phản hồi thành công có thể được hiển thị trong trang thanh toán của bạn mà không cần chuyển hướng khách hàng.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Hiển thị các giá trị này chính xác như được trả về:

• payer_amount và payer_currency — hướng dẫn thanh toán;
• network và address — điểm đến duy nhất cho hóa đơn này;
• qr — một URI dữ liệu cho cùng địa chỉ;
• expires_at — hạn chót của hóa đơn;
• url — một phương án dự phòng hữu ích được lưu trữ khi trang thanh toán tùy chỉnh không thể hoàn tất.

Hóa đơn cho một số tiền crypto chính xác

Đặt tiền điện tử vào currency khi chính hóa đơn được định giá bằng crypto:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Giá trị crypto yêu cầu được giữ nguyên trong payer_currency / payer_amount. Dịch vụ cũng có thể duy trì giá trị USD nội bộ cho mục kế toán và trường tỷ giá; không thay thế hướng dẫn crypto chính xác đó bằng giá trị này. Giữ nguyên chuỗi số thập phân trả về, bao gồm cả số thập phân cuối.

Đối với một loại tiền điện tử chỉ có một mạng được hỗ trợ, mạng có thể được chọn tự động. Vẫn nên cung cấp network một cách rõ ràng để có sự tích hợp xác định. Đối với các tài sản đa mạng như stablecoin, luôn luôn gửi nó.

Tính đơn nhất và các lần thử lại

order_id áp dụng cho dự án thương gia đã xác thực và đóng vai trò như khóa đơn nhất khi tạo. Nếu một khoản thanh toán đã tồn tại, API sẽ trả về phiên đó cùng với state: 0.

Thuật toán tạo được khuyến nghị:

1. Chèn nỗ lực thanh toán cục bộ của bạn và order_id duy nhất vào một giao dịch cơ sở dữ liệu.
2. Gửi yêu cầu API đã ký.
3. Lưu lại uuid được trả về và phản hồi đầy đủ.
4. Nếu kết quả HTTP bị mất, thử lại yêu cầu giống hệt hoặc truy vấn /v1/payment/info bằng order_id.
5. Không bao giờ tạo đơn hàng cục bộ thứ hai chỉ vì yêu cầu từ phía trên bị hết thời gian.

Các trường hợp thanh toán đặc biệt

URL trả về của trình duyệt chỉ để điều hướng. Khách hàng có thể mở nó mà không cần thanh toán, đóng nó sau khi thanh toán, hoặc phát lại sau. Chỉ trạng thái API/webhook đã được xác minh mới có thể xử lý đơn hàng của thương nhân.

Thông tin thanh toán

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"

Danh sách thanh toán

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"