https://api.fimepay.com/api/v1

curl https://api.fimepay.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl https://api.fimepay.com/api/v1/invoices \
  -H "x-api-key: fp_live_YOUR_API_KEY"

curl https://api.fimepay.com/api/v1/invoices \
  -H "x-api-key: fp_live_YOUR_API_KEY"

Create a new account and tenant. Returns an access token immediately — no email verification required to start.

curl -X POST https://api.fimepay.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Adaeze",
    "last_name": "Okonkwo",
    "email": "ada@fimedigital.ng",
    "password": "Secure123!",
    "business_name": "Fime Digital Ltd",
    "business_type": "sme",
    "tin": "12345678-0001"
  }'

Authenticate with email and password. Returns an access token in the response body and sets a refresh token as an httpOnly SameSite=Strict cookie.

curl -X POST https://api.fimepay.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@fimedigital.ng", "password": "Secure123!" }'

The refresh token is set as an httpOnly cookie — it is not visible in the response body and cannot be accessed by JavaScript. This is intentional for security.

Return the profile of the currently authenticated user and their tenant.

curl https://api.fimepay.com/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>"

Rotate the access token using the refresh token cookie. Returns a new access token. The refresh token is automatically rotated (7-day sliding window).

# Browser clients send the cookie automatically.
# Server-side: pass the cookie header explicitly.
curl -X POST https://api.fimepay.com/api/v1/auth/refresh \
  -H "Cookie: refresh_token=<your_refresh_token>"

Invalidate the current session. Clears the refresh token cookie and revokes the token server-side.

curl -X POST https://api.fimepay.com/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"

Send a password reset link to the given email. Always returns 200 — the response never reveals whether the email is registered.

curl -X POST https://api.fimepay.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@fimedigital.ng" }'

Set a new password using the token from the reset email. Tokens are single-use and expire after 1 hour.

curl -X POST https://api.fimepay.com/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6...",
    "password": "NewSecure456!"
  }'

curl https://api.fimepay.com/api/v1/invoices \
  -H "x-api-key: fp_live_abc123..."

Never expose API keys in client-side code, browser extensions, or public repositories. Always use environment variables and server-side requests.

GET https://api.fimepay.com/api/v1/auth/oauth/google
GET https://api.fimepay.com/api/v1/auth/oauth/microsoft

Generate a TOTP secret and QR code for authenticator app enrollment. Returns a base32 secret, a data URI QR code, and one-time backup codes.

curl -X POST https://api.fimepay.com/api/v1/auth/mfa/setup \
  -H "Authorization: Bearer <access_token>"

Verify a TOTP code to complete MFA enrollment or confirm identity during a login challenge.

curl -X POST https://api.fimepay.com/api/v1/auth/mfa/verify \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482931" }'

curl -X POST https://api.fimepay.com/api/v1/customers \
  -H "x-api-key: fp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fime Technologies Ltd",
    "email": "accounts@fime.ng",
    "tin": "12345678-0001",
    "address": "14 Broad Street, Lagos Island",
    "country": "NG"
  }'

curl -X POST https://api.fimepay.com/api/v1/invoices \
  -H "x-api-key: fp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "019547b3-0000-0000-0000-000000000001",
    "issue_date": "2025-03-24",
    "due_date": "2025-04-23",
    "currency": "NGN",
    "line_items": [
      {
        "description": "Software Consulting - March 2025",
        "quantity": 10,
        "unit_price": 35000,
        "discount_percent": 0
      }
    ],
    "notes": "Payment due within 30 days."
  }'

curl -X POST https://api.fimepay.com/api/v1/invoices/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a/finalize \
  -H "x-api-key: fp_live_YOUR_API_KEY"

curl -X POST https://api.fimepay.com/api/v1/invoices/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a/send \
  -H "x-api-key: fp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channels": ["email"]}'

curl -X POST https://api.fimepay.com/api/v1/invoices/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a/submit-firs \
  -H "x-api-key: fp_live_YOUR_API_KEY"

That's it — in 5 API calls you created a customer, issued a NRS-compliant signed invoice, emailed it with a PDF, and submitted it to NRS. The full API reference is in the sections below.

{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with id '019547a2-...' was not found.",
    "details": [],
    "request_id": "req_01954def-1234-5678-9abc-def012345678"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body validation failed.",
    "details": [
      { "field": "due_date", "message": "due_date must be a valid ISO date" },
      { "field": "line_items.0.unit_price", "message": "unit_price must be a positive number" }
    ],
    "request_id": "req_01954def-..."
  }
}

All 404 responses for tenant-scoped resources are intentional. If you request a resource that belongs to a different tenant, you receive 404 — not 403 — to prevent information leakage about whether the resource exists at all.

curl -X POST https://api.fimepay.com/api/v1/invoices \
  -H "x-api-key: fp_live_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "...", "issue_date": "2025-03-24", ...}'

If you consistently approach your plan limit, upgrade your plan or contact support for an Enterprise plan with custom limits. You can also purchase additional API call add-ons from the billing page.

{
  "data": [...],
  "next_cursor": "eyJpZCI6IjAxOTU0N2EyLTNiMWMtN2Q4ZS05ZjBhLTFiMmMzZDRlNWY2YSJ9",
  "has_more": true
}

async function getAllInvoices(apiKey: string) {
  const results = [];
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({ limit: '100' });
    if (cursor) params.set('cursor', cursor);

    const res = await fetch(
      `https://api.fimepay.com/api/v1/invoices?${params}`,
      { headers: { 'x-api-key': apiKey } }
    );
    const page = await res.json();

    results.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return results;
}

Cursor tokens are opaque and must be treated as strings. Do not attempt to decode or construct them manually — the format may change between API versions.

draft → finalized → sent ──────────► paid
            │          └─────────► partial → paid
            │
            ↓
        cancelled

finalized/sent → firs_submission_failed (NRS error — can retry)

List invoices for the authenticated tenant. Supports cursor pagination and filtering by status, date range, and customer.

Scope: invoices:read

Create a new invoice in draft status. The invoice is not locked or submitted to NRS at this stage — call POST /invoices/:id/finalize when ready.

Scope: invoices:write

{
  "description": "Web Application Development",
  "quantity": 1,
  "unit_price": 350000,
  "discount_percent": 0,
  "tax_rate_id": "019547c0-0000-0000-0000-000000000001"
}

Retrieve a single invoice with all fields including line items, payments, and NRS submission status.

Scope: invoices:read

Update a draft invoice. Returns 422 UNPROCESSABLE if the invoice is not in draft status.

Scope: invoices:write

PATCH on line_items is a full replacement — the entire array is replaced, not merged. Include all line items you want to keep.

Soft-delete a draft invoice. Finalized invoices cannot be deleted — use POST /invoices/:id/void instead.

Scope: invoices:write

Lock the invoice, generate an RSA digital signature, and assign a NRS IRN. The invoice moves from draft to finalized.

Scope: invoices:write

Requires Starter+ plan or higher

Once finalized, an invoice is immutable. Finalization generates an RSA digital signature using your tenant's private signing key and assigns a NRS IRN. The IRN is the SHA-256 hash of invoice_number + tenant_TIN + issue_date.

Enqueue the invoice for submission to the NRS e-Invoice API. The invoice must be finalized first. Returns 202 Accepted immediately — submission is asynchronous.

Scope: invoices:write

Requires Starter+ plan or higher

This endpoint enqueues an async job. Poll GET /invoices/:id and check firs_submitted_at — this is set when NRS confirms receipt. On failure, firs_response.error contains the NRS error message.

Send the invoice to the customer via email and/or WhatsApp. A PDF attachment is included in email sends. The invoice must be finalized.

Scope: invoices:write

Record a payment received against the invoice. Updates amount_due and moves the invoice to paid or partial status automatically.

Scope: payments:write

Cancel a finalized or sent invoice. Requires accountant role or higher.

Scope: invoices:write

Duplicate an invoice as a new draft. Copies all fields except invoice_number (auto-generated), status (set to draft), and payment history.

Scope: invoices:write

Download the invoice as a PDF. Returns application/pdf binary. The invoice must be finalized.

Scope: invoices:read

Requires Starter+ plan or higher

Download the UBL 2.1 XML representation of the invoice as required by NRS. The invoice must be finalized.

Scope: invoices:read

Requires Starter+ plan or higher

Issue a credit note against a finalized invoice. Creates a new invoice of type credit_note (UBL type code 381) linked to the original.

Scope: invoices:write

Requires Starter+ plan or higher

