FAQ

Frequently Asked Questions

Payments

Why am I not redirected to my success URL?

External redirects occur only if your URL meets the safety policy:

HTTPS on port 443
Domain is allow-listed

Contact your account manager to allowlist your domains.

Can I reuse the same `merchant_order_id`?

Same order ID + identical parameters → Returns same payment_id
Same order ID + different parameters → Returns 409 Conflict

Use unique order IDs for each payment attempt.

How long should I wait for a webhook?

Webhooks are typically sent within 1-5 seconds of payment completion. If you don’t receive one within 30 seconds, poll the payment status endpoint.

What happens if my webhook endpoint is down?

QRPay retries up to 4 times with exponential backoff. After that, poll the payment status endpoint manually.

Can I test webhooks locally?

Yes, use ngrok or a similar tunneling service to expose your local endpoint. Ensure your handler is publicly accessible over HTTPS.

Payouts

How long does a payout take?

EFT payouts typically take 1-3 business days after operator approval.

What happens if I don’t have enough balance?

The API returns a 400 error with code INSUFFICIENT_BALANCE. Check your balance and ensure funds are available before retrying.

Can I cancel a pending payout?

Contact your account manager to reject a pending payout. Once approved and processing, cancellation may not be possible.

How do I track payout status?

You can poll GET /api/v1/payouts/{id}, but we recommend using webhooks for real-time updates.

Can I test payouts in sandbox?

Yes, use the sandbox environment (https://api.sandbox.qrpay2.com). Contact your account manager for sandbox credentials.

How do I enable auto top-up?

Contact your account manager. Auto top-up automatically credits your payout balance from captured payments minus commissions.

What’s the difference between `reserved_cents` and `available_cents`?

reserved_cents - Funds allocated to pending/approved payouts
available_cents - What’s left for new payouts (balance_cents - reserved_cents)

Authentication

I rotated my API key but calls fail

Ensure you updated the X-API-Key header everywhere. Verify:

Correct environment (prd/tst/dev)
Key is active and not expired
No trailing whitespace

How do I handle webhook secret rotation?

During the 24-hour rotation window, verify webhooks against both old and new secrets. After 24 hours, only the new secret is valid.

Where do I get API credentials?

Contact your account manager. The Merchant Portal is under development.

General

What currencies are supported?

Currently only South African Rand (ZAR).

What are the payment amount limits?

Minimum: R55 (5500 cents)
Maximum: R3000 (300000 cents)

How do I switch from sandbox to production?

Get production API credentials from account manager
Update base URL to https://api.qrpay2.com
Update webhook URLs to HTTPS production endpoints
Ensure allow-listed domains are configured

How do I contact support?

Please contact your dedicated account manager for all support inquiries, including:

Technical support
Integration assistance
Production credentials
Urgent issues

FAQ