Troubleshooting

Solutions for the most common merchant issues.

Find your issue below. Each entry explains what you see, why it happens, and how to fix it. If your issue is not listed or the fix does not work, contact support at jopay.app/support.

1. I can't log in

Who sees this: Merchants trying to access their account.

What happened: The login page does not recognize your credentials, shows an error, or the page does not load.

Why:

• You are using a different email or social account than the one you onboarded with.
• Your browser has stale cookies or cached data.
• The wallet session has expired (embedded wallet).
• Your partner has disabled your merchant account.

Fix:

1. Verify you are using the exact same email or social account from onboarding.
2. Clear your browser cookies and cache, then try again.
3. Try a private/incognito browser window.
4. If using an external wallet, make sure the wallet extension is unlocked and connected.
5. Contact your partner to confirm your account is still active.

2. Payment stuck on "Pending"

Who sees this: Merchants waiting for a customer to pay.

What happened: You created a payment request but the status has not changed from Pending.

Why:

• The customer has not sent USDC yet.
• The customer sent USDC but on a chain JoPay does not monitor.
• The customer sent a different token (not USDC).
• The on-chain transaction is still confirming (blockchain congestion).

Fix:

1. Ask the customer if they have sent the payment.
2. If the customer says they paid, ask them for the transaction hash.
3. Open the payment drawer and use manual proof submission to paste the TX hash.
4. If the payment expires before the customer pays, create a new payment request.

3. Payment expired before the customer paid

Who sees this: Merchants and customers.

What happened: The payment status changed to Expired. The customer can no longer use the payment link.

Why:

• The customer did not send USDC within the expiry window.
• POS payments have shorter expiry windows than invoice-mode payments.

Fix:

1. Create a new payment request for the same amount.
2. Share the new link or QR code with the customer.
3. If the customer already sent funds to the expired payment's address, the funds are still in your wallet. The payment is expired in JoPay's system, but the on-chain transfer still happened.

4. Payment shows wrong amount

Who sees this: Merchants reviewing payment details.

What happened: The fiat amount displayed does not match what you expected, or the USDC amount seems off.

Why:

• FX rates fluctuate. The USDC amount is locked at creation time using the rate at that moment.
• You may be looking at the USDC value instead of the display currency value, or vice versa.
• The customer sent a different USDC amount than requested (amount mismatch).

Fix:

1. Open the payment drawer to see both the fiat amount and USDC amount side by side.
2. Check the FX rate that was used at payment creation time (shown in the drawer).
3. If there is an amount mismatch, see the mismatch reasons section for next steps.

5. I can't create a payment

Who sees this: Merchants trying to create a new payment request.

What happened: The New Payment button is not working, the form shows an error, or the payment fails to create.

Why:

• The amount is below the partner's minimum payment threshold.
• Your wallet is not connected or the session has expired.
• There is a network or server issue.
• Your partner has disabled payment creation for your account.

Fix:

1. Check that the amount meets the minimum threshold (shown in the form if applicable).
2. Refresh the page to re-establish your wallet session.
3. Try logging out and logging back in.
4. If the issue persists, contact your partner to check your account status.

6. Auto-forward did not work

Who sees this: Merchants with auto-forward enabled.

What happened: A payment was verified but the USDC was not forwarded to your withdraw address.

Why:

• Auto-forward is not enabled (check Settings).
• No withdraw address is set.
• The withdraw address is invalid or unreachable on the current chain.
• Network congestion caused the forward transaction to fail.
• The balance was already moved (e.g. manual send) before auto-forward could execute.

Fix:

1. Go to Settings and verify auto-forward is toggled on.
2. Verify your withdraw address is correct and valid.
3. Check your wallet balance: if it is 0, the funds may have already been forwarded or manually sent.
4. If auto-forward failed silently, you can manually send the funds using Send Funds.

7. Balance shows 0

Who sees this: Merchants checking their wallet balance.

What happened: Your USDC balance shows as 0 even though you expect funds to be there.

