Skip to main content

​
Authentication

All requests to the Notch Pay API must be authenticated. This guide explains the authentication methods available and how to implement them securely.

API Keys

Notch Pay uses API keys to authenticate requests. You can find your API keys in your Notch Pay Business suite under Settings > API Keys.
  • Test Keys
  • Live Keys
Test API Keys: Used for development and testing. These keys contain test_ prefix.All transactions made with test API keys don’t affect your live data and are only visible in test mode.

​
Authentication Methods

  • Standard Authentication
  • Advanced Authentication
  • Sync Account Authentication
For most API requests, you need to include your API key in the Authorization header:
Authorization: YOUR_PUBLIC_KEY

​
Example Request

curl https://api.notchpay.co/payments \
  -H "Authorization: YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "customer": {
      "email": "customer@example.com"
    }
  }'

​
API Key Security

1

Keep API Keys Private

Never share your API keys in publicly accessible areas such as GitHub, client-side code, or social media.
2

Whitelist Your IP Addresses

For API transfers, you must add your IP address to the whitelist in your dashboard at https://business.notchpay.co/settings/developer/ips
3

Use Environment Variables

Use environment variables or secure vaults to store API keys in your applications.
// Example in Node.js
const apiKey = process.env.NOTCHPAY_API_KEY;
4

Implement Access Controls

Implement proper access controls to limit who can access your API keys.Only give access to team members who absolutely need it.
5

Rotate Keys Regularly

Rotate your API keys periodically, especially if you suspect they may have been compromised.You can generate new API keys in your Notch Pay dashboard.
6

Use Test Keys for Development

Use test API keys for development and testing to avoid accidental charges.Switch to live keys only when you’re ready to process real transactions.

​
Error Responses

Authentication Error Responses

{
  "code": 401,
  "status": "Unauthorized",
  "message": "API key is missing"
}
This error occurs when you don’t include the Authorization header in your request.
{
  "code": 401,
  "status": "Unauthorized",
  "message": "Invalid API key"
}
This error occurs when the API key you provided is incorrect or has been revoked.
{
  "code": 403,
  "status": "Forbidden",
  "message": "This endpoint requires additional authentication"
}
This error occurs when you try to access an endpoint that requires the X-Grant header without providing it.
{
  "code": 403,
  "status": "Forbidden",
  "message": "Invalid grant key"
}
This error occurs when the private key you provided in the X-Grant header is incorrect.
{
  "code": 404,
  "status": "Not Found",
  "message": "Sync account not found"
}
This error occurs when the sync account ID you provided in the X-Sync header doesn’t exist or you don’t have access to it.

​
Best Practices

Use HTTPS

Always use HTTPS to encrypt your API requests and prevent man-in-the-middle attacks.Never send API requests over unencrypted HTTP connections.

Proper Error Handling

Handle authentication errors gracefully in your application.Implement retry logic with exponential backoff for transient errors.

Limit API Key Exposure

Only share API keys with trusted systems and developers.Consider using different API keys for different services or environments.

Monitor API Usage

Regularly review your API logs to detect unauthorized access.Set up alerts for unusual API activity patterns.

Implement Rate Limiting

Protect your API endpoints from brute force attacks by implementing rate limiting.Consider using a service like Redis to track and limit request rates.

​
Next Steps

API Reference

Explore the complete API documentation

Errors

Learn about error handling in the Notch Pay API

Security Best Practices

Discover more ways to secure your integration