FivoDocs
Docs/Testing

Testing

Test your integration before going live with real payments.

Testing Environment

Before processing real payments, you can test your integration using testnets. This allows you to verify the full payment flow without spending real money.

i
Testnet transactions use test tokens with no real value. You can test as many payments as you want without any cost. Use Circle's faucet to get free test USDC.

Getting Test USDC

To test payments, you'll need test USDC in your wallet. Circle provides a free faucet:

Circle Testnet Faucet

faucet.circle.com
  1. Visit faucet.circle.com
  2. Connect your wallet (MetaMask, etc.)
  3. Select the testnet (Sepolia, Amoy, Fuji, etc.)
  4. Select USDC and request tokens
  5. Tokens arrive in ~1 minute

Getting Testnet Gas

You'll also need native tokens for gas fees. Here are faucets for each chain:

ChainGas TokenFaucet
Ethereum SepoliaETHsepoliafaucet.com
Polygon AmoyPOLfaucet.polygon.technology
Avalanche FujiAVAXfaucet.avax.network
Arbitrum SepoliaETHquicknode.com/arbitrum
Base SepoliaETHquicknode.com/base
Optimism SepoliaETHquicknode.com/optimism

Test Scenarios

We recommend testing these scenarios before going live:

1. Same-Chain Payment

Test a basic payment where customer and merchant are on the same chain.

Example: Pay from Polygon Amoy → Merchant on Polygon Amoy

2. Cross-Chain Payment (CCTP)

Test a payment from a different chain than your merchant wallet.

Example: Pay from Ethereum Sepolia → Merchant on Polygon Amoy

3. Fixed Amount Payment

Test a payment with a fixed amount (e.g., product purchase).

html
<script data-merchant-id="..." data-amount="10.00" data-currency="USDC"></script>

4. Variable Amount Payment

Test a payment where the user enters their own amount (e.g., donation).

html
<script data-merchant-id="..." data-currency="USDC"></script>

5. Insufficient Balance

Test the widget behavior when customer doesn't have enough funds.

Expected: Balance shows "Insufficient" badge, payment option disabled

6. Transaction Rejection

Test what happens when user rejects the transaction in their wallet.

Expected: Widget shows error and allows retry

Pre-Launch Checklist

Before announcing your integration, verify these items:

Debugging

If something isn't working, check these common issues:

Widget doesn't load

  • Check browser console for JavaScript errors
  • Verify the script src URL is correct
  • Ensure data-merchant-id is a valid UUID
  • Check that <div id="fivo-widget-root"> exists

No balances showing

  • Ensure your test wallet has USDC on supported testnets
  • Wait a few seconds for balance scanning to complete
  • Check if wallet is connected to the correct network

Transaction fails

  • Ensure you have enough gas tokens for the transaction
  • Check that you have enough USDC for the payment amount
  • Try refreshing the page and reconnecting wallet

Cross-chain stuck on pending

  • CCTP attestation can take 2-5 minutes normally
  • During network congestion, it may take up to 15 minutes
  • Check payment status via API: GET /payments/:id/status

Console Logs

The widget logs useful debug information to the browser console:

Browser Console
[Fivo Widget] Configuration loaded: {merchantId: "...", amount: "49.99", currency: "USDC", mode: "fixed"}
[Fivo Widget] Wallet connected: 0x1234...
[Fivo Widget] Balance scan complete: 3 chains with funds
[Fivo Widget] Processing payment: 49.99 USDC on MATIC-AMOY
[Fivo Widget] Transaction submitted: 0xabc...
[Fivo Widget] Payment complete!

Going to Production

✓

Production Ready

Fivo is live on mainnet! When you're ready to accept real payments:
  • Ensure your wallet is set up on your preferred mainnet chain
  • Verify your webhook endpoints are configured correctly
  • Test with a small real payment first ($1-5 recommended)
  • Monitor your dashboard for incoming payments

Need Help?

If you're stuck or found a bug, we're here to help.

Contact Support