Why:

• Auto-forward swept the funds to your withdraw address already.
• You manually sent the funds using Send Funds.
• The balance cache has not refreshed yet (up to 30 seconds).
• You are viewing the balance on a different chain than where the USDC was received.
• The payment has not been verified yet (funds show after verification).

Fix:

1. Wait 30 seconds and refresh the page for the cache to update.
2. Check if auto-forward is enabled and whether funds were sent to your withdraw address.
3. Verify the payment status in the dashboard: if it is still Pending, the customer has not paid yet.
4. Check your wallet address on a block explorer (e.g. Polygonscan) to see the actual on-chain balance.

8. I can't enable auto-forward

Who sees this: Merchants trying to turn on auto-forward in Settings.

What happened: The auto-forward toggle is greyed out or shows an error when you try to enable it.

Why:

• You are using an external wallet (MetaMask, etc.). Auto-forward requires the embedded wallet (Sequence WaaS).
• You have not set a withdraw address yet.

Fix:

1. Check that you are using the embedded wallet. If you connected with MetaMask or another external wallet, auto-forward is not available.
2. Set a withdraw address in Settings first, then try enabling auto-forward.
3. If you need to switch from an external wallet to the embedded wallet, contact your partner about re-onboarding.

9. Recurring plan was automatically paused

Who sees this: Merchants with recurring billing plans.

What happened: A recurring plan's state changed to Paused without you pausing it manually.

Why:

• The plan failed to charge the customer 3 times in a row. After 3 consecutive failures, JoPay automatically pauses the plan to prevent further failed attempts.
• Common failure reasons: customer wallet has insufficient USDC, customer revoked authorization, or network issues.

Fix:

1. Contact the customer and ask them to ensure their wallet has enough USDC.
2. Verify that the customer's authorization is still valid.
3. Once the issue is resolved, manually resume the plan from the Recurring Plans page.
4. If the customer no longer wants the subscription, cancel the plan instead.

10. Customer can't pay

Who sees this: Merchants whose customers report issues paying.

What happened: The customer opened the payment link but cannot complete the payment.

Why:

• The customer's wallet does not have enough USDC.
• The customer is on an unsupported chain.
• The customer's wallet does not have enough native tokens for gas fees.
• The payment has already expired.
• The customer's wallet is not connected or the browser does not support the wallet extension.

Fix:

1. Ask the customer to check their USDC balance on a supported chain (Polygon, Base, Ethereum, Optimism, or Arbitrum).
2. Ensure they have enough native tokens for gas (e.g. MATIC on Polygon, ETH on Base).
3. If the payment expired, create a new one and share the fresh link.
4. Ask the customer to try a different browser or ensure their wallet extension is up to date.
5. As a fallback, the customer can send USDC directly to your wallet address and you can submit the TX hash manually.

11. QR code not working

Who sees this: Merchants or customers trying to scan a QR code.

What happened: Scanning the QR code does not open the payment page, or the page shows an error.

Why:

• The camera is not focused or the QR code is partially obscured.
• The payment has expired (QR codes link to payment pages that can expire).
• The phone's QR scanner does not open the URL in a browser.

Fix:

1. Ensure the QR code is fully visible, well-lit, and not cropped.
2. Try scanning with the default phone camera app (most phones support QR scanning natively).
3. If the QR links to an expired payment, create a new payment and display the new QR code.
4. As an alternative, copy the payment link and send it to the customer directly (the QR code and the payment link go to the same page).

12. Payment not showing in history

Who sees this: Merchants looking for a specific payment.

What happened: You created a payment but it does not appear in your payment list.

Why:

• You have a status filter active that is hiding the payment (e.g. filtering to "Verified" only, while the payment is still Pending).
• The dashboard is showing a limited number of recent payments and the payment is older.
• The page has not refreshed since the payment was created.

Fix:

