Payment gateway API errors occur when gateways return errors during subscription renewal attempts. Understanding and resolving these errors is crucial for maintaining successful subscription renewals.
What Are Gateway API Errors?
Gateway API errors are responses from payment gateways indicating that a charge attempt failed:
- Declined Cards: Card was declined by issuer
- Insufficient Funds: Customer account lacks funds
- Expired Cards: Payment method has expired
- Invalid Tokens: Saved payment token is no longer valid
- Gateway Issues: Temporary gateway service problems
- Configuration Errors: Incorrect gateway settings
Common Error Types
Card-Related Errors
| Error Type | Description | Solution |
| Card Declined | Issuer declined the charge | Customer needs to contact bank or use different card |
| Insufficient Funds | Not enough money in account | Customer needs to add funds |
| Expired Card | Card expiration date passed | Customer needs to update card |
| Invalid Card | Card number or details incorrect | Customer needs to verify card details |
Token-Related Errors
| Error Type | Description | Solution |
| Token Expired | Saved token no longer valid | Customer needs to update payment method |
| Token Invalid | Token doesn’t exist or was deleted | Re-save payment method |
| Token Mismatch | Token doesn’t match customer | Verify customer and token association |
Gateway Errors
| Error Type | Description | Solution |
| API Error | Gateway API returned error | Check gateway status, retry later |
| Rate Limit | Too many requests | Implement retry logic with backoff |
| Service Unavailable | Gateway temporarily down | Wait and retry |
| Authentication Failed | API keys invalid | Verify and update API keys |
Identifying API Errors
Admin Notifications
Sublium tracks recent API errors and displays notifications:
- Error Count: Number of errors in last 24 hours
- Gateway Name: Which gateway is experiencing errors
- Error Details: Specific error messages
- Affected Subscriptions: Subscriptions impacted by errors
Error Logs
- Navigate to Settings > Advanced > Logs
- Filter by gateway name
- Review error messages and timestamps
- Look for patterns in errors
Subscription Details
- Open affected subscription
- Check Payment History section
- Review failed payment attempts
- See error messages from gateway
Resolving Errors
For Card Declines
Customer Action Required
- Contact customer about declined payment
- Ask them to verify card details
- Suggest contacting their bank
Retry Logic
- Configure automatic retry schedule
- Retry failed payments after delay
- Stop retrying after max attempts
Payment Method Update
- Send customer update payment method link
- Use One-Click Card Update if available
- Guide customer through update process
For Expired Cards
Automatic Detection
- System detects expired cards
- Sends notification to customer
- Provides update link
Customer Update
- Customer updates card in My Account
- New token is saved
- Next renewal uses new card
Reminder System
- Send reminders before card expires
- Proactive communication reduces failures
For Token Errors
Re-save Payment Method
- Customer updates payment method
- New token is generated
- Future renewals use new token
Manual Processing
- Admin processes payment manually
- New token saved during manual charge
- Subscription continues normally
For Gateway Errors
Check Gateway Status
- Visit gateway status page
- Check for known issues
- Review gateway documentation
Verify Configuration
- Check API keys are correct
- Verify webhook URLs
- Review gateway settings
Contact Gateway Support
- Reach out to gateway support
- Provide error detail
