API thanh toán crypto xây cho tất toán trực tiếp

Tạo hóa đơn

Một POST. Số tiền viết theo cách con người viết và được nhân theo số thập phân của chính tài sản ở phía máy chủ, nên bạn không bao giờ phải tự quy đổi sang đơn vị cơ sở.

curl -X POST https://api.unheld.io/api/v1/invoices \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "11155111",
    "assetType": "native",
    "amountDecimal": "0.05",
    "expiresInSeconds": 900,
    "metadata": { "orderId": "A-1043" }
  }'

Phản hồi

{
  "id": "e2b0…",
  "status": "CREATED",
  "receiveAddress": "0x…",
  "expectedAmount": "50000000000000000",
  "minConfirmations": 3,
  "expiresAt": "2026-08-10T14:15:00.000Z",
  "instructions": {
    "chainId": "11155111",
    "to": "0x…",
    "amount": "50000000000000000",
    "assetType": "native"
  }
}

receiveAddress được dẫn xuất từ ví của bạn và khóa vào hóa đơn này. expectedAmount tính bằng đơn vị cơ sở. minConfirmations là ngưỡng của chính chuỗi, không phải thiết lập chúng tôi tự nghĩ ra.

Xác thực và phạm vi

Khóa là bearer token, tạo trong bảng điều khiển và chỉ hiển thị một lần. Mỗi khóa mang một danh sách phạm vi rõ ràng và request bị từ chối nếu khóa thiếu phạm vi cho tuyến đó.

Các phạm vi hiện có

• invoices:write
• invoices:read
• webhooks:write
• webhooks:read
• balances:read
• customers:write
• customers:read
• subscriptions:write
• subscriptions:read

Hãy cấp tập hẹp nhất mà vẫn chạy được. Khóa chỉ tạo hóa đơn không đọc được khách hàng của bạn, và một khóa đọc bị lộ cũng không di chuyển được gì — vì không gì trong API này làm được điều đó.

Webhook bạn có thể xác minh

Mọi lần gửi đều được ký. Chữ ký là HMAC-SHA256 của dấu thời gian và phần thân thô nối bằng một dấu chấm, dùng secret webhook của bạn, gửi dưới dạng chuỗi hex.

Xác minh một lần gửi

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["x-timestamp"]}.${rawBody}`)
  .digest("hex");

crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(req.headers["x-signature"])
);

So sánh digest trong thời gian hằng số, từ chối dấu thời gian nằm ngoài cửa sổ dung sai, và coi X-Request-Id là khóa idempotency: các lần thử lại dùng lại đúng giá trị đó, nên cùng một sự kiện đến hai lần là bình thường và không được xử lý hai lần.

Sự kiện hóa đơn

Một khoản thanh toán đi qua các trạng thái chứ không nhảy thẳng từ chưa trả sang đã trả, và mỗi lần chuyển là một webhook. Trả thiếu và trả dư là sự kiện riêng, không phải lỗi.

Câu hỏi của nhà phát triển

Ví dụ đã được đối chiếu với API đang chạy vào 21 tháng 9, 2026.