Skip to main content

Overview

This guide walks you through transitioning from sandbox to production, ensuring your QR payment integration is secure, reliable, and ready for real transactions.
Production involves real money transactions. Complete all testing in sandbox before going live.

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

Getting Production Credentials

1

Contact Modulus Labs

Email production@moduluslabs.io 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
For production, use a secrets manager instead of .env files:

Production Checklist

Before deploying to production, verify each item:

Security

  • Production credentials stored in secrets manager (not in code)
  • .env files added to .gitignore
  • No credentials in version control history
  • Secret rotation policy established
  • Access to production credentials restricted to authorized personnel only
  • All API calls use HTTPS (never HTTP)
  • Valid SSL/TLS certificate installed
  • TLS 1.2 or higher enforced
  • Certificate expiration monitoring configured
  • Webhook endpoint uses HTTPS
  • Webhook payload decryption implemented
  • Firewall configured to accept only Modulus Labs IPs
  • Request origin validation implemented
  • Rate limiting configured
  • 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

  • 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
  • API response time monitoring
  • Error rate tracking
  • Webhook delivery monitoring
  • Transaction volume monitoring
  • Alerting configured for critical failures
  • Health check endpoints implemented
  • All API requests logged (excluding sensitive data)
  • All webhook receipts logged
  • Transaction IDs tracked
  • Log retention policy configured
  • Log aggregation service configured

Performance

  • Load testing completed
  • Auto-scaling configured
  • Database connection pooling implemented
  • Caching strategy for QR codes if needed
  • CDN configured for static assets
  • Client-side rate limiting implemented
  • Exponential backoff for retries
  • Request queuing for high traffic
  • 429 (Too Many Requests) handling

Compliance

  • PII handling compliant with regulations
  • Data retention policy established
  • Audit trail for all transactions
  • Customer data encrypted at rest
  • Privacy policy updated
  • 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 duplicates

Retry 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

Symptoms:
  • HTTP 429 responses
  • Increased latency
  • Failed QR creations
Solutions:
  1. Implement request queuing
  2. Add exponential backoff
  3. Cache QR codes when appropriate
  4. Contact Modulus Labs to increase rate limit
Symptoms:
  • Payments not updating in system
  • Manual reconciliation needed
  • Customer complaints
Solutions:
  1. Check webhook endpoint health
  2. Review firewall rules
  3. Verify SSL certificate
  4. Check webhook processing logs
  5. Contact Modulus Labs to resend webhooks
Symptoms:
  • Sudden spike in API errors
  • Multiple error codes
  • Customer complaints
Solutions:
  1. Check Modulus Labs status page
  2. Review recent code changes
  3. Check production credentials haven’t expired
  4. Verify network connectivity
  5. Review error logs for patterns
Symptoms:
  • Slow QR code generation
  • Timeouts
  • Poor user experience
Solutions:
  1. Check database performance
  2. Review application logs
  3. Scale horizontally (add more servers)
  4. Optimize database queries
  5. Implement caching

Emergency Contacts

Production Support

Email: support@moduluslabs.io 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: tech@moduluslabs.io 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.