Raptors Freight and Courier Service

Revision history

Raptors Freight and Courier Service moves goods from the United States to Ghana. This project delivers one web application that runs the whole chain — from a customer buying online in the US, through USPS collection, warehousing, air or sea carriage, customs and warehousing in Ghana, to a rider delivering at the customer's door — with every price, payment, debt and cost visible in one financial view.

The application replaces the spreadsheets, WhatsApp threads and manual reconciliation currently filling the gaps between those steps.

What Raptors gets

• A customer portal where clients register, verify identity with their Ghana Card, receive an RFC locker ID, pre-alert purchases, get an instant price, book, pay and track.
• Two payment systems — Paystack and Hubtel — covering cards, mobile money and bank transfer, with split payments and discount management.
• On-site USPS label purchase and printing with real-time USPS pricing, including a small 2"×1" label for phones and gadgets.
• Pre-priced item pages, weight and customs pricing in GHS and USD, and Scan and Price at the warehouse for anything the system cannot price automatically.
• A Financial Sheet covering every priced item, payment, split payment, discount, debt and cost — visible to Administration, Finance and Customer Service.
• Air (RAP), Sea (RSP) and Courier (RCP) package handling with a new full-detail tracking page carrying images and video.
• Warehouse management at the US and Ghana ends, with product categorisation, pay-before-clearance and auction management for uncollected packages.
• Last-mile delivery with prices assigned to riders, a Riders page showing delivery cost per package, and a 10–15% Raptors commission on assigned rides.
• Full activity log, incognito account view, an improved dashboard, and a public API for external developers.

Every customer and every package carries a prefixed reference. The prefix identifies what it is on sight — on a label, in a message, in a report, or typed into the tracking box.

• Sequence numbers run independently per prefix, are non-guessable, and never repeat.
• The tracking box accepts any of the four prefixes, plus USPS tracking numbers and consolidation references.
• The prefix is printed on every label, invoice, waybill, manifest and proof of delivery, and returned by the public API.
• A package that changes service line keeps its original reference and records the change in the activity log, so history is never broken.

The complete list of what is being built, grouped by area. This is the working checklist for the project — every line is a deliverable and every line is signed off at User Acceptance Testing. NEW means it does not exist today; UPGRADE means it exists but is being rebuilt or extended.

6.1 Ghana Card identity verification

• Card numbers and document images are encrypted and stored outside the public web folder. They are never shown in a public URL.
• Documents with an expiry date trigger a re-verification prompt when they lapse.

6.2 Pricing — items, weight, customs, Scan and Price

The system works down the list and stops at the first rule that applies. Whichever rule set the price is recorded, so any price can be explained afterwards.

Customs charges, handling and delivery are then added on top of whichever rule applied.

Scan and Price

• Used when a package arrives that the system cannot price automatically — not in the item catalogue and weight pricing does not apply.
• The warehouse officer scans the package, and the screen shows the photograph, weight, dimensions, category and a suggested price.
• The officer sets the price. It flows straight onto the invoice and the customer is notified.
• Any item priced by hand can be saved into the catalogue so it prices automatically next time.

Multicurrency and discounts

• Every price is shown in GHS and USD together — package page, quote, invoice, tracking page and Financial Sheet.
• The exchange rate in force at the time of quoting is stored against the record, so a price never changes retrospectively.
• Discounts apply as a fixed amount or a percentage, need approval above a threshold, and appear as their own invoice line so discounting stays visible.

6.3 Product categorisation

• Set by the customer at booking, confirmed or corrected by the warehouse at intake.
• A consolidation can be exported showing weight and package count per category — the figure customs and carriers ask for.
• Categories and their rules are maintained in the admin, so new ones can be added without development work.

6.4 Payments — Paystack and Hubtel

• Payment is confirmed automatically by the provider calling back to the site. Staff never confirm a payment by hand.
• If one provider fails or times out, the payment is retried on the other without the customer noticing, and without any risk of a double charge.
• Split payments — several payments against one invoice, each with its own method, reference and date, with the running balance shown after each.
• A receipt goes out on WhatsApp and email as soon as a payment clears.

