Frequently Asked Questions
Integration & API
What do I need to get started?
You need an API Key (from the management page, under Store) and a callback URL (a public POST endpoint) to receive webhooks. Then call POST https://api.payerscan.com/payment/crypto to create an invoice and redirect the customer to url_payment. See Quick Start.
What is the API Base URL?
The official API Base URL is https://api.payerscan.com. All API requests must use HTTPS.
Can I create an invoice without sending callback_url?
Yes. But you won't receive completed/expired webhooks. You can only check status via GET https://api.payerscan.com/invoice/:trans_id (polling).
What is the rate limit?
- POST /payment/crypto: 5 requests/second, max 60 requests/minute (per API Key, fallback to IP).
- GET /invoice/:trans_id: 20 requests/second, max 200 requests/minute.
Exceeding the limit → HTTP 429, with retry_after_seconds in the body. See Rate Limits.
What is request_id and how does idempotency work?
request_id is an optional field you include when creating an invoice — typically your internal order ID (e.g., "ORDER-12345") or a unique random string that only your backend and PayerScan know.
Why use it? If your server crashes or times out mid-request, you can safely retry with the same request_id. The API guarantees no duplicate invoices will be created — instead, it returns the existing invoice with "idempotent": true in the response.
Matching webhooks to orders: The request_id is also included in webhook callbacks (completed / expired), so your backend can use it to identify which internal order (transaction) the payment belongs to.
Without request_id: Every POST creates a new invoice, even if the body is identical. You risk creating duplicate invoices for the same order if you retry.
What currency is the amount in?
The amount field is always in USD (US Dollars). The system automatically converts it to the corresponding cryptocurrency amount based on the real-time exchange rate at the time of payment.
Note: The exchange rate is sourced from one of four providers — Binance, Coinbase, CoinGecko, or CoinMarketCap — selected by the customer on the payment page.
What are the amount limits?
The invoice amount (in USD) must be a positive number and cannot exceed 1,000,000. Values can be sent as a string or number.
What are completed_url and expired_url?
These are optional redirect URLs for the customer's browser:
completed_url— the customer is redirected here after successful payment.expired_url— the customer is redirected here if the invoice expires.
They are for frontend redirection only and do not replace the callback_url webhook.
Payments & Confirmation
What happens if the customer sends the wrong amount?
The system only confirms when the blockchain transaction exactly matches the amount (token_amount), correct address, and within the time window. Sending too little or too much will not be considered a successful payment; the invoice may expire or the customer needs to create a new one.
How long does confirmation take?
Typically a few seconds to a few minutes, depending on the network and method:
- EVM (BSC, ETH, Polygon, ...): 3-15 seconds
- Tron (TRC20): 3-5 seconds
- Exchange deposits (Binance, OKX, Bybit, ...): Nearly instant
- Binance Pay: Nearly instant
Once a matching transaction is found, the system updates the invoice and sends the webhook immediately.
When does an invoice expire?
By default according to Store configuration (e.g., 15 minutes). When creating an invoice, the response includes expires_in_minutes. After that time, the invoice changes to expired and (if a callback_url is provided) you receive a webhook with status: "expired".
What are the possible invoice statuses?
| Status | Description |
|---|---|
waiting | Invoice created, waiting for customer to pay. |
completed | Payment confirmed on the blockchain. |
expired | Invoice expired without receiving payment. |
Can I cancel an invoice?
No. Invoices cannot be cancelled via the API. They will automatically expire after the configured time (expires_in_minutes). If the customer doesn't pay, just let it expire.
Webhook
What events trigger a webhook?
The system sends webhooks for two events:
- completed — when a matching payment is confirmed on the blockchain.
- expired — when the invoice expires without receiving payment.
What is the webhook timeout?
10 seconds. If the merchant server doesn't return an HTTP 2xx within this time, the request is considered failed and will be retried.
Do I need to return a specific body?
No. Just return an HTTP 2xx status (e.g., 200 OK). The body is up to you (can be empty or "OK").
Are webhooks retried on failure?
Yes. When you return an error or timeout, the system retries on this schedule: 10s → 30s → 30s → 60s → 60s (max 5 attempts). Ensure your endpoint handles idempotently (calling with the same trans_id multiple times is safe).
Errors & Troubleshooting
What does NO_PAYMENT_METHOD mean?
Your Store hasn't configured a payment method. Go to Store management → add at least one wallet address or connect an exchange platform before creating invoices.
What does INSUFFICIENT_BALANCE mean?
Your account balance is insufficient to cover the service fee for that invoice. The fee is calculated based on the invoice amount (USD) with your account's fee rate applied (discounts may reduce the rate). Top up your balance on the Dashboard and try again. Check the details field in the error response for the exact shortage amount.
Note: During the free trial period (first 7 days),
INSUFFICIENT_BALANCEwill not appear — all service fees are waived.
What is INVALID_MERCHANT_ID?
The merchant_id in the body doesn't match the Store of the API Key being used. Check the merchant_id in your Store management and send the correct one in the request.
Invoice lookup returns 404?
Possible causes: (1) wrong trans_id, (2) invoice belongs to a different Store (different API Key), or (3) doesn't exist. Check the trans_id and API Key.
Payment Methods
What payment methods does the system support?
PayerScan supports multiple payment methods:
- On-chain wallets: EVM (BSC, Ethereum, Polygon, Base, Arbitrum), Tron (TRC20), Solana
- Exchange platforms: Binance Pay, Binance Deposit, OKX, Bybit, MEXC, Gate.io, Bitget, Upbit, Bitkub
See Networks & Tokens for the full list of supported chains and tokens.
How does Binance Pay work?
Binance Pay allows customers to pay via Binance — no gas fees, instant confirmation. Merchants need to configure Binance API Key and Secret Key in the management page.
What needs to be configured for exchange platforms?
- Create an API Key on the exchange (enable required permissions)
- In the management page → configure API Key, Secret Key, and platform ID for the Store
Details: Binance Pay Setup.
Security
Should the API Key be sent from the frontend?
No. The API Key should only be used on the server (merchant's backend). Call POST /payment/crypto and GET /invoice from the server; the frontend only receives url_payment for redirection, and doesn't need the API Key.
Does the callback URL need authentication?
Recommended: verify merchant_id or trans_id with internal data to ensure the request is legitimate. Use HTTPS to prevent eavesdropping.
Can I have multiple Stores?
Yes. Each Store has its own API Key, merchant_id, payment methods, and settings. You can create multiple Stores to separate different businesses or environments (e.g., production vs. testing).