Troubleshooting

Solutions to the most common issues with UniPay for Shopify. If you can't find your issue here, contact support via the UniPay Help Centre.

UniPay doesn't appear at checkout

Possible causes and fixes:

Not activated in Shopify Payments settings. Go to Settings → Payments → Additional payment methods and confirm UniPay is listed and activated.
App is disabled. Open the UniPay app from your Shopify admin and confirm the Enable UniPay toggle is on.
Shopify Starter plan. UniPay requires a Shopify-hosted checkout, which is not available on the Starter plan. Upgrade to Basic or above.
Store currency not supported. Check the Merchant Portal — your store currency must be listed as a supported display currency.
Theme conflict. Rarely, a heavily customised theme can suppress additional payment methods. Test on a default Shopify theme (Dawn) to isolate the issue.

This means the webhook from UniPay did not reach your store, or was not processed.

Check the webhook URL is registered. Go to Merchant Portal → Integrations → Shopify and confirm the webhook URL shown matches your store URL. If not, click Re-register webhook.
Test mode mismatch. If test mode is on in the app but the customer is using a live UniCash account (or vice versa), payment will fail silently. Ensure test mode is off for live payments.
Webhook secret mismatch. If the webhook secret in the app settings does not match the one in the Merchant Portal, the webhook will be rejected. Re-enter the correct secret from Merchant Portal → Integrations → Shopify.
App uninstalled and reinstalled. Re-connecting the app via OAuth re-registers the webhook automatically. If you re-entered credentials manually, re-register the webhook from the Merchant Portal.

API key invalid or expired. Open the UniPay app settings and confirm the Live API Key is correct. Regenerate the key in the Merchant Portal if needed.
UniPay account suspended. Log in to the Merchant Portal to check your account status.
Test mode on but using a live API key. When test mode is on, the app expects the Test API Key. Confirm the correct key is in the Test API Key field.

Payment session expired. QR codes expire after 15 minutes. If the customer waited too long, they need to return to cart and start a new checkout.
Insufficient balance. The customer's UniCash balance was too low. Ask them to top up and retry.
Customer scanned wrong QR. Each QR code is unique to a specific payment session. A previous session's QR will not work for a new order.

Insufficient merchant balance. Refunds are deducted from your UniPay merchant balance. If your balance is lower than the refund amount, the refund will fail. Top up your merchant balance or use partial refunds.
Order already fully refunded. Shopify prevents refunding more than the original order value. Check the order history.
API connection error. Try the refund again after a few minutes. If it continues to fail, contact support.

Test API Key not set. Test mode requires a separate test API key. Go to Merchant Portal → Integrations → Shopify → Test credentials and copy the test API key into the app settings.
Test Webhook Secret not set. Similarly, the test webhook secret must be entered in the app settings.
UniCash app not in test mode. The customer's UniCash app must also be in test mode. Contact your UniPay account manager for test credentials for the UniCash app.

Changing your Shopify plan can occasionally reset payment method configurations. If UniPay disappears from checkout after a plan change:

Contact UniPay support with: