agent-api-doc

Markdown Live Preview
Reset
Copy

13131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350
- **TV:** Fixed amount per subscription type
- **Duplicate Prevention:** Reference uniqueness enforced
- **Balance Locking:** Wallet operations use database locks
- **Audit Logging:** All transactions logged with metadata
POS API Documentation
Base URL: /v1/pos
Middleware: api, force.json

Authentication Endpoints
Login
POST /auth/login
Description: Authenticate POS agent using email/password or email/PIN. Supports dual authentication methods - traditional password login and PIN-based login for faster access. Returns bearer token for API access.
Authentication: None required
Use Case: Initial authentication when agent starts POS session, supports both password and PIN login
Business Logic: Detects login type (password/PIN), validates credentials, checks verification status, generates Sanctum token
Request Parameters (Password Login):

email (string, required): Agent's email address or phone number
password (string, required): Agent's account password
Request Parameters (PIN Login):

email (string, required): Agent's email address or phone number
pin (string, required): 4-digit transaction PIN
Password Login Request:

{
  "email": "agent@example.com",
  "password": "password123"
}
PIN Login Request:

{
  "email": "08012345678",
  "pin": "1234"
}
Validation Rules:

Email/phone must exist in system
Password/PIN must match stored hash
Account verification_status must be 1 or 'Approved'
PIN must be exactly 4 digits if using PIN login
PIN must be set before PIN login can be used
Success Response:

{
  "status": "success",
  "responseCode": "00", 
  "message": "Login successful",
  "data": {
    "token": "sanctum_bearer_token",
    "agent": {
      "id": "subagent_id",
      "agent_id": "parent_agent_id",
      "name": "First Name Last Name",
      "email": "agent@example.com",
      "business_name": "Business Name"
    }
  }
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "Invalid credentials"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Account not verified"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "PIN not set. Please create a PIN first"
}
Logout
POST /auth/logout
Description: Invalidate current authentication token and logout agent. This endpoint revokes the bearer token, preventing further API access until re-authentication. All active sessions are terminated.
Authentication: Bearer token required
Use Case: End POS session securely, prevent unauthorized access after agent finishes work
Business Logic: Blacklists current token, logs session end, clears any cached session data
Request: No body required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Logout successful"
}
PIN Management
Request PIN Creation OTP
POST /auth/pin/create-otp
Description: Request OTP to create new transaction PIN. Sends a 4-digit verification code to the agent's registered email address. The OTP is valid for 10 minutes and can only be used once.
Authentication: None required
Use Case: First-time PIN setup for new agents or when PIN creation is required
Business Logic: Validates agent exists, checks no existing PIN, generates 4-digit OTP, sends email, stores OTP with reference
Request Parameters:

email (string, required): Agent's registered email address
Request:

{
  "email": "agent@example.com"
}
Validation Rules:

Email must be valid format and exist in system
Agent must not have existing PIN set
Email service must be available
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "OTP sent to your email",
  "data": {
    "reference": "otp_reference_string"
  }
}
Error Responses:

{
  "status": "error",
  "responseCode": "04",
  "message": "Agent not found"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "PIN already exists. Use reset PIN instead"
}
Create Transaction PIN
POST /auth/pin/create
Description: Create new transaction PIN using OTP verification. The PIN must be 4 digits and will be required for PIN-based login. PIN is encrypted using bcrypt and stored securely.
Authentication: None required
Use Case: Complete PIN setup process after OTP verification
Business Logic: Validates OTP with reference, encrypts PIN using bcrypt, stores hashed PIN in 2fa_pin field, invalidates OTP
Request Parameters:

email (string, required): Agent's email address or phone number
otp (string, required): 4-digit verification code received via email
reference (string, required): OTP reference from create-otp request
pin (string, required): New 4-digit transaction PIN
pin_confirmation (string, required): PIN confirmation (must match pin)
Request:

{
  "email": "agent@example.com",
  "otp": "1234",
  "reference": "otp_reference_string",
  "pin": "5678",
  "pin_confirmation": "5678"
}
Validation Rules:

