Skip to content

API Reference

Complete reference for Nivatio's REST API.

Interactive Documentation

When running the backend locally, visit: http://localhost:6001/api

This interactive Swagger UI allows you to: - Explore all endpoints (Auth, Projects, Orders, Analytics, Admin, Health) - See full request/response schemas - Execute requests directly from the browser using your JWT

Swagger Authentication

Swagger UI is protected by HTTP Basic Auth in non-production environments. Default credentials: admin / nivatio_dev

Override with SWAGGER_USER / SWAGGER_PASS env vars.

Base URLs

Environment Base URL Purpose
Production https://api.nivat.io Live payments
Sandbox https://sandbox.nivat.io Testing & development

Authentication

Nivatio API uses three authentication methods:

Header Used For Format
Authorization: Bearer <JWT> Merchant & admin endpoints JWT from POST /v1/auth/login
x-api-key Order creation/retrieval API key from your Project
x-nivatio-internal-key Sandbox simulate-pay, internal Internal service key

Endpoints Summary

Auth — /v1/auth

Method Path Auth Description
POST /v1/auth/register None Register new merchant (status: PENDING until approved)
POST /v1/auth/login None Authenticate and receive JWT
GET /v1/auth/profile JWT Get current user's profile

Rate Limiting

  • Register: 3 requests / 60 seconds
  • Login: 5 requests / 60 seconds

Projects — /v1/projects

Method Path Auth Description
POST /v1/projects JWT Create a new project
GET /v1/projects JWT List all projects for merchant
GET /v1/projects/{id} JWT Get project details
PATCH /v1/projects/{id} JWT Update project settings
POST /v1/projects/{id}/api-keys JWT Generate new API key
DELETE /v1/projects/{id}/api-keys/{keyId} JWT Revoke an API key

Orders — /v1/orders

Method Path Auth Description
POST /v1/orders API Key Create a new order
GET /v1/orders/{id} API Key Retrieve order details
GET /v1/orders JWT List orders (with filters)
PATCH /v1/orders/{id} API Key Update order metadata
POST /v1/orders/{id}/confirm API Key Confirm payment with txHash

Order Statuses

Status Description
PENDING Order created, awaiting payment
CONFIRMING Payment detected, waiting for confirmations
PAID Payment confirmed on-chain
FAILED Payment failed or rejected
EXPIRED Payment timeout reached

Analytics — /v1/analytics

Method Path Auth Description
GET /v1/analytics/overview JWT Get overview stats
GET /v1/analytics/transactions JWT Get transaction history

Admin — /v1/admin

Method Path Auth Description
GET /v1/admin/merchants JWT (admin) List all merchants
PATCH /v1/admin/merchants/{id}/approve JWT (admin) Approve merchant
GET /v1/admin/orders JWT (admin) List all orders
PATCH /v1/admin/settings JWT (admin) Update platform settings

Health — /health

Method Path Auth Description
GET /health None Check API health status

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-05-06T18:30:00.000Z",
  "services": {
    "api": "operational",
    "database": "operational",
    "blockchain": "operational",
    "webhooks": "operational"
  }
}

Request/Response Examples

Create Order

Request:

curl -X POST https://api.nivat.io/v1/orders \
  -H "x-api-key: nv_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "NUSD",
    "description": "Premium Subscription",
    "successUrl": "https://yourapp.com/success",
    "cancelUrl": "https://yourapp.com/cancel",
    "metadata": {
      "internalOrderId": "ord_12345"
    }
  }'

Response:

{
  "id": "order_abc123",
  "amount": 100000,
  "currency": "NUSD",
  "status": "PENDING",
  "description": "Premium Subscription",
  "checkoutUrl": "https://checkout.nivat.io/order_abc123",
  "createdAt": "2026-05-06T18:30:00.000Z",
  "metadata": {
    "internalOrderId": "ord_12345"
  }
}

Error Responses

All errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Invalid order amount",
  "error": "Bad Request",
  "code": "invalid_amount"
}

Common Error Codes

Code HTTP Status Description
invalid_amount 400 Amount not valid (must use 6 decimals)
invalid_currency 400 Currency not supported
unauthorized 401 Invalid API key or JWT
forbidden 403 Insufficient permissions
not_found 404 Resource not found
rate_limit 429 Too many requests
internal_error 500 Internal server error

Pagination

List endpoints support pagination:

Parameter Type Description
page number Page number (default: 1)
limit number Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Using OpenAPI Spec

Download the full OpenAPI specification:

curl https://api.nivat.io/api-json -o openapi.json

Import into: - Postman: Import openapi.json as OpenAPI spec - Insomnia: Drag & drop openapi.json - Swagger UI: Paste contents into editor

Next Steps