Aggregated invoice statistics for the authenticated tenant.

Scope: invoices:read

Customer TIN is required for NRS-compliant B2B invoicing. Invoices submitted to NRS without a customer TIN will be rejected at the validation step.

List all customers for the tenant. Supports cursor pagination and full-text search by name, email, or TIN.

Scope: customers:read

curl "https://api.fimepay.com/api/v1/customers?limit=20&search=Konga" \
  -H "x-api-key: <your_api_key>"

Create a new customer. TIN is required for NRS-compliant invoicing.

Scope: customers:write

curl -X POST https://api.fimepay.com/api/v1/customers \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Konga Technologies Ltd",
    "email": "finance@konga.com",
    "phone": "+2348012345678",
    "tin": "98765432-0001",
    "billing_address": {
      "street_name": "Plot 33, Kudirat Abiola Way",
      "city_name": "Lagos",
      "postal_zone": "100281",
      "country": "NG"
    }
  }'

Retrieve a single customer with all profile fields and contacts.

Scope: customers:read

curl https://api.fimepay.com/api/v1/customers/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a \
  -H "x-api-key: <your_api_key>"

Update customer fields. All body fields are optional — only the fields you include are changed.

Scope: customers:write

curl -X PATCH https://api.fimepay.com/api/v1/customers/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+2348099999999" }'

Soft-delete a customer. Existing invoices and their snapshots are not affected.

Scope: customers:write

List all invoices for a specific customer, newest first. Supports cursor pagination.

Scope: invoices:read

Add a contact person to a customer record (e.g. accounts payable contact to CC on invoices).

Scope: customers:write

curl -X POST https://api.fimepay.com/api/v1/customers/019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a/contacts \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Emeka Obi", "email": "emeka.obi@konga.com", "role": "Accounts Payable" }'

A dedicated Payments dashboard page is coming soon. In the meantime, payments are recorded directly from the invoice detail view using Record Payment, and Paystack payments are captured automatically via webhook.

List all payment records across all invoices. Supports filtering by date range and method.

Scope: payments:write

Retrieve a single payment record with the linked invoice details.

Scope: payments:write

Match an unlinked bank transfer to an invoice by amount and reference.

Scope: payments:write

Record a manual payment against an invoice. See the Invoices section for full documentation.

Scope: payments:write

curl -X POST https://api.fimepay.com/api/v1/invoices/01954abc-1234-5678-9abc-def012345678/record-payment \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150000.00",
    "method": "bank_transfer",
    "reference": "TRF-20260409-001",
    "paid_at": "2026-04-09",
    "notes": "Full payment received"
  }'

Full documentation for this section is coming soon. In the meantime, the endpoint reference below covers all available operations.

List all tax rates configured for the tenant, including system-seeded Nigerian VAT and WHT rates.

Scope: invoices:read

Create a custom tax rate. Requires accountant role or higher.

Scope: invoices:write

Update a custom tax rate. System-seeded rates cannot be modified.

Scope: invoices:write

Delete a custom tax rate. Rates in use on invoices cannot be deleted.

Scope: invoices:write

List generated VAT and WHT filing reports.

Scope: reports:read

Generate a VAT return report for a given period. Returns a downloadable PDF and structured JSON.

Scope: reports:read

Full documentation for this section is coming soon. In the meantime, the endpoint reference below covers all available operations.

Profit and loss statement for a given period. Aggregates invoiced revenue against recorded expenses.

Scope: reports:read

Cash flow report showing inflows from invoice payments and outflows from expenses.

Scope: reports:read

Receivables ageing analysis: outstanding invoices grouped by 0-30, 31-60, 61-90, 90+ days overdue.

Scope: reports:read

VAT and WHT summary for a period. Shows total output VAT, input VAT (from expenses), and net payable.

Scope: reports:read

API keys are tenant-scoped — each key only has access to data within the tenant it was created in. A key created under Fime Digital Ltd cannot access data from another tenant.

List all API keys for the tenant. Key values are never returned after creation — only the prefix, scopes, and metadata.

curl https://api.fimepay.com/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>"

Create a new API key with specified scopes and optional expiry date. The full key value is returned only once — store it immediately.

curl -X POST https://api.fimepay.com/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP Integration",
    "scopes": ["invoices:read", "invoices:write", "customers:read"],
    "expires_at": null
  }'

