Using the API
Learn how to authenticate and use the Nkwa Pay API, including environment endpoints, API key management, and additional security features.
Using the Nkwa Pay API
Nkwa Pay provides a robust API for integrating mobile money payments into your applications. This guide explains how to authenticate your requests and use the API effectively.
API Environments
When you create an account with Nkwa Pay, you first gain access to the sandbox environment, which is isolated from the production environment. This allows you to test your integration thoroughly before going live.
The base URL differs for each environment. You can call specific operations by appending the endpoint to the appropriate base URL.
Environment | Base URL |
---|---|
Sandbox | https://api.sandbox.nkwapay.com/ |
Production | https://api.nkwapay.com/ |
Authentication
Nkwa Pay uses API key authentication for all requests. You can generate an API key from the Nkwa Pay portal, and each request must include this key in the X-API-KEY
header.
If the API key is revoked or invalid, the request will return a 401 Unauthorized
response.
Never share your API keys or embed them directly in client-side code. Always store API keys securely and use server-side code to make API requests.
Additional Security Layers
Nkwa Pay offers several additional security features to protect your integration:
1. IP Whitelisting
You can configure a list of allowed IP addresses from which Nkwa Pay will accept API requests. This prevents unauthorized use of your API key even if it becomes compromised.
To set up IP whitelisting:
- Log in to the Nkwa Pay portal
- Navigate to API Settings
- Add the IP addresses that should be allowed to make API calls
2. Request Signatures
The API provides an extra layer of security by returning a signature in the X-Sig
response header. This allows you to verify that responses are genuinely from Nkwa Pay.
- The signature is generated using the request body, timestamp, and URL, and is encrypted using the
RS256
algorithm - You can find the public key for signature verification in the Nkwa Pay portal
- We recommend validating this signature for sensitive operations
3. Request Encryption
For maximum security, you can enable request encryption:
- If enabled, you will need to include a signature in the
X-Sig
request header, generated using theRS256
algorithm and signed with your private key - You’ll need to upload your public key to the Nkwa Pay portal so we can verify your requests
- This ensures that even if your API communication is intercepted, the contents remain secure
API Request Flow
A typical API request flow follows these steps:
- Prepare Request: Construct your API request with the required parameters
- Add Authentication: Include your API key in the
X-API-KEY
header - Send Request: Send the request to the appropriate endpoint
- Process Response: Handle the API response in your application
- Verify Signature: For sensitive operations, verify the signature in the
X-Sig
header
API Response Codes
The API uses standard HTTP response codes to indicate success or failure:
2xx
: Success (e.g.,200 OK
,201 Created
)4xx
: Client error (e.g.,400 Bad Request
,401 Unauthorized
,403 Forbidden
,404 Not Found
)5xx
: Server error (e.g.,500 Internal Server Error
)
Rate Limiting
To ensure system stability, the API implements rate limiting. If you exceed the rate limits, you’ll receive a 429 Too Many Requests
response.
The current limits are:
- 100 requests per minute for sandbox environment
- 300 requests per minute for production environment
Best Practices
- Use SDKs When Possible: Our language-specific SDKs handle much of the authentication and request formatting for you
- Implement Proper Error Handling: Account for all possible API response codes in your application
- Use Webhooks: Instead of polling for status updates, configure webhooks to receive real-time notifications
- Test Thoroughly: Use the sandbox environment to test all aspects of your integration before going to production
- Monitor Your Integration: Regularly check your API usage and payment success rates to identify potential issues