1. Clear all status filters to show all payments.
2. Refresh the page.
3. If the payment was created a long time ago, it may be beyond the visible window. Check with your partner if you need historical data.

13. Receipt unavailable

Who sees this: Merchants or customers trying to view a receipt.

What happened: The receipt option is not available or shows an error when you try to download it.

Why:

• The payment is not yet verified. Receipts are only available for verified payments.
• The payment has a mismatch status (proof did not fully match).

Fix:

1. Check the payment status in the drawer. If it shows Pending, Attached, or Mismatch, the receipt is not available.
2. Wait for verification to complete. Once the status changes to Verified, the receipt becomes available.
3. If the payment has a mismatch, resolve the mismatch first (see conflict resolution).

14. Not receiving email notifications

Who sees this: Merchants who expect email alerts.

What happened: A payment was verified (or a recurring plan event occurred) but you did not receive an email notification.

Why:

• Email notifications are disabled in Settings.
• The email went to your spam or junk folder.
• The email address on your account is incorrect.
• There is a temporary email delivery delay.

Fix:

1. Go to Settings and verify email notifications are toggled on.
2. Check your spam/junk folder.
3. Verify the email address associated with your account is correct.
4. Wait a few minutes for potential delivery delays.

15. Amounts shown in the wrong currency

Who sees this: Merchants seeing unexpected currency symbols or values.

What happened: The dashboard shows amounts in a currency you did not expect (e.g. showing EUR instead of USD).

Why:

• Your display currency is set to something other than what you intended.
• Your partner changed the default currency configuration.

Fix:

1. Go to Settings and change your display currency to the correct one.
2. Save and refresh the page. All amounts will update to the new currency.

16. I can't withdraw funds

Who sees this: Merchants trying to send USDC from their wallet.

What happened: The Send Funds feature is not working, shows an error, or the transaction fails.

Why:

• Your wallet balance is 0 (auto-forward may have already swept the funds).
• The destination address is invalid.
• For external wallets: insufficient native tokens for gas fees.
• Network issues or blockchain congestion.

Fix:

1. Check your wallet balance. If it shows 0, your funds may have been auto-forwarded or already sent.
2. Verify the destination address is a valid EVM address starting with 0x.
3. If using an external wallet, ensure you have enough native tokens (MATIC, ETH) for gas.
4. Try again after a few minutes if there is network congestion.

17. Payment verified but funds not in wallet

Who sees this: Merchants who see a verified payment but no balance increase.

What happened: The payment status shows Verified, but your wallet balance did not increase or shows the same amount as before.

Why:

• Auto-forward swept the funds immediately after verification.
• The balance cache has not refreshed yet (up to 30 seconds).
• The funds are on a different chain than you are viewing.

Fix:

1. If auto-forward is enabled, check your withdraw address on a block explorer. The funds should be there.
2. Wait 30 seconds and refresh the page.
3. Check your wallet address on a block explorer for the chain the payment was made on to confirm the funds arrived.

18. Invite link expired

Who sees this: New merchants trying to onboard with an expired invite.

What happened: You opened an invite link but it shows as expired and does not let you continue.

Why:

• Invite links have a time limit (15 minutes, 1 hour, or 24 hours). The link was not used within that window.
• The invite was already used by someone else (invites are single-use).

Fix:

1. Ask the person who invited you (merchant or partner) to generate a new invite link.
2. Use the new link promptly before it expires.

19. Duplicate payments

Who sees this: Merchants who see two payments for the same transaction.

What happened: The same customer payment appears to be linked to two payment requests, or the customer paid twice.

Why:

• The customer sent two separate on-chain transactions (e.g. they were unsure if the first one worked and sent again).
• You created two payment requests and the customer paid both.
• A TX hash was submitted manually to a payment request that Trails already matched to a different request.

Fix:

1. Open each payment in the drawer and compare the TX hashes. If they are different, the customer sent two separate transactions.
2. Coordinate with the customer to return one of the duplicate payments directly (JoPay does not handle returns).
3. If the same TX hash appears on two payment requests, contact support to resolve the duplicate.

