Nodela Developer Docs

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",
    "client_secret": "cs_live_9f2e1a4b8c3d...",
    "status": "pending",
    "created_at": "2026-01-30T12:00:00Z"
  }
}

Response Fields

Currency Conversion

When you create an invoice with a non-USD currency, the amount is automatically converted to USD using real-time exchange rates. Nodela supports 63 currencies across 6 regions.

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

Supported Currencies

Example Conversion:

Error Responses

Validation Error (400)

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Amount is required; Currency must be a supported currency code (e.g. USD, NGN, EUR, GBP)"
  }
}

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 that the invoice is paid and that the amount matches what you expected:

1. paid equals true
2. amount matches the expected payment amount

if (data.data.paid === true && data.data.amount === expectedAmount) {
  // 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);
}

Overview

nodela.js is a small script (under 10 KB) you load from Nodela's CDN. It renders the same checkout UI as the hosted redirect flow — network and currency selection, QR or wallet payment, live confirmation — inside a sandboxed iframe it manages for you, and reports back to your page via simple callbacks.

Use this when you want your customer to never leave your site, but don't want to build a payment UI yourself. If you want full control over the UI instead, see Self-Managed Checkout.

Installation

Add the script tag anywhere on the page you want the checkout available. It attaches window.Nodela once loaded — no build step, no package to install.

<script src="https://cdn.nodela.co/nodela.js"></script>

That's it — there is no npm package. nodela.js is plain JavaScript that attaches window.Nodela; it works the same way whether your page is a static HTML file, or built with React, Vue, or anything else — just call Nodela.open() from your own click handler.

Nodela.open()

Opens the checkout overlay. Create the invoice from your backend first (see Create Invoice) and pass its invoice_id here — never create the invoice from the browser, since that requires your secret API key. Everything else about the invoice — amount, currency, description, customer — is resolved server-side from that id, so there's nothing else to pass.

Options

Example

<script src="https://cdn.nodela.co/nodela.js"></script>

<button id="pay-btn">Pay with Crypto</button>

<script>
  document.getElementById("pay-btn").addEventListener("click", () => {
    Nodela.open({
      baseUrl: "https://checkout.nodela.co",
      invoiceId: "NOD_INV_1234567890",
      theme: "auto",
      onSuccess: (result) => {
        console.log("Payment confirmed:", result.txHash);
        window.location.href = "/thank-you";
      },
      onClose: () => {
        console.log("Checkout closed");
      }
    });
  });
</script>

Handling Events

The callbacks passed to Nodela.open() are the whole integration surface — you don't need to listen for anything else. onSuccess receives:

interface PaymentSuccessResult {
  invoiceId: string;
  txHash?: string;
  amount: number;
  currency: string;
  network?: string;
  token?: string;
}

Treat onSuccess firing as "the payer finished" — for order fulfillment, still confirm with Verify Invoice from your backend (or a webhook) before shipping anything, the same way you would after a hosted-redirect payment.

Call Nodela.close() at any time to dismiss the overlay programmatically.

Overview

Every endpoint below is plain JSON, authenticated the same way as the rest of this API but with a different credential (see The Client Secret, next). There is exactly one piece of this you can't do with a plain HTTP call: letting the payer connect and sign with a crypto wallet. That still needs something running in the browser that speaks to wallets — Headless Wallet Connect covers the one line of code that handles it for you.

Everything else — listing networks, listing currencies, generating a deposit address, polling status, rendering your own QR code — is a call you can make from anywhere: your backend, your frontend, a mobile app.

The Client Secret

Your API key authorizes your entire account and must never run in browser code. The endpoints below happen from the payer's browser, so they use a different credential instead: a client secret, scoped to exactly one invoice.

Get one by creating an invoice from your backend as usual — the response now includes client_secret alongside checkout_url. Hand that value to whatever runs in the payer's browser.

Every endpoint below accepts it the same two ways your API key works:

X-Client-Secret: cs_test_9f2e1a4b8c3d...

Test-mode invoices (created with an nk_test_ key) get a cs_test_ secret; live invoices get cs_live_. The two are not interchangeable, the same way test and live API keys aren't.

List Networks

Authentication: Client secret

curl -X GET "https://api.nodela.co/v1/invoices/NOD_INV_1234567890/networks" \
  -H "X-Client-Secret: cs_test_abc123..."

