Axelo API

The backend service powering the Axelo transport platform.

Overview

The Axelo API provides endpoints for managing transport orders, generating PDF reports, configuring vehicle classes and goods types, sending push notifications, and providing calendar feeds.

Available Modules

Authentication

Admin-protected endpoints require a Firebase Auth ID token in the Authorization header. The user must have isAdmin: true set in their Firestore users document.

Authorization: Bearer <firebase-id-token>

Getting a Token

import FirebaseAuth

let token = try await Auth.auth().currentUser?.getIDToken()
var request = URLRequest(url: url)
request.setValue("Bearer \(token ?? "")", forHTTPHeaderField: "Authorization")

import com.google.firebase.auth.FirebaseAuth

val user = FirebaseAuth.getInstance().currentUser
user?.getIdToken(true)?.addOnSuccessListener { result ->
    val token = result.token
    val request = Request.Builder()
        .url(url)
        .header("Authorization", "Bearer $token")
        .build()
}

import { getAuth } from "firebase/auth";

const token = await getAuth().currentUser.getIdToken();
const res = await fetch(url, {
  headers: { "Authorization": `Bearer ${token}` }
});

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body:

{
  "error": "Missing required field: reason",
  "details": "Additional context about the error"
}

Rate Limiting

Rate limits are enforced per IP address using draft-7 standard headers.

Overview

The Axelo cancellation system (Storno) handles order cancellations based on the current order status and the user's role (driver or client). Depending on timing and circumstances, the system routes the user to one of five form types, each with different requirements, reasons, and cost implications.

Form Types

Cancellation Actions

Not all cancellations require a form. The system defines four possible actions:

Cost Implications

Form Routing

The cancellation form type is determined by the order status, user role, and time until scheduled pickup. The client app must implement this decision matrix to display the correct UI.

Driver Decision Matrix

Client Decision Matrix

Implementation Example

func determineAction(status: OrderStatus, minutesUntilPickup: Int?, isASAP: Bool, role: UserRole) -> StornoAction {
    switch (role, status) {
    case (.driver, .pending), (.driver, .requestedDriver):
        return .notPossible
    case (.client, .pending), (.client, .requestedDriver):
        return .directCancel
    case (_, .accepted):
        if !isASAP, let minutes = minutesUntilPickup, minutes > 60 {
            return .directCancel
        }
        return .form(.f1)
    case (_, .drivingToPickup):
        return .form(.f2)
    case (_, .arrivedAtPickup):
        return .form(.f3)
    case (.driver, .pickedUp), (.driver, .drivingToDelivery):
        return .supportOnly
    case (.client, .pickedUp), (.client, .drivingToDelivery):
        return .form(.f5)
    default:
        return .notPossible
    }
}

fun determineAction(status: OrderStatus, minutesUntilPickup: Int?, isASAP: Boolean, role: UserRole): StornoAction {
    if (status == OrderStatus.CANCELLED || status == OrderStatus.CANCELLATION_REQUESTED) {
        return StornoAction.NotPossible
    }
    return when (role) {
        UserRole.DRIVER -> when (status) {
            OrderStatus.PENDING, OrderStatus.REQUESTED_DRIVER -> StornoAction.NotPossible
            OrderStatus.ACCEPTED -> {
                if (!isASAP && minutesUntilPickup != null && minutesUntilPickup > 60)
                    StornoAction.DirectCancel
                else StornoAction.Form(FormType.F1)
            }
            OrderStatus.DRIVING_TO_PICKUP -> StornoAction.Form(FormType.F2)
            OrderStatus.ARRIVED_AT_PICKUP -> StornoAction.Form(FormType.F3)
            OrderStatus.PICKED_UP, OrderStatus.DRIVING_TO_DELIVERY -> StornoAction.SupportOnly
            else -> StornoAction.NotPossible
        }
        UserRole.CLIENT -> when (status) {
            OrderStatus.PENDING, OrderStatus.REQUESTED_DRIVER -> StornoAction.DirectCancel
            OrderStatus.ACCEPTED -> {
                if (!isASAP && minutesUntilPickup != null && minutesUntilPickup > 60)
                    StornoAction.DirectCancel
                else StornoAction.Form(FormType.F1)
            }
            OrderStatus.DRIVING_TO_PICKUP -> StornoAction.Form(FormType.F2)
            OrderStatus.ARRIVED_AT_PICKUP -> StornoAction.Form(FormType.F3)
            OrderStatus.PICKED_UP, OrderStatus.DRIVING_TO_DELIVERY -> StornoAction.Form(FormType.F5)
            else -> StornoAction.NotPossible
        }
    }
}

