> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Compass Fuel Integration

> Import Compass Payment Services fuel card transactions into Alvys through a manual CSV upload to apply driver fuel deductions and update the Fuel Report.

<Note>
  Compass Payment Services connects to Alvys through a manual CSV upload process. Download fuel card transaction data from the Compass portal and upload it into Alvys to apply fuel deductions and maintain fuel records. Also referred to as Compass fuel card import.
</Note>

## Overview

The Compass fuel integration (Compass Payment Services, fuel card import, manual CSV upload) connects Compass fuel card data with Alvys. This is a manual import process: you download a CSV file from the Compass portal and upload it into Alvys. Alvys then matches each transaction to the correct driver using the fuel card number stored on their profile.

Use this integration to track fuel expenses, apply fuel deductions to driver pay, and maintain accurate fuel records in your Fuel Report. The integration is one-way: data flows from Compass into Alvys only.

## Prerequisites

Before setting up this integration, confirm the following:

* You have access in Alvys to manage Integrations ([https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)).
* You have login credentials for the Compass Payment Services portal at [cps.compasspaymentservices.com](http://cps.compasspaymentservices.com/).
* Your subsidiaries are already configured in Alvys.

## How to connect

1. In Alvys, select your Username in the bottom-left corner and click the integrations page ([https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)).
2. In the integrations list, expand the **Fuel** category.
3. Click the gray “Inactive” button next to **Compass**.
4. Confirm the correct subsidiaries are selected, then click **Save**.

<Info>
  💡 No API credentials are required for the Compass integration. Enabling the integration registers Compass as an available upload type in the [Fuel Report.](https://app.alvys.com/assets/fuel)
</Info>

**For Alvys to attribute transactions to the correct driver, each driver must have their Compass fuel card number on their profile:**

1. From the Alvys toolbar, go to **Assets** and select **Drivers**.
2. Find and open a driver profile.
3. In the first section, click the plus sign next to **Fuel Card Numbers**.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/b5b32a84a9bc.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=10a5abf83e1b6e62a12b2fe8068b2990" alt="This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted" width="1250" height="704" data-path="images/help/b5b32a84a9bc.png" />

  *This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted*
</Note>

1. Enter the fuel card number for this driver.
2. Select **Compass** in the provider dropdown.
3. Set the deduct fuel and discounted fuel checkboxes if applicable.
4. Click **Save**.
5. Repeat the fuel card steps for each driver who has a Compass fuel card.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/1f1aa73d4a7a.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=5e5d09447929a353f7432cf869842cf4" alt="This image shows the fuel card number entry popup with the Compass provider selected and the deduct fuel checkbox visible." width="670" height="491" data-path="images/help/1f1aa73d4a7a.png" />

  *This image shows the fuel card number entry popup with the Compass provider selected and the deduct fuel checkbox visible.*
</Note>

### To download fuel transactions from Compass:

* Log in to the Compass portal at [cps.compasspaymentservices.com](http://cps.compasspaymentservices.com/).
* Open the **Dashboard**.
* In the Transactions section, select **Export CSV**.

  <Note>
    <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/c66fcf70270e.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=e53b17e66c12250361b6aad51c0a9444" alt="This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section." width="2000" height="542" data-path="images/help/c66fcf70270e.png" />

    *This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section.*
  </Note>

  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/c66fcf70270e.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=e53b17e66c12250361b6aad51c0a9444" alt="This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section." width="2000" height="542" data-path="images/help/c66fcf70270e.png" />

  *This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section.*
* Select your date range and click **Export**.
* Save the CSV file to your device.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/66323aac7b6a.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=ae95bc20cfb10812e8417200899fca5b" alt="This image shows the date range selector and Export button in the Compass portal." width="960" height="550" data-path="images/help/66323aac7b6a.png" />

  *This image shows the date range selector and Export button in the Compass portal.*
</Note>

**To upload the file to Alvys (confirm each driver's Compass fuel card number is saved first):**

From the Alvys toolbar, go to \*\*Assets \*\*and select **Fuel Report**.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/7e6bd75430ef.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=602277986b621d5a5f1ffea7d17a4f13" alt="This image shows the Fuel Report page with the Transaction File Upload button visible." width="301" height="243" data-path="images/help/7e6bd75430ef.png" />

  *This image shows the Fuel Report page with the Transaction File Upload button visible.*
</Note>

Click the vertical ellipsis icon **(⋮)** next to the “**Add** \*\*Transaction” \*\*button.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/1f53290bffcb.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=6d6d89cab465e0ab0cbb83136e9eee59" alt="Image showing ellipsis icon next to “Add Transaction” button" width="548" height="107" data-path="images/help/1f53290bffcb.png" />

  *Image showing ellipsis icon next to “Add Transaction” button*
</Note>

Select the “**Import Report**” option.

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/a8c5c49bed65.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=67d336097504c45353c1444a8a409757" alt="Image showing Import Report option" width="271" height="186" data-path="images/help/a8c5c49bed65.png" />

  *Image showing Import Report option*
</Note>

**Select Compass** as the integration type.

Upload the CSV file you downloaded from the Compass portal.

Click the “Save” button

<Note>
  <img src="https://mintcdn.com/alvys/NbezcQvwUCJbTEUv/images/help/808b97ee10a5.png?fit=max&auto=format&n=NbezcQvwUCJbTEUv&q=85&s=3823404715ae3b91b1e273c2ce48c810" alt="Image showing ”Upload Fuel Report” form with Integration type and Add report input fields." width="562" height="417" data-path="images/help/808b97ee10a5.png" />

  *Image showing ”Upload Fuel Report” form with Integration type and Add report input fields.*
</Note>

After the upload completes, use the Transaction Date range filter in the Fuel Report to review the imported transactions.

## What syncs

The Compass integration is a manual, one-way sync from Compass into Alvys. After uploading a Compass CSV, Alvys maps transaction data as follows:

* Fuel card number on the CSV is matched against the digits stored in the driver's profile. Transactions are attributed to the driver whose fuel card number matches.
* Transaction date, amount, and gallons are imported into the Fuel Report.
* If the fuel card number on a transaction does not match any driver profile, the transaction will not be attributed to a driver. Add or correct the card number on the driver profile, then re-upload the file.
* Alvys detects duplicate transactions by transaction ID and will not import duplicates.
* There is no automatic or scheduled sync for this integration.

<Warning>
  ⚠️ This integration does not support automatic or scheduled imports. · Transactions with a card number not matching any driver profile will not be attributed to a driver. · Alvys does not write data back to Compass.
</Warning>

## Troubleshooting

### Driver fuel transactions not appearing after upload

1. Open the driver profile in **Assets > Drivers** and confirm a Compass fuel card number is saved under Fuel Card Numbers.
2. Verify the card number matches what appears in the Compass CSV export. Alvys matches on the exact digits stored in the profile.
3. Re-upload the CSV after correcting the card number. Alvys will not import a transaction already imported with the same transaction ID, so if the original upload was rejected entirely, a fresh upload of the same file will work.
4. If transactions are still missing after correcting the card number, contact Alvys support.

### Upload fails or returns an error

1. Confirm you selected **Compass** (not another provider) in the Integration Type dropdown before uploading.
2. Confirm the file is a CSV downloaded directly from the Compass portal. Modified or reformatted files may not parse correctly.
3. Contact Alvys support if the error persists after verifying the file and integration type.

## FAQs

**Q: What happens if I upload the same file twice?**

**A:** Alvys detects duplicate transactions by transaction ID and will not import them again. Re-uploading the same file is safe.

**Q: How often should I upload fuel transaction reports?**

**A:** This depends on your reporting and settlement schedule. Most teams upload weekly or monthly to keep fuel data current.

**Q: What if a driver's transactions are not showing up after upload?**

**A:** Confirm the driver has the correct Compass fuel card number on their profile under Assets > Drivers. Alvys matches transactions to drivers using that number. If the number is missing or incorrect, add or correct it and re-upload the file.

**Q: Do I need API credentials to set up this integration?**

**A:** No. The Compass integration does not require API credentials. You only need to activate it in Management > Integrations and then upload CSV files manually.