Response

{
  "success": true,
  "data": [
    { "id": "base", "name": "Base", "active": true },
    { "id": "polygon", "name": "Polygon", "active": true },
    { "id": "bsc", "name": "BNB Chain", "active": false }
  ]
}

id is what you pass to every other endpoint below as network — a stable identifier, never an internal numeric chain id.

List Currencies

Authentication: Client secret

Query Parameters

Response

{
  "success": true,
  "data": [
    { "symbol": "ETH", "name": "Ethereum", "address": "0x0", "decimals": 18, "icon_url": null, "is_native": true },
    { "symbol": "USDC", "name": "USD Coin", "address": "0x8335...", "decimals": 6, "icon_url": null, "is_native": false }
  ]
}

Only is_native: true currencies can be paid by sending to a plain deposit address. A non-native token means the payer needs a connected wallet — route them to Wallet Quote instead of Deposit Address.

Generate a Deposit Address

Authentication: Client secret

Request Body

No token field — a deposit address only ever exists for a network's native currency (see is_native: true in List Currencies), so it's resolved for you from network alone. Paying with any other token means signing a transaction, not sending to a static address — use Wallet Quote (or Headless Wallet Connect) instead. A native currency isn't limited to a deposit address either — it can go through Wallet Quote just as well, if that's what the payer prefers.

Amount and payer email are never accepted here either — they come from the invoice itself, so a payer can't change what they're being asked to pay.

curl -X POST "https://api.nodela.co/v1/invoices/NOD_INV_1234567890/deposit-address" \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: cs_test_abc123..." \
  -d '{ "network": "base" }'

Response

{
  "success": true,
  "data": {
    "payment_address": "0x71C8b3d4a1e...",
    "amount": "0.0161",
    "amount_smallest_unit": "16100000000000000",
    "token": "ETH",
    "barcode": "ethereum:0x71C8b3d4a1e..."
  }
}

token in the response is the network's native currency — it tells you what was resolved, not what you chose. barcode is ready to hand to any QR code library as-is.

Check Payment Status

Authentication: Client secret

const res = await fetch(
  `https://api.nodela.co/v1/invoices/${invoiceId}/status`,
  { headers: { "X-Client-Secret": clientSecret } }
);
const { data } = await res.json();

if (data.status === "paid" || data.status === "swept") {
  // Settled — safe to show a success state
}

Response

{
  "success": true,
  "data": {
    "status": "pending",
    "tx_hash": "0xabc123...",
    "expires_at": "2026-01-30T12:30:00Z",
    "payment": {
      "address": "0x71C8b3d4a1e...",
      "crypto_amount": "0.0161"
    }
  }
}

Two things worth building for explicitly:

• A tx_hash appearing is not settlement — an on-chain transaction still needs confirmation. Only status reaching paid or swept means done. Keep polling past the first hash.
• If payment.address ever changes between polls, the payer sent less than quoted — this is a fresh address/amount for the remaining balance. Show it in place of the old one rather than continuing to watch an address that will never fill.

A 2–3 second polling interval is reasonable — see Rate Limits.

Request a Wallet Payment Quote

Authentication: Client secret

Give it the payer's connected wallet address and which currency they're paying with, and it returns a route: one or more transactions to sign, in order — a swap, then a bridge, then the final settlement transfer, for instance. If you're not driving the signing yourself, Headless Wallet Connect does this whole exchange for you in one call.

Request Body

A native currency can be paid either way — Generate a Deposit Address, or a connected wallet, same as here. This prices the attempt itself before asking for a route — there's no separate call to make first.

Response

{
  "success": true,
  "data": {
    "payment_id": "abc123def456",
    "steps": [
      {
        "items": [
          { "to": "0x...", "data": "0x...", "value": "0", "chain_id": 8453 }
        ]
      }
    ]
  }
}

Sign every item in every step with the connected wallet, in order — switch to chain_id first if it doesn't match the wallet's current network. After each transaction is submitted, report it to Wallet Tx below.

Report a Signed Transaction

Authentication: Client secret

Request Body

Best-effort — settlement is still confirmed independently via Payment Status, this just gives verification a head start. Call it once per signed item.

Headless Wallet Connect

