Introduction
Overview
Wallet-as-a-Service (WaaS) is a financial wallet integration API that enables businesses to create, manage, and process transactions for customer wallets. The service provides comprehensive wallet management capabilities including creation, balance checking, transaction processing, and real-time notifications.
Environment: Production and Sandbox endpoints provided during integration
Protocol: HTTPS only
Format: RESTful API with JSON request/response format
Key Features:
- Customer wallet creation and management
- Real-time balance enquiries
- Secure debit transactions
- Transaction status tracking
- Transaction reversal (within 1 hour)
- Real-time webhook notifications
- Name verification services
Authentication & Security
Required Headers All POST requests require the following headers:
curl -X POST
-H "x-Client-Id: [Your unique client identifier]"
-H "x-hash-key: [Generated security hash]"
-H "Content-Type: application/json"
'
Hash Key Generation Algorithm
The security model uses different hash calculations based on the endpoint:
| Endpoint Type | Hash Formula | Notes |
|---|---|---|
| Wallet Creation | sha256(clientSecret + payload) | Initial setup |
| Wallet Debit | sha256(CustomerMAC + clientSecret + payload) | Requires CustomerMAC |
| Other POST Requests | sha256(clientSecret + payload) | Standard operations |
| GET Requests | sha256(clientSecret + payload) | Empty payload strings |
Components
- clientSecret: Provided during integration (keep secure)
- ayload: Complete JSON request body as string
- CustomerMAC: macchecksum from wallet creation response
Important Security Notes:
- Never expose clientSecret in client-side code
- Store macchecksum securely (encrypted database)
- Regenerate hashes for each request
- Validate all incoming webhook signatures (if implemented)
- Use environment variables for sensitive data
- Implement request logging without sensitive info
- Validate all inputs
- Use HTTPS for all communications
Implementation Checklist
Obtain the following from WaaS provider:
- clientId
- clientSecret
- schemeId
- walletShemeTierId
- baseUrl
Set up your environments
Configure secure credential storage
Set up logging and monitoring systems
Develop webhook endpoint (HTTPS)
Create error handling framework
Test with sample payloads
Deploy to staging environment
Perform UAT with test wallets
Register production webhook URL
Go-live with monitoring