> ## Documentation Index > Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt > Use this file to discover all available pages before exploring further. # Fuel Cards > Best practices for implementing Terminal in fuel card workflows, from fleet onboarding through fraud prevention and transaction verification. ## Overview This guide covers best practices for integrating Terminal into fuel card workflows. It's organized into key implementation areas that map to the fuel card lifecycle: ### What This Guide Covers This guide walks through the complete fuel card workflow with Terminal. Depending on your use case, some sections may be optional: | Section | Description | When to Use | | -------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------- | | **[Connecting Fleets](#connecting-fleets-with-terminal-link)** | Onboarding fleets and accessing telematics data | All implementations—required for telematics access | | **[Connection Lifecycle](#connection-lifecycle)** | Handling connection events, disconnections, and monitoring | All implementations—critical for maintaining data access | | **[API Usage](#api-usage)** | Entity sync, transaction verification, and polling strategies | All implementations—core integration pattern | | **[IFTA & Reconciliation](#ifta--reconciliation)** | Automating compliance reporting and transaction enrichment | If you handle IFTA reporting or expense reconciliation | | **[Offboarding](#offboarding)** | Archiving connections when accounts close | All implementations—for clean lifecycle management | ### Recommended Implementation Phases We recommend a phased rollout to de-risk your integration and validate data quality before enabling transaction declines: | Phase | Scope | What You're Validating | | ----------------------------- | ---------------------------------------------- | --------------------------------------------------- | | **V0: Logging Only** | Log GPS distance at authorization, no declines | Data quality, coverage gaps, false positive rates | | **V1: Location Verification** | Enable transaction declines based on location | Threshold tuning, operational workflows | | **V2: Fuel Verification** | Add fuel level and tank-capacity checks | Fueling to data presence delay, noise from sloshing | | **V3: Full Feature Set** | Routing, IFTA, analytics | End-to-end value delivery | **Start with V0**: Run in logging-only mode for 2-4 weeks to establish baseline metrics before enabling declines. This lets you tune distance thresholds and identify edge cases (e.g., card-not-present transactions, multi-vehicle fleets) without impacting cardholders. *** ## Connecting Fleets with Terminal Link The first step is obtaining **consent** from the fleet to access their telematics data. Terminal's [Link component](/link-component) handles the [consent flow](/terminal-platform/link) and authorization with the telematics provider. ### Configuring Terminal Link Use [Terminal Link](/link-component) to guide fleets through connecting their telematics provider. For fuel cards, use **Automatic sync mode** from the start—you need continuous data access for fraud prevention. The hosted flow is a URL you can send directly to fleets via email, SMS, or any messaging channel: ``` https://link.withterminal.com/?sync_mode=automatic&tags=account-1234,program-premium&key={PUBLISHABLE_KEY} ``` The React SDK can be embedded in your product or digital onboarding flow: ```tsx theme={null} const terminal = useTerminalLink({ publishableKey: process.env.REACT_APP_TERMINAL_PUBLISHABLE_KEY, onSuccess: exchangeToken, params: { syncMode: 'automatic', tags: ['account-1234', 'program-premium'], // Your internal identifiers }, }); ``` The JS SDK can be embedded in your product or digital onboarding flow: ```ts theme={null} TerminalLink.initialize({ publishableKey: process.env.TERMINAL_PUBLISHABLE_KEY, onSuccess: (result) => exchangePublicToken(result.publicToken), params: { syncMode: 'automatic', tags: ['account-1234', 'program-premium'], // Your internal identifiers }, }).open(); ``` Use `tags` to associate connections with your internal identifiers like account numbers (`account-1234`), fleet IDs (`fleet-5678`), or program tiers (`program-premium`). *** ## Connection Lifecycle Managing connection events is critical for fuel card workflows. A disconnected connection means degraded fraud protection—use [webhooks](/terminal-platform/webhooks) to automate responses to connection state changes. ### Handling Connection Completion When a fleet successfully connects their telematics provider, Terminal sends a [`connection.completed`](/api-reference/webhook-events/connection-completed) webhook. Use this to: * Enable telematics-backed features for that fleet (Location Verification, routing, etc.) * Update your internal systems with the connection details * Send a confirmation to the fleet ```ts theme={null} // Webhook handler for connection.completed app.post('/webhooks/terminal', async (req, res) => { const event = req.body; if (event.type === 'connection.completed') { const { connection } = event.detail; // Find account number from tags (e.g., 'account-1234') const accountTag = connection.tags?.find((t) => t.startsWith('account-')); const accountNumber = accountTag?.replace('account-', ''); // Record that fleet has connected telematics await recordTelematicsConnected({ accountNumber, connectionId: connection.id, provider: connection.provider.name, connectedAt: event.timestamp, }); // Enable telematics features for this account await enableTelematicsFeatures({ accountNumber, features: ['location_verification', 'fuel_verification'], }); // Notify the fleet await sendFleetConfirmation({ email: getFleetEmail(accountNumber), subject: 'Telematics Connected Successfully', message: 'Your telematics data is now connected. Location Verification fraud protection is active.', }); } res.status(200).send('OK'); }); ``` ### Handling Disconnections When a connection becomes disconnected (credentials expire, provider access revoked, etc.), Terminal sends a [`connection.disconnected`](/api-reference/webhook-events/connection-disconnected) webhook. This can result in a **fraud protection gap**—notify the fleet promptly and degrade gracefully. ```ts theme={null} if (event.type === 'connection.disconnected') { const { connection } = event.detail; // Find account number from tags const accountTag = connection.tags?.find((t) => t.startsWith('account-')); const accountNumber = accountTag?.replace('account-', ''); // Flag the account for reduced protection await updateAccountStatus({ accountNumber, telematicsStatus: 'disconnected', fraudProtectionLevel: 'reduced', // Fall back to static auth rules }); // Send urgent notification to fleet with reconnection link await notifyFleet({ email: getFleetEmail(accountNumber), subject: 'Action Required: Reconnect Your Telematics', body: 'Your telematics connection has been disconnected. Location Verification fraud protection is temporarily reduced. Please reconnect to restore full protection.', reconnectUrl: connection.linkUrl, priority: 'high', }); // Alert your operations team await alertOpsTeam({ accountNumber, reason: 'telematics_disconnected', impact: 'Fraud protection degraded to static rules', }); } ``` ### Handling Reconnections When a previously disconnected connection is restored, Terminal sends a [`connection.reconnected`](/api-reference/webhook-events/connection-reconnected) webhook. Resume full telematics-backed controls. ```ts theme={null} if (event.type === 'connection.reconnected') { const { connection } = event.detail; // Find account number from tags const accountTag = connection.tags?.find((t) => t.startsWith('account-')); const accountNumber = accountTag?.replace('account-', ''); // Restore full protection await updateAccountStatus({ accountNumber, telematicsStatus: 'connected', fraudProtectionLevel: 'full', }); // Confirm to the fleet await notifyFleet({ email: getFleetEmail(accountNumber), subject: 'Telematics Reconnected', body: 'Your telematics connection has been restored. Location Verification fraud protection is fully active.', }); } ``` ### Key Webhook Events for Fuel Cards | Event | Trigger | Recommended Action | | ------------------------- | ------------------------------------------- | ------------------------------------------------------ | | `connection.completed` | Fleet completes telematics connection | Enable Location Verification and verification features | | `connection.disconnected` | Connection credentials become invalid | Degrade to static auth, notify fleet | | `connection.reconnected` | Previously disconnected connection restored | Restore full telematics features | See the [Webhooks Guide](/terminal-platform/webhooks) for setup instructions and the [Webhook Events Reference](/api-reference/webhook-events/overview) for detailed payload schemas. *** ## API Usage For fuel card implementations, you'll use [Terminal's API](/api-reference) for two key workflows: **syncing fleet entities** (vehicles, drivers, trailers) and **real-time location verification** for fraud prevention. ### Entity Sync: Vehicles, Drivers, Trailers When a fleet connects their telematics, sync their roster to auto-populate your card management system. This eliminates manual data entry and keeps your system in sync with the fleet's actual assets. Start with [`GET /vehicles`](/api-reference/vehicles/list-vehicles), [`GET /drivers`](/api-reference/drivers/list-drivers), and [`GET /trailers`](/api-reference/trailers/list-trailers). ```ts theme={null} async function syncFleetRoster(connectionToken: string) { // Get vehicles from Terminal const vehiclesResponse = await fetch( 'https://api.withterminal.com/tsp/v1/vehicles', { headers: { Authorization: `Bearer ${SECRET_KEY}`, 'Connection-Token': connectionToken, }, }, ); const vehicles = await vehiclesResponse.json(); // Auto-populate your card management system for (const vehicle of vehicles.results) { await createOrUpdateVehicleRecord({ vin: vehicle.vin, name: vehicle.name, licensePlate: vehicle.licensePlate, fuelType: vehicle.fuelType, tankCapacityLiters: vehicle.fuelTankCapacity, telematicsId: vehicle.id, }); } // Repeat for /drivers and /trailers endpoints return { vehiclesImported: vehicles.results.length, }; } ``` **Keeping entities in sync with webhooks:** Subscribe to [entity webhooks](/terminal-platform/webhooks) to stay in sync as the fleet's roster changes: ```ts theme={null} // Webhook handler for entity changes app.post('/webhooks/terminal', async (req, res) => { const event = req.body; if (event.type === 'vehicle.added') { const { vehicle, connection } = event.detail; await createOrUpdateVehicleRecord({ vin: vehicle.vin, name: vehicle.name, fuelType: vehicle.fuelType, tankCapacityLiters: vehicle.fuelTankCapacity, telematicsId: vehicle.id, }); } if (event.type === 'vehicle.removed') { const { vehicle } = event.detail; await flagVehicleAsRemoved(vehicle.id); } if (event.type === 'driver.added') { const { driver } = event.detail; await createOrUpdateDriverRecord({ firstName: driver.firstName, lastName: driver.lastName, licenseNumber: driver.licenseNumber, telematicsId: driver.id, }); } if (event.type === 'driver.removed') { const { driver } = event.detail; await flagDriverAsRemoved(driver.id); } res.status(200).send('OK'); }); ``` ### Transaction Verification: Location & Fuel For card authorization, we recommend the fuel card provider **poll Terminal on a schedule** and maintain a traceable copy of vehicle state (location snapshots, tank capacity, timestamps, provider metadata) in your own datastore. Then at swipe time, evaluate **Location Verification** and **fuel verification** (capacity checks) from your local data, while using Terminal API reads only as fallback/refresh paths (see [Managed Polling](/terminal-platform/managed-polling) and [real-time data](/terminal-platform/real-time-data)). **Recommended authorization flow:** ```mermaid theme={null} sequenceDiagram participant Card as Card Network participant Issuer as Fuel Card Provider participant Terminal as Terminal API participant Provider as Telematics Provider Issuer->>Terminal: Poll /vehicles/locations Terminal->>Provider: Fetch location & fuel data Provider-->>Terminal: Response payloads Terminal-->>Issuer: Normalized response payloads Issuer->>Issuer: Store location & fuel data Card->>Issuer: Authorization request (merchant location) Issuer->>Issuer: Perform Location Verification Issuer->>Issuer: Perform Fuel Verification alt All checks pass Issuer-->>Card: Approve else Any check fails Issuer-->>Card: Decline end ``` **Key endpoints:** | Endpoint | Use Case | Latency | | ---------------------------------------------------------------------------------- | ---------------------------------------------- | ---------- | | [`GET /vehicles/locations`](/api-reference/vehicles/list-latest-vehicle-locations) | Current GPS position for Location Verification | Real-time | | [`GET /vehicles/{id}`](/api-reference/vehicles/get-vehicle) | Tank capacity for fuel verification | Cached | | [`GET /ifta/summary`](/api-reference/ifta/get-iftasummary) | Jurisdictional miles for IFTA | Aggregated | #### Fuel Verification Implementation Verify that the requested fuel amount doesn't exceed the vehicle's physical capacity. ```ts theme={null} async function verifyFuelCapacity( vehicleId: string, connectionToken: string, requestedGallons: number, ): Promise<{ approved: boolean; maxGallons: number; reason?: string; }> { // Get current vehicle location (includes fuel percentage) const locationResponse = await fetch( `https://api.withterminal.com/tsp/v1/vehicles/locations?vehicleIds=${vehicleId}`, { headers: { Authorization: `Bearer ${SECRET_KEY}`, 'Connection-Token': connectionToken, }, }, ); const locationData = await locationResponse.json(); const currentLocation = locationData.results[0]; // Get vehicle details for tank capacity const vehicleResponse = await fetch( `https://api.withterminal.com/tsp/v1/vehicles/${vehicleId}`, { headers: { Authorization: `Bearer ${SECRET_KEY}`, 'Connection-Token': connectionToken, }, }, ); const vehicle = await vehicleResponse.json(); if (!vehicle.fuelTankCapacity) { // Tank capacity unknown—approve but flag for review return { approved: true, maxGallons: requestedGallons, reason: 'Tank capacity unknown—approved with flag', }; } // Convert liters to gallons (Terminal uses liters) const tankCapacityGallons = vehicle.fuelTankCapacity * 0.264172; const currentFuelPercent = currentLocation?.fuel || 0; const currentFuelGallons = tankCapacityGallons * (currentFuelPercent / 100); const maxFillableGallons = tankCapacityGallons - currentFuelGallons; // Add 10% buffer for measurement variance const maxWithBuffer = maxFillableGallons * 1.1; if (requestedGallons > maxWithBuffer) { return { approved: false, maxGallons: maxFillableGallons, reason: `Requested ${requestedGallons.toFixed(1)} gal exceeds capacity (max: ${maxFillableGallons.toFixed(1)} gal)`, }; } return { approved: true, maxGallons: maxFillableGallons, }; } ``` ### Polling Strategy for Location Verification The [`/vehicles/locations`](/api-reference/vehicles/list-latest-vehicle-locations) endpoint is **real-time**—each request triggers a synchronous call to the telematics provider. You have two approaches: | Approach | Best For | Trade-offs | | ------------------- | ------------------------------------------ | --------------------------------------------- | | **On-demand** | Location Verification checks at swipe time | Highest freshness, but 1-3s latency | | **Managed Polling** | High-volume authorization workflows | Sub-100ms latency, but data may be 15-60s old | #### On-Demand Calls Fetch data directly from the telematics provider at request time. Best when latency of 1-3 seconds is acceptable and you want maximum data freshness. #### Managed Polling For sub-second response times, enable [Managed Polling](/terminal-platform/managed-polling) in your Terminal dashboard. Terminal proactively caches location data at your configured interval (e.g., every 15 seconds). | Latency Target | Recommended Approach | Trade-off | | --------------- | --------------------- | ----------------------------- | | Less than 800ms | Managed Polling (15s) | Location may be 15s old | | 1-3s acceptable | On-Demand | Freshest data, higher latency | **For sub-second Location Verification**: Most production implementations use managed polling with a 15-30 second interval. A vehicle's location rarely changes significantly in 15 seconds, making this acceptable for fraud prevention while achieving sub-500ms authorization response times. **Production recommendation**: Start with on-demand calls during pilot to validate data quality, then switch to managed polling when you need sub-second latency for production authorization flows. *** ## IFTA & Reconciliation After transactions occur, use Terminal data to automate IFTA compliance and enrich transactions for reconciliation. ### IFTA Automation The [`/ifta/summary`](/api-reference/ifta/get-iftasummary) endpoint provides jurisdictional miles by vehicle and month—the key input for IFTA reporting. ```ts theme={null} async function getIFTASummary( connectionToken: string, startMonth: string, // 'YYYY-MM' endMonth: string, ): Promise { const response = await fetch( `https://api.withterminal.com/tsp/v1/ifta/summary?` + `startMonth=${startMonth}&endMonth=${endMonth}&groupBy=vehicle,jurisdiction`, { headers: { Authorization: `Bearer ${SECRET_KEY}`, 'Connection-Token': connectionToken, }, }, ); const data = await response.json(); return data.results; } // Example response: // [ // { vehicle: 'vcl_123', jurisdiction: 'TX', distance: 1234.5, month: '2024-01' }, // { vehicle: 'vcl_123', jurisdiction: 'OK', distance: 567.8, month: '2024-01' }, // { vehicle: 'vcl_456', jurisdiction: 'TX', distance: 890.1, month: '2024-01' }, // ] ``` ### Dashboard Access The Terminal dashboard provides a visual interface for investigating transactions and verifying vehicle activity without writing code. Fraud and operations teams can: * **View vehicle history**: See trips, GPS breadcrumbs, and routes on an interactive map with timeline filtering * **Verify transaction locations**: Check where a vehicle was at a specific time to validate or investigate fuel purchases * **Browse live locations**: See current fleet positions for real-time verification * **Filter by date and vehicle**: Narrow down to specific vehicles and time ranges around suspicious transactions * **Export data**: Download trip and vehicle data as CSV for analysis or dispute resolution This is particularly useful for fraud investigation teams who need to quickly verify whether a vehicle was actually at a fuel station when a transaction occurred. *** ## Offboarding When a fleet churns or a contract ends, archive the connection to stop data syncing and clean up resources. ### Archiving Connections Mark a connection as archived when it's no longer needed using [`PATCH /connections/current`](/api-reference/connections/update-current-connection): ```bash theme={null} curl --request PATCH \ --url https://api.withterminal.com/tsp/v1/connections/current \ --header 'Authorization: Bearer {SECRET_KEY}' \ --header 'Connection-Token: {CONNECTION_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "status": "archived" }' ``` **Example: Account Closure Workflow** ```ts theme={null} async function handleAccountClosed(accountNumber: string) { // Find the connection by account tag const connections = await fetch( `https://api.withterminal.com/tsp/v1/connections?tag=account-${accountNumber}`, { headers: { Authorization: `Bearer ${SECRET_KEY}` } }, ); const data = await connections.json(); const connection = data.results?.[0]; if (connection) { // Archive the connection await fetch('https://api.withterminal.com/tsp/v1/connections/current', { method: 'PATCH', headers: { Authorization: `Bearer ${SECRET_KEY}`, 'Connection-Token': connection.token, 'Content-Type': 'application/json', }, body: JSON.stringify({ status: 'archived', }), }); // Record the archival in your system await recordConnectionArchived({ accountNumber, connectionId: connection.id, reason: 'account_closed', archivedAt: new Date().toISOString(), }); // Disable telematics features await disableTelematicsFeatures({ accountNumber, features: ['gps_lock', 'fuel_verification'], }); } } ``` Archiving a connection stops all data syncing and deliveries. Historical data remains in your systems for audits, disputes, and analytics. *** ## Complete Webhook Reference Here's a summary of all webhook events relevant to fuel card workflows: | Event | Trigger | Recommended Action | | ------------------------- | ------------------------------------------- | ---------------------------------------------------------------- | | `connection.completed` | Fleet completes telematics connection | Enable Location Verification and verification; sync fleet roster | | `connection.disconnected` | Connection credentials become invalid | Degrade fraud protection, notify fleet | | `connection.reconnected` | Previously disconnected connection restored | Restore full telematics features | | `vehicle.added` | New vehicle detected in fleet | Auto-add to card system, update mappings | | `vehicle.removed` | Vehicle removed from fleet | Flag/remove from card system | | `vehicle.modified` | Vehicle details changed | Update tank capacity, VIN records | | `driver.added` | New driver detected in fleet | Auto-add to card system | | `driver.removed` | Driver removed from fleet | Flag/deactivate driver cards | For event payload details, see the [Webhook Events Reference](/api-reference/webhook-events/overview). *** ## Full Sequence Diagram ```mermaid theme={null} %%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#e5e7eb', 'primaryTextColor':'#111827', 'primaryBorderColor':'#9ca3af', 'lineColor':'#6b7280', 'secondaryColor':'#f3f4f6', 'tertiaryColor':'#f9fafb'}}}%% sequenceDiagram participant Fleet participant Issuer as Fuel Card Provider participant Terminal participant CardNetwork as Card Network Note over Fleet,CardNetwork: Fleet Onboarding Issuer->>Fleet: Send Terminal Link URL Fleet->>Terminal: Connect telematics account Terminal->>Issuer: Webhook: connection.completed Issuer->>Terminal: GET /vehicles, /drivers, /trailers Terminal-->>Issuer: Fleet roster Issuer->>Issuer: Auto-populate card system Issuer->>Fleet: Confirm telematics active Note over Fleet,CardNetwork: Entity Sync loop Ongoing Terminal->>Issuer: Webhook: vehicle.added / driver.added Issuer->>Issuer: Update card system records end Note over Fleet,CardNetwork: Transaction: Location Verification & Fuel Verification loop Scheduled polling Issuer->>Terminal: Poll /vehicles/locations + /vehicles/{id} Terminal-->>Issuer: Latest location + tank data Issuer->>Issuer: Upsert local trace (data + timestamps) end Fleet->>CardNetwork: Swipe card at station CardNetwork->>Issuer: Authorization request Issuer->>Issuer: Read latest local vehicle snapshot Issuer->>Issuer: Perform Location Verification Issuer->>Issuer: Perform Fuel Verification opt Snapshot stale or missing Issuer->>Terminal: Refresh via Terminal API Terminal-->>Issuer: Latest vehicle data Issuer->>Issuer: Update local trace end alt All checks pass Issuer-->>CardNetwork: Approve CardNetwork-->>Fleet: Transaction approved else Any check fails Issuer-->>CardNetwork: Decline CardNetwork-->>Fleet: Transaction declined end Note over Fleet,CardNetwork: IFTA Reconciliation Issuer->>Terminal: GET /ifta/summary (monthly) Terminal-->>Issuer: Jurisdictional miles Issuer->>Issuer: Combine with fuel purchases Issuer->>Fleet: IFTA-ready reports Note over Fleet,CardNetwork: Disconnection Handling Terminal->>Issuer: Webhook: connection.disconnected Issuer->>Issuer: Degrade to static auth rules Issuer->>Fleet: Send reconnection notification Fleet->>Terminal: Reconnect via Link Terminal->>Issuer: Webhook: connection.reconnected Issuer->>Issuer: Restore full Location Verification Note over Fleet,CardNetwork: Offboarding Issuer->>Terminal: Archive connection Issuer->>Issuer: Disable telematics features ``` *** ## Next Steps * [Set up webhooks](/terminal-platform/webhooks) for event-driven automation * [Learn how to sync data](/guides/syncing-data) for API-based patterns * [Explore the API reference](/api-reference/authentication) to query telematics data * [Review custom identifiers](/terminal-platform/custom-identifiers) for connection organization * [Understand real-time data](/terminal-platform/real-time-data) for Location Verification implementation