Tutorial: Troubleshooting Payment Gateway Credential Errors Using a Test Order (BEOE)
Introduction
If your UltraCart store is showing credit card declines with messages such as:
“Your credit card has been declined. We're sorry, but there was an issue processing your payment due to a technical problem on our end. Please try again later or contact support if the issue persists.”
this typically indicates a payment gateway configuration issue, not necessarily a problem with the customer's credit card.
In this example, the storefront displayed the above decline message even though the underlying gateway response indicated a credential configuration error.
When reviewing the order transaction history in UltraCart, the gateway returned the following error:
| Setting | Recommended Value |
| Issue | Description |
|---|---|
| Invalid API credentials | Incorrect gateway API key or transaction key |
| Sandbox credentials used in production | Environment mismatch |
| Gateway account disabled | Merchant account inactive |
| Merchant ID mismatch | Gateway account configuration changed |
| IP restrictions | Gateway blocking UltraCart server requests |
Troubleshooting Checklist
Before contacting support, verify the following:
-
Gateway API credentials are correct
-
Gateway environment matches your credentials (Production vs Sandbox)
-
Merchant gateway account is active
-
API access is enabled within the gateway
-
UltraCart gateway type matches your gateway provider
Expected Outcome
After completing this troubleshooting procedure you should be able to:
-
Confirm whether gateway credentials are valid
-
Identify gateway configuration errors
-
Successfully process a real test transaction
-
Verify that your checkout can process live payments
FAQ
Why do customers see a decline message if the issue is technical?
UltraCart intentionally displays a generic decline message to customers for security reasons.
Detailed gateway responses (such as credential errors or authentication failures) are only visible inside the order transaction history for merchants.
Why don’t UltraCart test credit cards test the gateway?
UltraCart test card numbers are designed to bypass the payment gateway entirely.
They allow merchants to test checkout flows without contacting the gateway.
To verify that your gateway configuration works correctly, you must use a real credit card.
Why does UltraCart send orders to Accounts Receivable after failed attempts?
By default, UltraCart attempts to process the payment three times.
If all attempts fail, the order is automatically routed to Accounts Receivable (A/R) so the merchant can:
-
Review the gateway error
-
Contact the customer if needed
-
Retry the transaction manually
Can I retry the payment after fixing gateway credentials?
Yes.
Once the gateway credentials are corrected, you can return to the order in Accounts Receivable and click Process Payment to retry the transaction.
Next Steps
After successfully processing a test transaction:
-
Place a normal storefront order to confirm checkout works
-
Monitor new orders to confirm payments are captured successfully
-
Securely store your gateway credentials
-
Document your gateway configuration for future reference
If problems persist, contact UltraCart support and provide:
-
Order ID
-
Transaction UUID
-
Gateway type
-
Timestamp of the failed transaction