Collaborative Authorization Fleet Data

Overview

Highnote provides fleet-specific data from Visa and Mastercard during authorization requests, which can be used to enhance your collaborative authorization decision-making process. For an overview of the collaborative authorization feature, see Collaborative Authorization.

This guide provides an overview of each card network's fleet-specific data, examples of request bodies, and resources to simulate fleet transactions in your Test environment.

Fleet Data

When a cardholder initiates a transaction, Highnote sends a collaborative authorization request to your endpoint that contains transaction data. Fleet collaborative authorization requests contain a field called mastercardFleetData or visaFleetData depending on the network.
You can configure your collaborative authorization flow to use this data in decisioning.

Note the following about fleet-specific collaborative authorization data:

Fleet data fields may be null if the payment card is not configured to prompt the cardholder or POS did not return fleet information in the authorization message.
Fleet data provided by Visa and Mastercard differ.

Visa

info

For an overview of Visa product codes, see the Visa Fleet 2.0 Global Implementation Guide V1.2.

The following data is available for Visa fleet card products:

Field	Description	Possible values
`visaFleetData.purchasetype`	Indicates whether fuel or non-fuel items are included in the transaction	`FUEL_PURCHASE`, `NON_FUEL_PURCHASE`, `MIXED`, `NOT_SPECIFIED`
`visaFleetData.servicetype`	Indicates whether the transactions took place at a self-service or full-service station	`FULL_SERVICE`, `SELF_SERVICE`, `NOT_SPECIFIED`
`visaFleetData.purchaseIdFormat`	Indicates whether `visaFleetData.purchaseId` is an order or invoice number
`visaFleetData.purchaseId`	An alphanumeric value representing an order or invoice number provided by the cardholder
`visaFleetData.fleetId`	An alphanumeric value representing either a vehicle, driver, or generic ID provided by the cardholder
`visaFleetData.odometer`	The odometer value provided by the cardholder
`visaFleetData.employeeNumber`	An alphanumeric value representing the employee's ID number
`visaFleetData.trailerNumber`	An alphanumeric value representing the trailer's ID number
`visaFleetData.customPrompt1`	An alphanumeric value representing the answer to a custom prompt
`visaFleetData.customPrompt2`	An alphanumeric value representing the answer to a custom prompt
`visaFleetData.nonFuelProductCodes`	A list of non-fuel product codes for the products purchased
`visaFleetData.purchaseRestrictonsFlag`	Indicates whether the POS supports host-based restriction processing

Mastercard

info

For an overview of Mastercard prompt values and product codes, see the Mastercard Fleet Implementation Guide v4.

The following data is available for Mastercard fleet card products:

Field	Description
`mastercardFleetData.driverId`	An alphanumeric value representing a driver ID provided by the cardholder
`mastercardFleetData.vehicleId`	An alphanumeric value representing a vehicle ID provided by the cardholder
`mastercardFleetData.prompts`	A list of prompt codes and cardholder-entered values
`mastercardFleetData.fuelProducts`	A list of fuel products purchased
`mastercardFleetData.nonFuelProducts`	A list of non-fuel products purchased
`mastercardFleetData.spendControlOverrideFlag`	Indicates whether the POS supports overriding the fleet spend controls on the card

Request body

When you receive a collaborative authorization request for a fleet card product, the request body contains fleet-specific data you can use in decisioning. Each request body has network-specific visaFleetData or mastercardFleetData.

Note, some fields in a fleet collaborative authorization request body may be null in the following scenarios:

The card is not configured to prompt the cardholder.
The POS did not return fleet information in the authorization message.

Visa Request Example

The following payload is an example of a Visa fleet collaborative authorization request body:

{
  "data": {
    "collaborativeAuthorizationRequest": {
      "id": "TRANSACTION_EVENT_ID",
      "transaction": {
        "id": "TRANSACTION_ID"
      },
      "transactionTimestamp": "2024-03-20T02:59:36.160Z",
      "paymentCard": {
        "id": "PAYMENT_CARD_ID"
      },
      "networkRetrievalReferenceNumber": "408002084606",
      "transactionAmount": {
        "value": 100,
        "currencyCode": "USD"
      },
      "settlementAmount": {
        "value": 100,
        "currencyCode": "USD"
      },
      "requestedAmount": {
        "value": 15000,
        "currencyCode": "USD"
      },
      "surchargeFee": null,
      "merchantDetails": {
        "merchantId": "merchantId",
        "category": "AUTOMATED_FUEL_DISPENSERS",
        "categoryCode": "5542",
        "countryCodeAlpha3": "USA",
        "description": "KWIK TRIP 123456",
        "name": "My Awesome Fuel",
        "address": {
          "streetAddress": "",
          "extendedAddress": "",
          "postalCode": "94105",
          "region": "CA",
          "locality": "San Francisco",
          "countryCodeAlpha3": "USA"
        }
      },
      "responseCode": "PARTIAL_AMOUNT_APPROVED",
      "avsResponseCode": "NOT_PROVIDED",
      "postalCodeResponseCode": "NOT_PROVIDED",
      "cvvResponseCode": "MATCH",
      "pointOfSaleDetails": {
        "panEntryMode": "MAGNETIC_STRIPE",
        "pinEntryMode": "PIN_ENTRY_CAPABILITY",
        "terminalAttendance": "ATTENDED",
        "isCardHolderPresent": true,
        "isCardPresent": true,
        "purchaseAmountOnlyCapable": true,
        "isRecurring": false,
        "terminalSupportsPartialApproval": true
      },
      "createdAt": "2024-03-20T02:59:36.160Z",
      "visaFleetData": {
        "purchaseType": "FUEL_PURCHASE",
        "serviceType": "HIGH_SPEED_DISPENSE",
        "purchaseIdFormat": "INVOICE",
        "purchaseId": "purchaseIdentifier",
        "fleetId": "fleetIdentifier",
        "odometer": "odometer",
        "employeeNumber": "employeeNumber",
        "trailerNumber": "trailerNumber",
        "customPrompt1": "customPrompt1",
        "customPrompt2": "customPrompt2",
        "nonFuelProductCodes": [
          "BATTERIES",
          "OIL_CHANGE",
          "LUBE",
          "ENGINE_SERVICE"
        ],
        "purchaseRestrictionsFlag": true
      },
      "__typename": "PaymentCardAuthorizationRequest"
    }
  },
  "extensions": {
    "signatureTimestamp": 1710903576292
  }
}