The key field is only returned once at creation. Copy it now and store it securely — it cannot be retrieved again. If lost, revoke the key and create a new one.

Revoke an API key immediately. Any in-flight requests using the key will receive 401 UNAUTHORIZED.

curl -X DELETE https://api.fimepay.com/api/v1/api-keys/019554b9-0a8d-e4f5-a6b7-8c9d0e1f2a3b \
  -H "Authorization: Bearer <access_token>"

Use the minimum scope needed. Create separate keys per integration. Revoke immediately if a key is compromised — Settings → API Keys → Revoke.

Full documentation for this section is coming soon. In the meantime, the endpoint reference below covers all available operations.

List all team members for the tenant, including their role and invitation status.

Invite a new team member by email. They receive an invitation email with a sign-up link pre-populated with the tenant context.

Update a team member's role. Only the owner can assign or remove the admin role.

Remove a team member. They lose all access immediately. The owner cannot be removed.

Full documentation for this section is coming soon. In the meantime, the endpoint reference below covers all available operations.

Get the tenant's profile: business name, TIN, address, contact email, logo URL, and FIRS configuration status.

Update tenant profile fields. All fields are optional.

Get default invoice settings: number prefix, payment terms, footer text, and logo.

Update invoice defaults.

Get integration connection status: FIRS credentials, Xero, QuickBooks, WhatsApp.

Connect or disconnect third-party integrations.

Request a full NDPR data export. Returns a download link valid for 24 hours.

Full documentation for this section is coming soon. In the meantime, the endpoint reference below covers all available operations.

List all available subscription plans with pricing, features, and limits. Public endpoint — no authentication required.

Get the current subscription status, plan details, current period dates, and usage summary.

Create or upgrade a subscription. Returns a Paystack checkout URL to complete payment.

Change billing cycle (monthly/annual) or downgrade plan. Effective at end of current period.

Cancel the subscription. Access continues until the end of the current billing period, then downgrades to Free.

Current period usage: invoices created, API calls made, storage used, versus plan limits.

List billing invoice history from Paystack. Shows amount, date, plan, and payment status.

Register a new webhook endpoint. FimePay will send POST requests to your URL for the events you subscribe to.

Scope: webhooks:manage

The secret is shown only once. Store it securely — you will use it to verify webhook signatures. If you lose it, delete the webhook and create a new one.

{
  "event": "invoice.paid",
  "tenant_id": "01954abc-1234-5678-9abc-def012345678",
  "timestamp": "2025-03-24T14:32:00.000Z",
  "data": {
    "invoice_id": "019547a2-3b1c-7d8e-9f0a-1b2c3d4e5f6a",
    "invoice_number": "INV-2025-001",
    "total_amount": "376250.00",
    "amount_due": "0.00",
    "paid_at": "2025-03-24T14:32:00.000Z"
  }
}

Always verify the X-FimePay-Signature header before processing a webhook. Discard any webhook that fails verification — it may be forged or replayed.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,     // raw request body as a string
  signature: string,   // X-FimePay-Signature header value
  secret: string       // your webhook endpoint secret
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

app.post(
  '/webhooks/fimepay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-fimepay-signature'];
    const secret = process.env.FIMEPAY_WEBHOOK_SECRET;

    if (!verifyWebhookSignature(req.body.toString(), signature, secret)) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body);

    switch (event.event) {
      case 'invoice.paid':
        await markOrderFulfilled(event.data.invoice_id);
        break;
      case 'payment.received':
        await updateAccountsReceivable(event.data);
        break;
    }

    res.status(200).send('OK');
  }
);

List recent delivery attempts for a webhook endpoint.

Scope: webhooks:manage

Send a test event to the webhook endpoint with a sample payload.

Scope: webhooks:manage

List all registered webhook endpoints for the authenticated tenant.

Scope: webhooks:manage

Update a webhook endpoint's URL, events subscription, or status (active/paused).

Scope: webhooks:manage

Delete a webhook endpoint and stop all deliveries to it.

Scope: webhooks:manage

Full documentation for NRS integration is coming soon. In the meantime, see the key concepts below.

NRS submission requires the Starter plan or higher. Free plan invoices can be finalized and signed but cannot be submitted to NRS.

Full Paystack integration documentation is coming soon.

Never expose your Paystack secret key in client-side code. All payment verification happens server-side.