OTP must be valid and not expired (10 minutes)
PIN must be exactly 4 digits
PIN confirmation must match PIN
Reference must match OTP session
Agent must not have existing PIN
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "PIN created successfully"
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "PIN confirmation does not match"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Invalid or expired OTP"
}
Request PIN Reset OTP
POST /auth/pin/reset-otp
Description: Request OTP to reset existing transaction PIN. Sends a 4-digit verification code to the agent's registered phone number. The OTP is valid for 10 minutes and can only be used once.
Authentication: Bearer token required
Use Case: Reset forgotten transaction PIN
Business Logic: Validates existing PIN exists, generates 4-digit OTP, sends SMS, stores OTP with expiry
Request Parameters:

email (string, required): Agent's email or phone number
Request:

{
  "email": "agent@example.com"
}
Validation Rules:

Email/phone must match registered agent
Agent must have existing PIN set
SMS service must be available
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "OTP sent successfully",
  "data": {
    "reference": "otp_reference_123"
  }
}
Reset Transaction PIN
PUT /auth/pin/reset
Description: Reset existing transaction PIN using OTP verification. Replaces current PIN with new 4-digit PIN after successful OTP validation. Agent must have existing PIN.
Authentication: None required
Use Case: Reset forgotten PIN or change existing PIN
Business Logic: Validates existing PIN exists, verifies OTP with reference, encrypts new PIN, replaces old PIN, invalidates OTP
Request Parameters:

email (string, required): Agent's email address or phone number
otp (string, required): 4-digit verification code received via email
reference (string, required): OTP reference from reset-otp request
new_pin (string, required): New 4-digit transaction PIN
new_pin_confirmation (string, required): PIN confirmation (must match new_pin)
Request:

{
  "email": "agent@example.com",
  "otp": "1234",
  "reference": "otp_reference_123",
  "new_pin": "9876",
  "new_pin_confirmation": "9876"
}
Validation Rules:

Agent must have existing PIN set
OTP must be valid and not expired
PIN must be exactly 4 digits
PIN confirmation must match new PIN
Reference must match OTP session
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "PIN reset successfully"
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "No PIN exists. Use create PIN instead"
}
Password Management
Request Password Reset OTP
POST /auth/password/reset-otp
Description: Request OTP to reset account password. Sends a 4-digit verification code to the agent's registered phone number for password reset verification.
Authentication: None required
Use Case: Initiate password reset when agent forgets login password
Business Logic: Validates agent exists, generates 4-digit OTP, sends SMS, stores OTP with expiry
Request Parameters:

email (string, required): Agent's registered email address
Request:

{
  "email": "agent@example.com"
}
Validation Rules:

Email must exist in system
Agent account must be active
SMS service must be available
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "OTP sent successfully",
  "data": {
    "reference": "pwd_reset_ref_123"
  }
}
Change Password
PUT /auth/password/reset
Description: Change account login password using OTP verification. Updates the password used for email/password login after successful OTP validation.
Authentication: None required
Use Case: Reset forgotten password or change existing password
Business Logic: Validates OTP with reference, encrypts new password using bcrypt, updates password field, invalidates OTP
Request Parameters:

email (string, required): Agent's email address or phone number
otp (string, required): 4-digit verification code received via email
reference (string, required): OTP reference from reset-otp request
new_password (string, required): New password (minimum 6 characters)
new_password_confirmation (string, required): Password confirmation (must match new_password)
Request:

{
  "email": "agent@example.com",
  "otp": "1234",
  "reference": "pwd_reset_ref_123",
  "new_password": "newpassword123",
  "new_password_confirmation": "newpassword123"
}
Validation Rules:

OTP must be valid and not expired
Password must be minimum 6 characters
Password confirmation must match new password
Reference must match OTP session
Agent must exist in system
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Password changed successfully"
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "Password confirmation does not match"
}
Profile & Wallet Endpoints
Get Agent Profile
GET /profile
Description: Retrieve authenticated agent's complete profile information including personal details, business information, account status, wallet balances, and PIN status. Used for POS dashboard display.
Authentication: Bearer token required
Use Case: Display agent details in POS dashboard, verify agent information, check account status
Business Logic: Authenticates agent via token, fetches SubAgent record, formats response with all profile fields
Request: No parameters required

Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Agent details retrieved successfully",
  "data": {
    "id": "subagent_id",
    "name": "First Name Last Name",
    "email": "agent@example.com",
    "phone": "08012345678",
    "business_name": "Business Name",
    "verification_status": "Approved",
    "wallet_balance": "15000.00",
    "comm_balance": "2500.00",
    "has_pin": true
  }
}
Update Agent Profile
PUT /profile
Description: Update authenticated agent's profile information including personal details, contact information, and business details. Only provided fields will be updated, others remain unchanged.
Authentication: Bearer token required
Use Case: Update agent information, change contact details, update addresses
Business Logic: Authenticates agent, validates input fields, updates only provided fields in SubAgent record
Request Parameters:

first_name (string, optional): Agent's first name (max 255 characters)
surname (string, optional): Agent's surname/last name (max 255 characters)
contact_phone_number (string, optional): Phone number (max 20 characters)
business_name (string, optional): Business/shop name
residential_address (string, optional): Home address (max 500 characters)
business_location (string, optional): Business address (max 500 characters)
Request:

{
  "first_name": "Updated First",
  "surname": "Updated Last",
  "contact_phone_number": "08087654321",
  "business_name": "Updated Business Name",
  "residential_address": "123 New Street, Lagos",
  "business_location": "456 Market Road, Lagos"
}
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Profile updated successfully",
  "data": {
    "id": "agent_id",
    "name": "Updated Agent Name",
    "email": "agent@example.com",
    "phone": "08087654321",
    "business_name": "Updated Business Name"
  }
}
Get Wallet Balance
GET /wallet
Description: Retrieve current wallet balance for authenticated agent. Shows available funds for transactions, commission earnings, and recent balance changes. Balance is updated in real-time after each transaction.
Authentication: Bearer token required
Use Case: Check available funds before processing transactions, display balance in POS interface
Business Logic: Queries latest wallet balance, includes pending transactions, calculates available balance
Request: No parameters required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Wallet balance retrieved successfully",
  "data": {
    "balance": "15000.00",
    "currency": "NGN",
    "last_updated": "2024-01-15T10:30:00Z"
  }
}
Get Sub-Agents ⚠️ DISABLED
GET /sub-agents
Description: Retrieve list of sub-agents under authenticated agent
Authentication: Bearer token required
⚠️ IMPORTANT: This endpoint is currently DISABLED in routes (commented out). The controller method exists but the route is not active.
Request: No parameters required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Sub-agents retrieved successfully",
  "data": [
    {
      "id": "subagent_id_1",
      "name": "Sub Agent 1",
      "email": "subagent1@example.com",
      "phone": "08011111111",
      "status": "active",
      "wallet_balance": "5000.00"
    },
    {
      "id": "subagent_id_2",
      "name": "Sub Agent 2",
      "email": "subagent2@example.com",
      "phone": "08022222222",
      "status": "active",
      "wallet_balance": "3000.00"
    }
  ]
}
Payment Endpoints
Process General Payment
POST /payments
Description: Process general payment transactions through POS service including card payments and other payment methods. Handles POS terminal transactions with optional card details and merchant information.
Authentication: Bearer token required
Use Case: Process customer card payments at POS terminal, handle various payment types
Business Logic: Authenticates agent, validates payment data, calls PosService for processing, handles success/failure responses
Request Parameters:

amount (number, required): Payment amount (minimum 1.00)
merchant_id (string, optional): Merchant identifier (max 50 characters)
terminal_id (string, optional): POS terminal identifier (max 50 characters)
card_type (string, optional): Card type (visa, mastercard, verve, americanexpress)
card_last_four (string, optional): Last 4 digits of card (exactly 4 characters)
Request:

{
  "amount": 5000.00,
  "merchant_id": "merchant_123",
  "terminal_id": "terminal_456",
  "card_type": "visa",
  "card_last_four": "1234"
}
Validation Rules:

Amount must be numeric and minimum 1
Card type must be one of: visa, mastercard, verve, americanexpress
Card last four must be exactly 4 characters if provided
Merchant ID and Terminal ID have 50 character limits
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Payment processed successfully",
  "data": {
    "transaction_id": "txn_123456",
    "amount": 5000.00,
    "status": "success",
    "reference": "payment_ref_789"
  }
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "Payment processing failed"
}
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Payment processed successfully",
  "data": {
    "transaction_id": "txn_789",
    "amount": 5000.00,
    "status": "completed",
    "reference": "payment_ref_123"
  }
}
Bills Services
Service Providers
Get Airtime Providers
GET /bills/providers/airtime
Description: Retrieve list of available airtime service providers and minimum purchase amounts. Returns all active network operators supported by the platform with their service codes and display names.
Authentication: Bearer token required
Use Case: Populate network selection dropdown in POS interface
Business Logic: Returns static list of supported networks (MTN, Glo, Airtel, 9mobile, Smile) with minimum purchase amounts
Request: No parameters required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request is Successful",
  "data": {
    "value": {
      "minimum": "100"
    },
    "list": [
      {
        "service_name": "mtn",
        "name": "MTN Nigeria"
      },
      {
        "service_name": "glo",
        "name": "Globalcom Nigeria"
      }
    ]
  }
}
Get Data Providers
GET /bills/providers/data
Description: Retrieve list of available data service providers (same as airtime providers)
Authentication: Bearer token required
Request: No parameters required

Response: Same as airtime providers response

Airtime Services
Purchase Airtime
POST /bills/airtime/purchase
Description: Purchase airtime for a specified phone number using available wallet balance. Validates phone number format, checks wallet balance, processes payment through Baxi API, and credits commission to agent.
Authentication: Bearer token required
Use Case: Sell airtime to customers at POS terminal
Business Logic: Validates Nigerian phone format, checks sufficient balance, debits wallet, calls Baxi API, handles success/failure, credits commission, logs transaction
Request Parameters:

service_type (string, required): Network provider code (mtn, glo, airtel, 9mobile)
amount (number, required): Airtime amount (minimum ₦100, maximum ₦50,000)
phone_number (string, required): Customer's phone number (11 digits)
terminal_id (string, required): POS terminal identifier
reference (string, required): Unique transaction reference (max 50 characters)
Request:

{
  "service_type": "mtn",
  "amount": 1000,
  "phone_number": "08012345678",
  "terminal_id": "POS001",
  "reference": "POS001_1642234567"
}
Validation Rules:

Service type must be supported network
Amount must be within min/max limits
Phone number must be valid Nigerian format
Reference must be unique across all transactions
Sufficient wallet balance required
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request Successful",
  "data": {
    "status": "success",
    "ref_id": "baxi_transaction_reference",
    "transaction_id": "terminal_id_timestamp"
  }
}
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "Your Wallet balance is Insufficient"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Duplicate transaction. Kindly check your history"
}
Data Services
Get Data Plans
GET /bills/data/plans/{product}
Description: Retrieve available data plans for a specific network provider using Baxi API. Uses the same service as mobile app (Airtime_Data controller) to fetch real-time data plans.
Authentication: Bearer token required
Use Case: Display available data plans for customer selection
Business Logic: Creates Airtime_Data instance, calls get_baxi_data_plan(), formats response with plan details
Path Parameters:
product (string): Network provider code (mtn, glo, airtel, 9mobile)
Example: /bills/data/plans/mtn
Request: No body required

Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request Successful",
  "data": [
    {
      "validity": "30 days",
      "product_id": "mtn_1gb_datacode",
      "amount": "500",
      "type": "1GB"
    },
    {
      "validity": "30 days", 
      "product_id": "mtn_2gb_datacode",
      "amount": "1000",
      "type": "2GB"
    }
  ]
}
Response Fields:

validity: Plan validity period from Baxi
product_id: Data plan code (datacode from Baxi)
amount: Plan price from Baxi
type: Data allowance description
Error Responses:

{
  "status": "error",
  "responseCode": "01",
  "message": "An Error Occurred Try Again"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Unable to fetch data plans"
}
Purchase Data Bundle
POST /bills/data/purchase
Description: Purchase data bundle using SubAgent authentication and Baxi API integration. Auto-generates reference, handles wallet locking, processes via Baxi, manages commissions, and comprehensive logging.
Authentication: Bearer token required (SubAgent model)
Use Case: Sell data bundles to customers with specific plan selection
Business Logic: Authenticates SubAgent, generates reference (terminal_id + timestamp), locks wallet, debits balance, calls Baxi API, handles commissions, extensive logging
Request Parameters:

service_type (string, required): Network provider code (mtn, glo, airtel, 9mobile)
amount (number, required): Data plan amount (varies by plan)
phone_number (string, required): Customer's phone number (11 digits)
product_code (string, required): Data plan identifier from plans endpoint
terminal_id (string, required): POS terminal identifier
reference (string, optional): Transaction reference (auto-generated as terminal_id + timestamp if not provided)
Request:

{
  "service_type": "mtn",
  "amount": 1500,
  "phone_number": "08012345678",
  "product_code": "mtn_2gb_30days",
  "terminal_id": "POS001",
  "reference": "POS001_1642234568"
}
Validation Rules:

Product code must exist and be active
Amount must match selected plan price
Phone number must match network type
Plan must be available for purchase
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request Successful",
  "data": {
    "status": "success",
    "ref_id": "baxi_transaction_reference",
    "transaction_id": "terminal_id_timestamp"
  }
}
Cable TV Services
Get TV Subscription Plans
GET /bills/tv/plans/{product}
Description: Retrieve available TV subscription plans for a specific provider
Authentication: Bearer token required
Path Parameters:
product (string): TV provider code (dstv, gotv, startimes)
Example: /bills/tv/plans/dstv
Request: No body required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request Successful",
  "data": [
    {
      "product_name": "DStv Compact",
      "product_id": "dstv_compact",
      "amount": "9000",
      "validity": 1
    },
    {
      "product_name": "DStv Premium",
      "product_id": "dstv_premium",
      "amount": "21000",
      "validity": 1
    }
  ]
}
Verify TV Device Number
POST /bills/tv/verify
Description: Verify TV device/smartcard number and retrieve customer information. Validates device number format, checks with TV provider API, and returns customer details for confirmation before purchase.
Authentication: Bearer token required
Use Case: Verify customer details before processing TV subscription payment
Business Logic: Validates device number format, calls provider verification API, returns customer name and account details
Request:

{
  "product": "dstv|gotv|startimes",
  "device_number": "1234567890"
}
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Verified Successfully",
  "data": {
    "customer_name": "John Doe",
    "customer_number": "1234567890",
    "reference": "generated_reference"
  }
}
Purchase TV Subscription
POST /bills/tv/purchase
Description: Purchase TV subscription for verified device using selected plan. Processes payment for cable TV subscriptions (DStv, GOtv, Startimes) and activates service on customer's account.
Authentication: Bearer token required
Use Case: Renew or activate TV subscriptions for customers
Business Logic: Validates device verification, checks plan availability, processes payment, activates subscription, handles addon services
Request Parameters:

service_type (string, required): TV provider code (dstv, gotv, startimes)
amount (number, required): Subscription amount (varies by plan)
device_number (string, required): Smartcard/IUC number (10-15 digits)
product_code (string, required): TV plan identifier from plans endpoint
validity (number, required): Subscription validity in months (usually 1)
addon_code (string, optional): Additional service code (e.g., XtraView for DStv)
terminal_id (string, required): POS terminal identifier
reference (string, required): Unique transaction reference
Request:

{
  "service_type": "dstv",
  "amount": 9000,
  "device_number": "1234567890",
  "product_code": "dstv_compact",
  "validity": 1,
  "addon_code": "HDPVRE36",
  "terminal_id": "POS001",
  "reference": "POS001_1642234569"
}
Validation Rules:

Service type must be supported TV provider
Amount must match selected plan price
Device number must be verified first
Product code must exist and be active
Validity must be supported by provider
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Transaction successful",
  "data": {
    "reference": "unique_reference",
    "amount": 4000,
    "device_number": "1234567890",
    "service_type": "dstv",
    "product_code": "plan_code",
    "transaction_id": "internal_transaction_id"
  }
}
Electricity Services
Get Electricity Providers
GET /bills/electricity/plans
Description: Retrieve list of available electricity distribution companies
Authentication: Bearer token required
Request: No parameters required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Request is Successful",
  "data": [
    {
      "product_name": "Ikeja Electric Prepaid",
      "product_id": "ikeja_electric_prepaid"
    },
    {
      "product_name": "Eko Electric Prepaid",
      "product_id": "eko_electric_prepaid"
    }
  ]
}
Verify Electricity Meter
POST /bills/electricity/verify
Description: Verify electricity meter number and retrieve customer information. Validates meter number with electricity distribution company, returns customer name, address, and meter details for confirmation.
Authentication: Bearer token required
Use Case: Verify customer meter details before processing electricity payment
Business Logic: Validates meter number format, calls DISCO API for verification, returns customer details and meter type
Request:

{
  "service_type": "ikeja_electric_prepaid",
  "meter_no": "12345678901"
}
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Meter verified successfully",
  "data": {
    "customer_name": "John Doe",
    "meter_number": "12345678901",
    "address": "Customer Address",
    "reference": "generated_reference"
  }
}
Purchase Electricity Units
POST /bills/electricity/purchase
Description: Purchase electricity units for verified meter using specified amount. Processes prepaid electricity payment, generates token, and provides units calculation based on current tariff rates.
Authentication: Bearer token required
Use Case: Buy electricity units for customers' prepaid meters
Business Logic: Validates meter verification, processes payment amount, generates electricity token, calculates units, handles DISCO API integration
Request Parameters:

service_type (string, required): Electricity provider code
amount (number, required): Purchase amount (minimum ₦100, maximum ₦200,000)
meter_no (string, required): Prepaid meter number (8-15 digits)
customer_number (string, optional): Customer account number
user_category (string, optional): Customer category (residential/commercial)
access_code (string, optional): Special access code if required
aggregator (string, optional): Payment aggregator identifier
terminal_id (string, required): POS terminal identifier
reference (string, required): Unique transaction reference
Request:

{
  "service_type": "ikeja_electric_prepaid",
  "amount": 5000,
  "meter_no": "12345678901",
  "customer_number": "CUST123456",
  "user_category": "residential",
  "terminal_id": "POS001",
  "reference": "POS001_1642234570"
}
Validation Rules:

Service type must be supported DISCO
Amount must be within min/max limits
Meter number must be verified first
Customer category must be valid if provided
Reference must be unique
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Transaction successful",
  "data": {
    "reference": "unique_reference",
    "amount": 1000,
    "meter_no": "12345678901",
    "service_type": "ikeja_electric_prepaid",
    "transaction_id": "internal_transaction_id",
    "token": "electricity_token",
    "units": "kwh_units"
  }
}
Transaction Endpoints
Transaction History
Get Transaction List
GET /transactions
Description: Retrieve list of transactions for authenticated agent with optional filtering by status and date range. Uses PosService for transaction retrieval and formatting.
Authentication: Bearer token required
Use Case: View transaction history, generate reports, reconcile daily sales
Business Logic: Authenticates agent, validates query parameters, calls PosService to fetch filtered transactions
Query Parameters:

status (string, optional): Filter by transaction status (pending, completed, failed, success)
date_from (string, optional): Start date filter (YYYY-MM-DD format)
date_to (string, optional): End date filter (YYYY-MM-DD format, must be after date_from)
page (number, optional): Page number for pagination (default: 1)
limit (number, optional): Items per page (default: 20, max: 100)
type (string, optional): Filter by transaction type (Airtime, Data, TV, Electricity)
Example Request: GET /transactions?status=success&date_from=2024-01-01&date_to=2024-01-31&page=1&limit=50

Validation Rules:

Date format must be YYYY-MM-DD
date_to must be after or equal to date_from
Page must be positive integer
Limit must be between 1 and 100
Status must be valid transaction status
Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "id": 1,
      "transaction_id": "terminal_123_1234567890",
      "amount": "1000",
      "status": "success",
      "type": "Airtime",
      "product_name": "mtn",
      "product_no": "08012345678",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Get Transaction Details
GET /transactions/{transactionId}
Description: Retrieve detailed information for a specific transaction by transaction ID. Uses PosService to fetch transaction details with agent verification.
Authentication: Bearer token required
Use Case: Look up specific transaction details, resolve customer queries, check transaction status
Business Logic: Authenticates agent, calls PosService to get transaction by ID, verifies agent access to transaction
Path Parameters:

transactionId (string, required): Unique transaction identifier
Success Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Transaction retrieved successfully",
  "data": {
    "id": "transaction_id",
    "amount": "1000.00",
    "status": "success",
    "type": "payment",
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {}
  }
}
Error Responses:

{
  "status": "error",
  "responseCode": "04",
  "message": "Transaction not found"
}
{
  "status": "error",
  "responseCode": "06",
  "message": "Failed to retrieve transaction"
}
Path Parameters:
transactionId (string): Unique transaction identifier
Request: No body required

