Chuyển tới nội dung chính

Câu hỏi thường gặp

Tích hợp & API​

Tôi cần gì để bắt đầu?​

Bạn cần API Key (từ trang quản lý, mục Store) và callback URL (endpoint POST công khai) để nhận webhook. Sau đó gọi POST https://api.payerscan.com/payment/crypto để tạo hóa đơn và chuyển hướng khách hàng đến url_payment. Xem Bắt đầu nhanh.

Base URL của API là gì?​

Base URL chính thức của API là https://api.payerscan.com. Tất cả request API phải sử dụng HTTPS.

Tôi có thể tạo hóa đơn mà không gửi callback_url không?​

Có. Nhưng bạn sẽ không nhận được webhook completed/expired. Bạn chỉ có thể kiểm tra trạng thái qua GET https://api.payerscan.com/invoice/:trans_id (polling).

Giới hạn tốc độ là bao nhiêu?​

  • POST /payment/crypto: 5 request/giây, tối đa 60 request/phút (theo API Key, fallback theo IP).
  • GET /invoice/:trans_id: 20 request/giây, tối đa 200 request/phút.

Vượt giới hạn → HTTP 429, kèm retry_after_seconds trong body. Xem Giới hạn tốc độ.

request_id là gì và idempotency hoạt động như thế nào?​

request_id là trường tùy chọn bạn gửi kèm khi tạo hóa đơn — thường là mã đơn hàng nội bộ (ví dụ: "ORDER-12345") hoặc một chuỗi ngẫu nhiên duy nhất mà chỉ backend của bạn và PayerScan biết.

Tại sao nên dùng? Nếu server của bạn bị crash hoặc timeout giữa chừng, bạn có thể retry an toàn với cùng request_id. API đảm bảo không tạo hóa đơn trùng — thay vào đó trả về hóa đơn đã tồn tại với "idempotent": true trong response.

Đối chiếu webhook với đơn hàng: request_id cũng được gửi kèm trong webhook callback (completed / expired), giúp backend của bạn xác định thanh toán đó thuộc về hóa đơn (giao dịch, đơn hàng) nào.

Không dùng request_id: Mỗi lần POST đều tạo hóa đơn mới, dù body giống hệt. Bạn có nguy cơ tạo nhiều hóa đơn trùng cho cùng một đơn hàng nếu retry.

amount dùng đơn vị tiền tệ nào?​

amount luôn tính bằng USD (Đô la Mỹ). Hệ thống tự động quy đổi sang số lượng tiền mã hóa tương ứng theo tỷ giá thời gian thực tại thời điểm thanh toán.

Lưu ý: Tỷ giá được lấy từ một trong bốn nguồn — Binance, Coinbase, CoinGecko hoặc CoinMarketCap — do khách hàng lựa chọn trên trang thanh toán.

Giới hạn amount là bao nhiêu?​

amount của hóa đơn (USD) phải là số dương và không vượt quá 1,000,000. Có thể gửi dạng string hoặc number.

completed_url và expired_url là gì?​

Đây là các URL chuyển hướng tùy chọn cho trình duyệt của khách hàng:

  • completed_url — khách hàng được chuyển hướng đến đây sau khi thanh toán thành công.
  • expired_url — khách hàng được chuyển hướng đến đây nếu hóa đơn hết hạn.

Chúng chỉ dùng cho chuyển hướng frontend, không thay thế webhook callback_url.

Thanh toán & Xác nhận​

Điều gì xảy ra nếu khách hàng gửi sai số tiền?​

Hệ thống chỉ xác nhận khi giao dịch blockchain khớp chính xác số tiền (token_amount), đúng địa chỉ, và trong khung thời gian cho phép. Gửi thiếu hoặc thừa sẽ không được coi là thanh toán thành công; hóa đơn có thể hết hạn hoặc khách hàng cần tạo hóa đơn mới.

Xác nhận mất bao lâu?​

Thường từ vài giây đến vài phút, tùy thuộc vào mạng và phương thức:

  • EVM (BSC, ETH, Polygon, ...): 3-15 giây
  • Tron (TRC20): 3-5 giây
  • Nạp qua sàn (Binance, OKX, Bybit, ...): Gần như tức thì
  • Binance Pay: Gần như tức thì

Khi tìm thấy giao dịch khớp, hệ thống cập nhật hóa đơn và gửi webhook ngay lập tức.

Khi nào hóa đơn hết hạn?​

Mặc định theo cấu hình Store (ví dụ: 15 phút). Khi tạo hóa đơn, response bao gồm expires_in_minutes. Sau thời gian đó, hóa đơn chuyển sang expired và (nếu có callback_url) bạn nhận được webhook với status: "expired".

Các trạng thái hóa đơn có thể có?​

