Tích hợp một API thanh toán crypto theo một hình dạng dễ đoán bất kể nhà cung cấp: bạn tạo hóa đơn, chuyển hướng hoặc nhúng một trang thanh toán, nhận các webhook bất đồng bộ khi khoản thanh toán tiến triển, xác minh chúng và đối soát với bản ghi của chính bạn. Phần khó không phải là kịch bản thuận lợi — mà là các trường hợp biên.
Luồng cốt lõi
Hầu hết các cổng cung cấp một REST API với cùng vòng đời. Bạn gọi nó phía máy chủ (đừng bao giờ để lộ khóa API trong trình duyệt), và bạn coi webhook — chứ không phải chuyển hướng trình duyệt — là nguồn sự thật về việc một đơn hàng đã được trả hay chưa.
Hãy thiết kế máy trạng thái đơn hàng của bạn trước: đang chờ → trả thiếu/đã trả → đã xác nhận → hoàn tất, với các nhánh rõ ràng cho hết hạn và trả thừa. Đấu nối việc đó ngay từ đầu ngăn được các điều kiện rối rắm gây ra hoàn tất đơn hàng hai lần.
- Tạo một hóa đơn với số tiền, đơn vị tiền tệ, ID đơn hàng và một URL webhook.
- Hiển thị trang thanh toán được lưu trữ sẵn hoặc tự hiển thị địa chỉ và số tiền.
- Nhận webhook cho mỗi thay đổi trạng thái và xác minh chữ ký của chúng.
- Xác nhận khoản thanh toán đạt số lần xác nhận cần thiết trước khi hoàn tất.
- Đối soát webhook với giao dịch on-chain và đơn hàng của bạn.
Tạo một hóa đơn
Một hóa đơn gắn một số tiền cụ thể với một đơn hàng cụ thể trong một khoảng thời gian giới hạn. Gửi ID đơn hàng của bạn như metadata để webhook có thể được khớp lại không cần đoán, và lưu ID hóa đơn mà cổng trả về.
Báo giá hết hạn — cổng khóa một tỷ giá trong vài phút. Lưu lại thời điểm hết hạn và trạng thái của hóa đơn để giao diện của bạn có thể hiển thị đồng hồ đếm ngược và để một khoản thanh toán muộn được xử lý như một trường hợp đối soát, chứ không phải một đơn hàng mất.
Webhook là nguồn sự thật
Chuyển hướng trình duyệt sau khi thanh toán là một tiện lợi, không phải một đảm bảo — người dùng có thể đóng tab. Webhook mà máy chủ của bạn nhận được là thứ bạn hành động dựa trên đó. Hãy xác minh mọi webhook: kiểm tra chữ ký (thường là một HMAC trên nội dung thô với khóa bí mật của bạn) trước khi tin tưởng bất kỳ trường nào.
Hãy làm cho việc xử lý webhook có tính lũy đẳng. Các cổng gửi lại nhiều lần, nên cùng một sự kiện 'đã trả' có thể đến hai lần; hãy khóa việc xử lý theo ID sự kiện hoặc hóa đơn và biến các lần gửi lặp thành không tác dụng. Trả về 2xx nhanh chóng và làm việc chậm một cách bất đồng bộ để cổng không hết thời gian chờ và gửi lại một cách không cần thiết.
Xác nhận và tính chung cuộc
Một khoản thanh toán có thể được thấy (trong mempool hoặc với không lần xác nhận) rất lâu trước khi nó chung cuộc. Hãy quyết định một ngưỡng xác nhận phù hợp với số tiền và chuỗi, và chỉ hoàn tất khi đã đạt. Với các khoản thanh toán stablecoin nhỏ trên chuỗi nhanh việc này diễn ra nhanh; với số tiền lớn, hãy chờ lâu hơn.
Phòng ngừa reorg và double-spend bằng cách tin tưởng trạng thái 'đã xác nhận' của cổng thay vì lần nhìn thấy đầu tiên của chính bạn, và bằng cách không giao hàng dựa trên một khoản thanh toán không lần xác nhận trừ khi bạn chấp nhận rủi ro.
Đối soát và các tình huống lỗi
Đối soát là công việc hằng ngày chứng minh rằng mọi đơn hàng 'đã trả' ứng với một giao dịch on-chain thật và ngược lại. Lưu mã băm giao dịch, số tiền nhận được và mạng trên mỗi đơn hàng để một chênh lệch là một truy vấn, chứ không phải một cuộc điều tra.
Hãy lên kế hoạch rõ ràng cho việc trả thiếu (người mua gửi quá ít), trả thừa (hoàn phần chênh lệch hoặc ghi có), gửi sai mạng và hóa đơn hết-hạn-rồi-được-trả. Đây không phải là các trường hợp biên hiếm gặp ở quy mô lớn — chúng là các sự kiện hằng tuần, và một hệ thống xử lý chúng lặng lẽ mới là ý nghĩa thực sự của 'sẵn sàng cho môi trường sản xuất'.
Câu hỏi thường gặp
Tôi nên tin chuyển hướng trình duyệt hay webhook?
Webhook. Chuyển hướng có thể mất nếu người dùng đóng tab, và nó có thể bị giả mạo. Hãy xác minh chữ ký của webhook phía máy chủ và coi nó là tín hiệu đáng tin cậy rằng một đơn hàng đã được trả.
Làm sao để một webhook không bị xử lý hai lần?
Hãy làm cho việc xử lý có tính lũy đẳng. Các cổng gửi lại nhiều lần, nên hãy khóa logic của bạn theo ID hóa đơn hoặc sự kiện và biến một lần lặp thành không tác dụng. Đừng bao giờ hoàn tất một đơn hàng hai lần vì cùng một sự kiện 'đã trả' lại đến.
Tôi nên chờ bao nhiêu lần xác nhận?
Tùy thuộc vào số tiền và chuỗi. Các khoản thanh toán stablecoin nhỏ trên mạng nhanh có thể được coi là chung cuộc gần như ngay lập tức; số tiền lớn hơn xứng đáng chờ nhiều hơn. Hãy dùng trạng thái 'đã xác nhận' của cổng thay vì lần nhìn thấy đầu tiên của chính bạn.
Điều gì xảy ra nếu khách hàng trả thiếu hoặc trả thừa?
Hãy xử lý cả hai một cách rõ ràng. Các cổng đánh dấu việc trả thiếu để bạn có thể yêu cầu phần chênh lệch hoặc hoàn tiền; với việc trả thừa bạn hoàn phần dư hoặc ghi có. Xây dựng các nhánh này ngay từ đầu là khác biệt giữa một bản demo và môi trường sản xuất.