Documentation

Authentication Methods

Nodela supports two methods for providing your API key. Both methods are equally valid, so choose whichever fits best with your existing codebase or framework.

Method 1: X-API-Key Header

Pass your API key directly using the X-API-Key HTTP header. This is a straightforward approach commonly used in API integrations.

curl -X GET "https://api.nodela.co/v1/transactions" \
  -H "X-API-Key: nk_test_abc123..."

Method 2: Bearer Token

Pass your API key using the standard Authorization header with the Bearer scheme. This approach follows OAuth 2.0 conventions and may integrate more easily with frameworks that expect Bearer token authentication.

curl -X GET "https://api.nodela.co/v1/transactions" \
  -H "Authorization: Bearer nk_test_abc123..."

Which Method Should I Use?

Both authentication methods provide identical functionality. Here are some considerations:

• X-API-Key is more explicit and makes it immediately clear that you're using an API key for authentication. It's a good choice for simple integrations or when you want clarity in your codebase.
• Bearer Token follows the widely-adopted OAuth 2.0 convention. If your application already uses Bearer tokens for other services, or if your HTTP client or framework has built-in support for Bearer authentication, this method may fit more naturally into your existing code.

Authentication Errors

If authentication fails, the API returns one of the following errors:

Missing API Key (401)

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "API key is required"
  }
}

This error occurs when no API key is provided in either the X-API-Key or Authorization header.

Invalid API Key (401)

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "API key not found, inactive, or malformed"
  }
}

This error occurs when the provided API key does not exist, has been deactivated, or is incorrectly formatted.

Health Check

Check the API and database health status. Use this endpoint to verify that the API is operational before making other requests.

Authentication: Not required

Request

curl -X GET "https://api.nodela.co/health"

Response

Success (200 OK)

{
  "status": "healthy"
}

Service Unavailable (503)

{
  "status": "unhealthy"
}

Invoices

The Invoices API allows you to create payment requests and verify their status. When you create an invoice, your customer receives a checkout URL where they can complete their payment in cryptocurrency.

Create Invoice

Create a new invoice for payment processing. The response includes a checkout_url that you should redirect your customer to for payment.

Authentication: Required

Request Body Parameters

Request

curl -X POST "https://api.nodela.co/v1/invoices" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nk_test_abc123..." \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "webhook_url": "https://example.com/webhook",
    "reference": "order-12345",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "title": "Product Purchase",
    "description": "Order #12345"
  }'

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "id": "6789abcd1234567890abcdef",
    "invoice_id": "NOD_INV_1234567890",
    "original_amount": 50000,
    "original_currency": "NGN",
    "amount": 33.33,
    "currency": "USD",
    "exchange_rate": 1500.0,
    "webhook_url": "https://example.com/webhook",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "checkout_url": "https://checkout.nodela.co/checkout?id=6789abcd1234567890abcdef&invoice_id=NOD_INV_1234567890",
    "status": "pending",
    "created_at": "2026-01-30T12:00:00Z"
  }
}

Response Fields

Currency Conversion

When you create an invoice with currency set to NGN, the amount is automatically converted to USD using real-time exchange rates.

• The exchange_rate field in the response shows the NGN per USD rate used
• The final amount is rounded to 2 decimal places

Example Conversion:

Error Responses

Validation Error (400)

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Amount is required; Currency must be one of: NGN USD"
  }
}

Invalid Webhook (400)

{
  "success": false,
  "error": {
    "code": "invalid_webhook",
    "message": "Webhook URL not registered for this user"
  }
}

Duplicate Reference (409)

{
  "success": false,
  "error": {
    "code": "duplicate_reference",
    "message": "duplicate reference: order-12345"
  }
}

Currency Service Unavailable (503)

{
  "success": false,
  "error": {
    "code": "currency_error",
    "message": "Exchange rate service unavailable"
  }
}

Verify Invoice

Verify the status of an invoice and retrieve payment details. Use this endpoint to confirm that a payment was successful before fulfilling an order.

Authentication: Required

URL Parameters

Request

curl -X GET "https://api.nodela.co/v1/invoices/NOD_INV_1234567890/verify" \
  -H "X-API-Key: nk_test_abc123..."

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "id": "6789abcd1234567890abcdef",
    "invoice_id": "NOD_INV_1234567890",
    "reference": "order-12345",
    "original_amount": 50000,
    "original_currency": "NGN",
    "amount": 33.33,
    "currency": "USD",
    "exchange_rate": 1500.0,
    "title": "Product Purchase",
    "description": "Order #12345",
    "status": "paid",
    "paid": true,
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "created_at": "2026-01-30T12:00:00Z",
    "payment": {
      "id": "abc123def456789012345678",
      "network": "ethereum",
      "token": "USDT",
      "address": "0x1234567890abcdef...",
      "amount": 33.33,
      "status": "completed",
      "tx_hash": ["0xabc123..."],
      "transaction_type": "credit",
      "payer_email": "customer@example.com",
      "created_at": "2026-01-30T12:05:00Z"
    }
  }
}

Response Fields

Payment Object Fields

Verifying Payment Success

To confirm a payment was successful, check both conditions:

1. status equals paid
2. paid equals true

if (data.data.status === "paid" && data.data.paid === true) {
  // Payment confirmed - fulfill the order
}

