Environments

NjiaPay provides two separate environments to support your development and production workflows. Each environment has its own base URL, API keys, and behavior.

Environment Overview

Sandbox Environment

The sandbox environment is designed for testing your integration without processing real payments or incurring charges.

Base URL

https://app.staging.infinic.dev/

Key Features

✅ Safe Testing

• No real money is processed
• No actual charges to cards
• Free to use indefinitely

✅ Mock Payment Processor

• Simulates successful payments
• Test decline scenarios
• Simulate error responses

✅ Full API Access

• All endpoints available
• Same API structure as production
• Test webhooks

✅ Realistic Behavior

• Payment flows mirror production
• Status transitions work the same
• Webhook delivery identical to production

Obtaining Sandbox API Keys

Sandbox API keys are provided by NjiaPay support:

1. Contact NjiaPay support team
2. Request sandbox credentials
3. Receive API key via secure channel
4. Start testing immediately

Sandbox Limitations

Testing with MockPSP

The sandbox uses MockPSP to simulate different payment scenarios:

Successful Payment (Default)

{
  "payment_method": {
    "number": "4242424242424242",
    "holder_name": "John Doe",
    "expiry_month": "12",
    "expiry_year": "2026",
    "cvv": "123"
  }
}

Result: Payment succeeds

Declined Payment

{
  "payment_method": {
    "number": "4242424242424242",
    "holder_name": "DECLINED", // ← Set holder name to "DECLINED"
    "expiry_month": "12",
    "expiry_year": "2026",
    "cvv": "123"
  }
}

Result: Payment declined with REFUSED result

Error Response

{
  "payment_method": {
    "number": "4242424242424242",
    "holder_name": "ERROR", // ← Set holder name to "ERROR"
    "expiry_month": "12",
    "expiry_year": "2026",
    "cvv": "123"
  }
}

Result: Payment fails with ERROR result

Using Merchant Reference

{
  "reference_id": "{\"status\": \"declined\"}" // ← JSON string in reference
}

Result: Payment declined

{
  "reference_id": "{\"status\": \"error\"}" // ← JSON string in reference
}

Result: Payment error

See Testing Guide for complete details.

When to Use Sandbox

Use sandbox for:

• Initial development - Build your integration
• Testing flows - Test happy path and error scenarios
• Webhook testing - Verify webhook handling
• QA/Staging - Pre-production testing
• Demos - Demonstrate integration to stakeholders
• CI/CD pipelines - Automated integration tests

Production Environment

The production environment processes real payments with real payment service providers.

Base URL

https://app.infinic.com/

Key Features

✅ Real Payment Processing

• Actual charges to customer cards
• Real money transfer
• Live PSP integration

✅ High Availability

• Always online
• No spin-down behavior
• Production-grade infrastructure

✅ Real Webhooks

• Immediate notifications
• Guaranteed delivery with retries
• 7-day retry window

✅ Full Compliance

• PCI DSS compliant
• Data encryption at rest and in transit
• Audit logging

Obtaining Production API Keys

Production API keys are generated from the merchant portal:

1. Log into merchant portal
2. Navigate to Settings > API Keys
3. Click Generate New API Key
4. Copy and securely store your key
5. Use in your production application

Production Checklist

Before going live, ensure:

• Tested all payment flows in sandbox
• Implemented proper webhook handling
• Added error handling for all failure scenarios
• Stored API keys in environment variables
• Set up monitoring and alerting
• Documented your integration
• Set up logging for troubleshooting
• Configured return_url to production domain
• Verified webhook URL is publicly accessible

Switching Between Environments

Environment-Specific Configuration

Store environment configuration separately:

// config/environments.js
const environments = {
  sandbox: {
    baseUrl: "https://app.staging.infinic.dev",
    apiKey: process.env.NJIAPAY_SANDBOX_API_KEY,
  },
  production: {
    baseUrl: "https://app.infinic.com",
    apiKey: process.env.NJIAPAY_PRODUCTION_API_KEY,
  },
};

const env = process.env.NODE_ENV === "production" ? "production" : "sandbox";
module.exports = environments[env];

# config/environments.py
import os

ENVIRONMENTS = {
    'sandbox': {
        'base_url': 'https://app.staging.infinic.dev',
        'api_key': os.environ['NJIAPAY_SANDBOX_API_KEY']
    },
    'production': {
        'base_url': 'https://app.infinic.com',
        'api_key': os.environ['NJIAPAY_PRODUCTION_API_KEY']
    }
}

ENV = 'production' if os.environ.get('ENVIRONMENT') == 'production' else 'sandbox'
config = ENVIRONMENTS[ENV]

# .env.sandbox
NJIAPAY_BASE_URL=https://app.staging.infinic.dev
NJIAPAY_API_KEY=test_merchant_abc_xxxxxxxxxxxxx

# .env.production
NJIAPAY_BASE_URL=https://app.infinic.com
NJIAPAY_API_KEY=live_merchant_abc_xxxxxxxxxxxxx

Data Isolation

Each environment maintains completely separate data:

• Separate databases - No data sharing between environments
• Separate intents - Intent IDs don't overlap
• Separate credentials - Stored payment methods are per-environment
• Separate webhooks - Configure webhook URLs independently

Mode Property

All payment intents include a mode property indicating which environment they belong to:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "test",  // or "live"
  "amount": 10000,
  "currency": "ZAR",
  ...
}

This helps you filter and separate transactions in analytics and reporting.

Best Practices

✅ DO

• Use sandbox for all development and testing
• Test thoroughly in sandbox before production
• Use separate API keys for each environment
• Store API keys in environment variables
• Configure different webhook URLs per environment
• Monitor both environments separately
• Test failure scenarios in sandbox

❌ DON'T

• Use production API keys in development
• Test in production with real customer data
• Share API keys between environments
• Hard-code API keys or URLs
• Skip sandbox testing
• Use sandbox for production traffic

Troubleshooting

Sandbox Slow Response

Issue: First request to sandbox takes 10-20 seconds

Solution: This is expected due to spin-down. Subsequent requests will be fast. Consider:

• Warming up sandbox with a health check request
• Waiting patiently on first request
• Using production for performance testing

Wrong Environment

Issue: API key doesn't work or unexpected behavior

Solution: Verify:

• API key prefix matches environment (test*/live*)
• Base URL matches environment
• Webhook URL is configured for correct environment

Can't Access Production

Issue: Don't have production API keys

Solution:

• Log into merchant portal at https://portal.njiapay.com
• If no account, contact NjiaPay support
• Request production access

Related Topics