Tạo thanh toán crypto và nhận redirectUrl
Cách tạo thanh toán crypto và nhận redirectUrl trong một lệnh gọi API: POST /api/v1/payment, header x-api-key, giá theo đơn vị tiền của bạn (mặc định USD) và chuyển hướng thanh toán.
Tạo thanh toán và nhận redirectUrl là một yêu cầu trong Host-to-Host API v1 của Qvard. Hướng dẫn này trình bày các trường của yêu cầu, phản hồi và cách chuyển khách hàng tới trang thanh toán an toàn.
Các trường của yêu cầu
Gửi POST tới /api/v1/payment với header x-api-key. id là mã giao dịch của bạn, price là số tiền theo đơn vị tiền của trường currency (ISO-4217, mặc định USD), currency là mã ISO-4217 tùy chọn như INR, RUB hoặc EUR, còn paymentSystemId là tùy chọn. Giữ id duy nhất cho mỗi đơn hàng để khớp phản hồi với hồ sơ của bạn. Đơn vị tiền không được hỗ trợ bị từ chối với 422 unsupported_currency, số chữ số thập phân vượt quy định của đơn vị tiền đó với 422 invalid_amount_precision, và đơn vị tiền chưa có tỷ giá với 422 rate_unavailable.
Đọc phản hồi
Phản hồi gồm id thanh toán và redirectUrl, trỏ tới trang hosted tại https://my.qvard.com/pay/ kèm id thanh toán. Lưu cả hai giá trị cùng đơn hàng trước khi chuyển hướng khách hàng.
Chuyển hướng khách hàng
Chuyển khách hàng tới redirectUrl bằng một chuyển hướng HTTP thông thường hoặc một liên kết trên website của bạn. Trên trang hosted, khách hàng chọn tài sản và mạng và thấy số tiền chính xác theo tỷ giá cố định.
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
}Lỗi và thử lại
Nếu yêu cầu thất bại, hãy kiểm tra hồ sơ trước khi gửi lại để một đơn hàng không tạo hai thanh toán. Ghi lại nội dung phản hồi cho bộ phận hỗ trợ và chỉ thử lại khi đã xác nhận không có thanh toán nào cho đơn hàng đó.
Những lỗi thường gặp
Không đặt x-api-key trong mã front-end, không coi chuyển hướng là xác nhận thanh toán và không gửi giá bằng đơn vị tiền khác với trường currency. Trạng thái cuối luôn đến qua webhook.
Một đơn hàng online, từng bước
Khi người mua nhấn thanh toán, máy chủ của bạn tạo thanh toán với mã đơn hàng và tổng giỏ hàng, rồi chuyển người mua tới redirectUrl. Khi webhook báo đã thanh toán, bạn đánh dấu đơn hàng là đã thanh toán.
FAQ
Tôi có bắt buộc phải gửi paymentSystemId không?
Không, trường này là tùy chọn. Hãy gửi khi bạn muốn một phương thức thanh toán cụ thể; nếu không, trang hosted sẽ hiện các lựa chọn có sẵn.
Tôi có thể dùng lại redirectUrl cho đơn hàng khác không?
Không. Mỗi thanh toán có redirectUrl riêng. Hãy tạo thanh toán mới cho mỗi đơn hàng.
Khách hàng có thể thanh toán qua liên kết tôi gửi qua email không?
Có. redirectUrl là trang HTTPS thông thường nên hoạt động trong email hoặc chat. Liên kết thanh toán không cần code từ dashboard nằm trong lộ trình.
Khách hàng trả bao nhiêu?
Trang hosted hiển thị đúng số tiền của tài sản đã chọn theo tỷ giá cố định trong thời hạn hóa đơn.
