API thanh toán crypto cho nhà phát triển

API Qvard cố ý nhỏ gọn. Ba route bao phủ toàn bộ vòng đời: tạo thanh toán, kiểm tra một phương thức thanh toán có sẵn sàng hay không và gửi payout. Tài liệu này mô tả từng route đúng như hôm nay chúng hoạt động, kèm các lỗi bạn sẽ gặp, và nói thẳng về những gì API không có, để bạn không xây dựng trên một tính năng không tồn tại.

API bao gồm những gì

API công khai nằm ở https://api.qvard.com/api/v1 và có ba route:

POST /payment: tạo thanh toán và nhận địa chỉ trang thanh toán được lưu trữ.
GET /method/:id/info: kiểm tra phương thức thanh toán của dự án đã sẵn sàng nhận thanh toán chưa.
POST /payout: gửi payout tới một địa chỉ crypto.

Kết quả đến qua webhook: Qvard gọi một URL bạn đã lưu trong dự án khi thanh toán hoàn tất. Không có route nào để đọc lại một thanh toán theo id, nên webhook là cách bạn biết kết quả. Mọi thứ còn lại, như bảng điều khiển, số dư và cài đặt, được thực hiện trên giao diện web.

Xác thực

Mỗi yêu cầu mang khóa API của dự án trong header x-api-key. Không có token cần làm mới và không có OAuth. Khóa thiếu hoặc không xác định trả về 401 với thông báo error.wrong.api.key.

Hãy coi khóa như mật khẩu: giữ nó trên máy chủ, trong biến môi trường hoặc trình quản lý bí mật, và không bao giờ để trong mã front-end hay kho mã công khai. Chính khóa này được Qvard gửi lại cho bạn trong header x-api-key của webhook, nên rò rỉ ảnh hưởng cả hai chiều.

Tạo thanh toán

POST /api/v1/payment nhận một nội dung JSON:

id (chuỗi, bắt buộc): mã định danh của riêng bạn cho đơn hàng hoặc hóa đơn. Nó được trả lại trong webhook.
price (số, bắt buộc): số tiền bằng đô la Mỹ. Khách trả khoản tương đương bằng tài sản và mạng họ chọn.
paymentSystemId (số, tùy chọn): một phương thức thanh toán của dự án. Nếu truyền, trang thanh toán mở ra với tài sản và mạng đó đã chọn sẵn.

Phản hồi là 201 với hai trường: id, mã định danh thanh toán phía Qvard, và redirectUrl, địa chỉ trang thanh toán được lưu trữ, dạng https://my.qvard.com/pay/<id>. Chuyển hướng khách tới đó, hoặc đặt liên kết vào email.

Lệnh gọi idempotent theo id và phương thức thanh toán: gửi lại cùng id cho cùng phương thức trả về khoản thanh toán hiện có thay vì tạo khoản thứ hai, nên thử lại sau khi quá thời gian là an toàn. Lưu ý mã trạng thái là 201, không phải 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Lỗi

Lỗi có một dạng chung, nội dung JSON với message:

400: nội dung không qua kiểm tra hợp lệ. Thông báo là Error validation và đối tượng errors ánh xạ từng trường với vấn đề đầu tiên của nó, ví dụ id bị thiếu hoặc price không phải số. Số tiền dưới mức tối thiểu của phương thức đã chọn cũng bị từ chối theo cách đó.
401: header x-api-key bị thiếu hoặc không xác định (error.wrong.api.key).
404: ở route thông tin phương thức, id phương thức không tồn tại (error.notfound).

Hãy ghi lại toàn bộ nội dung phản hồi khi gặp 4xx; thông báo nêu tên trường cần sửa. Đừng thử lại 400 hoặc 401 khi chưa thay đổi gì, nhưng hãy thử lại khi quá thời gian hoặc 5xx, việc này an toàn nhờ tính idempotent ở trên.

Trạng thái thanh toán và webhook

Một thanh toán có một trong bốn trạng thái: wait (đã tạo, chưa trả), partial (số tiền đến ít hơn đủ), completed (đủ số tiền) và rejected.

