Create Payment Intent

Creates a new payment intent and returns a redirect URL to the hosted checkout page.

Endpoint

POST /api/intents

Authentication: Required (API Key)

Description

This endpoint is used to create a payment intent for processing payments through the hosted checkout page. A payment intent serves as the foundation for a transaction, specifying details such as the amount and currency required for payment processing.

Hosted Checkout Flow

Once a payment intent is created, you receive a redirect_url to the hosted checkout page. This URL can be used to redirect users to the checkout page, enabling customers to complete the payment process. Our checkout page manages different multi-step flows and 3DS redirection flows, ensuring a smooth user experience.

Request

Headers

Body Parameters

Purchaser Info Object

Payment Method Filter Object

Split Object

See Split Payouts Guide for details.

Future Payments Object

Future Payment Constraints Object

See Mandates for how to manage a mandate after it has been signed.

Example Request

curl -X POST https://api.njiapay.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": true,
    "request_unscheduled_mit": false,
    "purchaser_info": {
      "email": "customer@example.com",
      "phone": "+27123456789",
      "country": "ZA",
      "locale": "en-ZA"
    }
  }'

const response = await fetch("https://api.njiapay.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: true,
    purchaser_info: {
      email: "customer@example.com",
      phone: "+27123456789",
      country: "ZA",
    },
  }),
});

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

import requests

response = requests.post(
    'https://api.njiapay.com/api/intents',
    headers={
        'Authorization': f'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': True,
        'purchaser_info': {
            'email': 'customer@example.com',
            'phone': '+27123456789',
            'country': 'ZA'
        }
    }
)

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

Response

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "redirect_url": "https://pay.njiapay.com/pay/550e8400-e29b-41d4-a716-446655440000?token=eyJ0eXAi..."
}

Error Responses

401 Unauthorized

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

Causes:

• Missing Authorization header
• Invalid API key
• Using sandbox key with production URL (or vice versa)

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "ensure this value is greater than or equal to 0",
      "type": "value_error"
    }
  ]
}

Common validation errors:

• Negative amount
• Invalid currency code
• Missing required fields
• Invalid return_url format
• Split amounts don't sum to total amount

Important Notes

Allow Remember Credentials

The allow_remember_credentials parameter must be set to true if you plan to:

• Allow 1-click payments
• Enable unscheduled Merchant-Initiated Transactions (MIT)
• Use auto-payment attempts

If you intend to use auto-payments, ensure the original payment intent is successfully completed and meets all prerequisites.

See Auto Payments Guide for details.

Split Payouts

If you want to split the payment between multiple parties, use the split field:

• Minimum 2 beneficiaries required
• Sum of splits must equal total amount
• No duplicate beneficiaries
• All beneficiaries must have same currency as intent

Before using splits, create beneficiaries using the /api/merchants/{merchant_id}/beneficiaries endpoint.

See Split Payouts Guide for complete details.

Next Steps

After creating a payment intent:

1. Redirect the customer to the redirect_url
2. Set up webhook listener to receive payment status updates
3. Handle return_url callback when customer returns to your site

Related

• Hosted Checkout Flow
• Webhook Events
• Payment Intent Concept
• Get Intent
• Cancel Intent