JUST ERRAND

📖 API Overview

The Cyber 1 Transaction Management System (TMS) API enables seamless integration for processing customer transactions including vehicle road tax, toll payments, and transport levies.

Base URL: https://tms-local-api.justerrand.ie/api/v1
Method: POST
Format: JSON

📋 Two-Phase Workflow:

Phase	Purpose	Frequency
Phase 1: Onboarding	Register corporate entities, agents, and terminals	One-time setup
Phase 2: Transactions	Validate customers, create transactions, update payment status	Every transaction

⚠️ Important: Every agent must belong to a registered corporate entity. Complete corporate onboarding before agent onboarding.

🔐 Authentication

All API requests require a valid API key. You need to include the API key in every request.

📌 Headers:

Content-Type: application/json

📌 API Key Parameter:

{
    "key": "your_api_key_here"
}

⚠️ Note: Contact administrator at osuntola.oluwaseun@cyber1systemsnetwork.com to get your API key.

📋 Phase 1: Onboarding (One-Time Setup)

🏢 Create Corporate Entity

Action: create-company

The corporate entity is the legal umbrella under which agents operate.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecocreate-companyNonedeco。nameNonedecostringNonedecoYesNonedecoFull registered company nameNonedeco。rc_numberNonedecostringNonedecoYesNonedecoCAC registration numberNonedeco。emailNonedecostringNonedecoYesNonedecoOfficial company emailNonedeco。phone_numberNonedecostringNonedecoYesNonedeco11-digit phone numberNonedeco。addressNonedecostringNonedecoYesNonedecoRegistered business addressNonedeco。contact_addressNonedecostringNonedecoYesNonedecoAlternative contact addressNonedeco。tinNonedecostringNonedecoYesNonedecoTax Identification NumberNonedeco。cityNonedecostringNonedecoYesNonedecoCity of operationNonedeco。stateNonedecostringNonedecoYesNonedecoState of operationNonedeco。lgaNonedecostringNonedecoYesNonedecoLGA of operationNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "create-company",   
    "name": "Cyber1 Systems Network International Limited",
    "rc_number": "RC1234567",
    "email": "info@cyber1systemsnetwork.com",
    "phone_number": "08012345678",
    "address": "23, Allen Avenue, Ikeja",
    "contact_address": "Suite 5, Mega Plaza, Lagos",
    "tin": "12345678-0001",
    "city": "Lagos",
    "state": "LAGOS",
    "lga": "Ikeja"
}

✅ Success Response:

{
    "status": true,
    "message": "Company Registration Successful!",
    "data": {
        "company_number": "C09649886901"
    }
}

💡 Note: Save the company_number - required when creating agents.

👤 Register Agent

Action: add-agent

Agents are individuals who use POS terminals to collect payments. Each agent must be linked to a corporate entity.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecoadd-agentNonedeco。titleNonedecostringNonedecoYesNonedecoMr/Mrs/Miss/Chief/Dr/ProfNonedeco。first_nameNonedecostringNonedecoYesNonedecoFirst nameNonedeco。last_nameNonedecostringNonedecoYesNonedecoLast nameNonedeco。emailNonedecostringNonedecoYesNonedecoEmail addressNonedeco。passwordNonedecostringNonedecoYesNonedecoPassword (min 6 characters)Nonedeco。phone_numberNonedecostringNonedecoYesNonedeco11-digit phone numberNonedeco。company_numberNonedecostringNonedecoYesNonedecoCorporate number from create-companyNonedeco。bank_nameNonedecostringNonedecoYesNonedecoName of bankNonedeco。account_numberNonedecostringNonedecoYesNonedecoBank account numberNonedeco。account_nameNonedecostringNonedecoYesNonedecoAccount holder nameNonedeco。bvnNonedecostringNonedecoYesNonedecoBank Verification Number (11 digits)Nonedeco。ninNonedecostringNonedecoYesNonedecoNational Identification NumberNonedeco。id_typeNonedecostringNonedecoYesNonedecoVoters Card/Passport/Drivers LicenseNonedeco。identity_numberNonedecostringNonedecoYesNonedecoNumber on selected ID documentNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "add-agent",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "password": "password123",
    "phone_number": "08012345678",
    "company_number": "C09649886901",
    "gender": "male",
    "marital_status": "single",
    "date_of_birth": "1989-01-16",
    "address": "15, Peace Avenue, Abuja",
    "city": "Abuja",
    "nationality": "Nigerian",
    "state": "FCT",
    "lga": "Abuja Municipal",
    "state_of_origin": "Ogun",
    "lga_of_origin": "Sagamu",
    "bvn": "22422467081",
    "nin": "12345678901",
    "bank_name": "First Bank of Nigeria",
    "account_number": "0123456789",
    "account_name": "John Doe",
    "sort_code": "011234567",
    "id_type": "International Passport",
    "identity_number": "A12345678",
    "tin": "12345678-0002",
    "utility_bill": "base64_encoded_string_here",
    "identity_document": "base64_encoded_string_here",
    "passport_photo": "base64_encoded_string_here"
}

✅ Success Response:

{
    "status": true,
    "message": "Agent Registration Successful!",
    "data": {
        "id": 404,
        "agent_number": "AG91922595558"
    }
}

💻 Create POS Terminal

Action: create-terminal

Each physical POS machine must be registered and assigned to a specific agent.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecocreate-terminalNonedeco。serial_numberNonedecostringNonedecoYesNonedecoUnique serial number of POS deviceNonedeco。terminal_idNonedecostringNonedecoYesNonedecoTerminal identifier (printed on device)Nonedeco。agent_numberNonedecostringNonedecoYesNonedecoAgent number from registrationNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "create-terminal",
    "serial_number": "920082592",
    "terminal_id": "TX3456QW",
    "agent_number": "AG91922595558"
}

✅ Success Response:

{
    "status": true,
    "message": "Terminal Profiling Successful!",
    "data": null
}

💰 Phase 2: Transaction Processing

✅ Validate Customer

Action: validate-customer

Before collecting payment, verify customer details to determine the correct amount.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecovalidate-customerNonedeco。vehicle_licenseNonedecostringNonedecoYesNonedecoVehicle license plate numberNonedeco。transaction_typeNonedecostringNonedecoYesNonedeco"single" or "complete"Nonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "validate-customer",
    "vehicle_license": "BAL31XA",
    "transaction_type": "complete"
}

✅ Success Response:

{
    "status": true,
    "message": "success",
    "data": {
        "vehicle_type": "pick up heavy duty 6/8 tyres",
        "vehicle_license": "YAB444CJ",
        "enumerating_lga": "Esit Eket",
        "enumerating_state": "Akwa Ibom",
        "issuing_state": "Anambra",
        "price": {
            "name": "pick up heavy duty 6/8 tyres",
            "type": "single",
            "price": "5850.00"
        }
    }
}

📝 Create Transaction

Action: create-transaction

Create a transaction record and trigger the payment processing engine.

📝 Required Fields:

Parameter	Type	Required	Description
`key`	string	Yes	API Key for authentication
`action`	string	Yes	Must be `create-transaction`
`payer_name`	string	Yes	Customer's full name
`payer_phone`	string	Yes	Customer's phone number
`payer_email`	string	Yes	Customer's email address
`amount`	string	Yes	Base amount from validation (formatted as string with 2 decimals)
`fee`	string	Yes	Convenience fee (formatted as string with 2 decimals)
`payment_method`	string	Yes	Options: `card`, `wallet`, `transfer`
`terminal_id`	string	Yes	POS terminal ID
`vehicle_license`	string	Yes	License plate number
`vehicle_type`	string	Yes	Type of vehicle
`transaction_type`	string	Yes	Options: `single` or `complete`
`origin_state`	string	Yes	State where trip begins
`origin_lga`	string	Yes	LGA where trip begins
`destination_state`	string	No	Destination state (null if single trip)
`destination_lga`	string	No	Destination LGA (null if single trip)

📤 Example Request (Complete Trip):

{
    "key": "your_api_key_here",
    "action": "create-transaction",
    "transaction_reference": "TXN17819420351921",
    "payer_name": "Amalunweze Chinecherem Johnmartin",
    "payer_phone": "08161160841",
    "payer_email": "customer@example.com",
    "amount": "3000.00",
    "fee": "250.00",
    "transaction_date": "2026-06-20 07:53:55",
    "channel_number": "CH84693954642",
    "payment_method": "card",
    "terminal_id": "TX3456QW",
    "service_number": "S13401182324",
    "metadata": {
        "channel": "dealcity",
        "channel_type": "pos",
        "terminal_id": "TX3456QW",
        "contact": "08161160841",
        "vehicle_type": "Pick up Vans and its equivalent (4 Tyres)",
        "transaction_type": "complete",
        "transaction_date": "2026-06-20 07:53:55",
        "amount": "3000.00",
        "vehicle_license": "BAL31XA",
        "transaction_reference": "TXN17819420351921",
        "origin_state": "LAGOS",
        "origin_lga": "IKEJA",
        "destination_state": "ABUJA",
        "destination_lga": "AMAC",
        "payload": null
    }
}

💡 Note: The transaction_reference, transaction_date, channel_number, and service_number are automatically generated by the system. The metadata object contains additional transaction details.

📤 Example Request (Single Trip):

{
    "key": "your_api_key_here",
    "action": "create-transaction",
    "transaction_reference": "TXN17819420351922",
    "payer_name": "John Doe",
    "payer_phone": "08012345678",
    "payer_email": "john@example.com",
    "amount": "1500.00",
    "fee": "100.00",
    "transaction_date": "2026-06-20 08:30:00",
    "channel_number": "CH84693954642",
    "payment_method": "wallet",
    "terminal_id": "TX3456QW",
    "service_number": "S13401182324",
    "metadata": {
        "channel": "dealcity",
        "channel_type": "pos",
        "terminal_id": "TX3456QW",
        "contact": "08012345678",
        "vehicle_type": "Saloon Cars",
        "transaction_type": "single",
        "transaction_date": "2026-06-20 08:30:00",
        "amount": "1500.00",
        "vehicle_license": "LAG123ABC",
        "transaction_reference": "TXN17819420351922",
        "origin_state": "LAGOS",
        "origin_lga": "MAINLAND",
        "destination_state": null,
        "destination_lga": null,
        "payload": null
    }
}

✅ Success Response:

{
    "status": true,
    "message": "Transaction created successfully",
    "data": {
        "transaction_reference": "TXN17819420351921",
        "status": "pending",
        "transaction_details": {
            "session_id": "SES123456789",
            "status": "Pending",
            "total": 3250.00,
            "reference": "TXN17819420351921"
        }
    }
}

❌ Error Response:

{
    "status": false,
    "message": "Validation failed",
    "errors": {
        "payer_name": ["The payer name field is required."],
        "amount": ["The amount must be a number."]
    }
}

👍 Get All Transaction

Action: get-all-transaction

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecoapprove-transactionNonedeco。terminal_idNonedecostringNonedecoYesNonedecoTransaction reference from create-transactionNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "get-all-transaction",
    "terminal_id": "TXN2024001"
}

✅ Success Response:

{
    "status": true,
    "message": "All Transaction Retrived successfully!"
}

👍 Approve Transaction

Action: approve-transaction

After successful payment processing, update the transaction status to approved.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecoapprove-transactionNonedeco。transaction_referenceNonedecostringNonedecoYesNonedecoTransaction reference from create-transactionNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "approve-transaction",
    "transaction_reference": "TXN2024001"
}

✅ Success Response:

{
    "status": true,
    "message": "Transaction approved and confirmed successfully!"
}

👎 Decline Transaction

Action: decline-transaction

When payment fails, update the transaction status to declined.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecodecline-transactionNonedeco。transaction_referenceNonedecostringNonedecoYesNonedecoTransaction reference from create-transactionNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "decline-transaction",
    "transaction_reference": "TXN2024001"
}

✅ Success Response:

{
    "status": true,
    "message": "Transaction declined!"
}

🔍 Verify Transaction Status

Action: verify-transaction

Check the final status of a transaction.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecoverify-transactionNonedeco。transaction_referenceNonedecostringNonedecoYesNonedecoTransaction reference to verifyNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "verify-transaction",
    "transaction_reference": "TXN2024001"
}

✅ Success Response:

{
    "status": true,
    "message": "success",
    "data": {
        "transaction_reference": "TXN2024001",
        "status": "approved",
        "amount": "3000.00",
        "fee": "250.00"
    }
}

🛠️ Supporting Endpoints

🗺️ Get Nigerian States

Action: get-states

Retrieve list of all Nigerian states.

📤 Example Request:

{
    "key": "your_key",
    "action": "get-states"
}

✅ Success Response:


                      {
    "status": true,
    "message": "success",
    "data": [
        {"id": 1, "name": "First Item"},
        {"id": 2, "name": "Second Item"},
        {"id": 3, "name": "Third Item"},
        "..."
    ]
}

📍 Get LGAs by State

Action: get-lgas

Retrieve list of Local Government Areas for a specific state.

📝 Required Fields:

。state_idNonedecostringNonedecoYesNonedecoName of the state (e.g., "Lagos")Nonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "get-lgas",
    "state_id": "123"
}

✅ Success Response:

{
    "status": true,
    "message": "success",
    "data": ["Ikeja", "Surulere", "Victoria Island", ...]
}

📍 Get Company

Action: get-company

📝 Required Fields:

。rc_numberNonedecostringNonedecoYesNonedecocompany_number (e.g., "C09649886901")Nonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_api_key",
    "action": "get-company",
    "company_number": "C09649886901"
}

✅ Success Response (200):

{ "status": true, "message": "success", "data": { "company_number": "C09649886901", "name": "Dealgadget Upgrade Limited", "rc_number": "RC1234567", "email": "info@company.com", "phone_number": "08012345678", "address": "Registered address", "contact_address": "Contact address", "tin": "12345678-0001", "city": "Lagos", "state": "LAGOS", "lga": "Ikeja" } }

📍 Get All Company

Action: get-all-companies

📝 Required Fields:

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_api_key",
    "action": "get-all-companies"    
}

✅ Success Response (200):

{ "status": true, "message": "Companies retrieve successfully", "data": [] }

📍 Get All Agents

Action: get-all-agents

📝 Required Fields:

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_api_key",
    "action": "get-all-agents"    
}

✅ Success Response (200):

{ "status": true, "message": "Companies retrieve successfully", "data": [] }

📍 Get All Terminals

Action: view-terminals

📝 Required Fields:

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_api_key",
    "action": "view-terminals"    
}

✅ Success Response (200):

{ "status": true, "message": "Terminals retrieve successfully", "data": [] }

📍 Get Terminal Detail

Action: get-terminal-detail

📝 Required Fields:

Parameter	Type	Required	Description
`tid`NonedecostringNonedecoYesNonedeco

📤 Example Request:

{
    "key": "your_api_key",
    "action": "get-terminal-detail",
    "id": "TX3456QW"    
}

✅ Success Response (200):

{ "status": true, "message": "Terminals retrieve successfully", "data": [] }

🔑 User Login

Action: login

Authenticate users (agents) into the system.

📝 Required Fields:

。keyNonedecostringNonedecoYesNonedecoAPI KeyNonedeco。actionNonedecostringNonedecoYesNonedecologinNonedeco。emailNonedecostringNonedecoYesNonedecoEmail or phone numberNonedeco。passwordNonedecostringNonedecoYesNonedecoPasswordNonedeco

Parameter	Type	Required	Description

📤 Example Request:

{
    "key": "your_key",
    "action": "login",
    "email": "john.doe@example.com",
    "password": "password123"
}

✅ Success Response:

{
    "status": true,
    "message": "User login successful",
    "data": {
        "id": 404,
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "role": "Agent",
        "agent_number": "AG91922595558",
        "company_number": "C09649886901"
    }
}

⚠️ Error Codes

Error Code	Description	Solution
`Invalid API key`	The provided API key is not valid	Contact admin for valid API key
`Email already registered`	The email is already in use	Use a different email address
`Phone number already registered`	The phone number is already in use	Use a different phone number
`Invalid credentials`	Email/phone or password is incorrect	Check your login credentials
`Validation failed`	Request validation errors	Check required fields and formats
`Transaction not found`	Transaction reference doesn't exist	Verify transaction reference
`Duplicate transaction`	Transaction reference already exists	Generate unique reference

🧪 cURL Examples

Create Company:

curl -X POST https://tms-local-api.justerrand.ie/api/api_data \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_key",
    "action": "create-company",
    "name": "Test Company Ltd",
    "rc_number": "RC1234567",
    "email": "info@test.com",
    "phone_number": "08012345678",
    "address": "23 Test Street",
    "contact_address": "Suite 5",
    "tin": "12345678-0001",
    "city": "Lagos",
    "state": "LAGOS",
    "lga": "Ikeja"
}'

Create Transaction:

curl -X POST https://tms-local-api.justerrand.ie/api/api_data \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_key",
    "action": "create-transaction",
    "payer_name": "John Customer",
    "payer_phone": "08161160841",
    "payer_email": "customer@example.com",
    "amount": "3000.00",
    "fee": "250.00",
    "payment_method": "card",
    "terminal_id": "TX3456QW",
    "vehicle_license": "BAL31XA",
    "vehicle_type": "Pick up Vans",
    "transaction_type": "complete",
    "origin_state": "LAGOS",
    "origin_lga": "IKEJA",
    "destination_state": "ABUJA",
    "destination_lga": "AMAC"
}'

📱 Flutter Integration Examples

Create Company in Flutter:

Future createCompany() async {
  final response = await http.post(
    Uri.parse('https://tms-local-api.justerrand.ie/api/api_data'),
    headers: {'Content-Type': 'application/json'},
    body: json.encode({
      'key': 'your_key',
      'action': 'create-company',
      'name': 'Test Company Ltd',
      'rc_number': 'RC1234567',
      'email': 'info@test.com',
      'phone_number': '08012345678',
      'address': '23 Test Street',
      'contact_address': 'Suite 5',
      'tin': '12345678-0001',
      'city': 'Lagos',
      'state': 'LAGOS',
      'lga': 'Ikeja',
    }),
  );
  
  if (response.statusCode == 200) {
    var data = json.decode(response.body);
    print('Success: ${data['message']}');
  }
}

Validate Customer in Flutter:

Future validateCustomer() async {
  final response = await http.post(
    Uri.parse('https://tms-local-api.justerrand.ie/api/api_data'),
    headers: {'Content-Type': 'application/json'},
    body: json.encode({
      'key': 'your_key',
      'action': 'validate-customer',
      'vehicle_license': 'BAL31XA',
      'transaction_type': 'complete',
    }),
  );
  
  if (response.statusCode == 200) {
    var data = json.decode(response.body);
    if (data['status'] == true) {
      setState(() {
        vehicleType = data['data']['vehicle_type'];
        amount = data['data']['price']['price'];
      });
    }
  }
}

🚀 TMS API Documentation

📖 API Overview

📋 Two-Phase Workflow:

🔐 Authentication

📌 Headers:

📌 API Key Parameter:

📋 Phase 1: Onboarding (One-Time Setup)

🏢 Create Corporate Entity

📝 Required Fields:

📤 Example Request:

✅ Success Response:

👤 Register Agent

📝 Required Fields:

📤 Example Request:

✅ Success Response:

💻 Create POS Terminal

📝 Required Fields:

📤 Example Request:

✅ Success Response:

💰 Phase 2: Transaction Processing

✅ Validate Customer

📝 Required Fields:

📤 Example Request:

✅ Success Response:

📝 Create Transaction

📝 Required Fields:

📤 Example Request (Complete Trip):

📤 Example Request (Single Trip):

✅ Success Response:

❌ Error Response:

👍 Get All Transaction

📝 Required Fields:

📤 Example Request:

✅ Success Response:

👍 Approve Transaction

📝 Required Fields:

📤 Example Request:

✅ Success Response:

👎 Decline Transaction

📝 Required Fields:

📤 Example Request:

✅ Success Response:

🔍 Verify Transaction Status

📝 Required Fields:

📤 Example Request:

✅ Success Response:

🛠️ Supporting Endpoints

🗺️ Get Nigerian States

📤 Example Request:

✅ Success Response:

📍 Get LGAs by State

📝 Required Fields:

📤 Example Request:

✅ Success Response:

📍 Get Company

📝 Required Fields:

📤 Example Request:

✅ Success Response (200):

📍 Get All Company

📝 Required Fields:

📤 Example Request:

✅ Success Response (200):

📍 Get All Agents

📝 Required Fields:

📤 Example Request:

✅ Success Response (200):

📍 Get All Terminals

📝 Required Fields:

📤 Example Request:

✅ Success Response (200):

📍 Get Terminal Detail

📝 Required Fields:

📤 Example Request:

✅ Success Response (200):

🔑 User Login

📝 Required Fields:

📤 Example Request:

✅ Success Response:

⚠️ Error Codes

🧪 cURL Examples