Webhook được gửi khi thanh toán hoàn tất: Qvard thực hiện POST tới callback URL của dự án với một JSON nhỏ chứa id của bạn và status, đồng thời đặt khóa API của bạn vào header x-api-key. Endpoint của bạn phải trả lời đúng HTTP 200; mọi trạng thái khác, quá thời gian hay chuyển hướng đều tính là gửi thất bại và được thử lại, tổng cộng năm lần trong khoảng sáu phút. Header là header xác thực, không phải chữ ký mật mã, nên hãy so sánh với khóa của bạn theo thời gian không đổi. Làm trình xử lý idempotent, vì một lần gửi có thể đến hai lần.

Chi tiết kèm mã nằm trong cách bảo mật webhook thanh toán crypto, và toàn bộ luồng được trình bày trong cách nhận thanh toán crypto trên website.

Kiểm tra phương thức đã sẵn sàng

GET /api/v1/method/:id/info nhận id số của một phương thức thanh toán trong dự án và trả lời 200 với ba trường:

server: thông tin về trạng thái của phương thức.
isReady: true khi phương thức sẵn sàng nhận thanh toán.
isActive: true khi phương thức không ngoại tuyến, dù vẫn đang đồng bộ với mạng.

Dùng nó trước khi đưa ra một tài sản và mạng cụ thể ở bước thanh toán, ví dụ để ẩn một phương thức tạm thời không khả dụng. Id không xác định trả về 404. Đây là bước tùy chọn: nếu bạn để khách chọn trên trang thanh toán thì không cần đến nó.

Payout

POST /api/v1/payout gửi tiền từ số dư của bạn tới một địa chỉ crypto. JSON gồm:

id (chuỗi, bắt buộc): mã định danh payout của riêng bạn, dùng để loại trùng khi thử lại, nên gửi cùng id hai lần không trả hai lần.
price (số, bắt buộc): số tiền bằng crypto của phương thức, không phải đô la.
methodId (số, bắt buộc): phương thức thanh toán của dự án.
address (chuỗi, bắt buộc): địa chỉ đích.
comment (chuỗi, tùy chọn).

Lệnh gọi thành công trả về 201. Payout di chuyển tiền thật, nên hãy thử với số tiền nhỏ, kiểm tra kỹ địa chỉ và mạng của phương thức, và xác nhận với Qvard rằng payout qua API đã được bật cho dự án của bạn. Rút về tài khoản ngân hàng bằng tiền pháp định không khả dụng; payout đi tới địa chỉ crypto và chỉ tốn phí mạng.

API chưa có gì

Để bạn khỏi tìm kiếm:

Không có endpoint lấy thanh toán theo id, nên hãy dựa vào webhook và bản ghi của bạn.
Không có chữ ký webhook; xác thực là header x-api-key.
Không có sandbox: môi trường thử riêng nằm trong lộ trình, nên hãy dùng số tiền thật nhỏ. Hóa đơn demo cho xem trang thanh toán mà không cần trả tiền.
Không có URL quay lại sau khi thanh toán: khách tự quay lại trang của bạn.
Không có plugin dựng sẵn cho các nền tảng cửa hàng, và liên kết thanh toán đang được phát triển.

Về định dạng và ví dụ, xem tài liệu cho nhà phát triển. Về điều kiện thương mại, xem trang bảng giá.

FAQ

Tôi đặt giá bằng tiền tệ nào?

Bằng đô la Mỹ. Khách trả khoản tương đương bằng tài sản và mạng họ chọn trên trang thanh toán, theo tỷ giá cố định trong một giờ. Payout là ngoại lệ: số tiền tính bằng crypto của phương thức.

Thử lại việc tạo thanh toán có an toàn không?

Có. Gửi cùng id cho cùng phương thức thanh toán trả về khoản thanh toán hiện có, nên thử lại sau khi quá thời gian không tạo bản trùng.

Làm sao biết kết quả của một thanh toán?

Từ webhook, được gửi khi thanh toán hoàn tất. Không có route đọc thanh toán theo id, nên hãy lưu id bạn gửi và đối chiếu khi webhook đến.

Có sandbox không?

Chưa có. Môi trường thử riêng đang được lên kế hoạch. Hiện tại hãy dùng số tiền thật nhỏ và một hóa đơn demo để xem trang thanh toán.