function determineAction(status, minutesUntilPickup, isASAP, role) {
  if (["cancelled", "cancellationRequested"].includes(status)) return "notPossible";

  if (role === "driver") {
    switch (status) {
      case "pending": case "requestedDriver": return "notPossible";
      case "accepted":
        return (!isASAP && minutesUntilPickup > 60) ? "directCancel" : "form:F1";
      case "drivingToPickup": return "form:F2";
      case "arrivedAtPickup": return "form:F3";
      case "pickedUp": case "drivingToDelivery": return "supportOnly";
      default: return "notPossible";
    }
  } else {
    switch (status) {
      case "pending": case "requestedDriver": return "directCancel";
      case "accepted":
        return (!isASAP && minutesUntilPickup > 60) ? "directCancel" : "form:F1";
      case "drivingToPickup": return "form:F2";
      case "arrivedAtPickup": return "form:F3";
      case "pickedUp": case "drivingToDelivery": return "form:F5";
      default: return "notPossible";
    }
  }
}

Cancellation Reasons

Each form type has a predefined set of selectable reasons. Some reasons require the user to provide photo evidence.

F1 Reasons (Driver & Client)

F2 Driver Reasons

F2 Client Reasons

F3–F5 Generic Reasons

Validation Rules

Photo Upload

Evidence photos are uploaded to Firebase Storage before submitting the cancellation request. The resulting download URLs are then included in the API request body.

Storage Path

cancellation_photos/{orderId}/{index}.jpg

Where {orderId} is the Firestore order document ID and {index} is the 0-based photo index.

Upload Example

import FirebaseStorage

let ref = Storage.storage().reference()
    .child("cancellation_photos/\(orderId)/\(index).jpg")

guard let data = image.jpegData(compressionQuality: 0.7) else { return }

let metadata = StorageMetadata()
metadata.contentType = "image/jpeg"

let _ = try await ref.putDataAsync(data, metadata: metadata)
let url = try await ref.downloadURL()
// Store url.absoluteString in photoURLs array

val ref = FirebaseStorage.getInstance().reference
    .child("cancellation_photos/$orderId/$index.jpg")

val baos = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.JPEG, 70, baos)
val data = baos.toByteArray()

ref.putBytes(data)
    .addOnSuccessListener {
        ref.downloadUrl.addOnSuccessListener { uri ->
            photoURLs.add(uri.toString())
        }
    }

import { getStorage, ref, uploadBytes, getDownloadURL } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, `cancellation_photos/${orderId}/${index}.jpg`);

const blob = await fetch(imageUri).then(r => r.blob());
await uploadBytes(storageRef, blob, { contentType: "image/jpeg" });
const url = await getDownloadURL(storageRef);
photoURLs.push(url);

Firebase Storage Security Rules

match /cancellation_photos/{orderId}/{fileName} {
  allow read: if request.auth != null;
  allow write: if request.auth != null
    && fileName.matches('[0-9]+\\.jpg')
    && request.resource.size < 10 * 1024 * 1024
    && request.resource.contentType.matches('image/.*');
}

Generates a cancellation report PDF (F1–F5). The server downloads evidence photos from their Firebase Storage URLs, embeds them into the PDF, uploads the result to Storage, and returns the PDF bytes.

Request Body

Wrap all fields inside a request object:

Response

Example

curl -X POST https://api.axelo.app/reports/cancellation \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "orderId": "abc123",
      "formType": "F1",
      "reason": "Vehicle Breakdown",
      "detailedDescription": "Engine failure on highway A1 near km 42",
      "confirmedTruthfulness": true,
      "confirmedConditions": true,
      "orderNumber": "AXL-2026-001234",
      "requestedBy": "driver",
      "requestedAt": "2026-02-21T14:30:00.000Z",
      "pickupAddress": "Musterstr. 1, 1010 Wien",
      "deliveryAddress": "Beispielweg 5, 4020 Linz",
      "vehicleClass": "pkwCaddy",
      "price": 45.90,
      "photoURLs": [
        "https://firebasestorage.googleapis.com/..."
      ]
    }
  }' --output cancellation.pdf