6.5 Financial Sheet, debt and auctions

One page showing the full financial position of the platform. Visible to Administration, Finance and Customer Service.

Auction management

6.6 USPS labels and label printing

Label sizes

6.7 New tracking page

• One box accepts RFC, RAP, RSP, RCP, USPS and consolidation references.
• Complete event history with date, time, location and the action behind each event.
• Package detail — weight, dimensions, category, contents and declared value.
• Photographs taken at intake, repack and delivery, shown on the timeline.
• Video where captured — condition on arrival, damage evidence, disputed handover.
• Map view, consolidation view, expected delivery window and rider details once assigned.
• Price breakdown, payment status and downloadable documents for the logged-in owner. Basic detail is public; full detail requires login.

6.8 Last-mile delivery, riders and commission

• Ghana is divided into delivery zones, each with its own delivery price.
• Break-out at the Ghana warehouse creates a delivery job for each customer automatically.
• The dispatcher assigns deliveries to riders, singly or as a route.
• A delivery price is attached to each rider job — from the zone by default, or set manually.

The Riders page

• Each rider logs in and sees the packages assigned to them, with the delivery cost showing on each package.
• Daily total — deliveries, gross delivery earnings, commission deducted, net due.
• Earnings history and settlement statement.
• One tap opens the delivery address in the phone's map application.
• Works offline and syncs when signal returns.

At the door

• Proof of delivery: recipient name, signature on screen, delivery photograph, GPS position and time. Video for high-value or disputed handovers.
• Delivery PIN sent to the recipient for high-value parcels.
• Outstanding payment collected at the door by mobile money prompt or cash.
• Failed deliveries recorded with a reason and automatically rescheduled, with a re-delivery charge rule.

6.9 Customer management, incognito view and activity log

• Every client listed with their packages, total paid and total debt showing on the list itself.
• Opening a client shows full package history, payment history, split payments, discounts, debt position, documents and internal notes on one page.

Incognito account view

• A staff member opens a client's account and sees it exactly as the client sees it.
• The session is read-only. Nothing can be changed while in incognito view.
• A banner is visible at all times showing whose account is being viewed.
• Sessions are time-limited and written to the activity log with the staff member, the client and the duration.

Full activity log

• Every action by every user — logins, price changes, discounts, payments, refunds, releases, overrides, verifications, assignments, deletions and incognito sessions.
• Each entry carries the user, role, action, record affected, values before and after, time and IP address.
• Searchable and filterable. Cannot be edited or deleted by any user. Exportable for audit.

6.10 Notifications and bulk messaging

• WhatsApp and email fire on every status change and every account activity — verification outcomes, payments, discounts, debt reminders, auction notices, out-for-delivery and proof of delivery.
• SMS runs through Hubtel with a Ghanaian sender ID, with mNotify or Hubtel SMS as the fallback route.
• Bulk messaging carries images and video — flyers, rate cards, announcements, how-to clips, promotions.
• Audience built by filtering on customer status, debt position, package status, category, zone or agency.
• Preview before sending, scheduled send, throttled to provider limits.
• Campaign report — sent, delivered, read, failed, opted out. Every message logged with channel, status and cost.

6.11 API for external developers

• Developers register and generate their own API keys, each scoped — tracking only, rates only, or wider access.
• Written documentation with live try-it pages, plus a test environment with sample data.
• Usage limits and a usage log per key. Raptors can revoke a key at any time.
• The same API powers the Raptors mobile application.

