Overview
The Modulus Labs Sandbox environment allows you to test your QR Ph integration without processing real payments. The sandbox mirrors production behavior, making it perfect for development and testing.Sandbox vs. Production: The sandbox environment uses separate credentials and URLs. No real money changes hands in sandbox mode.
Prerequisites
Before testing, ensure you have:1
Sandbox Credentials
- Secret Key (for authentication)
- Encryption Key (for JWE tokens)
- Activation Code (for your sub-merchant account)
2
Webhook Integration
Register a webhook endpoint using the Modulus Labs Webhooks API to receive payment notifications
3
Development Environment
Set up your local development environment with the required libraries (jose, axios, etc.)
Testing Workflow
Testing Dynamic QR Ph requires simulating the entire payment flow:1
Register Webhook
Create a webhook endpoint to receive transaction status updates
2
Create QR Code
Generate a Dynamic QR Ph using the Create API
3
Convert QR Body
Convert the Base64-encoded QR body to an image
4
Decode QR Image
Extract the raw QR value from the generated image
5
Simulate Payment
Use the Simulate Webhook API to trigger a payment event
6
Receive Webhook
Your webhook endpoint receives the transaction status
Step 1: Register a Webhook
First, register your webhook URL to receive payment notifications:Step 2: Create a Dynamic QR Code
Generate a QR code for testing:Step 3: Convert Base64 to QR Image
TheqrBody field contains a Base64-encoded PNG image. Convert it to an image file:
Online Converter (For Quick Testing)
Alternatively, use this online tool:- Visit https://base64.guru/converter/decode/image/png
- Paste your Base64-encoded QR body
- Click “Decode” to generate the image
- Download the PNG file

Step 4: Decode the QR Image
Extract the raw QR value from the image:Using Online Tool
- Visit https://zxing.org/w/decode.jspx
- Upload your QR code image
- Click “Submit”
- Copy the raw text value
Using Code
Step 5: Simulate Payment
Now simulate a payment by calling the Simulate Webhook API:Step 6: Receive Webhook Notification
After simulating the payment, your webhook endpoint will receive a notification:Successful Payment Webhook
Failed Payment Webhook
Test Scenarios
Test different scenarios to ensure your integration handles all cases:Successful Payment
Successful Payment
Use Case:
SUCCESSExpected Result: Webhook receives payment.succeeded eventTest: Verify your app processes successful payments correctlyMissing Revenue Account
Missing Revenue Account
Use Case:
MISSING_PARTNER_REVENUE_ACCOUNTExpected Result: Webhook receives payment.failed eventTest: Verify your app handles this specific error gracefullyInsufficient Funds
Insufficient Funds
Use Case:
INSUFFICIENT_FUNDSExpected Result: Webhook receives payment.failed eventTest: Ensure user is informed of insufficient fundsInvalid QR Code
Invalid QR Code
Use Case: Use a malformed or expired QR valueExpected Result: API returns error before webhook is sentTest: Verify error handling for invalid QR codes
Duplicate Payment
Duplicate Payment
Use Case: Reuse the same
merchantReferenceNumberExpected Result: API rejects duplicate transactionTest: Ensure idempotency is working correctlyTimeout Scenario
Timeout Scenario
Use Case: Delay webhook simulation by 30+ secondsExpected Result: Test timeout handling in your applicationTest: Verify your app doesn’t hang waiting for webhook
Complete Test Script
Here’s a complete end-to-end test script:Debugging Tips
Enable Verbose Logging
Log all requests, responses, and encryption/decryption steps
Use Webhook.site
Test webhook delivery without setting up a server
Check Base64 Encoding
Ensure Base64 strings aren’t corrupted during copy/paste
Verify Credentials
Double-check you’re using sandbox credentials, not production
Test Incrementally
Test each step independently before running end-to-end
Monitor Webhook Logs
Check webhook server logs for incoming requests
Common Issues
QR Code Won't Decode
QR Code Won't Decode
- Ensure the image was saved correctly from Base64
- Try a different QR decoder tool
- Check if the image file is corrupted
- Verify the Base64 string wasn’t truncated
Webhook Not Received
Webhook Not Received
- Verify webhook URL is publicly accessible
- Check webhook registration was successful
- Ensure firewall isn’t blocking incoming requests
- Use webhook.site for initial testing
Simulation Returns Error
Simulation Returns Error
- Verify the QR value was decoded correctly
- Check that the transaction hasn’t been used already
- Ensure proper authentication
- Verify the useCase parameter is valid