Vòng đời hóa đơn

Hóa đơn đi từ lúc tạo đến khi được đóng hoặc hết hạn. Mục này mô tả các trạng thái hóa đơn có thể ở, cách nó chuyển giữa các trạng thái và người bán có thể làm gì ở mỗi bước.

Trạng thái hóa đơn

Trạng thái	Giá trị API	Mô tả	Có trong tìm kiếm thanh toán
Chưa thanh toán	unpaid	Hóa đơn đã phát hành, thời hạn thanh toán chưa qua, chưa nhận được khoản thanh toán	Có
Đã thanh toán	paid	Đã tìm thấy khoản thanh toán và khớp với hóa đơn	Không
Hết hạn	expired	Thời hạn thanh toán đã qua, chưa nhận được khoản thanh toán	Có, thêm một giờ sau khi hết hạn
Đã hủy	canceled	Người bán hủy hóa đơn theo cách thủ công hoặc qua API	Không

Chuyển trạng thái

• Tạo hóa đơn. Hóa đơn ngay lập tức nhận trạng thái Chưa thanh toán.
• Chưa thanh toán → Đã thanh toán. Một khoản thanh toán đúng bằng số tiền hóa đơn đã đến, hoặc người bán khớp khoản thanh toán thủ công.
• Chưa thanh toán → Hết hạn. Thời hạn thanh toán đã qua mà không nhận được khoản thanh toán.
• Chưa thanh toán → Đã hủy. Người bán đã hủy hóa đơn.
• Hết hạn → Đã thanh toán. Khoản thanh toán đến trong vòng một giờ sau khi hết hạn và được tìm thấy tự động, hoặc người bán khớp thủ công.
• Đã hủy. Trạng thái cuối cùng; không có đường quay lại.

Hóa đơn ở trạng thái Đã thanh toán cũng không đổi trạng thái nữa — không thể thanh toán lại hay hủy nó.

Thời hạn thanh toán

Thời hạn đặt khi tạo hóa đơn và nằm trong khoảng từ 30 phút đến 12 giờ. Giá trị cho phép: 30 phút, 1 giờ, 3 giờ, 6 giờ, 12 giờ.

Trước thời hạn, người mua thấy biểu mẫu thanh toán và có thể thanh toán hóa đơn. Sau khi hết hạn, hóa đơn chuyển sang Hết hạn và biểu mẫu thanh toán không còn cho thanh toán nữa.

Cả hai thái cực đều có giá của nó. Thời hạn ngắn rủi ro trên các mạng chậm — người mua có thể không kịp. Thời hạn dài nới rộng khoảng cách giữa tỷ giá lúc tạo hóa đơn và tỷ giá lúc thanh toán.

Cửa sổ tìm kiếm thanh toán

Việc tìm kiếm thanh toán tiếp tục thêm một giờ sau thời hạn thanh toán — để tính đến các mạng chậm, nơi giao dịch có thể được xác nhận sau khi hóa đơn đã chính thức hết hạn. Suốt thời gian này người mua thấy hóa đơn hết hạn, nhưng khi khoản thanh toán đúng số tiền đến, hóa đơn tự động chuyển sang Đã thanh toán cùng đầy đủ thông báo.

Từ đó có quy tắc cho người tích hợp: đừng từ chối thông báo thanh toán vì thời hạn đã qua — phép kiểm tra đó cắt mất một phần các khoản thanh toán thật.

Hủy hóa đơn

Bạn có thể hủy hóa đơn nếu nó chứa sai sót. Việc hủy đòi hỏi hai điều kiện:

• Hóa đơn chưa được thanh toán — tức là đang ở trạng thái Chưa thanh toán
• Chưa ai mở trang thanh toán của hóa đơn; bộ đếm lượt xem bằng không

Điều kiện thứ hai bảo vệ khỏi việc hủy hóa đơn mà người mua đã thấy và có thể đã bắt đầu thanh toán.

Việc hủy không thể đảo ngược. Hóa đơn đã hủy bị loại khỏi tìm kiếm thanh toán, và không thể khớp khoản thanh toán với nó ngay cả thủ công. Nếu khả năng thanh toán còn cao, hãy chờ thời hạn qua đi thay vì hủy — hóa đơn hết hạn vẫn có thể được đóng bằng một khoản thanh toán.

Điều gì khóa khi tạo và điều gì tính lại khi thanh toán

Khi tạo hóa đơn, dịch vụ quy đổi số tiền pháp định sang tiền mã hóa theo tỷ giá hiện tại và khóa các số tiền thu được cho hóa đơn. Đây là những số tiền người mua thấy, và cũng là những gì dịch vụ tìm on-chain. Tỷ giá không còn ảnh hưởng đến chúng: dù bao nhiêu thời gian trôi qua, người mua trả đúng số tiền đã khóa.

Tại thời điểm thanh toán, các số tiền kế toán được tính lại:

Trường	Điều gì xảy ra
amountFiat	Số tiền gốc của hóa đơn bằng tiền pháp định. Không bao giờ thay đổi
amountFiatUSD	Bị ghi đè bằng số tiền thực nhận, quy đổi sang USD theo tỷ giá tại thời điểm thanh toán
commissionFiatUSD	Tính lại từ giá trị amountFiatUSD mới theo mức phí của dự án

Do biến động tỷ giá, các giá trị này có thể khác giá trị ban đầu ngay cả khi khoản thanh toán chính xác. Để đối chiếu với đơn hàng trong cửa hàng của bạn, hãy dùng amountFiat — số tiền duy nhất giữ nguyên.

Thông báo trong vòng đời hóa đơn

Thông báo được cấu hình theo từng dự án. Hóa đơn có hai loại:

• Khoản thanh toán đến (Incoming payment). Dịch vụ gửi đến email và Telegram khi phát hiện bất kỳ giao dịch đến nào trên ví của bạn, dù nó có khớp với hóa đơn hay không.
• Hóa đơn đã thanh toán (Invoice paid). Dịch vụ gửi đến email, Telegram và Webhook URL ngay khi hóa đơn chuyển sang Đã thanh toán — cả khi khớp tự động lẫn khớp thủ công.

Từ đây có quy tắc chẩn đoán đơn giản: nếu thông báo khoản thanh toán đến đã tới nhưng không có thông báo hóa đơn đã thanh toán theo sau, khoản thanh toán không khớp do chênh lệch số tiền và cần xử lý thủ công.

Đưa người mua quay lại trang cửa hàng

Trong cài đặt dự án, bạn có thể đặt hai URL mà người mua quay về từ trang thanh toán:

• URL thành công (Successful URL) — tự động chuyển hướng sau khi hóa đơn được thanh toán
• URL không thành công (Unsuccessful URL) — tự động chuyển hướng khi mở hóa đơn hết hạn hoặc đã hủy

Mỗi URL bật riêng. Nếu URL không được đặt, người mua ở lại trang thanh toán và thấy trạng thái hóa đơn.

Tham số uid — định danh hóa đơn dành cho người mua — được nối vào URL: https://example.com/order/success?uid=AFhygKX21ecd. Cửa hàng dùng nó để tìm đơn hàng và cho người mua xem trang của riêng mình.

Việc rơi vào các URL này không xác nhận thanh toán — người mua có thể tự mở liên kết. Hãy giao hàng dựa trên webhook hoặc sau khi kiểm tra trạng thái hóa đơn qua API.