---
updatedAt: 2026-02-26T13:11:22.000Z
agentTools:
  projectIndex: https://docs.ksa.ngenius-payments.com/llms.txt
---

# Creating Orders

To process payments through N-Genius, your server must first authenticate with our identity service and then create an order with the payment gateway. This flow is common across SDK, API, and plugin integrations.

To create orders through the N-Genius platform, your merchant server must authenticate and communicate with the N-Genius API. This process is essential for both mobile and web integrations.

> 📘 This guide is backend-focused and applies to all platforms.

If you're using the Android or iOS SDK, your app will send order details to your server, which then handles authentication and order creation.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/c63a7dbd1f74d9e7c10a28e1a2dd9dc84dab25d3b392495245a5aaed3d5b7e4c-creating-orders-flow-diagram.png",
        "",
        "The flow diagram demonstrates the steps taken to create an order from web or mobile devices. "
      ],
      "align": "center",
      "caption": "Create Order Flow"
    }
  ]
}
[/block]

## Step 1: Authenticate and Create a Session

Before creating an order, your server must authenticate using credentials provided during onboarding.

Required Credentials

[block:parameters]
{
  "data": {
    "h-0": "Key",
    "h-1": "Description",
    "0-0": "API_KEY",
    "0-1": "Generated in the admin portal",
    "1-0": "IDENTITY_API_URL",
    "1-1": "Auth endpoint:  \nUAT: <https://api-gateway.sandbox.ksa.ngenius-payments.com/identity/auth/access-token>  \nProduction: <https://api-gateway.ksa.ngenius-payments.com/identity/auth/access-token>",
    "2-0": "GATEWAY_API_URL",
    "2-1": "Order endpoint:  \nUAT: - <https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/XXXX/orders>
  \nProduction - <https://api-gateway.ksa.ngenius-payments.com/transactions/outlets/XXXX/orders>",
    "3-0": "REALM",
    "3-1": "UAT: ni  \nProduction: networkinternational"
  },
  "cols": 2,
  "rows": 4,
  "align": [
    "left",
    "left"
  ]
}
[/block]

**Sample Authentication Function (Node.js)**

```javascript
const axios = require('axios');

async function authenticate() {
  try {
    const { data } = await axios.post(IDENTITY_API_URL, {
      grant_type: 'client_credentials',
      realm: REALM,
    }, {
      headers: {
        'Content-Type': 'application/vnd.ni-identity.v1+json',
        'Authorization': `Basic ${API_KEY}`
      }
    });

    return { access_token: data.access_token };
  } catch (error) {
    console.error('Authentication failed:', error);
    return { error };
  }
}
```

> 📘 Prefer PHP? View our PHP [Merchant Server implementation](https://github.com/network-international/sample-merchant-server-php) on GitHub (link it to the repo)

## Step 2: Create an Order

Once authenticated, use the bearer token to create an order.

### Required Endpoint

| Environment | URL                                                                                     |
| :---------- | :-------------------------------------------------------------------------------------- |
| UAT         | <https://api-gateway.sandbox.ksa.ngenius-payments.com/transactions/outlets/XXXX/orders> |
| Production  | <https://api-gateway.ksa.ngenius-payments.com/transactions/outlets/XXXX/orders>         |

> 📘 Replace XXXX with your outletid.

**Sample `orderRequest` object**

```json
{
  "action": "PURCHASE",
  "amount": {
    "currencyCode": "SAR",
    "value": 1000
  },
  "merchantAttributes": {
    "redirectUrl": "https://yourdomain.com/callback",
    "cancelUrl": "https://yourdomain.com/cancel"
  }
}
```

**Sample Order Creation Function (Node.js)**

```javascript
async function createOrder(access_token, orderRequest) {
  try {
    const { data: orderData } = await axios.post(GATEWAY_API_URL, orderRequest, {
      headers: {
        'Authorization': `Bearer ${access_token}`,
        'Content-Type': 'application/vnd.ni-payment.v2+json',
        'Accept': 'application/vnd.ni-payment.v2+json'
      }
    });

    return orderData;
  } catch (error) {
    console.error('Order creation failed:', error);
    return {
      error,
      message: 'An error occurred while creating the order',
    };
  }
}
```

## Step 3: Handle Payment Status Callbacks

Once a payment is completed or canceled, the N-Genius platform sends a webhook (callback) to your server with the transaction result.

To learn how to set up and handle these callbacks securely, see our [**Consuming Webhooks**](https://docs.ksa.ngenius-payments.com/ksa/docs/consuming-web-hooks) guide.

This ensures your system stays up to date with payment statuses and can trigger the next steps in your business logic.

### Additional Resources

* [Merchant Server GitHub Repo](https://github.com/network-international/sample-merchant-server-javascript)
* [API Reference – Create Order](https://docs.ksa.ngenius-payments.com/ksa/docs/createorder-1)