Trạng tháiMô tả
waitingHóa đơn đã tạo, đang chờ khách hàng thanh toán.
completedThanh toán đã được xác nhận trên blockchain.
expiredHóa đơn hết hạn mà chưa nhận được thanh toán.

Tôi có thể hủy hóa đơn không?​

Không. Hóa đơn không thể hủy qua API. Chúng sẽ tự động hết hạn sau thời gian đã cấu hình (expires_in_minutes). Nếu khách hàng không thanh toán, chỉ cần để hóa đơn hết hạn.

Webhook​

Sự kiện nào kích hoạt webhook?​

Hệ thống gửi webhook cho hai sự kiện:

  • completed — khi thanh toán khớp được xác nhận trên blockchain.
  • expired — khi hóa đơn hết hạn mà chưa nhận được thanh toán.

Webhook timeout là bao lâu?​

10 giây. Nếu server merchant không trả về HTTP 2xx trong thời gian này, request được coi là thất bại và sẽ được retry.

Tôi có cần trả về body cụ thể không?​

Không. Chỉ cần trả về HTTP 2xx (ví dụ: 200 OK). Body tùy bạn (có thể để trống hoặc "OK").

Webhook có retry khi thất bại không?​

Có. Khi bạn trả về lỗi hoặc timeout, hệ thống retry theo lịch: 10s → 30s → 30s → 60s → 60s (tối đa 5 lần). Đảm bảo endpoint xử lý idempotent (gọi với cùng trans_id nhiều lần vẫn an toàn).

Lỗi & Xử lý sự cố​

NO_PAYMENT_METHOD nghĩa là gì?​

Store của bạn chưa cấu hình phương thức thanh toán. Vào quản lý Store → thêm ít nhất một địa chỉ ví hoặc kết nối sàn giao dịch trước khi tạo hóa đơn.

INSUFFICIENT_BALANCE nghĩa là gì?​

Số dư tài khoản không đủ để trả phí dịch vụ cho hóa đơn đó. Phí được tính dựa trên amount (USD) của hóa đơn với tỷ lệ phí áp dụng cho tài khoản (có thể được giảm giá). Nạp thêm số dư trên Dashboard và thử lại. Kiểm tra trường details trong response lỗi để biết chính xác số tiền thiếu.

Lưu ý: Trong thời gian dùng thử miễn phí (7 ngày đầu), INSUFFICIENT_BALANCE sẽ không xuất hiện — mọi phí dịch vụ được miễn.

INVALID_MERCHANT_ID là gì?​

merchant_id trong body không khớp với Store của API Key đang dùng. Kiểm tra merchant_id trong quản lý Store và gửi đúng trong request.

Tra cứu hóa đơn trả về 404?​

Nguyên nhân có thể: (1) sai trans_id, (2) hóa đơn thuộc Store khác (API Key khác), hoặc (3) không tồn tại. Kiểm tra trans_id và API Key.

Phương thức thanh toán​

Hệ thống hỗ trợ những phương thức thanh toán nào?​

PayerScan hỗ trợ nhiều phương thức thanh toán:

  • Ví on-chain: EVM (BSC, Ethereum, Polygon, Base, Arbitrum), Tron (TRC20), Solana
  • Sàn giao dịch: Binance Pay, Binance Deposit, OKX, Bybit, MEXC, Gate.io, Bitget, Upbit, Bitkub

Xem Mạng & Token để biết danh sách đầy đủ.

Binance Pay hoạt động như thế nào?​

Binance Pay cho phép khách hàng thanh toán qua Binance — không phí gas, xác nhận tức thì. Merchant cần cấu hình Binance API Key và Secret Key trong trang quản lý.

Cần cấu hình gì cho sàn giao dịch?​

  1. Tạo API Key trên sàn (bật quyền cần thiết)
  2. Trong trang quản lý → cấu hình API Key, Secret Key, và ID nền tảng cho Store

Chi tiết: Thiết lập Binance Pay.

Bảo mật​

API Key có nên gửi từ frontend không?​

Không. API Key chỉ nên sử dụng trên server (backend của merchant). Gọi POST /payment/crypto và GET /invoice từ server; frontend chỉ nhận url_payment để chuyển hướng, không cần API Key.

Callback URL có cần xác thực không?​

Khuyến nghị: xác minh merchant_id hoặc trans_id với dữ liệu nội bộ để đảm bảo request hợp lệ. Sử dụng HTTPS để ngăn nghe lén.

Tôi có thể có nhiều Store không?​

Có. Mỗi Store có API Key, merchant_id, phương thức thanh toán, và cài đặt riêng. Bạn có thể tạo nhiều Store để tách biệt các doanh nghiệp hoặc môi trường khác nhau (ví dụ: production vs. testing).