Prerequisites
| Requirement | Minimum version |
|---|---|
| NestJS | 10.0 |
| Node.js | 18.0 |
| Simiz account | Create one free |
Installation
Import the module
Register the Simiz module in your Or use
AppModule:forRootAsync for dynamic configuration:Usage
Inject the service
Webhook controller
SimizWebhookGuard automatically verifies the HMAC-SHA256 signature.
DTOs
The package includes built-in DTOs for request validation:Supported payment methods
| Method | Type | Status |
|---|---|---|
| Orange Money | Mobile Money | Available |
| MTN Mobile Money | Mobile Money | Available |
| Wave | Mobile Money | Coming Soon |
| Moov Money | Mobile Money | Coming Soon |
| Airtel Money | Mobile Money | Coming Soon |
| M-Pesa | Mobile Money | Coming Soon |
Supported currencies
| Currency | Code | Countries |
|---|---|---|
| Central African CFA Franc | XAF | Cameroon, Central African Republic, Chad, Congo, Equatorial Guinea, Gabon |
| West African CFA Franc | XOF | Benin, Burkina Faso, Ivory Coast, Guinea-Bissau, Mali, Niger, Senegal, Togo |
| Ghanaian Cedi | GHS | Ghana |
| Nigerian Naira | NGN | Nigeria |
| Kenyan Shilling | KES | Kenya |
| Ugandan Shilling | UGX | Uganda |
| Rwandan Franc | RWF | Rwanda |
| Tanzanian Shilling | TZS | Tanzania |
Webhook events
| Event | Description |
|---|---|
transaction.created | Transaction initiated |
transaction.processing | Being processed by the provider |
transaction.completed | Payment successful |
transaction.failed | Payment failed |
transaction.cancelled | Cancelled by customer |
transaction.expired | Payment window expired |
refund.created | Refund initiated |
refund.completed | Refund completed |
refund.failed | Refund failed |
Test mode
Set the following environment variables:sandbox.api.simiz.io and no real money is charged.
Full sandbox documentation
See all test numbers and scenarios in the Sandbox Testing guide.
Troubleshooting
- Webhook signature invalid
- Module not injecting
- API key errors
Solutions:
- Verify
SIMIZ_WEBHOOK_SECRETis set correctly - Ensure no middleware is parsing the body before the guard (use raw body)
- Enable raw body in your NestJS app:
app.useBodyParser('raw', { type: 'application/json' })
Next steps
Node.js SDK
Explore the underlying Node.js SDK for advanced usage.
Webhook Verification
Learn about webhook configuration and signature verification.
API Reference
Explore the full Simiz API.
Support
Need help? Contact our support team.
Changelog
Version history
Version history
| Version | Date | Changes |
|---|---|---|
1.0.0 | 2026-03-01 | Initial release — mobile money payments, webhooks, sandbox |

