Compass Fuel Integration

​

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).
• You have login credentials for the Compass Payment Services portal at 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).
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.

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.

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.

​

To download fuel transactions from Compass:

• Log in to the Compass portal at cps.compasspaymentservices.com.
• Open the Dashboard.
• In the Transactions section, select Export CSV.
  This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section.
  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.

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. Click the vertical ellipsis icon (⋮) next to the “Add **Transaction” **button. Select the “Import Report” option. Select Compass as the integration type. Upload the CSV file you downloaded from the Compass portal. Click the “Save” button 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.

​

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.