Authentication

NjiaPay uses API keys for authentication. All API requests must include a valid API key in the Authorization header to authenticate your requests.

API Keys

API keys are environment-specific and should be kept secure at all times. You'll need different keys for sandbox testing and production usage.

Obtaining API Keys

For sandbox environment: Your API keys will be provided to you by NjiaPay support. Contact our team to request sandbox credentials.

For production environment:

1. Log into the merchant portal
2. Navigate to Settings > API Keys
3. Click Generate New API Key
4. Copy and securely store your API key
5. Never share or expose this key publicly

Environments

NjiaPay provides two separate environments with different base URLs and API keys:

Sandbox Environment

Purpose: Testing your integration without processing real payments

• Base URL: https://app.staging.infinic.dev/
• API Keys: Provided by NjiaPay support during onboarding
• Behavior: Mock payment processor simulates various scenarios

Production Environment

Purpose: Processing real payments from real customers

• Base URL: https://app.infinic.com/
• API Keys: Generated from the merchant portal
• Behavior: Real payment processing with actual PSPs

You can learn more about the different environments in our environments documentation

Making Authenticated Requests

To authenticate your API requests, include your API key in the Authorization header using the Bearer token scheme:

Authorization: Bearer YOUR_API_KEY

Example Requests

curl -X GET https://app.staging.infinic.dev/api/intents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://app.staging.infinic.dev/api/intents/550e8400-e29b-41d4-a716-446655440000",
  {
    headers: {
      Authorization: `Bearer ${YOUR_API_KEY}`,
    },
  },
);

import requests

response = requests.get(
    'https://app.staging.infinic.dev/api/intents/550e8400-e29b-41d4-a716-446655440000',
    headers={'Authorization': f'Bearer {YOUR_API_KEY}'}
)

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,
  'https://app.staging.infinic.dev/api/intents/550e8400-e29b-41d4-a716-446655440000');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . YOUR_API_KEY
]);

$response = curl_exec($ch);
curl_close($ch);

API Key Format

API keys follow this format:

{environment}_{merchant_id}_{random_string}

Examples:

• Sandbox: test_merchant_abc123_xxxxxxxxxxxxxxxx
• Production: live_merchant_abc123_xxxxxxxxxxxxxxxx

The prefix indicates the environment:

• test_ - Sandbox environment
• live_ - Production environment

Security Best Practices

✅ DO

• Store API keys in environment variables or secure secret management systems
• Use different API keys for different environments (sandbox vs production)
• Rotate your API keys periodically
• Revoke compromised keys immediately via the merchant portal
• Keep API keys on your server-side code only

❌ DON'T

• Commit API keys to version control systems (Git, SVN, etc.)
• Expose API keys in client-side JavaScript code
• Share API keys in public forums, chat, or email
• Use production keys in sandbox/testing environments
• Hard-code API keys directly in your source code

Example: Environment Variables

Store your API key in environment variables:

# .env file (add to .gitignore!)
NJIAPAY_API_KEY=live_merchant_abc123_xxxxxxxxxxxxxxxx
NJIAPAY_BASE_URL=https://app.infinic.com

// Load from environment
const apiKey = process.env.NJIAPAY_API_KEY;
const baseUrl = process.env.NJIAPAY_BASE_URL;

const response = await fetch(`${baseUrl}/api/intents`, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

import os

# Load from environment
api_key = os.environ['NJIAPAY_API_KEY']
base_url = os.environ['NJIAPAY_BASE_URL']

response = requests.get(
    f'{base_url}/api/intents',
    headers={'Authorization': f'Bearer {api_key}'}
)

Authentication Errors

401 Unauthorized

This error occurs when your API key is invalid, missing, or malformed.

{
  "detail": "Invalid or missing API key"
}

Common causes:

• Missing Authorization header
• Incorrect header format (missing "Bearer " prefix)
• Invalid or expired API key
• Using sandbox key with production URL (or vice versa)

Resolution:

1. Verify your API key is correct
2. Check the header format: Authorization: Bearer YOUR_API_KEY
3. Ensure you're using the correct base URL for your environment
4. Regenerate your API key if it has been compromised

403 Forbidden

This error occurs when your API key is valid but doesn't have permission for the requested resource.

{
  "detail": "Not authorized to access this resource"
}

Common causes:

• Attempting to access another merchant's resources
• Using API key without required permissions
• Accessing disabled or inactive merchant account

Resolution:

• Verify you're using the correct API key for your merchant account
• Contact support if you believe you should have access

Alternative Authentication Methods

Intent Token (iauth)

For certain endpoints that customers interact with directly (like retrieving payment intent details from the checkout page), you can use an intent token instead of an API key.

The intent token is returned when you create a payment intent and can be passed as a query parameter:

GET /api/intents/{intent_id}?iauth={intent_token}

This allows customers to view their own payment details without exposing your API key.

Testing Authentication

You can verify your authentication is working correctly by making a test request:

curl -X POST https://app.staging.infinic.dev/api/intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "ZAR",
    "reference_id": "test_auth",
    "purchaser_id": "test_user",
    "return_url": "https://example.com",
    "allow_remember_credentials": false
  }'

If authentication is successful, you'll receive a 201 Created response with a payment intent. If it fails, you'll receive a 401 Unauthorized error.

Next Steps

Now that you understand authentication, you're ready to start integrating: