Businesses

Create and manage businesses on the Earnipay platform. Each business represents a legal entity with its own FIRS configuration, team members, customers, products, and invoices. Users can belong to multiple businesses with different roles.

Endpoints

Method	Endpoint	Description
POST	`/v1/businesses`	Create a new business
GET	`/v1/businesses`	List your businesses
GET	`/v1/businesses/{id}`	Get business details
PATCH	`/v1/businesses/{id}`	Update a business
DELETE	`/v1/businesses/{id}`	Delete a business (soft delete)
PATCH	`/v1/businesses/{id}/settings`	Update business settings
PATCH	`/v1/businesses/{id}/firs-config`	Update FIRS configuration
PATCH	`/v1/businesses/{id}/crypto-keys`	Upload FIRS crypto keys file
PATCH	`/v1/businesses/{id}/app-config`	Configure APP connection
POST	`/v1/businesses/{id}/test-app-connection`	Test APP connection
PATCH	`/v1/businesses/{id}/app-provider`	Update APP provider
GET	`/v1/businesses/providers/supported`	List supported APP providers
PATCH	`/v1/businesses/{id}/interswitch-credentials`	Update Interswitch credentials
POST	`/v1/businesses/{id}/test-interswitch-connection`	Test Interswitch connection
POST	`/v1/businesses/{id}/set-default`	Set as default business
POST	`/v1/businesses/upload`	Upload a file (e.g., logo)

🔑
All endpoints on this page require authentication. See Authentication for details.

Create a Business

curl -X POST https://e-invoicing.earnipay.com/v1/businesses \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okafor Trading Ltd",
    "TIN": "12345678-0001",
    "businessType": "LLC",
    "address": "15 Marina Road",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "logoUrl": "https://example.com/logo.png",
    "firsEmail": "[email protected]",
    "firsPassword": "firs-portal-password"
  }'

Parameter	Type	Required	Description
`name`	string	Yes	Business legal name
`TIN`	string	Yes	Tax Identification Number
`businessType`	string	Yes	One of: `SOLE_PROPRIETORSHIP`, `PARTNERSHIP`, `LLC`, `CORPORATION`, `NON_PROFIT`, `OTHER`
`address`	string	Yes	Street address
`city`	string	Yes	City
`state`	string	Yes	State
`country`	string	Yes	Country
`logoUrl`	string	No	URL to business logo (use the upload endpoint first)
`firsEmail`	string	No	Email registered with FIRS
`firsPassword`	string	No	FIRS portal password

{
  "statusCode": 201,
  "message": "Business created successfully.",
  "data": {
    "id": "biz_xyz789",
    "name": "Okafor Trading Ltd",
    "TIN": "12345678-0001",
    "businessType": "LLC",
    "address": "15 Marina Road",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "logoUrl": "https://example.com/logo.png",
    "firsEmail": "[email protected]",
    "settings": {
      "requireApproval": false,
      "autoSubmitToFirs": false
    },
    "firsConfig": null,
    "appProvider": null,
    "createdAt": "2026-03-13T10:00:00.000Z",
    "updatedAt": "2026-03-13T10:00:00.000Z"
  }
}

List Businesses

Retrieve all businesses associated with your account.

curl https://e-invoicing.earnipay.com/v1/businesses \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Businesses retrieved successfully.",
  "data": [
    {
      "id": "biz_xyz789",
      "name": "Okafor Trading Ltd",
      "TIN": "12345678-0001",
      "businessType": "LLC",
      "city": "Lagos",
      "state": "Lagos",
      "country": "Nigeria",
      "createdAt": "2026-03-13T10:00:00.000Z"
    }
  ]
}

Get Business Details

Retrieve full details for a specific business, including its FIRS configuration and APP provider settings.

curl https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Business retrieved successfully.",
  "data": {
    "id": "biz_xyz789",
    "name": "Okafor Trading Ltd",
    "TIN": "12345678-0001",
    "businessType": "LLC",
    "address": "15 Marina Road",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "logoUrl": "https://example.com/logo.png",
    "firsEmail": "[email protected]",
    "settings": {
      "requireApproval": true,
      "autoSubmitToFirs": false
    },
    "firsConfig": {
      "businessId": "FIRS-BIZ-001",
      "serviceId": "FIRS-SVC-001"
    },
    "appProvider": {
      "name": "interswitch",
      "isConnected": true
    },
    "createdAt": "2026-03-13T10:00:00.000Z",
    "updatedAt": "2026-03-13T12:30:00.000Z"
  }
}

Update a Business

Update business details. Send only the fields you want to change.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okafor Trading International Ltd",
    "address": "42 Victoria Island Blvd"
  }'

{
  "statusCode": 200,
  "message": "Business updated successfully.",
  "data": {
    "id": "biz_xyz789",
    "name": "Okafor Trading International Ltd",
    "address": "42 Victoria Island Blvd",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "updatedAt": "2026-03-13T14:00:00.000Z"
  }
}

Delete a Business

Soft-delete a business. The business and its data are retained but marked as deleted and no longer accessible through normal queries.

curl -X DELETE https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Business deleted successfully."
}

⚠️
Deleting a business is a soft delete — the record is preserved for historical and compliance purposes but becomes inaccessible. Only business owners can delete a business.

Business Settings

Configure approval workflows and automatic FIRS submission for a business.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/settings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "requireApproval": true,
    "autoSubmitToFirs": true
  }'

Parameter	Type	Required	Description
`requireApproval`	boolean	No	When `true`, invoices move to `PENDING_APPROVAL` status and require manual approval before submission
`autoSubmitToFirs`	boolean	No	When `true`, approved invoices are automatically submitted to FIRS via the configured APP provider

