Skip to main content

Billing

Overview​

The eFICA Billing API provides comprehensive billing and payment management functionality. This document covers the public billing endpoints available to all authenticated users.

Authentication​

All billing endpoints require Bearer token authentication. Include the following header in your requests:

Authorization: Bearer <your-jwt-token>
Content-Type: application/json

Endpoints​

1. Get Invoice Month Details​

Endpoint: GET /billing/getInvoiceMonthDetail/{year}/{month}

Authentication: Bearer token required (Admin users only)

Description: Retrieve detailed invoice information for a specific year and month. This endpoint provides transaction-level details for billing reconciliation.

Parameters:

  • year (path parameter): Year for invoice details (e.g., 2024)
  • month (path parameter): Month for invoice details (1-12)

Example Request:

curl -X GET "https://api.efica.co.za/billing/getInvoiceMonthDetail/2024/5" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json"

Response Structure:

[
  {
    "gross": -398.0000,
    "nett": -346.0870,
    "vat": -51.9130,
    "transactionChargeType": "Individual",
    "qty": 1
  }
]

Response Codes:

  • 200 - Invoice month details retrieved successfully
  • 400 - Bad Request - Invalid year or month parameters
  • 403 - Forbidden - Admin access required
  • 404 - Not Found - No invoice data found for specified period
  • 500 - Internal server error

2. Get Account Summary​

Endpoint: GET /billing/getAccountSummary

Authentication: Bearer token required (Admin users only)

Description: Retrieve account summary with transaction history for the authenticated user's partner. Supports pagination and date filtering.

Query Parameters:

  • take (optional): Number of records to return (default: 10, max: 100)
  • skip (optional): Number of records to skip for pagination (default: 0)
  • startDate (optional): Start date for filtering (ISO format)
  • endDate (optional): End date for filtering (ISO format)

Example Request:

curl -X GET "https://api.efica.co.za/billing/getAccountSummary?take=10&skip=0&startDate=01/01/2020&endDate=01/01/2026" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json"

Response Structure:

{
  "totalRecords": 173,
  "transactionHistory": [
    {
      "transactionID": 8835,
      "amount": -397,
      "paymentType": null,
      "status": "COMPLETE",
      "transactionDate": "2024-10-04T13:30:00.000Z",
      "transactionDescription": "Jane Doe Individual Fica Application",
      "individualFicaStatus": "In Progress",
      "entityFicaStatus": null,
      "entityRisk": null,
      "riskDescription": "Low Risk",
      "entityClientReference": null,
      "entityRegName": null,
      "entityRegNumber": null,
      "entityFicaApproveDate": null,
      "entityFicaApproveAdminName": null,
      "individualClientReference": "jd-001",
      "individualFirstName": "Jane",
      "individualLastName": "Doe",
      "individualIDNumber": "0101015000081",
      "individualPassportNumber": "",
      "individualFicaApproveDate": null,
      "individualFicaApproveAdminName": null,
      "entityNextReviewDate": null,
      "individualNextReviewDate": null,
      "usersFirstName": "Jane",
      "usersLastName": "Doe",
      "nettAmount": -345.2174,
      "vatAmount": -51.7826,
      "trustFicaStatus": null,
      "trustRiskStatus": null,
      "trustNextReviewDate": null,
      "trustClientReference": null,
      "trustName": null,
      "trustRegNumber": null,
      "trustFicaApproveDate": null
    }
  ]
}

Response Codes:

  • 200 - Account summary retrieved successfully
  • 400 - Bad Request - Invalid query parameters
  • 401 - Unauthorized - Invalid or missing authentication token
  • 403 - Forbidden - Admin access required
  • 500 - Internal server error

Error Handling​

Common Error Responses​

1. Authentication Errors​

{
  "message": "Unauthorized",
  "statusCode": 401
}

Causes:

  • Missing Authorization header
  • Invalid JWT token
  • Expired token

2. Permission Errors​

{
  "message": "Forbidden",
  "error": "Forbidden",
  "statusCode": 403
}

Causes:

  • User not admin
  • Insufficient permissions

3. Validation Errors​

{
  "message": ["amount must be a positive number"],
  "error": "Bad Request",
  "statusCode": 400
}

Causes:

  • Invalid parameters
  • Missing required fields

Usage Examples​

Get Invoice Details for Specific Month​

const response = await fetch('/billing/getInvoiceMonthDetail/2024/5', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  }
});

const invoiceDetails = await response.json();
console.log('Invoice details:', invoiceDetails);

Get Account Summary with Pagination​

const response = await fetch('/billing/getAccountSummary?take=10&skip=0&startDate=01/01/2020&endDate=01/01/2026', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  }
});

const accountSummary = await response.json();
console.log('Total records:', accountSummary.totalRecords);
console.log('Transactions:', accountSummary.transactionHistory);

Last Updated: 19 July 2025