Documentation

# Rate Token Lock-in Architecture

When booking logistics in high-volatility urban environments, real-time prices can fluctuate based on driver availability, distance bands, and surge rules.

Tumr solves the pricing race condition and client tampering problem using cryptographic rate tokens.

  MERCHANT APPLICATION                     TUMR PLATFORM
          │                                        │
          │ 1. POST /api/v1/rates/                │
          ├───────────────────────────────────────>│
          │                                        │ (Calculate tariffs & sign tokens)
          │ 2. Returns rates with [rate_token]     │
          │<───────────────────────────────────────┤
          │                                        │
    (User selects courier)                         │
          │                                        │
          │ 3. POST /api/v1/shipments/             │
          │    { rate_token, customer, ... }       │
          ├───────────────────────────────────────>│
          │                                        │ (Cryptographically verify token)
          │ 4. Order created & escrow locked       │
          │<───────────────────────────────────────┤

---

Why Rate Tokens?

Tamper Prevention: The rate token encodes the exact delivery fee, pickup/dropoff coordinates, package weight, declared value, fulfillment mode (marketplace or carrier), and carrier UUID. If a client attempts to alter offered_fee, the server rejects the request.
Atomic Price Lock: Once a quote is calculated, the quoted price is locked for 15 minutes. Even if marketplace demand increases before the customer completes payment, the rate remains honored.
Zero Configuration for Carriers: When selecting a private carrier fleet option, passing the carrier's rate_token automatically populates the carrier assignment, hub routing, and first-mile pickup fees.

---

Token Verification & Expiry

Every token is signed on the server with HMAC-SHA256:

Valid Duration: 15 minutes from generation.
Payload Contents:
```json
{
"fulfillment_mode": "marketplace",
"service_level": "EXPRESS",
"total": "2450.00",
"currency": "NGN",
"pickup_latitude": "6.4281",
"pickup_longitude": "3.4219",
"dropoff_latitude": "6.5244",
"dropoff_longitude": "3.3792",
"package_weight_kg": "2.50",
"declared_value": "15000.00",
"country_code": "NG"
}
```

If an expired or forged token is sent to POST /api/v1/shipments/, the API responds with: ``json { "rate_token": "The provided rate_token is invalid or has expired. Please obtain a fresh rate quote." }``