let requestBody: [String: Any] = [
    "request": [
        "orderId": order.id,
        "formType": formType.rawValue,
        "reason": selectedReason.label,
        "detailedDescription": description,
        "confirmedTruthfulness": true,
        "confirmedConditions": true,
        "orderNumber": order.deliveryOrderNumber ?? "",
        "requestedBy": userRole == .driver ? "driver" : "client",
        "requestedAt": ISO8601DateFormatter().string(from: Date()),
        "pickupAddress": order.pickupLocation.address,
        "deliveryAddress": order.deliveryLocation.address,
        "vehicleClass": order.vehicleClass.rawValue,
        "price": order.price,
        "photoURLs": uploadedPhotoURLs
    ]
]
var urlRequest = URLRequest(url: URL(string: "https://api.axelo.app/reports/cancellation")!)
urlRequest.httpMethod = "POST"
urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
urlRequest.timeoutInterval = 60
urlRequest.httpBody = try JSONSerialization.data(withJSONObject: requestBody)

let (data, response) = try await URLSession.shared.data(for: urlRequest)
let storageURL = (response as? HTTPURLResponse)?.value(forHTTPHeaderField: "X-Download-URL")

val requestJson = JSONObject().apply {
    put("request", JSONObject().apply {
        put("orderId", order.id)
        put("formType", "F1")
        put("reason", "Vehicle Breakdown")
        put("detailedDescription", "Engine failure on highway A1")
        put("confirmedTruthfulness", true)
        put("confirmedConditions", true)
        put("orderNumber", order.orderNumber)
        put("requestedBy", "driver")
        put("pickupAddress", order.pickupAddress)
        put("deliveryAddress", order.deliveryAddress)
        put("vehicleClass", order.vehicleClass)
        put("price", order.price)
        put("photoURLs", JSONArray(uploadedPhotoURLs))
    })
}
val body = requestJson.toString().toRequestBody("application/json".toMediaType())
val request = Request.Builder()
    .url("https://api.axelo.app/reports/cancellation")
    .post(body)
    .build()

val client = OkHttpClient.Builder()
    .callTimeout(60, TimeUnit.SECONDS)
    .build()
val response = client.newCall(request).execute()
val pdfBytes = response.body?.bytes()
val storageURL = response.header("X-Download-URL")

const res = await fetch("https://api.axelo.app/reports/cancellation", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    request: {
      orderId: "abc123",
      formType: "F1",
      reason: "Vehicle Breakdown",
      detailedDescription: "Engine failure on highway A1 near km 42",
      confirmedTruthfulness: true,
      confirmedConditions: true,
      orderNumber: "AXL-2026-001234",
      requestedBy: "driver",
      pickupAddress: "Musterstr. 1, 1010 Wien",
      deliveryAddress: "Beispielweg 5, 4020 Linz",
      vehicleClass: "pkwCaddy",
      price: 45.90,
      photoURLs: ["https://firebasestorage.googleapis.com/..."]
    }
  })
});
const pdfBlob = await res.blob();
const storageURL = res.headers.get("X-Download-URL");

Firestore Data Model

After the PDF is generated, the complete cancellation request is saved to the cancellationRequests Firestore collection. This document serves as the permanent record for support review.

Collection Path

cancellationRequests/{requestId}

Document Schema

Security Rules

Both the requesting user and the other order party (client or driver) can read a cancellation request. This ensures the affected party can view the cancellation PDF.

match /cancellationRequests/{requestId} {
  allow read: if request.auth != null
    && (resource.data.requesterId == request.auth.uid
        || resource.data.clientId == request.auth.uid
        || resource.data.driverId == request.auth.uid);

  allow create: if request.auth != null
    && request.resource.data.requesterId == request.auth.uid
    && request.resource.data.keys().hasAll([
      'orderId', 'formType', 'reason', 'detailedDescription',
      'confirmedTruthfulness', 'confirmedConditions',
      'clientId', 'driverId'
    ]);

  allow update: if false;  // Only via Admin SDK
  allow delete: if false;
}

Integration Flow

The complete cancellation flow consists of four sequential steps. Implement them in order for a full integration.

Step 1: Determine Action

Use the Form Routing logic to determine which cancellation action applies. If the result is directCancel, skip to updating the order status. If it's form(F1–F5), proceed with the wizard flow.

Step 2: Upload Evidence Photos

If the user selected photos, upload them to Firebase Storage at cancellation_photos/{orderId}/{index}.jpg. Collect the resulting download URLs. See Photo Upload.

Step 3: Generate Cancellation PDF

Call POST /reports/cancellation with the full request object including photoURLs. The server downloads the photos, embeds them into the PDF, uploads it to cancellation_reports/{orderId}_{formType}.pdf, and returns the PDF bytes. Save the X-Download-URL header value as the permanent PDF URL.

Step 4: Save to Firestore & Update Order

Save the complete StornoRequest (including pdfURL from the previous step) to the cancellationRequests collection. Then update the order status to cancellationRequested.

Sequence Diagram

User          Client App       Firebase Storage      API Server         Firestore
 |                |                    |                   |                  |
 | tap cancel     |                    |                   |                  |
 |───────────────>| determineAction()  |                   |                  |
 |                |────────┐           |                   |                  |
 |                |<───────┘ form(F2)  |                   |                  |
 |                |                    |                   |                  |
 | fill form      |                    |                   |                  |
 | select photos  |                    |                   |                  |
 | confirm        |                    |                   |                  |
 |───────────────>|                    |                   |                  |
 |                | upload photos      |                   |                  |
 |                |───────────────────>| save to Storage   |                  |
 |                |<───────────────────| return URLs       |                  |
 |                |                    |                   |                  |
 |                | POST /reports/cancellation             |                  |
 |                |───────────────────────────────────────>|                  |
 |                |                    | fetch photos      |                  |
 |                |                    |<──────────────────|                  |
 |                |                    |──────────────────>|                  |
 |                |                    |                   | generate PDF     |
 |                |                    |    upload PDF     |                  |
 |                |                    |<──────────────────|                  |
 |                |<─────────────────────────────── PDF bytes + X-Download-URL|
 |                |                    |                   |                  |
 |                | save StornoRequest |                   |                  |
 |                |──────────────────────────────────────────────────────────>|
 |                |                    |                   |                  |
 | show success   |                    |                   |                  |
 |<───────────────|                    |                   |                  |
 |                |                    |                   |                  |
 | tap "Done"     |                    |                   |                  |
 |───────────────>| update order status: cancellationRequested               |
 |                |──────────────────────────────────────────────────────────>|

Generates a professional delivery report PDF. Supports single-delivery and multi-stop orders. Optionally uploads the PDF to Firebase Storage.

Request Body

Response Headers

Example

curl -X POST https://api.axelo.app/reports/delivery \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "id": "abc123",
      "deliveryOrderNumber": "AXL-2026-001",
      "status": "delivered",
      "pickupLocation": { "address": "Musterstr. 1, 1010 Wien" },
      "deliveryLocation": { "address": "Beispielweg 5, 4020 Linz" },
      "price": 45.90
    },
    "clientName": "Max Mustermann",
    "driverName": "Hans Fahrer",
    "userId": "firebase-uid"
  }' --output report.pdf

var request = URLRequest(url: URL(string: "https://api.axelo.app/reports/delivery")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = [
    "order": orderDict,
    "clientName": "Max Mustermann",
    "driverName": "Hans Fahrer",
    "userId": Auth.auth().currentUser?.uid ?? ""
]
request.httpBody = try JSONSerialization.data(withJSONObject: body)
let (data, response) = try await URLSession.shared.data(for: request)
// data contains the PDF bytes

val client = OkHttpClient()
val json = JSONObject().apply {
    put("order", orderJson)
    put("clientName", "Max Mustermann")
    put("driverName", "Hans Fahrer")
    put("userId", FirebaseAuth.getInstance().currentUser?.uid)
}
val body = json.toString().toRequestBody("application/json".toMediaType())
val request = Request.Builder()
    .url("https://api.axelo.app/reports/delivery")
    .post(body)
    .build()
val response = client.newCall(request).execute()
val pdfBytes = response.body?.bytes()

const res = await fetch("https://api.axelo.app/reports/delivery", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    order: { id: "abc123", deliveryOrderNumber: "AXL-2026-001",
             status: "delivered", price: 45.90,
             pickupLocation: { address: "Musterstr. 1, 1010 Wien" },
             deliveryLocation: { address: "Beispielweg 5, 4020 Linz" } },
    clientName: "Max Mustermann",
    driverName: "Hans Fahrer",
    userId: "firebase-uid"
  })
});
const pdfBlob = await res.blob();

Downloads a previously generated report PDF from Firebase Storage. Returns application/pdf stream or 404.

Path Parameters

curl https://api.axelo.app/reports/download/USER_ID/ORDER_ID --output report.pdf

Lists all generated reports for a user.

{
  "reports": [
    { "name": "abc123.pdf", "path": "reports/uid/abc123.pdf",
      "created": "2026-02-21T14:30:00.000Z", "size": "125432" }
  ]
}

Deletes a report PDF from Firebase Storage.

{ "success": true, "message": "Report deleted" }

Returns all vehicle classes sorted by sortOrder. Use ?includeInactive=true to include inactive classes.

[{
  "id": "pkw_caddy",
  "name": "PKW/Caddy",
  "icon": "car.fill",
  "sortOrder": 0,
  "active": true,
  "maxPayload": 500,
  "maxVolume": 1,
  "interiorLength": 100,
  "interiorWidth": 100,
  "interiorHeight": 70,
  "palletCapacity": 0,
  "hasLiftgate": false,
  "pricing": {
    "basePrice": 25.0, "hourlyRate": 30.0,
    "pricePerKmOutside": 0.85, "pricePerKmVienna": 0.72,
    "nightWeekendSurcharge": 0.50, "rushHourSurcharge": 0.10
  },
  "formatted": { "payload": "500 kg", "volume": "Bis 1 m³", "dimensions": "~100×100×70 cm" }
}]

Returns a single vehicle class by document ID (e.g. pkw_caddy, klein_lkw, klein_lkw_lbw).

Creates a new vehicle class. Returns 201 on success, 409 if ID exists.

Request Body

Partial update. Only provided fields are changed. Accepts the same fields as the create endpoint.

Toggles active status. No request body needed.

{ "id": "pkw_caddy", "active": false }

Permanently deletes a vehicle class.

{ "deleted": true, "id": "pkw_caddy" }

Calculates delivery price based on vehicle class, distance, and surcharges.

Request Body

{
  "vehicleClass": "PKW/Caddy", "distance": 25, "price": 46.25,
  "breakdown": {
    "basePrice": 25.0, "kmRate": 0.85, "distanceCost": 21.25,
    "surcharges": { "nightWeekend": 0, "rushHour": 0 }
  }
}

Recommends the smallest vehicle class that fits all criteria. At least one of weight (kg), volume (m³), or pallets is required.

{
  "recommended": { "id": "klein_lkw", "name": "Klein-LKW" },
  "details": [
    { "criteria": "weight", "vehicleClass": "klein_lkw", "name": "Klein-LKW" }
  ]
}

Returns all goods types sorted by sortOrder. Use ?includeInactive=true to include inactive.

[{
  "id": "europalette", "name": "Europalette", "dimensions": "120×80 cm",
  "length": 120, "width": 80, "height": null,
  "icon": "shippingbox.fill", "isCustom": false, "sortOrder": 0, "active": true
}]

Returns a single goods type by ID.

Creates a new goods type. Required: id, name. Returns 201 / 409.

Request Body

Partial update. Only provided fields are changed.

Toggles active status.

Permanently deletes a goods type.

Sends a push notification to a single user via FCM.

Request Body

{ "success": true, "messageId": "projects/.../messages/..." }

Sends a notification to a list of users. Requires userIds (array), title, body.

{ "success": true, "sent": 15, "total": 20 }

Broadcasts to all available drivers. Filters by region (matches city, postal code, or delivery areas). If orderId is provided, triggers the automatic driver notification flow instead.

{ "success": true, "sent": 8, "totalDrivers": 12, "region": "Wien" }

Creates a maintenance alert and pushes it to the target audience.

Request Body

{ "success": true, "id": "firestore-doc-id", "sent": 42 }

Lists maintenance alerts. Use ?all=true to include deactivated. Returns up to 50 sorted by creation date.

Deactivates a maintenance alert (sets active: false).

Returns recent notification logs from the in-memory buffer. Use ?limit=100 to control count (default: 200).

Returns aggregated notification statistics.

Returns all predefined notification template variants used by the system.

Returns an iCal (.ics) feed of a user's orders for Apple Calendar, Google Calendar, or Outlook. Use ?filter=all for all orders (default: active only).

Verifies the provided Firebase Auth token belongs to an admin user. Used by the admin dashboard to validate sessions.

{ "ok": true, "email": "admin@axelo.app" }

Overview

The Payments module handles the full money flow on Axelo using Stripe Connect with the Separate Charges & Transfers pattern. Clients pay the full order amount to the platform, the funds are held for 24 hours after delivery, and 90 % are then transferred to the driver's Connect account. Axelo retains a 10 % platform fee.

Endpoint Summary

Authentication

All non-webhook endpoints accept the same Authorization: Bearer <firebase-id-token> header as the rest of the API (see Authentication). In addition, every request must include the X-Firestore-Database header naming the database the user lives in:

Authorization: Bearer <firebase-id-token>
X-Firestore-Database: axelo-production-database
Content-Type: application/json

Allowed values: axelo-production-database, axelo-ios-test-database, axelo-android-test-database, axelo-test-database. The chosen database id is also written as metadata onto every Stripe object the backend creates so that webhooks can mirror status updates back into the correct Firestore.

Money Split

Stripe processing fees (1.5 % + €0.25 in the EU) are deducted from Axelo's 10 % share, not from the driver. The percentage is configurable via the STRIPE_PLATFORM_FEE_PERCENT environment variable.

Payment Flow

One full happy-path order from creation to driver payout:

Edge cases

Firestore Model

The backend mirrors all relevant Stripe state into Firestore so the iOS & Web clients never need to call Stripe directly. Two collections are touched:

users/{uid} — Stripe Connect mirror (drivers only)

orders/{orderId} — Stripe payment fields

Public liveness probe for the Stripe subdomain. Used by uptime monitors and the iOS app to verify connectivity before showing the PaymentSheet.

Response

{
  "status": "healthy",
  "service": "axelo-payments",
  "platformFeePercent": 10,
  "timestamp": "2026-05-01T14:39:55.436Z"
}

Example

curl https://payments.axelo.app/health

Creates a Stripe Express account for the authenticated driver, or returns the existing one. Mirrors the freshly retrieved Stripe state into users/{uid}. Idempotent — safe to call multiple times.

Request Body

No body required. The driver is identified via the Firebase ID token.

Response

{
  "accountId": "acct_1Q9f7s2eZvKYlo2C",
  "chargesEnabled": false,
  "payoutsEnabled": false,
  "detailsSubmitted": false,
  "onboardingCompleted": false,
  "requirementsCurrentlyDue": ["external_account", "tos_acceptance.date"],
  "requirementsPastDue": [],
  "bankLast4": null,
  "bankName": null
}

Example

curl -X POST https://payments.axelo.app/connect/account/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Firestore-Database: axelo-production-database"

let token = try await Auth.auth().currentUser?.getIDToken()
var req = URLRequest(url: URL(string: "https://payments.axelo.app/connect/account/create")!)
req.httpMethod = "POST"
req.setValue("Bearer \(token!)", forHTTPHeaderField: "Authorization")
req.setValue("axelo-production-database", forHTTPHeaderField: "X-Firestore-Database")
let (data, _) = try await URLSession.shared.data(for: req)

Returns a one-time URL to Stripe's hosted onboarding flow. The link expires after a few minutes and must be regenerated for each session.

Response

{
  "url": "https://connect.stripe.com/setup/e/acct_1Q…/Z3Z…",
  "expiresAt": 1746118800
}

Example

curl -X POST https://payments.axelo.app/connect/account/onboarding-link \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Firestore-Database: axelo-production-database"

Re-fetches the driver's Connect account from Stripe (with expanded external_accounts) and mirrors the result into Firestore. Returns the same shape as /account/create. Used by the iOS app on every appear of the Finance settings screen.

Example

curl https://payments.axelo.app/connect/account/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Firestore-Database: axelo-production-database"

Returns a one-time login URL to the Stripe Express Dashboard so the driver can review payouts, edit their bank account or update tax info. Only available once stripeOnboardingCompleted is true.

Response

{ "url": "https://connect.stripe.com/express/acct_1Q…/J5K…" }

Errors

Creates (or reuses) a Stripe Customer for the authenticated client, then creates a PaymentIntent + Ephemeral Key for the iOS PaymentSheet. The paymentStatus on the order is flipped to pending and the stripePaymentIntentId is mirrored.

Request Body

Response

{
  "paymentIntentClientSecret": "pi_3Q…_secret_AbCdEf",
  "ephemeralKeySecret": "ek_test_YWNjdF…",
  "customerId": "cus_Q…",
  "publishableKey": "pk_test_…"
}

Example

curl -X POST https://payments.axelo.app/intents/create-for-order \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Firestore-Database: axelo-production-database" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "abc123",
    "amountEur": 131.88
  }'

let body: [String: Any] = ["orderId": orderId, "amountEur": price]
let data = try await StripePaymentService.shared.post("/intents/create-for-order", body: body)
let response = try JSONDecoder().decode(PaymentIntentResponse.self, from: data)

var config = PaymentSheet.Configuration()
config.merchantDisplayName = "Axelo"
config.customer = .init(id: response.customerId,
                        ephemeralKeySecret: response.ephemeralKeySecret)

let sheet = PaymentSheet(paymentIntentClientSecret: response.paymentIntentClientSecret,
                         configuration: config)
sheet.present(from: viewController) { [weak self] result in
  Task { await self?.handleSheetResult(result, orderId: orderId) }
}

Best-effort sync from the iOS PaymentSheet completion handler — the webhook is the authoritative source of truth, but the app calls this endpoint immediately after the sheet returns to give the user instant feedback. Re-validates that the PaymentIntent's metadata (axelo_order_id, axelo_client_uid) matches the caller before writing.

Request Body

Response

{
  "paymentStatus": "held",
  "stripePaymentIntentId": "pi_3Q…",
  "stripeChargeId": "ch_3Q…"
}

Server-to-server endpoint Stripe calls on every state transition. Signature is verified against STRIPE_WEBHOOK_SECRET; requests with an invalid or missing signature get a 400 and are not retried by Stripe.

Handled Events

Multi-Database Routing

The webhook does not receive an X-Firestore-Database header. Instead, every PaymentIntent and Connect account is created with metadata.axelo_firestore_database set to the requester's database id. The handler reads that metadata to decide which Firestore database to write back into.

Stripe CLI Setup

# Forward live events from Stripe to your local server (or to staging)
stripe listen --forward-to https://payments.axelo.app/webhook

# Trigger a test event manually
stripe trigger payment_intent.succeeded

Response

{ "received": true, "eventId": "evt_1Q…" }

Manually triggers the 24-hour payout sweep. Same code path as the cron job — useful when an admin needs to force-pay a backlog after server downtime, or to verify the flow end-to-end after a Stripe Sandbox reset. Returns a per-database breakdown.

Response

{
  "ok": true,
  "summary": {
    "startedAt": "2026-05-01T14:55:00.000Z",
    "durationMs": 412,
    "processedDatabases": 2,
    "transfersAttempted": 3,
    "transfersSucceeded": 2,
    "transfersSkipped": 1,
    "transfersFailed": 0,
    "perDatabase": [
      {
        "databaseId": "axelo-production-database",
        "attempted": 2, "succeeded": 2, "skipped": 0, "failed": 0
      },
      {
        "databaseId": "axelo-ios-test-database",
        "attempted": 1, "succeeded": 0, "skipped": 1, "failed": 0
      }
    ]
  }
}

Skip reasons

An attempted order is "skipped" (not "failed") for any of the following — none of them are fatal, the next sweep tries again:

• Driver has no stripeConnectAccountId on the user doc.
• Driver has not finished onboarding (stripeOnboardingCompleted == false).
• Driver's payouts are not enabled (stripePayoutsEnabled == false).
• Order has no stripeChargeId (should never happen if paymentStatus == "held").
• Order already carries a stripeTransferId — already paid.

Example

curl -X POST https://payments.axelo.app/transfers/run-sweep \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "X-Firestore-Database: axelo-production-database"

Returns the cron configuration so an admin can confirm the sweep is enabled and the platform fee is what they expect.

Response

