Skip to main content

Products

Overview​

You can declare products on NGnair Payments and these products can be used in your checkout flow. This guide will walk you through the steps to create, update, and delete products using the NGnair Payments API.

Authentication​

All API requests must include your authentication token in the request headers:

  • token: Your authentication token

Example:

-H 'token: tok_123456789'

API Reference​

List Products​

Retrieve a list of products with pagination support.

Sort Options​

  • order: Specifies the sort direction
    • asc: Ascending order (A to Z, 0 to 9)
    • desc: Descending order (Z to A, 9 to 0)

Filter Operations​

  • contains: Field contains the specified value
  • equals: Field exactly matches the specified value
  • gt: Greater than the specified value
  • lt: Less than the specified value
  • gte: Greater than or equal to the specified value
  • lte: Less than or equal to the specified value
  • neq: Not equal to the specified value
note

When filtering by price or currency values, use amounts in cents (smallest currency unit). For example, to filter products priced at $10.00 or higher, use "value": "1000". The API will handle the conversion, and responses will show prices in decimal format (e.g., 10.00).

Example with Currency Filter​

POST /api/gateway/products
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "filter": [
        {
          "field": "price",
          "operation": "gte",
          "value": "1000"  // Filter products priced at $10.00 or higher
        }
      ]
    }
  }
}
POST /api/gateway/products
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "page": 1,
      "pageSize": 10,
      "sort": {
        "field": "string",
        "order": "asc" | "desc"  // Sort direction options
      },
      "filter": [
        {
          "field": "string",
          "operation": "contains" | "equals" | "gt" | "lt" | "gte" | "lte" | "neq",  // Filter operation options
          "value": "string"
        }
      ],
      "search": "string"
    }
  }
}

Example with Sort and Filter​

POST /api/gateway/products
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "page": 1,
      "pageSize": 10,
      "sort": {
        "field": "price",
        "order": "desc"  // Sort by price in descending order
      },
      "filter": [
        {
          "field": "price",
          "operation": "gte",  // Filter products with price greater than or equal to
          "value": "100"
        },
        {
          "field": "category",
          "operation": "equals",  // Filter products with exact category match
          "value": "electronics"
        }
      ],
      "search": "laptop"
    }
  }
}

Create Product​

Create a new product with the specified details.

POST /api/gateway/createProduct
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "form": {
      "name": "string",
      "category": "string",
      "subCategory": "string",
      "sku": "string",
      "brand": "string",
      "price": number,
      "itemWeight": number,
      "length": number,
      "breadth": number,
      "width": number,
      "description": "string",
      "isInStore": boolean,
      "isOnline": boolean,
      "kitchenItem": "string",
      "taxExempt": boolean,
      "productImages": [
        {
          "b64": "string",
          "type": "string",
          "url": "string"
        }
      ]
    }
  }
}

Update Product​

Update an existing product's details.

POST /api/gateway/updateProduct
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "string",
    "form": {
      "name": "string",
      "category": "string",
      "subCategory": "string",
      "brand": "string",
      "price": number,
      "itemWeight": number,
      "length": number,
      "breadth": number,
      "width": number,
      "description": "string",
      "isInStore": boolean,
      "isOnline": boolean,
      "kitchenItem": "string",
      "taxExempt": boolean,
      "sku": "string",
      "productImages": [
        {
          "b64": "string",
          "type": "string"
        }
      ]
    }
  }
}

Delete Product​

Remove a product from your catalog.

POST /api/gateway/deleteProduct
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "string"
  }
}

Get Product Details​

Retrieve detailed information about a specific product.

POST /api/gateway/product
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "string"
  }
}

Response Examples​

List Products Response​

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "price": number,
      "discount": number,
      "productStatus": "string",
      "taxExempt": boolean,
      "kitchenItem": boolean,
      "sku": "string"
    }
  ],
  "page": {
    "total": number,
    "range": {
      "from": number,
      "to": number
    },
    "page": number,
    "pageSize": number
  }
}

Create/Update Product Response​

{
  "productID": "string"
}

Get Product Response​

{
  "id": "string",
  "name": "string",
  "price": number,
  "discount": number,
  "productStatus": "string",
  "taxExempt": boolean,
  "kitchenItem": boolean,
  "sku": "string",
  "category": "string",
  "subCategory": "string",
  "brand": "string",
  "itemWeight": number,
  "length": number,
  "breadth": number,
  "width": number,
  "description": "string",
  "isInStore": boolean,
  "isOnline": boolean,
  "productImages": [
    {
      "url": "string",
      "name": "string"
    }
  ]
}

Sample API Requests​

List Products Example​

Request:

POST /api/gateway/products
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "page": 1,
      "pageSize": 10,
      "sort": {
        "field": "name",
        "order": "asc"
      },
      "filter": [
        {
          "field": "category",
          "operation": "equals",
          "value": "electronics"
        }
      ],
      "search": "laptop"
    }
  }
}

Response:

{
  "data": [
    {
      "id": "prod_123456789",
      "name": "Gaming Laptop",
      "price": 1299.99,
      "discount": 100,
      "productStatus": "active",
      "taxExempt": false,
      "kitchenItem": false,
      "sku": "LAP-001"
    }
  ],
  "page": {
    "total": 1,
    "range": {
      "from": 1,
      "to": 1
    },
    "page": 1,
    "pageSize": 10
  }
}

Create Product Example​

Request:

POST /api/gateway/createProduct
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "form": {
      "name": "Wireless Mouse",
      "category": "electronics",
      "subCategory": "accessories",
      "sku": "MOU-001",
      "brand": "TechPro",
      "price": 29.99,
      "itemWeight": 0.2,
      "length": 4.5,
      "breadth": 2.8,
      "width": 1.5,
      "description": "Ergonomic wireless mouse with long battery life",
      "isInStore": true,
      "isOnline": true,
      "kitchenItem": "false",
      "taxExempt": false,
      "productImages": [
        {
          "b64": "base64_encoded_image_data",
          "type": "image/jpeg",
          "url": "https://example.com/images/mouse.jpg"
        }
      ]
    }
  }
}

Response:

{
  "productID": "prod_987654321"
}

Update Product Example​

Request:

POST /api/gateway/updateProduct
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "prod_987654321",
    "form": {
      "name": "Wireless Mouse Pro",
      "price": 34.99,
      "description": "Professional ergonomic wireless mouse with extended battery life",
      "isInStore": true,
      "isOnline": true
    }
  }
}

Response:

{
  "productID": "prod_987654321"
}

Delete Product Example​

Request:

POST /api/gateway/deleteProduct
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "prod_987654321"
  }
}

Response:

{
  "productID": "prod_987654321"
}

Get Product Details Example​

Request:

POST /api/gateway/product
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "productID": "prod_987654321"
  }
}

Response:

{
  "id": "prod_987654321",
  "name": "Wireless Mouse Pro",
  "price": 34.99,
  "discount": 0,
  "productStatus": "active",
  "taxExempt": false,
  "kitchenItem": false,
  "sku": "MOU-001",
  "category": "electronics",
  "subCategory": "accessories",
  "brand": "TechPro",
  "itemWeight": 0.2,
  "length": 4.5,
  "breadth": 2.8,
  "width": 1.5,
  "description": "Professional ergonomic wireless mouse with extended battery life",
  "isInStore": true,
  "isOnline": true,
  "productImages": [
    {
      "url": "https://example.com/images/mouse.jpg",
      "name": "mouse-main"
    }
  ]
}