Wallet payment is the one part of self-managed checkout that genuinely needs something running in the browser — a wallet has to be discovered, connected, and a transaction has to be signed. Doing that yourself means adding wagmi or an equivalent library to your bundle, and handling wallet discovery (EIP-6963) yourself so a payer with more than one wallet installed isn't left to whichever one happened to win window.ethereum.

The same nodela.js script from Embedded Checkout includes a headless helper that does all of it for you — discover wallets, connect, quote, sign every step, report each hash — behind one function call. It has no UI of its own; you keep your button, your loading state, your success screen.

It prefers the payer's injected browser wallet directly (EIP-1193, discovered via EIP-6963) — a desktop extension, or a mobile in-app browser. When none is found, which is the normal case for a payer on a plain mobile browser tab with a wallet app installed rather than an extension, it falls back to WalletConnect automatically, using Nodela's own Cloud project — you never register one of your own. That fallback loads as a separate script, on demand, only for a payer who actually needs it, so it never adds weight to nodela.js itself for anyone else.

Installation

<script src="https://cdn.nodela.co/nodela.js"></script>

The whole integration

document.getElementById("pay-with-wallet-btn").addEventListener("click", async () => {
  try {
    const result = await Nodela.headless.payWithWallet({
      invoiceId: "NOD_INV_1234567890",
      clientSecret: "cs_test_abc123...", // from your backend
      network: "base", // from List Networks
      token: "USDC", // from List Currencies — native currencies work here too
      onStatusChange: (status) => {
        // "connecting" -> "switching_network" -> "awaiting_signature" -> "confirming"
        updateYourOwnSpinner(status);
      },
    });

    console.log("Submitted:", result.txHash);
    // Now watch for settlement:
  } catch (err) {
    alert("Payment failed: " + err.message);
  }
});

Payers with more than one wallet

A payer with several wallet extensions installed (MetaMask and Rabby, say) has no single window.ethereum to fall back on — which extension holds that slot is a race between them on page load, entirely outside your control or the payer's intent. Calling payWithWallet with no providerId in that situation throws rather than guessing. Use discoverWallets to list what's installed (via EIP-6963) and let the payer pick:

const wallets = await Nodela.headless.discoverWallets();
// [{ rdns: "io.metamask", name: "MetaMask", icon: "data:..." },
//  { rdns: "io.rabby", name: "Rabby Wallet", icon: "data:..." },
//  { rdns: "walletconnect", name: "WalletConnect", icon: "" }]  <- always last, when configured

// Render your own picker from `wallets`, then:
const result = await Nodela.headless.payWithWallet({
  invoiceId: "NOD_INV_1234567890",
  clientSecret: "cs_test_abc123...",
  providerId: chosenWallet.rdns,
  onStatusChange: updateYourOwnSpinner,
});

Safe to skip entirely when there's exactly one EIP-6963 wallet installed — payWithWallet resolves it on its own. With zero, it falls back to the legacy window.ethereum global (a wallet that hasn't adopted EIP-6963 yet), then to WalletConnect if that's empty too — the normal case for a payer on a plain mobile browser tab.

Pass providerId: "walletconnect" directly to skip straight to it — useful for an explicit "Scan QR code" option in your own UI, alongside whatever injected wallets discoverWallets found.

Then watch for settlement

payWithWallet resolves once the transaction is submitted, not once it's settled — the same distinction as Payment Status above. Use watchPayment to know when it's actually done:

const stopWatching = Nodela.headless.watchPayment({
  invoiceId: "NOD_INV_1234567890",
  clientSecret: "cs_test_abc123...",
  onConfirmed: ({ txHash }) => {
    console.log("Settled:", txHash);
    window.location.href = "/thank-you";
  },
});

// Call stopWatching() if the user navigates away

Options

Nodela.headless also exposes the pieces above as standalone functions, if you want to drive the sequence yourself instead of one payWithWallet call: discoverWallets(), isWalletAvailable(), connectWallet(providerId?), and generateQrData(options) for rendering your own QR from a deposit address.

That's the entire wallet-connect integration — no provider setup, no chain configuration, no WalletConnect project of your own. If you'd rather drive the wallet yourself (you already use wagmi for something else, say), call Wallet Quote and Wallet Tx directly — the SDK is a convenience, not a requirement.

Rate Limits

The endpoints on this page have their own budget, separate from your account-level API key limits — they're reachable from any payer's browser, not just your trusted backend.

Exceeding either returns 429 with error code rate_limited.

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