20. Dashboard not updating

Who sees this: Merchants whose dashboard appears stale.

What happened: New payments, balance changes, or status updates are not appearing on the dashboard.

Why:

• The dashboard poller may have paused (e.g. browser tab was in the background for a long time).
• Network connectivity issues are preventing data refresh.
• Browser cache is serving stale content.

Fix:

1. Refresh the page (F5 or pull-to-refresh on mobile).
2. Switch to the dashboard tab and wait a few seconds. The poller resumes when the tab is active.
3. Check your internet connection.
4. If the issue persists, clear your browser cache and reload.

21. I can't change my display name

Who sees this: Merchants trying to edit their business name in Settings.

What happened: The display name field is greyed out or read-only in Settings.

Why:

• The display name is read-only for merchants. It is set during onboarding and can only be changed by your partner.

Fix:

1. Contact your partner and ask them to update your display name from the admin portal.

22. Landed on the wrong page

Who sees this: Merchants or customers who see an unexpected page.

What happened: After clicking a link, you landed on a page you did not expect (e.g. a partner login page instead of the merchant dashboard, or a 404 error).

Why:

• The URL is incorrect or incomplete.
• You are not authenticated and the system redirected you to a login page.
• The page requires a different role (e.g. partner vs merchant).
• A cached redirect is sending you to the wrong destination.

Fix:

1. Check the URL in your browser and ensure it is correct.
2. Log in if prompted, then navigate to the correct page from the menu.
3. Clear your browser cache if you are being redirected incorrectly.
4. If you received the link from someone else, ask them to verify it is correct.

23. Invalid transaction hash

Who sees this: Merchants or customers submitting manual proof.

What happened: You pasted a transaction hash for manual verification but the system says it is invalid.

Why:

• The hash is malformed (wrong length, missing characters, includes spaces).
• The hash is for a transaction on an unsupported chain.
• The hash is for a transaction that has not been verified on-chain yet.
• You pasted a wallet address instead of a transaction hash.

Fix:

1. Verify the hash is a valid transaction hash (66 hex characters starting with 0x on EVM chains).
2. Make sure you are pasting the transaction hash, not the wallet address or block number.
3. Confirm the transaction exists by looking it up on a block explorer (Polygonscan, Basescan, Etherscan, etc.).
4. If the transaction is still pending on-chain, wait for it to confirm before submitting.
5. Ensure the transaction is on a supported chain (Polygon, Base, Ethereum, Optimism, or Arbitrum).

24. Rate limited

Who sees this: Merchants performing many actions in a short time.

What happened: You received a rate limit error when trying to create a payment, invite, or perform another action.

Why:

• JoPay enforces rate limits to prevent abuse. You have exceeded the limit for a specific action within the rolling time window.
• For invites: 5 per hour per merchant.
• For other actions: limits vary but are designed for normal usage patterns.

Fix:

1. Wait for the rate limit window to reset (usually 1 hour for invite limits).
2. Avoid rapid-fire actions. Space out your requests.
3. If you need to perform bulk actions (e.g. many invites), contact your partner. Partners have different rate limits and can perform bulk operations.

25. Subscription charge failed

Who sees this: Merchants with active recurring plans.

What happened: A scheduled recurring charge did not go through. The plan may show a Failed state for the latest charge.

Why:

• The customer's wallet does not have enough USDC to cover the charge.
• The customer revoked the recurring authorization.
• Network congestion or RPC issues prevented the transaction from being submitted.
• The customer's wallet is on a chain that is temporarily unavailable.

Fix:

1. Contact the customer and ask them to ensure their wallet has enough USDC.
2. Verify the customer has not revoked authorization. If they have, they will need to re-authorize through a new authorization link.
3. If it was a network issue, the system may retry on the next scheduled cycle automatically.
4. If the plan has been auto-paused (3 consecutive failures), resolve the underlying issue and then manually resume the plan.