​
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.
EnvironmentBase URL
Sandboxhttps://api.pay.staging.mynkwa.com/
Productionhttps://api.pay.mynkwa.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. 
curl https://api.pay.staging.mynkwa.com/payments/:id -H "X-API-KEY: your_api_key"
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:
  1. Log in to the Nkwa Pay portal
  2. Navigate to API Settings
  3. 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 the RS256 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:
  1. Prepare Request: Construct your API request with the required parameters
  2. Add Authentication: Include your API key in the X-API-KEY header
  3. Send Request: Send the request to the appropriate endpoint
  4. Process Response: Handle the API response in your application
  5. 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

  1. Use SDKs When Possible: Our language-specific SDKs handle much of the authentication and request formatting for you
  2. Implement Proper Error Handling: Account for all possible API response codes in your application
  3. Use Webhooks: Instead of polling for status updates, configure webhooks to receive real-time notifications
  4. Test Thoroughly: Use the sandbox environment to test all aspects of your integration before going to production
  5. Monitor Your Integration: Regularly check your API usage and payment success rates to identify potential issues