Mastercard example payload

The following payload is an example of a Mastercard fleet collaborative authorization request body:

{
  "data": {
    "collaborativeAuthorizationRequest": {
      "id": "TRANSACTION_EVENT_ID",
      "transaction": {
        "id": "TRANSACTION_ID"
      },
      "transactionTimestamp": "2024-03-20T04:41:03.948Z",
      "paymentCard": {
        "id": "PAYMENT_CARD_ID"
      },
      "networkRetrievalReferenceNumber": "408004325699",
      "transactionAmount": {
        "value": 100,
        "currencyCode": "USD"
      },
      "settlementAmount": {
        "value": 100,
        "currencyCode": "USD"
      },
      "requestedAmount": {
        "value": 17500,
        "currencyCode": "USD"
      },
      "surchargeFee": null,
      "merchantDetails": {
        "merchantId": "merchantId",
        "category": "AUTOMATED_FUEL_DISPENSERS",
        "categoryCode": "5542",
        "countryCodeAlpha3": "USA",
        "description": "The awesomest awesome fuel dispensers of all time super deluxe",
        "name": "My Awesome Fuel",
        "address": {
          "streetAddress": "",
          "extendedAddress": "",
          "postalCode": "94105",
          "region": "CA",
          "locality": "San Francisco",
          "countryCodeAlpha3": "USA"
        }
      },
      "responseCode": "PARTIAL_AMOUNT_APPROVED",
      "avsResponseCode": "NOT_PROVIDED",
      "postalCodeResponseCode": "NOT_PROVIDED",
      "cvvResponseCode": "MATCH",
      "pointOfSaleDetails": {
        "panEntryMode": "MAGNETIC_STRIPE",
        "pinEntryMode": "PIN_ENTRY_CAPABILITY",
        "terminalAttendance": "ATTENDED",
        "isCardHolderPresent": true,
        "isCardPresent": true,
        "purchaseAmountOnlyCapable": true,
        "isRecurring": false,
        "terminalSupportsPartialApproval": true
      },
      "createdAt": "2024-03-20T04:41:03.948Z",
      "mastercardFleetData": {
        "driverId": "driverIdentifier",
        "vehicleId": "vehicleIdentifier",
        "prompts": [
          {
            "code": "BATTERY_VOLTAGE",
            "value": "500"
          },
          {
            "code": "ODOMETER",
            "value": "1000000"
          }
        ],
        "fuelProducts": [
          {
            "code": "PREMIUM_SUPER",
            "unitPrice": 1234,
            "unitPricePrecision": 3,
            "unitOfMeasure": "GALLONS",
            "quantity": 2345,
            "quantityPrecision": 3,
            "saleAmount": {
              "value": 200,
              "currencyCode": "USD"
            }
          },
          {
            "code": "PREMIUM_DIESEL_1",
            "unitPrice": 34567,
            "unitPricePrecision": 4,
            "unitOfMeasure": "GALLONS",
            "quantity": 4567,
            "quantityPrecision": 3,
            "saleAmount": {
              "value": 300,
              "currencyCode": "USD"
            }
          }
        ],
        "nonFuelProducts": [
          {
            "code": "BATTERIES",
            "unitOfMeasure": "EACH",
            "quantity": 5678,
            "quantityPrecision": 3,
            "extendedItemAmount": {
              "value": 400,
              "currencyCode": "USD"
            }
          },
          {
            "code": "VEHICLE_PARKING",
            "unitOfMeasure": "HOURS",
            "quantity": 678,
            "quantityPrecision": 2,
            "extendedItemAmount": {
              "value": 500,
              "currencyCode": "USD"
            }
          }
        ],
        "spendControlOverrideFlag": true
      },
      "__typename": "PaymentCardAuthorizationRequest"
    }
  },
  "extensions": {
    "signatureTimestamp": 1710909664039
  }
}

Simulate fleet transactions

To simulate collaborative authorization fleet data, you can use the fleet transaction simulator to simulate transactions in the Test environment. For more information, see Simulate Fleet Transactions.

Overview​

Fleet Data​

Visa​

Mastercard​

Request body​

Visa Request Example​

Mastercard example payload​

Simulate fleet transactions​