Ví tĩnh

Ví tĩnh là các địa chỉ vĩnh viễn để nhận thanh toán tiền điện tử. Chúng được liên kết với một order_id cụ thể và là duy nhất theo tổ hợp project_id + order_id + currency + network.

Sử dụng ví tĩnh cho:

• Các khoản nạp định kỳ từ cùng một người dùng
• Địa chỉ thanh toán dài hạn hiển thị trên hồ sơ người dùng
• Các luồng nạp tiền có khối lượng lớn khi bạn muốn có địa chỉ ổn định cho mỗi người dùng

Tạo ví tĩnh

Tham số yêu cầu

Ví dụ yêu cầu

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Ví dụ phản hồi

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Thông tin ví

Lấy thông tin ví tĩnh theo uuid hoặc address.

Tham số yêu cầu

Ví dụ phản hồi

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

• total_received — tổng tất cả các khoản nạp ví này đã nhận, theo currency.
• transactions_count — số lần nạp đã nhận tới thời điểm hiện tại.
• qr — data URI QR mã hóa Base64 của địa chỉ nạp tiền (luôn có sẵn cho ví tĩnh, vì địa chỉ được gán ngay khi tạo).

Danh sách ví

Tham số yêu cầu

Ví dụ phản hồi

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Bật / tắt ví

Bật/tắt việc một ví tĩnh có chấp nhận thanh toán mới hay không.

Yêu cầu

Cả hai endpoint đều nhận một tham số duy nhất:

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Ví dụ phản hồi

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

Đối với enable, status là "active" và message là "Static wallet enabled successfully".

Giao dịch của ví

Lấy danh sách tất cả các khoản nạp đã nhận của một ví tĩnh.

Tham số yêu cầu

Ví dụ phản hồi

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

• fee_amount — phí nền tảng được trừ từ khoản nạp này, theo currency.
• net_amount — số tiền được ghi có vào số dư merchant sau khi trừ phí.

Webhook ví tĩnh

Khi một thanh toán được nhận trên ví tĩnh, hệ thống sẽ gửi webhook đến url_callback.

Payload webhook

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Tham chiếu trường

Best practices

• order_id duy nhất — Sử dụng order_id duy nhất cho mỗi người dùng hoặc đơn hàng
• Idempotency — Kiểm tra txid trước khi xử lý để tránh ghi có trùng lặp
• Xác minh chữ ký — LUÔN xác minh chữ ký sign trước khi ghi có tiền
• Sử dụng merchant_amount — Ghi có cho người dùng dựa trên merchant_amount, không phải payment_amount

Vòng đời và tính không thay đổi

Ví tĩnh là một định danh gửi tiền có thể tái sử dụng, không phải là hóa đơn. Nó không có số tiền dự kiến và không có hạn sử dụng. Một địa chỉ có thể tạo ra bất kỳ số lượng giao dịch gửi tiền nào trong suốt vòng đời của nó.

Việc tạo lập là không thay đổi đối với cùng một dự án thương nhân, order_id, currency, và network: ví hiện có sẽ được trả về. Giữ bộ ba đó ổn định và lưu giữ ví được trả về uuid; không sử dụng một order_id mới mỗi lần cùng một khách hàng mở màn hình gửi tiền.

Tính không thay đổi của giao dịch gửi tiền khác với tính không thay đổi của ví:

• order_id xác định ánh xạ ví/khách hàng có thể tái sử dụng;
• ví uuid xác định bản ghi ví vĩnh viễn;
• webhook uuid xác định một giao dịch nạp tiền được phát hiện;
• txid xác định chuyển khoản trên chuỗi và là khóa loại trùng chính để ghi có.

Sử dụng ràng buộc duy nhất trong cơ sở dữ liệu cho nhận dạng chuỗi/mạng/txid đã xử lý và xác nhận nó trong cùng giao dịch ghi có vào số dư nội bộ của khách hàng.

Kích hoạt và vô hiệu hóa ngữ nghĩa

Vô hiệu hóa ví ngăn ứng dụng xử lý nó như một mục tiêu nạp tiền đang hoạt động; điều này không xóa địa chỉ hoặc lịch sử của nó và không thể ngăn chặn chuyển khoản trên blockchain đã được người dùng gửi.

Việc bật lại giữ nguyên danh tính ví và địa chỉ. Không tạo ví thay thế chỉ để thay đổi nhãn; nhãn không phải là định danh thanh toán.

Các trường hợp đặc biệt của ví tĩnh

Mô hình đối chiếu

Chạy một công việc định kỳ mà duyệt qua /v1/static-wallet/transactions, cập nhật hoặc chèn các khoản tiền gửi theo txid, và so sánh merchant_amount, trạng thái, và kết quả chuyển đổi tùy chọn của chúng với sổ cái nội bộ của bạn. Việc gửi webhook nên làm cho việc đối chiếu nhanh chóng, nhưng đối chiếu phải đảm bảo đầy đủ.