Khớp thanh toán và chênh lệch số tiền

Mục này mô tả quy tắc dịch vụ dùng để khớp giao dịch on-chain đến với hóa đơn đã phát hành, điều gì xảy ra khi số tiền khác biệt và người bán có thể làm gì trong trường hợp đó.

Trạng thái hóa đơn, thời hạn và các bước chuyển trạng thái được mô tả trong Vòng đời hóa đơn.

Quy tắc khớp số tiền

Khi tạo hóa đơn, dịch vụ quy đổi số tiền pháp định sang tiền mã hóa và khóa các số tiền thu được cho hóa đơn. Chúng trở thành định danh của khoản thanh toán: người mua thấy chúng trên biểu mẫu thanh toán, và dịch vụ tìm on-chain giao dịch có đúng số tiền đó.

Số tiền thanh toán phải khớp chính xác với số tiền hóa đơn. Không có dung sai. Số tiền cần trả được lập với 2 chữ số thập phân cho stablecoin USDT và USDC và 8 chữ số thập phân cho các tiền mã hóa khác, và khoản thanh toán đến được so sánh với nó một cách chính xác. Bất kỳ sai lệch nào — thanh toán thiếu hay thanh toán thừa, dù nhỏ đến đâu — đều có nghĩa là không có khớp tự động.

Ví dụ. Một hóa đơn 100.00 USD được phát hành với số tiền đã khóa là 100.12 USDT.

Số tiền thanh toán đến	Kết quả
100.12 USDT	Hóa đơn tự động chuyển sang Đã thanh toán (Paid)
100.11 USDT	Không khớp tự động
100.50 USDT	Không khớp tự động

Nếu nhiều hóa đơn cùng một số tiền pháp định được phát hành đến một địa chỉ cùng lúc, dịch vụ gán cho mỗi hóa đơn một số tiền mã hóa hơi khác nhau. Tính duy nhất được kiểm tra trên tất cả hóa đơn chưa thanh toán của bạn trên ví đó, nên một địa chỉ có thể yên tâm dùng trong nhiều dự án của bạn — các số tiền sẽ không va chạm.

Nguyên nhân chênh lệch phổ biến nhất là người mua tự làm tròn số tiền, hoặc phí mạng bị trừ khi rút từ sàn giao dịch. Hãy nhắc người mua chuyển đúng số tiền hiển thị trên biểu mẫu thanh toán.

Điều gì xảy ra khi chênh lệch số tiền

Dịch vụ ghi nhận tiền đã đến nhưng không làm gì với hóa đơn:

• Hóa đơn không đổi trạng thái. Nó vẫn chưa thanh toán cho đến thời hạn thanh toán. Người mua vẫn có thể đóng nó bằng đúng số tiền khi cửa sổ tìm kiếm còn mở.
• Không gửi webhook. Thông báo đến Webhook URL chỉ phát đi vào thời điểm hóa đơn chuyển sang Đã thanh toán.
• Không theo dõi thanh toán một phần. Dịch vụ không nhận diện thanh toán thiếu và không giữ số còn phải trả trên hóa đơn.
• Các khoản thanh toán không được cộng dồn. Nếu sau lần thanh toán thiếu, người mua gửi giao dịch thứ hai cho phần còn thiếu, hai khoản thanh toán không được cộng lại. Cả hai vẫn là những khoản thanh toán chưa khớp riêng lẻ.
• Thanh toán thừa không được hoàn tự động. Tiền đi thẳng vào ví của bạn; việc hoàn phần chênh lệch cho người mua xử lý bên ngoài dịch vụ.

Trong dịch vụ không có trạng thái trung gian như Thanh toán một phần hay Thanh toán thừa.

Người bán biết về vấn đề bằng cách nào

Nếu thông báo được bật trong cài đặt dự án, người bán nhận email và tin nhắn bot Telegram về mọi khoản thanh toán đến — dù nó có khớp với hóa đơn hay khô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.

Quy tắc này chỉ hoạt động trong cửa sổ tìm kiếm. Dịch vụ chỉ theo dõi ví khi còn ít nhất một hóa đơn đang trong quá trình tìm kiếm. Nếu người mua thanh toán khi không có hóa đơn nào như vậy, khoản thanh toán hoàn toàn không vào hệ thống — không có thông báo, và không có cách khớp thủ công.

Bạn cũng có thể tìm các khoản thanh toán chưa khớp bằng chương trình. Phương thức payments/list trả về các khoản thanh toán trên tất cả ví của bạn, và khoản thanh toán chưa khớp với hóa đơn không có khối invoice trong phản hồi. Đây là những ứng viên cho khớp thủ công: so sánh số tiền và thời gian với hóa đơn dự kiến rồi gọi invoices/bindPayment.

Khớp thanh toán thủ công

Nếu bạn chắc chắn khoản thanh toán nào ứng với hóa đơn nào, hãy khớp chúng thủ công — trong bảng điều khiển trên trang hóa đơn hoặc trong danh sách thanh toán, hay qua API bằng phương thức invoices/bindPayment.

Điều kiện khớp

Chỉ có thể khớp khi tất cả các điều kiện cùng thỏa mãn:

1. Hóa đơn đang Chưa thanh toán hoặc Hết hạn. Hóa đơn đã hủy và đã thanh toán không thể khớp.
2. Khoản thanh toán chưa khớp với hóa đơn khác. Một khoản thanh toán chỉ có thể gắn với một hóa đơn.
3. Khoản thanh toán đến ví tham gia vào hóa đơn này.
4. Khoản thanh toán nằm trong cửa sổ thanh toán khả dụng — 24 giờ trước và 24 giờ sau khi tạo hóa đơn.

Cửa sổ này rộng hơn hiệu lực của hóa đơn, mở ra hai khả năng: bạn có thể khớp khoản thanh toán với hóa đơn đã hết hạn, và có thể khớp hóa đơn với khoản thanh toán đến trước khi hóa đơn được tạo. Khả năng thứ hai hữu ích khi người mua tự gửi tiền và hóa đơn được phát hành sau khi tiền đã đến.

Điều gì xảy ra sau khi khớp

• Hóa đơn chuyển sang Đã thanh toán — hệt như khi khớp tự động.
• Webhook luôn được gửi. Thông báo phát đi ở mỗi lần chuyển sang Đã thanh toán, bất kể khớp bằng cách nào.
• Số tiền hóa đơn bằng USD được tính lại từ khoản thanh toán thực tế. Trường amountFiatUSD bị ghi đè bằng số tiền thực nhận, theo tỷ giá tại thời điểm khớp. Số tiền gốc trong amountFiat không thay đổi.
• Phí được tính lại từ số tiền thực tế. Phí thu theo mức phí của dự án trên số tiền bạn đã nhận.