Important Notes

• The payment object is only included when a payment has been made
• Test API keys can only verify test invoices (NOD_TEST_INV_*)
• Live API keys can only verify live invoices (NOD_INV_*)
• The invoice must belong to the authenticated user

Error Responses

Invoice Not Found (404)

{
  "success": false,
  "error": {
    "code": "invoice_not_found",
    "message": "Invoice not found"
  }
}

Transactions

The Transactions API allows you to list all payments made through your API integration with pagination support.

List Transactions

Retrieve a paginated list of all transactions made through your API integration. This endpoint returns invoices created via the API, not payment links.

Authentication: Required

Query Parameters

Request

# Get first page with default limit
curl -X GET "https://api.nodela.co/v1/transactions" \
  -H "X-API-Key: nk_test_abc123..."

# Get page 2 with 50 items per page
curl -X GET "https://api.nodela.co/v1/transactions?page=2&limit=50" \
  -H "X-API-Key: nk_test_abc123..."

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "6789abcd1234567890abcdef",
        "invoice_id": "NOD_INV_1234567890",
        "reference": "order-12345",
        "original_amount": 50000,
        "original_currency": "NGN",
        "amount": 33.33,
        "currency": "USD",
        "exchange_rate": 1500.0,
        "title": "Product Purchase",
        "description": "Order #12345",
        "status": "paid",
        "paid": true,
        "customer": {
          "email": "customer@example.com",
          "name": "John Doe"
        },
        "created_at": "2026-01-30T12:00:00Z",
        "payment": {
          "id": "abc123def456789012345678",
          "network": "ethereum",
          "token": "USDT",
          "address": "0x1234567890abcdef...",
          "amount": 33.33,
          "status": "completed",
          "tx_hash": ["0xabc123..."],
          "transaction_type": "credit",
          "payer_email": "customer@example.com",
          "created_at": "2026-01-30T12:05:00Z"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "total_pages": 3,
      "has_more": true
    }
  }
}

Pagination Object

Pagination Example

Here's how to iterate through all transactions:

async function getAllTransactions() {
  const allTransactions = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`https://api.nodela.co/v1/transactions?page=${page}&limit=100`, {
      method: "GET",
      headers: {
        "X-API-Key": "nk_test_abc123..."
      }
    });

    const data = await response.json();

    allTransactions.push(...data.data.transactions);
    hasMore = data.data.pagination.has_more;
    page++;
  }

  return allTransactions;
}

Important Notes

• Only returns invoices created via API integration (not payment links)
• Transactions are sorted by creation date, newest first
• The payment object contains only the credit (deposit) payment
• Test API keys return test transactions; live keys return live transactions
• The maximum limit is 100; values above this are automatically capped

Errors

All API errors follow a consistent format to make error handling straightforward in your application.

Error Response Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Error Codes Reference

Error Handling Example

const response = await fetch("https://api.nodela.co/v1/invoices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "nk_test_abc123..."
  },
  body: JSON.stringify({
    amount: 50000,
    currency: "NGN"
  })
});

const data = await response.json();

if (!data.success) {
  switch (data.error.code) {
    case "validation_error":
      console.error("Invalid request:", data.error.message);
      break;
    case "duplicate_reference":
      console.error("Reference already exists:", data.error.message);
      break;
    case "invalid_api_key":
      console.error("Authentication failed:", data.error.message);
      break;
    case "currency_error":
      console.error("Try again later:", data.error.message);
      break;
    default:
      console.error("Error:", data.error.message);
  }
} else {
  // Success - process the invoice
  console.log("Invoice created:", data.data.invoice_id);
}

Keeping Your API Keys Safe

Your API keys grant access to your Nodela account and should be treated like passwords. Follow these best practices to keep them secure:

Never expose keys in client-side code. API keys should only be used in server-side code. Never include them in JavaScript that runs in the browser, mobile app source code, or any code that end users can access.

Use environment variables. Store your API keys in environment variables rather than hardcoding them in your source code. This prevents accidental exposure through version control systems.

# .env file (never commit this to version control)
NODELA_API_KEY=nk_live_abc123...

Add sensitive files to .gitignore. Ensure that files containing API keys (like .env) are listed in your .gitignore file to prevent them from being committed to your repository.

# .gitignore
.env
.env.local
.env.production

Use different keys for different environments. Use test keys for development and staging environments, and reserve live keys for production only. This limits exposure and makes it easier to rotate keys if needed.

Limit access within your team. Only share API keys with team members who need them. Use your dashboard's team management features to control access rather than sharing keys directly.

Monitor your API usage. Regularly review your transaction history and API logs in the dashboard. Unusual activity could indicate that your keys have been compromised.

Regenerating API Keys

If you suspect your API key has been compromised, or as part of routine security practices, you should regenerate your keys immediately.

To regenerate an API key:

1. Log in to your Nodela dashboard
2. Navigate to the API keys section
3. Click Regenerate next to the key you want to replace
4. Copy the new key immediately

After regenerating a key, the old key is immediately invalidated. Any requests using the old key will fail with an invalid_api_key error. Be prepared to update your applications with the new key to avoid service interruptions.

Account & API Keys

Invoices & Payments

Webhooks

Errors & Troubleshooting

Testing

Support