Authentication
All API requests must be authenticated using your merchant API credentials. Requests without valid credentials are rejected with HTTP 401.
Credential Types
| Credential | Header | Description |
|---|---|---|
| API Key | X-API-Key |
Public identifier prefixed with SVX_. Safe to use in webhook signature verification. |
| Secret Key | X-Secret-Key |
Private key prefixed with SVS_. Never expose in client-side code, mobile apps, or public repositories. |
| Merchant ID | — | Your unique merchant identifier (e.g. MCHXXXXXXXX). Displayed in dashboard; not required in API headers. |
Request Headers
| Header | Required | Value |
|---|---|---|
X-API-Key | Yes | Your API Key |
X-Secret-Key | Yes | Your Secret Key |
Content-Type | Yes (POST) | application/json |
Never share your Secret Key. If compromised, regenerate credentials immediately from the merchant dashboard (requires MPIN + OTP).
IP Whitelisting
For enhanced security, all API requests must originate from IP addresses whitelisted in your merchant dashboard. If no IPs are configured, requests from any IP are allowed — we strongly recommend whitelisting your production server IPs.
- Add IPs in Merchant Dashboard → API Management → IP Whitelist
- Supports IPv4 addresses (e.g.
203.0.113.45) - Requests from non-whitelisted IPs return HTTP
403
Credential Regeneration
Regenerating credentials invalidates the previous API Key and Secret Key immediately. To regenerate:
- Enter your MPIN
- Verify OTP on registered mobile
- New credentials are displayed once — copy and update your server configuration
Alternative: Body Parameters
Credentials can also be passed in the request body (not recommended for production):
{
"api_key": "SVX_...",
"secret_key": "SVS_...",
"order_id": "ORD-001",
"amount": 100
}Security Best Practices
- Store Secret Key in environment variables, not source code
- Use HTTPS for all API and webhook endpoints
- Whitelist only necessary server IPs
- Verify webhook signatures on every incoming notification
- Rotate credentials periodically or after team member changes
- Monitor API access logs in your merchant dashboard