Testing & Sandbox

Sandbox environment

Use the sandbox environment for all development and QA testing.

• Sandbox dashboard: https://sandbox.3pa-y.com/

• Sandbox is isolated from production:

  • Separate API keys
  • Separate webhooks
  • Separate wallets and balances

⚠️

Sandbox data never carries over to live. Treat sandbox and live as two separate environments.

Supported testnets in sandbox

3PAY uses public blockchain testnets to simulate real payment behavior.

Testnet tokens have no real value and may be limited or unstable depending on the network.

Getting testnet wallets & funds

To complete sandbox tests you will need:

• A compatible testnet wallet
• Testnet USDT on the chosen test network

If you need help:

• generating a testnet wallet
• obtaining testnet funds (Sepolia / Nile)

Please contact the 3PAY support team, and we will assist with setup.

What you should test in sandbox

You should validate your integration end-to-end for the payment model you use.

A) Invoice payments (checkout / one-time)

Test the following:

☐ Create invoice successfully ☐ Display invoice payment instructions to user ☐ Send testnet USDT to the invoice address ☐ Confirm status becomes Successful ☐ Webhook received and processed correctly ☐ Order marked paid only after success ☐ Wrong network scenario handled in UI (ERC20 vs TRC20)

API Reference links to place here:

• Create Invoice
• Get Invoice
• Invoice Webhooks

B) Per-user wallet payments (persistent balances)

Test the following:

☐ Create user successfully (userId, email) ☐ Retrieve wallet details (address) ☐ Send testnet USDT deposit to the user wallet ☐ Confirm deposit becomes Successful ☐ Get wallet balance reflects deposit correctly ☐ Webhook received and processed correctly ☐ Duplicate webhook events handled safely

API Reference links to place here:

• Create User
• Get Wallet Details
• Get Wallet Balance
• Wallet Webhooks

C) Pay-outs & withdrawal automation (if enabled)

If you use withdrawals / auto-withdrawals / auto-payouts, test:

☐ Create withdrawal request (API) ☐ Confirm withdrawal status changes correctly ☐ Auto-withdrawal threshold behavior works as expected ☐ Auto-payout triggers correctly at configured balance threshold ☐ Destination wallet/network validation in your UI ☐ “Wrong address” scenarios are clearly warned to end users

API Reference links to place here:

• Create Withdrawal Request
• Get Withdrawal Status
• Auto-withdrawal configuration endpoint (if applicable)
• Auto-payout configuration endpoint (if applicable)

Webhooks in sandbox (must test)

Webhooks are your primary integration mechanism.

In sandbox, validate:

• Your endpoint is reachable
• You store and process events reliably
• You handle retries and duplicates safely

Remember:

• Sandbox and live webhook URLs are configured separately
• Sandbox and live webhook secrets (if used) are different

API Reference link to place here:

• Webhooks (Events + Signature Verification)

Recommended testing workflow

1. Build and test everything in sandbox
2. Confirm your webhook and status handling are correct
3. Validate edge cases (wrong network, duplicate events, retries)
4. Only then generate live keys and go live

Common pitfalls to catch early

Wrong network selection

ERC20 and TRC20 are not interchangeable. Your UI should:

• clearly display the network
• prevent users from sending on the wrong network when possible

Treating “pending” as paid

Only treat a payment as final when it is Successful.

Missing webhook deduplication

Webhooks may be delivered more than once. Your system should be idempotent.

Mixing sandbox and live credentials

Sandbox keys do not work on live, and live keys must never be used in testing.

Sandbox limitations

• Testnet confirmations may be slower or unstable
• Testnet token availability may be limited
• Sandbox balances do not represent real funds
• Sandbox transactions cannot be migrated to production

Sandbox is for integration validation, not performance benchmarking.