• Two-factor authentication on all staff logins, using an authenticator app with SMS or WhatsApp fallback.
• Password rules: minimum ten characters with upper case, lower case, a number and a symbol. Account locks after five failed attempts.
• Ghana Card numbers, document images, bank details and provider keys encrypted and stored outside the public web folder.
• Identity documents served only through short-lived secure links. No file path is ever exposed publicly.
• HTTPS enforced across the whole site.
• Card details never touch Raptors servers — Paystack handles them in its own secure fields.
• Payment confirmations verified by signature before anything is marked paid; replayed or fake callbacks rejected.
• Protection against SQL injection, cross-site scripting and cross-site request forgery throughout.
• File and media uploads restricted by type and size, scanned, renamed and stored non-executable.
• Rate limits on login, password reset, payment, label purchase and bulk messaging.
• Approval required from a second person on refunds, write-offs, discounts above threshold, price overrides and warehouse release overrides.
• Incognito sessions read-only, banner-marked, time-limited and logged.
• Full activity log that cannot be edited or deleted.
• Daily encrypted database backups with an off-site copy.
• Personal data handled in line with the Ghana Data Protection Act (Act 843).

Recommended server sizes

Storage is sized higher than a standard deployment because the platform stores package photographs and video at intake, repack and delivery.

Eight weeks from contract signing. Modules are built in parallel, so several areas progress at once.

Assumptions

• Raptors provides hosting for the live, staging and backup servers, or instructs iSolveAfrica to arrange it.
• Raptors provides brand assets, website content and the setup data — item prices, tariffs, product categories, delivery zones, warehouse shelf maps, commission rates, auction timings and customs rates — in week 1.
• Raptors holds the accounts for Paystack, Hubtel, WhatsApp Business API, mNotify, email sending and USPS in its own name.
• Raptors completes the USPS Ship enrolment and funds a USPS Enterprise Payment Account, and completes Hubtel's merchant onboarding. iSolveAfrica supports both applications but cannot control or speed up their approval.
• A named person from Raptors is available throughout for day-to-day decisions and to lead testing.
• Any existing data to be moved into the new system is provided in a readable format by week 7.
• Meetings are held online unless otherwise agreed. Working language is English.

Not included

• Native iOS and Android apps — scoped separately. The API delivered here is what those apps will use.
• Stripe and PayPal. International card and wallet processing is out of scope.
• Carriers other than USPS. UPS, FedEx and DHL label purchase and tracking are out of scope.
• Vessel booking, Bill of Lading issuance, container management and demurrage tracking. Sea packages are handled at package level only.
• Direct filing with customs authorities or customs broker data feeds.
• Live two-way connection to accounting software. A formatted export file is included.
• Weighing scale and barcode scanner drivers. Scanners that type into a field are supported; direct cable or Bluetooth scale connections are not.
• Purchase of printers, scanners, phones or other hardware.
• Conducting auctions themselves — the platform manages the auction list, notices and settlement; the sale process itself is Raptors' own.
• Marketing, SEO campaigns, advertising and social media.
• Security penetration testing.
• Insurance underwriting. The site can charge an insurance fee; it does not act as an insurer.

1. Raptors submits the requested change in writing.
2. iSolveAfrica responds within three working days with the effort involved and the effect on the timeline.
3. Raptors approves or declines in writing. Approved changes are added to this document as an addendum.
4. The change is built, tested and delivered.

Small adjustments during a week that do not affect effort or timeline are absorbed and logged. Commercial treatment of changes is dealt with in the Cost and Management Proposal.

Ownership

• Raptors receives a perpetual, irrevocable, worldwide licence to use, run, host and modify the application for its own business, with no ongoing licence fee.
• Raptors receives the full source code and may engage any developer it chooses to maintain or extend the application.
• iSolveAfrica retains copyright in the algorithms and may reuse that logic in its other work, but may not reuse any Raptors content or data.
• All content and data in the platform is and remains the property of Raptors Freight and Courier Service at all times, and is exportable by Raptors on demand.

Confidentiality

• Both parties protect each other's confidential project information and use it only for this project.
• Confidentiality obligations run for one (1) year and are between Raptors Freight and Courier Service and iSolveAfrica Ltd only.
• Neither party discloses project data to any third party without the other's written consent.

Third-party services

Paystack, Hubtel, USPS, WhatsApp, mNotify and mapping providers remain governed by their own terms and are contracted by Raptors directly.

By signing below, both parties agree to the scope of work described in this document, the duration of 2 months, and the ownership and confidentiality terms in Section 13.