Thanh toán và rút tiền/Ví tĩnh

Ví tĩnh

Các địa chỉ nạp tiền vĩnh viễn gắn với một đơn hàng hoặc người dùng cụ thể, hoàn hảo cho các thanh toán định kỳ và dài hạn.

Xem dưới dạng Markdown·llms.txt

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

POST/v1/static-wallet

Tham số yêu cầu

Field	Type	Required	Description
`currency`	string	yes	Tiền điện tử (USDT, BTC, ETH, v.v.)
`network`	string	yes	Mã mạng
`order_id`	string	yes	ID đơn hàng / người dùng của bạn (tối đa 255 ký tự)
`label`	string	no	Nhãn ví (tối đa 255 ký tự)
`url_callback`	string	yes	URL nhận thông báo webhook
`invite_code`	string	no	Mã người giới thiệu

Ví dụ yêu cầu

JSON

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

JSON

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

POST/v1/static-wallet/info

Tham số yêu cầu

Field	Type	Required	Description
`uuid`	string	yes*	UUID ví tĩnh
`address`	string	yes*	Địa chỉ ví blockchain

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

Ví dụ phản hồi

JSON

{
  "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í

POST/v1/static-wallet/list

Tham số yêu cầu

Field	Type	Required	Description
`status`	string	no	Lọc theo trạng thái (`active`, `inactive`)
`currency`	string	no	Lọc theo đồng tiền
`network`	string	no	Lọc theo mạng
`order_id`	string	no	Lọc theo order_id
`page`	int	no	Số trang (mặc định: 1)
`per_page`	int	no	Số mục mỗi trang (mặc định: 20, tối đa: 100)

Ví dụ phản hồi

JSON

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

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

Yêu cầu

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

JSON

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

Ví dụ phản hồi

JSON

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

POST/v1/static-wallet/transactions

Tham số yêu cầu

Field	Type	Required	Description
`uuid`	string	yes	UUID ví tĩnh
`date_from`	date	no	Ngày bắt đầu (YYYY-MM-DD)
`date_to`	date	no	Ngày kết thúc (YYYY-MM-DD)
`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)

Ví dụ phản hồi

JSON

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

Định dạng webhook cho ví tĩnh khác với webhook thanh toán thông thường. Đáng chú ý, webhook ví tĩnh có trường merchant_amount mà bạn nên dùng để ghi có.

Payload webhook

JSON

{
  "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",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Webhook ví tĩnh không bao gồm url hoặc expires_at (vì địa chỉ là vĩnh viễn, không phải phiên). Chúng có bao gồm exchange_rate và created_at.

Tham chiếu trường

Field	Type	Description
`uuid`	string	UUID giao dịch (hóa đơn) cho khoản nạp này
`order_id`	string	`order_id` của ví tĩnh của bạn
`amount`	decimal (8 dp)	Số crypto đã nhận
`currency`	string	Crypto đã nhận (khớp với `currency` của ví)
`amount_usd`	decimal (8 dp)	Giá trị USD tại thời điểm nhận
`exchange_rate`	decimal	Tỷ giá Crypto / USD đã sử dụng
`payer_currency`	string	Giống `currency` đối với ví tĩnh
`payer_amount`	decimal (8 dp)	Giống `amount` đối với ví tĩnh
`network`	string	Mạng blockchain
`address`	string	Địa chỉ ví tĩnh
`payment_status`	string	Luôn là `paid` đối với ví tĩnh
`txid`	string	Hash giao dịch blockchain
`payment_amount`	decimal (8 dp)	Giống `amount`
`merchant_amount`	decimal (18 dp)	Số tiền sau khi trừ phí — dùng giá trị này để ghi có
`created_at`	string (ISO 8601)	Thời điểm khoản nạp được nhận
`sign`	string (hex)	Chữ ký HMAC-SHA256 của payload

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