Troubleshooting — Payment Gateway Connection Issues
Applies To: [ All Licenses ]
Overview
This guide covers the most common payment gateway connection issues — including failed connections, credentials not saving, and checkout errors customers encounter.
Gateway Not Connecting After Credentials Are Entered
Navigate to Settings > Payment Processing and confirm the gateway is selected.
Re-enter your credentials carefully — API keys and merchant IDs are case-sensitive.
Save the settings and refresh the page to confirm the credentials persisted.
Check whether your gateway account is in test mode — test mode credentials will not work in a live environment and vice versa.
Log in to your gateway's merchant dashboard and confirm the account is active and not suspended.
Customers Receive Payment Errors at Checkout
Ask the customer for the exact error message they received.
Check the gateway's transaction log in your merchant dashboard for a corresponding declined transaction.
Common decline reasons and resolutions:
Error | Likely Cause | Resolution |
|---|---|---|
Card declined | Issuing bank declined the charge | Customer should contact their bank or use another card |
Invalid CVV | Customer entered incorrect CVV | Customer should re-enter card details |
Address mismatch (AVS) | Billing address does not match card records | Customer should confirm billing address |
Gateway timeout | Connectivity issue between platform and gateway | Retry the transaction; check gateway status page |
Duplicate transaction | Same transaction submitted twice | Check gateway dashboard; do not charge again without confirming |
Saved Cards Not Working at Checkout
If customers with saved payment methods are experiencing errors:
Confirm CIM (Customer Information Manager) or equivalent tokenization is enabled in the gateway settings.
Verify the saved card has not expired.
Have the customer remove the saved card and re-add it.
For Authorize.net CIM issues, see CIM for Authorize.net.
PayPal Checkout Not Completing
Confirm PayPal API credentials are correctly entered under Settings > Payment Processing.
Check whether your PayPal account has any outstanding verification or compliance requirements in the PayPal dashboard.
For PayPal Pro, confirm your API username, password, and signature are from the correct PayPal account. See Generate PayPal Pro API Keys.
Notes / Tips
After any credential change, always place a test order using the Cash payment method first to confirm checkout flow is working independently of the gateway.
Some gateways require IP whitelisting — if your server IP has changed, add it to the gateway's allowed IP list.
If you switch gateways, existing saved customer cards will not carry over — customers will need to re-enter their payment details.