{
  "ok": true,
  "platformFeePercent": 10,
  "cronEnabled": true,
  "cronSchedule": "*/5 * * * *"
}

Environment Variables

Mail API

A dedicated microservice for sending transactional emails — verification codes and password-reset links — via Microsoft Graph (Office 365).

Overview

The Mail API runs as a separate Docker container on the same Hetzner server as the main API. It was introduced to move sensitive SMTP / Microsoft Graph credentials off the iOS client binary and onto a hardened server-side service.

Endpoints

Design Principles

• Credentials stay on the server. The iOS app never sees SMTP passwords or Graph client secrets.
• Codes are hashed. Only the bcrypt hash of the 6-digit code is stored in Firestore; the plaintext is emailed and never persisted.
• Anti-enumeration. /v1/password-reset/send always returns 200 OK whether or not the address is registered.
• App Check enforcement. All /v1/* endpoints require a valid X-Firebase-AppCheck token (disable only in dev via APP_CHECK_ENABLED=false).

Security

Firebase App Check

Every /v1/* request must include an App Check attestation token. The server verifies the token against Firebase before processing the request.

Rate Limiting

Two independent rate-limit layers protect the send endpoints:

When a limit is exceeded the server responds with 429 Too Many Requests and a Retry-After header (seconds).

Generates a fresh 6-digit verification code, stores its bcrypt hash in Firestore under email_verifications/{email}, and sends an Apple-style HTML email containing the plaintext code to the recipient.

Request Headers

Request Body

{ "email": "user@example.com" }

Response

{
  "ok": true,
  "expiresAt": "2026-05-04T11:30:00.000Z",
  "ttlSeconds": 600
}

Error Responses

Example

curl -X POST https://mailapi.axelo.app/v1/verification-code/send \
  -H "Content-Type: application/json" \
  -H "X-Firebase-AppCheck: $APP_CHECK_TOKEN" \
  -H "X-Firestore-Database: axelo-production-database" \
  -d '{"email": "user@example.com"}'

let expiresAt = try await MailAPIService.shared.sendVerificationCode(to: email)

Validates a 6-digit code submitted by the user against the bcrypt hash stored in Firestore. On success, the document is marked verified: true so the rest of the app's Firestore-backed onboarding logic detects the verification without any additional iOS-side write.

Request Body

{ "email": "user@example.com", "code": "483920" }

Response — Success

{ "verified": true }

Response — Failure

{ "verified": false, "reason": "invalid" }

Failure Reasons

Example

let result = try await MailAPIService.shared.verifyCode(code, for: email)
if result.verified {
    // proceed
} else {
    print(result.reason?.rawValue ?? "unknown")
}

Uses Firebase Admin SDK's generatePasswordResetLink() to create a Firebase action code, rewrites the destination URL to https://account.axelo.app/reset?oobCode=…, and delivers an Apple-style branded email containing a "Reset Password" button.

Request Body

{ "email": "user@example.com" }

Response

{ "ok": true, "ttlSeconds": 3600 }

Flow

1. iOS app calls this endpoint after the user taps "Forgot Password".
2. Server calls firebase-admin.auth().generatePasswordResetLink(email).
3. Server extracts the oobCode query parameter and builds https://account.axelo.app/reset?oobCode=….
4. Server sends the branded HTML email via Microsoft Graph (noreply@axelo.app).
5. User taps the button in the email → browser opens account.axelo.app/reset.
6. Page uses the Firebase Web SDK to verify the oobCode and call confirmPasswordReset().

Example

try await authManager.sendPasswordReset(email: email)
// Always show generic success message — server never reveals
// whether the address is registered.

curl -X POST https://mailapi.axelo.app/v1/password-reset/send \
  -H "Content-Type: application/json" \
  -H "X-Firebase-AppCheck: $APP_CHECK_TOKEN" \
  -H "X-Firestore-Database: axelo-production-database" \
  -d '{"email": "user@example.com"}'

Liveness check. No authentication required. Used by monitoring and deploy scripts.

Response

{ "ok": true, "service": "mail-api" }

curl https://mailapi.axelo.app/health

Firestore Model

Collection: email_verifications — document ID equals the normalised (lowercase) email address.

Password Reset Page

A static single-page application served by the mail-api container at https://account.axelo.app/reset. It uses the Firebase Web SDK to validate the action code and set the new password.

Page States