Response:

{
  "status": "success",
  "responseCode": "00",
  "message": "Transaction retrieved successfully",
  "data": {
    "id": 1,
    "transaction_id": "terminal_123_1234567890",
    "amount": "1000",
    "status": "success",
    "type": "Airtime",
    "product_name": "mtn",
    "product_no": "08012345678",
    "product_description": "MTN Airtime Purchase",
    "ref_id": "baxi_reference_123",
    "wallet_balance": "5000",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
Common Error Responses
Authentication Errors
{
  "status": "error",
  "responseCode": "01",
  "message": "Agent not found"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Invalid credentials"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "Account not verified"
}
Validation Errors
{
  "status": "error",
  "responseCode": "01",
  "message": "Validation error",
  "errors": {
    "phone_number": ["The phone number field is required."],
    "amount": ["The amount must be at least 100."]
  }
}
Business Logic Errors
{
  "status": "insufficient_balance",
  "responseCode": "03",
  "message": "Your Wallet balance is Insufficient"
}
{
  "status": "duplicate_reference",
  "responseCode": "04",
  "message": "Duplicate transaction. Kindly check your history"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "PIN not set. Please create a PIN first"
}
Service Errors
{
  "status": "error",
  "responseCode": "05",
  "message": "Unable to process request at this time. Please try again."
}
{
  "status": "error",
  "responseCode": "01",
  "message": "An Error Occurred In Transaction Try Again"
}
OTP Errors
{
  "status": "error",
  "responseCode": "01",
  "message": "Invalid or expired OTP"
}
{
  "status": "error",
  "responseCode": "01",
  "message": "PIN confirmation does not match"
}
Response Codes
00 - Success
01 - General error/Authentication error
02 - Invalid agent (deprecated - now uses 01)
03 - Insufficient balance
04 - Duplicate reference
05 - Service unavailable
06 - Internal error
Transaction Flow
Standard Purchase Flow
Authentication → Login with email/password or email/PIN
Get Service Plans → Choose provider/plan from available options
Verify (TV/Electricity only) → Validate device/meter number
Purchase → Complete transaction with wallet debit
Check Status → Verify transaction completion and get receipt
PIN Creation Flow
Request OTP → Send OTP to registered phone
Create PIN → Set 4-digit transaction PIN with OTP verification
Login with PIN → Use email/PIN for subsequent logins
PIN Reset Flow
Request Reset OTP → Send OTP for PIN reset
Reset PIN → Change PIN with OTP verification
Password Reset Flow
Request Password OTP → Send OTP for password reset
Change Password → Update login password with OTP verification
Required Fields for Transactions
terminal_id - POS terminal identifier (alphanumeric, max 50 chars)
reference - Unique transaction reference (must be globally unique)
amount - Transaction amount (minimum varies by service)
service_type - Provider code (network/TV/electricity provider)
Authentication token in Authorization header
Validation Rules
Phone numbers: Nigerian format (11 digits starting with 0)
Email addresses: Valid email format, must exist in system
Amounts: Service-specific minimums (Airtime: ₦100, Data: varies, TV: varies, Electricity: ₦100)
References: Must be unique per transaction, alphanumeric, max 50 characters
Device/Meter numbers: Provider-specific formats and lengths
PINs: Exactly 4 digits
OTPs: 4 or 6 digits depending on service
Passwords: Minimum 8 characters
Commission Structure
Airtime: 1.5% agent commission, 1.5% sub-agent commission
Data: Variable based on plan and provider
TV: Fixed amount per subscription type
Electricity: Percentage based on amount and provider
Transaction States
pending: Transaction initiated, awaiting processing
success: Transaction completed successfully
failed: Transaction failed, amount refunded
error: System error occurred, manual review required
Rate Limiting
Authentication: 5 attempts per minute per IP
Transactions: 100 per hour per agent
OTP Requests: 3 per 10 minutes per phone number
Security Features
Token Expiry: Bearer tokens expire after 24 hours
PIN Encryption: All PINs stored using bcrypt hashing
OTP Expiry: OTPs expire after 10 minutes
Duplicate Prevention: Reference uniqueness enforced
Balance Locking: Wallet operations use database locks
Audit Logging: All transactions logged with metadata