Payment Gateway Errors
Payment gateway errors are the most costly website problems. A customer has decided to buy, entered their payment details, clicked "Pay" — and something fails. Many won't try again. Even if you fix it, they're gone.
Most payment errors are configuration or credential issues, not code problems. That's good news: they're usually quick to fix once diagnosed.
Common payment error types
| Error | Meaning | Fix |
|---|---|---|
| Invalid credentials | API keys wrong or expired | Update keys in settings |
| Gateway timeout | Payment provider slow/down | Check provider status |
| Card declined | Customer's issue, not yours | Show helpful message |
| Currency mismatch | Gateway doesn't support currency | Adjust settings or gateway |
| Invalid request | Malformed data sent to gateway | Check integration code |
Critical distinction: Is the error affecting all transactions or just some? All transactions means configuration. Some transactions means specific card/customer issues.
Diagnosing payment failures
1. Check the payment gateway dashboard
Your gateway (Stripe, PayPal, Square, etc.) has its own dashboard showing transactions. Look for:
- Failed payment attempts with error details
- Test vs live mode status
- Webhook delivery failures
Gateway error messages are more detailed than what users see.
2. Verify credentials are current
API keys expire or get rotated. Check:
- When were credentials last updated?
- Are you using test keys in production (or vice versa)?
- Did someone regenerate keys without updating your site?
3. Check for provider outages
Payment gateways have outages like any service:
- Stripe: status.stripe.com
- PayPal: paypal-status.com
- Square: issquareup.com
During outages, you can only wait or switch to a backup gateway.
4. Review recent changes
Payment integrations break when:
- Platform updated (Shopify, WooCommerce version)
- Payment plugin updated
- Someone changed gateway settings
- SSL certificate changed or expired
Specific error fixes
"Invalid API key"
Your credentials are wrong. This is almost always a copy-paste error or test/live key confusion.
Fix:
- Log into your payment gateway dashboard
- Copy the API keys fresh (don't trust cached values)
- Paste carefully — watch for extra spaces
- Verify you're using live keys (not test keys) in production
"Payment not completed"
The transaction started but didn't finish. Common with 3D Secure/SCA flows.
Fix:
- Ensure redirect URLs are configured correctly
- Check that your site handles the return flow
- Verify 3D Secure is properly configured
"Transaction refused by gateway"
The payment provider explicitly rejected the transaction.
Check:
- Is the card type supported?
- Is the currency supported?
- Are there velocity limits (too many transactions)?
- Is the account in good standing?
Minimizing payment failure impact
Show clear error messages: "Something went wrong" doesn't help. Tell customers what to try next.
Offer payment alternatives: If Stripe fails, having PayPal as backup prevents lost sales.
Monitor payment success rates: A sudden drop in payment success rate signals a problem. Use error monitoring to catch failures before they pile up.
Test after any changes: Before and after updating anything payment-related, run a test transaction.
Related pages
Parent: Shopify Issues — Common Shopify problems and fixes
Siblings:
- Shopify Checkout Broken — When checkout fails
Pillar: Common Fixes — Solutions for frequent issues