{
  "statusCode": 200,
  "message": "Business settings updated successfully.",
  "data": {
    "requireApproval": true,
    "autoSubmitToFirs": true
  }
}

💡
When both settings are enabled, invoices follow the full workflow: DRAFT → PENDING_APPROVAL → APPROVED → automatically submitted to FIRS. When requireApproval is false, invoices skip the approval step.

FIRS Configuration

Update FIRS Config

Set the FIRS Business ID and Service ID for your business. These identifiers are assigned by FIRS when you register for e-invoicing.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/firs-config \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "FIRS-BIZ-001",
    "serviceId": "FIRS-SVC-001"
  }'

Parameter	Type	Required	Description
`businessId`	string	Yes	Your FIRS-assigned Business ID
`serviceId`	string	Yes	Your FIRS-assigned Service ID

{
  "statusCode": 200,
  "message": "FIRS configuration updated successfully.",
  "data": {
    "businessId": "FIRS-BIZ-001",
    "serviceId": "FIRS-SVC-001"
  }
}

Upload Crypto Keys

Upload the crypto_keys.txt file provided by FIRS. This file contains the RSA public key used to encrypt QR codes on invoices.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/crypto-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@crypto_keys.txt"

Parameter	Type	Required	Description
`file`	file	Yes	The `crypto_keys.txt` file from FIRS (contains RSA public key)

{
  "statusCode": 200,
  "message": "Crypto keys uploaded successfully."
}

APP Provider Configuration

Configure an Access Point Provider (APP) to submit invoices to FIRS. APPs are licensed service providers in Nigeria's e-invoicing network that handle secure invoice signing and transmission.

List Supported Providers

Get the list of APP providers that Earnipay supports.

curl https://e-invoicing.earnipay.com/v1/businesses/providers/supported \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Supported providers retrieved successfully.",
  "data": [
    {
      "name": "interswitch",
      "displayName": "Interswitch",
      "description": "Submit invoices to FIRS via Interswitch"
    }
  ]
}

Update APP Provider

Set which APP provider to use for this business.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/app-provider \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "interswitch"
  }'

{
  "statusCode": 200,
  "message": "APP provider updated successfully.",
  "data": {
    "name": "interswitch",
    "isConnected": false
  }
}

Configure APP Connection

Provide the connection details for your APP provider.

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/app-config \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "apiUrl": "https://app-provider.example.com/api",
    "apiKey": "your-app-provider-api-key",
    "clientId": "your-client-id"
  }'

Test APP Connection

Verify that the APP provider connection is working before submitting invoices.

curl -X POST https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/test-app-connection \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "APP connection test successful.",
  "data": {
    "connected": true
  }
}

{
  "statusCode": 400,
  "message": "APP connection test failed. Please check your configuration.",
  "data": {
    "connected": false,
    "error": "Unable to reach the APP provider endpoint."
  }
}

Interswitch Integration

If you're using Interswitch as your APP provider, configure and test the connection with these endpoints.

Update Interswitch Credentials

curl -X PATCH https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/interswitch-credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "ISW-CLIENT-12345",
    "clientSecret": "isw-secret-key",
    "merchantCode": "MX12345"
  }'

Parameter	Type	Required	Description
`clientId`	string	Yes	Interswitch client ID
`clientSecret`	string	Yes	Interswitch client secret
`merchantCode`	string	Yes	Your Interswitch merchant code

{
  "statusCode": 200,
  "message": "Interswitch credentials updated successfully."
}

Test Interswitch Connection

curl -X POST https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/test-interswitch-connection \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Interswitch connection test successful.",
  "data": {
    "connected": true
  }
}

Set Default Business

Set a business as your default. The default business is used when no business ID is specified in API calls that require one.

curl -X POST https://e-invoicing.earnipay.com/v1/businesses/biz_xyz789/set-default \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Default business set successfully."
}

Upload File

Upload a file (such as a business logo) to cloud storage. Returns a URL you can use in other API calls.

curl -X POST https://e-invoicing.earnipay.com/v1/businesses/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "[email protected]"

{
  "statusCode": 200,
  "message": "File uploaded successfully.",
  "data": {
    "url": "https://storage.earnipay.com/uploads/company-logo-abc123.png"
  }
}

Use the returned url as the logoUrl when creating or updating a business.

Setup Checklist

To fully configure a business for FIRS e-invoicing, complete these steps in order:

Create the business — POST /v1/businesses with your TIN and business details
Update FIRS config — PATCH /v1/businesses/{id}/firs-config with your FIRS Business ID and Service ID
Upload crypto keys — PATCH /v1/businesses/{id}/crypto-keys with the crypto_keys.txt file from FIRS
Choose an APP provider — PATCH /v1/businesses/{id}/app-provider
Configure the provider — PATCH /v1/businesses/{id}/app-config or PATCH /v1/businesses/{id}/interswitch-credentials
Test the connection — POST /v1/businesses/{id}/test-app-connection or POST /v1/businesses/{id}/test-interswitch-connection
Configure settings — PATCH /v1/businesses/{id}/settings to enable approval workflows and auto-submit

Error Handling

Status Code	Error	Description
`400`	Bad Request	Invalid parameters or failed connection test
`401`	Unauthorized	Missing or expired access token
`403`	Forbidden	You don't have permission (e.g., not an OWNER or ADMIN)
`404`	Not Found	Business ID doesn't exist or was deleted
`409`	Conflict	Business with this TIN already exists

{
  "statusCode": 403,
  "message": "You do not have permission to perform this action.",
  "error": "Forbidden"
}