Quick Start

Get your first payment up and running in just 5 minutes. This guide will walk you through creating a payment intent, redirecting a customer to checkout, and receiving payment confirmation.

Prerequisites

Before you begin, make sure you have:

• An NjiaPay account (sandbox or production)
• API keys from NjiaPay support (sandbox) or our merchant portal (production)
• A server-side application that can make HTTP requests
• A webhook endpoint to receive payment notifications (optional but recommended)

Step 1: Get Your API Key

For sandbox testing, your API key will be provided by NjiaPay support.

For production, log into the merchant portal and generate your API key from the Settings section.

Your API key will look like this:

live_merchant_abc123_xxxxxxxxxxxx

Step 2: Create a Payment Intent

Make a POST request to create a payment intent. This will return a redirect_url that you'll use to send your customer to the checkout page.

curl -X POST https://app.infinic.com/api/intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ZAR",
    "reference_id": "order_12345",
    "purchaser_id": "customer_abc",
    "return_url": "https://yoursite.com/payment/callback",
    "allow_remember_credentials": false
  }'

const response = await fetch("https://app.infinic.com/api/intents", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "ZAR",
    reference_id: "order_12345",
    purchaser_id: "customer_abc",
    return_url: "https://yoursite.com/payment/callback",
    allow_remember_credentials: false,
  }),
});

const data = await response.json();
console.log("Redirect URL:", data.redirect_url);

import requests

response = requests.post(
    'https://app.infinic.com/api/intents',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 10000,
        'currency': 'ZAR',
        'reference_id': 'order_12345',
        'purchaser_id': 'customer_abc',
        'return_url': 'https://yoursite.com/payment/callback',
        'allow_remember_credentials': False
    }
)

data = response.json()
print('Redirect URL:', data['redirect_url'])

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "redirect_url": "https://app.infinic.com/checkout?intent=550e8400-e29b-41d4-a716-446655440000&token=eyJ0eXAi..."
}

Step 3: Redirect Customer to Checkout

Take the redirect_url from the response and redirect your customer to it. This can be done via:

• HTTP redirect (302/307)
• JavaScript redirect (window.location.href)
• HTML link (<a href="...">Pay Now</a>)

// Example: JavaScript redirect
window.location.href = data.redirect_url;

The hosted checkout page will:

1. Display available payment methods
2. Handle payment collection securely
3. Process 3D Secure authentication if needed
4. Redirect back to your return_url when complete

Step 4: Handle the Return

After the customer completes (or cancels) the payment, they'll be redirected back to your return_url with query parameters:

https://yoursite.com/payment/callback?intent_id=550e8400-e29b-41d4-a716-446655440000&status=success

Step 5: Verify Payment Status

Query the payment intent status using the GET endpoint:

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

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

const intent = await response.json();
console.log("Payment status:", intent.status);

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

intent = response.json()
print('Payment status:', intent['status'])

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "amount": 10000,
  "currency": "ZAR",
  "reference_id": "order_12345", // Your own provided reference
  "purchaser_id": "customer_abc",
  ...
}

Payment statuses:

• selection - Customer is choosing a payment method
• pending - Payment is processing
• success - Payment completed successfully ✅
• failed - Payment failed
• canceled - Payment was canceled

Step 6: Set Up Webhooks (Recommended)

For production integrations, you should use webhooks to receive real-time payment updates instead of polling the API.

1. Set your webhook URL in the merchant portal
2. Listen for StatusChange events
3. Verify the payment status and fulfill the order

Example webhook payload:

{
  "type": "StatusChange",
  "created": "2024-09-01T00:00:00Z",
  "content": {
    "intent_id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_id": "order_12345", // Your own provided reference
    "amount": 10000,
    "currency": "ZAR",
    "status": "success"
  }
}

See the Webhooks Guide for complete implementation details.

Testing Your Integration

Use our MockPSP in the sandbox environment to test different payment scenarios:

Successful Payment

Enter any card details. The payment will succeed automatically.

Declined Payment

Set the cardholder name to DECLINED. The payment will fail with a declined status.

Error Response

Set the cardholder name to ERROR. The payment will fail with an error status.

See the complete Testing Guide for more scenarios.

Next Steps

Now that you've completed your first payment, explore more features:

Common Issues

"Invalid API Key" Error

• Make sure you're using the correct API key for your environment (sandbox vs production)
• Verify the Authorization header format: Bearer YOUR_API_KEY

Checkout Page Not Loading

• Check that the redirect_url is complete and properly formatted
• Ensure the sandbox environment has had time to spin up (10-20 seconds on first request)

Return URL Not Working

• Verify your return_url is a valid HTTPS URL
• Make sure it's publicly accessible (not localhost for production)