API thanh toán crypto: thanh toán server-to-server
Hướng dẫn API thanh toán crypto: tạo thanh toán từ máy chủ bằng POST /api/v1/payment, nhận redirectUrl và trạng thái cuối qua webhook. Có ví dụ mã.
API thanh toán crypto cho phép backend của bạn tạo thanh toán, chuyển khách hàng sang trang thanh toán hosted và biết trạng thái cuối mà không cần tự xây hạ tầng blockchain. Qvard cung cấp luồng này dưới dạng Host-to-Host API v1.
API thanh toán crypto làm gì
API thanh toán crypto biến một sự kiện thanh toán trên máy chủ của bạn thành một yêu cầu thanh toán. Backend của bạn gửi mã đơn hàng và giá tính bằng đơn vị tiền của bạn (mặc định USD), còn cổng thanh toán trả về redirectUrl tới trang thanh toán hosted, nơi khách hàng chọn tài sản và mạng. Địa chỉ, tỷ giá và giám sát blockchain nằm phía cổng thanh toán.
Yêu cầu v1 của Qvard trông như thế nào
Lệnh gọi là một POST tới /api/v1/payment kèm header x-api-key. Trường id mang mã giao dịch của riêng bạn, còn price là số tiền theo đơn vị tiền của trường currency tùy chọn (ISO-4217, mặc định USD). paymentSystemId là tùy chọn, dùng để chọn phương thức thanh toán khi cần. Phản hồi trả về id thanh toán và redirectUrl.
x-api-key: sk_live_…
{
"id": "order_1024",
"price": 12499.00,
"currency": "INR",
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}Server-to-server, không phải trình duyệt tới cổng
Yêu cầu được gửi từ backend của bạn nên khóa API không bao giờ tới trình duyệt. Khách hàng chỉ thấy trang thanh toán hosted sau khi bạn chuyển hướng họ. Bạn cũng kiểm tra từng đơn hàng ở phía mình trước khi tạo thanh toán.
Trạng thái cuối đến qua webhook
Phản hồi API xác nhận thanh toán đã được tạo, chứ không phải đã được trả. Trạng thái cuối được gửi tới URL webhook của bạn bằng POST với các trường id và status, nên logic đơn hàng nên phản ứng theo webhook.
Cần kiểm tra gì trước khi chạy thật
Lưu id thanh toán cùng đơn hàng, làm cho bộ xử lý webhook an toàn khi chạy lặp lại, và kiểm thử toàn bộ luồng bằng hóa đơn demo. Dùng cùng một id cho mọi yêu cầu của một đơn hàng để có thể đối soát các lần gọi lặp lại.
Phí và mạng
Tỷ lệ xử lý cơ bản là 1% mỗi thanh toán và giảm riêng cho từng merchant xuống 0,1% khi khối lượng tăng. Phí mạng được thanh toán riêng trên mạng khách hàng chọn. Trang bảng giá có điều khoản hiện hành.
FAQ
API thanh toán crypto có giống liên kết thanh toán không?
Không. Liên kết thanh toán là trang chia sẻ cho bán hàng thủ công. API tạo thanh toán từ hệ thống của bạn và trả về redirectUrl do mã của bạn kiểm soát.
Tôi có cần chạy node blockchain không?
Không. Qvard giám sát các mạng và gửi trạng thái cuối qua webhook, nên bạn không cần tự chạy node hay scanner.
Giá được tính bằng đơn vị tiền nào?
Trường price tính theo đơn vị tiền của trường currency (ISO-4217, ví dụ INR hoặc EUR); không có trường này thì là USD. Khách hàng thanh toán bằng tài sản và mạng họ chọn trên trang thanh toán.
Tôi có thể thử trước khi chạy thật không?
Có. Tạo hóa đơn demo và xem đúng trang thanh toán hosted mà khách hàng sẽ thấy.
