Authentication
Learn how to authenticate with the Notch Pay API
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 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.
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.
Live API Keys: Used for production environments.
Only use these keys when your application is ready for real transactions.
Authentication Methods
For most API requests, you need to include your API key in the Authorization
header:
Example Request
For most API requests, you need to include your API key in the Authorization
header:
Example Request
Include your private key in the X-Grant
header:
Endpoints Requiring Advanced Authentication
Endpoints Requiring Advanced Authentication
The following endpoints require the X-Grant
header:
/balance
- Check your account balance/transfers/*
- All transfer-related endpoints/beneficiaries/*
(or/recipients/*
) - All beneficiary-related endpoints/webhooks/*
- All webhook-related endpoints
Example Request with Advanced Authentication
For operations related to synchronized accounts, you need to pass the sync account identifier in the X-Sync
header:
Operations requiring Sync Authentication
Operations requiring Sync Authentication
This is necessary when you need to perform operations on behalf of a synchronized account, such as:
- Creating payments for a sync account
- Viewing transactions for a sync account
- Managing resources for a sync account
Example Request with Sync Authentication
API Key Security
Keep API Keys Private
Whitelist Your IP Addresses
Use Environment Variables
Use environment variables or secure vaults to store API keys in your applications.
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.
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.
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
Authentication Error Responses
Missing API Key
Missing API Key
This error occurs when you don’t include the Authorization
header in your request.
Invalid API Key
Invalid API Key
This error occurs when the API key you provided is incorrect or has been revoked.
Missing Grant Key
Missing Grant Key
This error occurs when you try to access an endpoint that requires the X-Grant
header without providing it.
Invalid Grant Key
Invalid Grant Key
This error occurs when the private key you provided in the X-Grant
header is incorrect.
Invalid Sync Account
Invalid Sync Account
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.