Môi trường
PayerScan API hiện vận hành trong môi trường Production cho các giao dịch thực.
Base URL
Tất cả request API phải gửi đến:
https://api.payerscan.com
Các Endpoint khả dụng
| Phương thức | Endpoint | Mô tả |
|---|---|---|
POST | /payment/crypto | Tạo hóa đơn thanh toán mới. |
GET | /invoice/:trans_id | Kiểm tra trạng thái và chi tiết hóa đơn. |
Yêu cầu HTTPS
Tất cả request API phải gửi qua HTTPS.
Các URL callback (callback_url, completed_url, expired_url) phải sử dụng HTTPS trong production. Khi PayerScan gửi webhook cho hóa đơn đã hoàn thành hoặc hết hạn, hệ thống sẽ kiểm tra callback URL trước khi gửi — URL dùng HTTP hoặc trỏ đến địa chỉ IP nội bộ/riêng tư sẽ bị từ chối, và webhook sẽ không được gửi.
Bảo vệ SSRF
Khi gửi webhook, PayerScan kiểm tra callback URL để ngăn chặn tấn công Server-Side Request Forgery (SSRF). Webhook sẽ không được gửi đến:
- Localhost —
127.0.0.0/8,localhost,::1 - Mạng nội bộ —
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 - Link-local —
169.254.0.0/16 - Domain trỏ đến IP nội bộ — DNS resolution được kiểm tra
Luôn sử dụng URL HTTPS công khai cho callback_url để đảm bảo webhook được gửi thành công.
CORS
API hỗ trợ Cross-Origin Resource Sharing (CORS). Tuy nhiên, bạn không bao giờ nên gọi API trực tiếp từ mã client-side — luôn gọi thông qua backend server. Xem Xác thực để biết chi tiết.
Định dạng Response
Response thành công
{
"status": "success",
"data": { ... }
}
Response lỗi
{
"status": "error",
"message": "Mô tả lỗi",
"error_code": "ERROR_CODE"
}
Xem chi tiết rate limiting tại Rate Limits. Mã lỗi xác thực tại Xác thực.