Proper authentication is essential for securing your Notch Pay integration. This guide explains the key concepts of authentication and how to get started with implementing it in your applications.

API Keys Overview

Notch Pay uses API keys to authenticate requests to our API. When you create a Notch Pay account, you’ll receive two sets of API keys:

Test API Keys

Used for development and testing. These keys contain the 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.

You can find your API keys in your Notch Pay Business suite under Settings > API Keys.

Types of API Keys

Notch Pay provides two types of API keys for different purposes:

Public keys (starting with pk_) are used for client-side operations that don’t require access to sensitive data. These keys can be safely included in your frontend code.

Example: pk_test_123456789abcdef

Use for: Creating payment sessions, initializing the Notch Pay SDK in client-side code

Authentication Methods

Notch Pay supports several authentication methods depending on the type of operation:

Standard Authentication

For most API requests, include your API key in the Authorization header:

Authorization: YOUR_PUBLIC_KEY

Advanced Authentication

Some sensitive operations require additional authentication using the X-Grant header with your private key:

X-Grant: YOUR_PRIVATE_KEY

Sync Account Authentication

When working with connected accounts, specify the account using the X-Sync header:

X-Sync: SYNC_ACCOUNT_ID

API Key Security

1

Keep Keys Secure

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

2

Use Environment Variables

Store API keys in environment variables or secure vaults, not in your application code.

3

Implement Access Controls

Limit who can access your API keys within your organization.

4

Rotate Keys Regularly

Periodically rotate your API keys, especially if you suspect they may have been compromised.

5

Use Test Keys for Development

Always use test API keys for development and testing to avoid accidental charges.

Common Authentication Errors

The API returns specific error codes and messages when authentication fails:

ErrorDescriptionSolution
401 - API key missingNo API key was providedInclude your API key in the Authorization header
401 - Invalid API keyThe API key is incorrect or revokedCheck that you’re using the correct API key
403 - Missing grant keyAdvanced authentication requiredInclude your private key in the X-Grant header
403 - Invalid grant keyThe private key is incorrectVerify your private key is correct
404 - Sync account not foundInvalid sync account IDCheck that the sync account exists and you have access to it

Next Steps