Overview
This guide walks you through transitioning from sandbox to production, ensuring your QR payment integration is secure, reliable, and ready for real transactions.Prerequisites
Before moving to production, ensure you have:1
Complete Integration
- Successfully created QR codes in sandbox
- Tested payment flow end-to-end
- Implemented webhook handling
- Added proper error handling
- Tested all edge cases and error scenarios
2
Security Review
- Credentials stored securely (environment variables, secrets manager)
- HTTPS enabled on all endpoints
- Webhook endpoint secured
- Input validation implemented
- Logging and monitoring configured
3
Business Requirements
- Business verification completed with Modulus Labs
- Legal agreements signed
- Bank account for settlements configured
- Customer support process established
Sandbox vs Production
| Aspect | Sandbox | Production |
|---|---|---|
| Base URL | https://qrph.sbx.moduluslabs.io | https://qrph.moduluslabs.io |
| Secret Key | Starts with sk_test_ | Starts with sk_live_ |
| Encryption Key | Test encryption key | Production encryption key |
| Activation Code | Test activation code | Production activation code |
| Transactions | Simulated | Real money |
| Webhooks | Manual simulation | Automatic from banks |
| Rate Limits | 100 requests/minute | 1000 requests/minute |
| QR Validity | 15 minutes | 15 minutes |
| Support | Developer support | 24/7 production support |
Getting Production Credentials
1
Contact Modulus Labs
Email [email protected] with:
- Company name and registration details
- Business verification documents
- Expected transaction volume
- Technical contact information
2
Complete Verification
Modulus Labs will:
- Verify your business identity
- Review your integration
- Conduct security assessment
- Process legal agreements
3
Receive Credentials
Upon approval, you’ll receive:
- Production Secret Key (
sk_live_...) - Production Encryption Key
- Production Activation Code (
XXXX-XXXX-XXXX-XXXX) - Production Base URL
- Webhook IP Whitelist
Production credential approval typically takes 3-5 business days after document submission.
Environment Configuration
1. Separate Environment Variables
Never mix sandbox and production credentials. Use separate environment files:2. Load Based on Environment
config.js
3. Use Secrets Manager (Recommended)
For production, use a secrets manager instead of.env files:
- AWS Secrets Manager
- Google Secret Manager
- Azure Key Vault
Production Checklist
Before deploying to production, verify each item:Security
Credentials Management
Credentials Management
- Production credentials stored in secrets manager (not in code)
-
.envfiles added to.gitignore - No credentials in version control history
- Secret rotation policy established
- Access to production credentials restricted to authorized personnel only
HTTPS & Transport Security
HTTPS & Transport Security
- All API calls use HTTPS (never HTTP)
- Valid SSL/TLS certificate installed
- TLS 1.2 or higher enforced
- Certificate expiration monitoring configured
Webhook Security
Webhook Security
- Webhook endpoint uses HTTPS
- Webhook payload decryption implemented
- Firewall configured to accept only Modulus Labs IPs
- Request origin validation implemented
- Rate limiting configured
Input Validation
Input Validation
- Amount validation (1.00 - 99,999.99)
- Currency code validation (PHP only)
- Merchant reference number validation (1-36 chars)
- Activation code format validation
- SQL injection prevention
- XSS prevention for user-facing displays
Reliability
Error Handling
Error Handling
- All API calls wrapped in try-catch
- Proper error logging implemented
- User-friendly error messages
- Retry logic for transient failures
- Circuit breaker pattern for API failures
- Graceful degradation when API unavailable
Monitoring & Alerting
Monitoring & Alerting
- API response time monitoring
- Error rate tracking
- Webhook delivery monitoring
- Transaction volume monitoring
- Alerting configured for critical failures
- Health check endpoints implemented
Logging
Logging
- All API requests logged (excluding sensitive data)
- All webhook receipts logged
- Transaction IDs tracked
- Log retention policy configured
- Log aggregation service configured
Performance
Scalability
Scalability
- Load testing completed
- Auto-scaling configured
- Database connection pooling implemented
- Caching strategy for QR codes if needed
- CDN configured for static assets
Rate Limiting
Rate Limiting
- Client-side rate limiting implemented
- Exponential backoff for retries
- Request queuing for high traffic
- 429 (Too Many Requests) handling
Compliance
Data Protection
Data Protection
- PII handling compliant with regulations
- Data retention policy established
- Audit trail for all transactions
- Customer data encrypted at rest
- Privacy policy updated
Business Operations
Business Operations
- Settlement account configured
- Reconciliation process established
- Refund process documented
- Customer support trained
- Dispute resolution process defined
Deployment Process
1. Pre-deployment Testing
2. Deploy to Staging
Deploy to a staging environment that mirrors production:3. Deploy to Production
1
Schedule Deployment
Choose low-traffic period for deployment (e.g., 2 AM local time)
2
Notify Stakeholders
Alert customer support, operations team, and key stakeholders
3
Create Backup
4
Deploy
5
Verify
- Test health check endpoint
- Create a small test transaction (₱1.00)
- Verify webhook delivery
- Check monitoring dashboards
- Review logs for errors
6
Monitor
Actively monitor for 1-2 hours after deployment:
- Error rates
- Response times
- Transaction success rates
- Webhook delivery rates
4. Rollback Plan
Prepare a rollback plan in case issues arise:Production URL Configuration
Update all API calls to use production URL:Verify No Sandbox URLs Remain
Production Best Practices
Idempotency
Use unique
merchantReferenceNumber for each transaction to prevent duplicatesRetry Logic
Implement exponential backoff with max retries (3-5 attempts)
Timeouts
Set appropriate timeouts (10-30 seconds for API calls)
Circuit Breaker
Fail fast when API is down, prevent cascading failures
Monitoring
Track success rates, latency, and error rates in real-time
Logging
Log all transactions with sufficient detail for debugging
Alerts
Set up alerts for error spikes, latency increases, webhook failures
Documentation
Maintain runbooks for common production issues
Monitoring Production
Key Metrics to Track
Example Monitoring Setup
Handling Production Issues
Common Production Issues
API Rate Limiting (429 Error)
API Rate Limiting (429 Error)
Symptoms:
- HTTP 429 responses
- Increased latency
- Failed QR creations
- Implement request queuing
- Add exponential backoff
- Cache QR codes when appropriate
- Contact Modulus Labs to increase rate limit
Webhook Delivery Failures
Webhook Delivery Failures
Symptoms:
- Payments not updating in system
- Manual reconciliation needed
- Customer complaints
- Check webhook endpoint health
- Review firewall rules
- Verify SSL certificate
- Check webhook processing logs
- Contact Modulus Labs to resend webhooks
High Error Rates
High Error Rates
Symptoms:
- Sudden spike in API errors
- Multiple error codes
- Customer complaints
- Check Modulus Labs status page
- Review recent code changes
- Check production credentials haven’t expired
- Verify network connectivity
- Review error logs for patterns
Performance Degradation
Performance Degradation
Symptoms:
- Slow QR code generation
- Timeouts
- Poor user experience
- Check database performance
- Review application logs
- Scale horizontally (add more servers)
- Optimize database queries
- Implement caching
Emergency Contacts
Production Support
Email: [email protected]
Phone: Available in partner portal
SLA: < 1 hour response for critical issues
Status Page
URL: status.moduluslabs.io
Check for ongoing incidents or maintenance
Technical Support
Email: [email protected]
For integration and API questions
Account Manager
Contact your dedicated account manager
For business and billing questions
Production Maintenance
Regular Tasks
1
Daily
- Monitor error rates and alerts
- Review transaction volumes
- Check webhook delivery rates
- Scan security logs
2
Weekly
- Review performance metrics
- Analyze transaction patterns
- Update documentation
- Review and address technical debt
3
Monthly
- Rotate API keys (if policy requires)
- Update dependencies and security patches
- Review and optimize database
- Conduct security audit
- Business reconciliation
4
Quarterly
- Disaster recovery drill
- Load testing
- Review SLAs and performance
- Update runbooks
- Security penetration testing
Key Rotation
Rotate production credentials periodically:Scaling for Growth
As your transaction volume grows:Horizontal Scaling
Database Optimization
Caching Strategy
Next Steps
Webhooks
Implement production webhook handling
Monitoring Setup
See monitoring examples above for Prometheus, DataDog, and CloudWatch
API Reference
Review production API documentation
Support
Contact production support team
You’re ready for production! Follow this guide carefully and don’t hesitate to contact Modulus Labs support if you need assistance.