Logo

Haulage API Documentation

Available API endpoints for login, trip creation, payment initialization, payment confirmation, and trip lookup.

Login

Base URL

https://haulage.hilinks.app/api
POST

Mobile Login

Authenticates a mobile user, validates the device, and returns a Sanctum bearer token.

https://haulage.hilinks.app/api/mobile/login
Headers
Accept: application/json
Content-Type: application/json
Request Body
{
  "email": "user@example.com",
  "password": "user_password",
  "device_id": "XXXXXXXXXXX",
}
Success Response - 200
{
  "success": true,
  "message": "Login successful.",
  "data": {
    "user_id": 1,
    "name": "User Name",
    "email": "user@example.com",
    "type": "user_type",
    "device_id": "XXXXXXXXXXX",
    "token_type": "Bearer",
    "token": "1|SANCTUM_TOKEN_HERE"
  }
}
Invalid Login Details - 401
{
  "success": false,
  "message": "Invalid login details."
}
Blocked / Inactive Device - 403
{
  "success": false,
  "message": "This device is not active.",
  "device_status": "blocked"
}
Device Linked To Another User - 403
{
  "success": false,
  "message": "This device is already linked to another user."
}
Validation Error - 422
{
  "message": "The email field is required. (and 2 more errors)",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ],
    "device_id": [
      "The device id field is required."
    ]
  }
}
After Login

Store the returned token on the mobile app and send it on all protected API requests. 

Authorization: Bearer SANCTUM_TOKEN_HERE
Accept: application/json
Content-Type: application/json
X-Device-ID: XXXXXXXXXXXXXXX
GET

Get Logged-in User

Returns the authenticated mobile user's profile.

https://haulage.hilinks.app/api/mobile/logged-in
Headers
Authorization: Bearer SANCTUM_TOKEN_HERE
Accept: application/json
X-Device-ID: XXXXXXXXXXXXXXX
Success Response - 200
{
  "success": true,
  "data": {
    "user_id": 1,
    "name": "User Name",
    "email": "user@example.com",
    "type": "user_type"
  }
}
Unauthenticated - 401
{
  "message": "Unauthenticated."
}
POST

Device Heartbeat

Updates the mobile device last seen time.

https://haulage.hilinks.app/api/mobile/heartbeat
Headers
Authorization: Bearer SANCTUM_TOKEN_HERE
Accept: application/json
Content-Type: application/json
X-Device-ID: XXXXXXXXXXXXXXX
Request Body
{
  "device_id": "XXXXXXXXXXXXX"
}
Success Response - 200
{
  "success": true,
  "message": "Device heartbeat updated."
}
POST

Mobile Logout

Deletes the current Sanctum access token.

https://haulage.hilinks.app/api/mobile/logout
Headers
Authorization: Bearer SANCTUM_TOKEN_HERE
Accept: application/json
Content-Type: application/json
X-Device-ID: XXXXXXXXXXXXXXX
Request Body
{
  "device_id": "XXXXXXXXXXXXX"
}
Success Response - 200
{
  "success": true,
  "message": "Logged out successfully."
}
POST

Create Trip

Creates a new trip and creates a pending payment record for that trip.

https://haulage.hilinks.app/api/trips/create
Request Body
{
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "card_id": "04:A1:B2:C3:D4",
  "truck_no": "KJA-123-XY",
  "origin": "Jalingo",
  "destination": "Kaduna",
  "amount": "15000.00",
  "vehicleType": "Truck",
  "trip_type": "Single",
  "goods": "Cement",
  "expiry_date": "2026-06-30"
}
Success Response
{
  "success": true,
  "message": "Trip created successfully",
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "payment_status": "PENDING"
}
POST

Initialize Monnify Transfer

Starts a transfer payment process and returns transfer/account details.

https://haulage.hilinks.app/api/payments/monnify-init-transfer
Request Body
{
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "amount": "15000.00",
  "customer_name": "Haulage Customer",
  "customer_email": "customer@example.com"
}
Success Response
{
  "success": true,
  "message": "Transfer initialized successfully",
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "amount": "15000.00",
  "payment_method": "TRANSFER",
  "payment_status": "PENDING",
  "monnify_reference": "MNFY-REFERENCE",
  "checkout_url": null,
  "account_number": "1234567890",
  "bank_name": "Wema Bank",
  "account_name": "Haulage Customer"
}
GET

Check Monnify Payment Status

Checks the payment status using the payment reference.

https://haulage.hilinks.app/api/payments/monnify-status?payment_ref=PAY-202606091200-ABCD
Query Parameters
Parameter Required Description
payment_ref Yes The unique payment reference generated for the trip.
Success Response
{
  "success": true,
  "message": "Payment status fetched successfully",
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "amount": "15000.00",
  "payment_method": "TRANSFER",
  "payment_status": "PAID",
  "paid": true
}
GET

Search Trip By Plate Number

Searches trip records using the truck/plate number.

https://haulage.hilinks.app/api/trips/search-by-truck?truck_no=KJA-123-XY
Query Parameters
Parameter Required Description
truck_no Yes The plate number/truck number to search for.
Success Response
{
  "success": true,
  "message": "Trips found",
  "count": 1,
  "trips": [
    {
      "trip_id": "TRIP-202606091200-ABCD",
      "truck_no": "KJA-123-XY",
      "origin": "Jalingo",
      "destination": "Kaduna",
      "amount": "15000.00",
      "payment_status": "PENDING"
    }
  ]
}
GET

Check Trip Payment Ready

Checks whether a trip exists and is ready for payment.

https://haulage.hilinks.app/api/trips/payment-ready?trip_id=TRIP-202606091200-ABCD
Query Parameters
Parameter Required Description
trip_id Yes The unique trip ID to check.
Success Response
{
  "success": true,
  "ready": true,
  "message": "Trip is ready for payment",
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "amount": "15000.00",
  "payment_status": "PENDING"
}
POST

Confirm POS Payment

Confirms a POS payment, stores the POS reference, and marks the trip/payment as paid.

https://haulage.hilinks.app/api/payments/pos-confirm
Request Body
{
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "pos_ref": "POS-REF-123456",
  "amount": "15000.00"
}
Success Response
{
  "success": true,
  "message": "POS payment confirmed successfully",
  "trip_id": "TRIP-202606091200-ABCD",
  "payment_ref": "PAY-202606091200-ABCD",
  "pos_ref": "POS-REF-123456",
  "amount": "15000.00",
  "payment_method": "POS",
  "payment_status": "PAID",
  "paid": true
}
Notes
  • All POST requests should send JSON with Content-Type: application/json.
  • All endpoints return JSON.
  • payment_ref should be unique for every payment.
  • trip_id should be unique for every trip.
  • card_id should match an active NFC card in the nfc_cards table.

© 2026 Hilinks Network Solutions Ltd. All rights reserved.