# Aggregated Transit Rules source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md ## Overview {#overview} The aggregation model is designed for situations where the final fare is not known at the time of travel. Instead, the fare is calculated at the end of a predefined travel period, typically 24 hours, based on the journeys made during that period. You can charge flat, distance, or time-based fares for each trip within the travel period. Ensure to familiarize yourself with the scheme rules and comply with all the requirements. ## API version and parameters {#api-version-and-parameters} Mastercard Gateway supports transit aggregation from Mastercard Gateway API version 66 and later. ### posTerminal parameters {#posterminal-parameters} This table describes the most common **posTerminal** parameters. | Mastercard Gateway API Field | Value | |------------------------------|--------------------------------------------------------------------------------------------------| | cardPresenceCapability | CARD_PRESENT | | Attended | UNATTENDED | | cardholderActivated | NOT_CARDHOLDER_ACTIVATED | | Location | MERCHANT_TERMINAL_ON_PREMISES | | Lane | Use a unique Terminal ID for the device. Do not use a fixed Terminal ID value across the estate. | | inputCapability | CONTACTLESS_CHIP | | pinEntry capability | PIN_NOT_SUPPORTED | | panEntryMode | CONTACTLESS | | onlineReasonCode | N/A | ### transaction.transit.aggregatedFare parameter group {#transactiontransitaggregatedfare-parameter-group} Additionally, the `transaction.transit.aggregatedFare` is required for aggregation. | Mastercard Gateway API Field | Value | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | .type | * FARE * DEBT_RECOVERY_MERCHANT_INITIATED * DEBT_RECOVERY_PAYER_INITIATED * DEBT_RECOVERY_TAP_INITIATED | | .aggregationStartDate | `` of first trip yyyy-mm-dd | | .transportationMode | CABLE_CAR * COACH * COMMUTER_TRAIN * EXPRESS_COMMUTER_TRAIN * FUNICULAR_TRAIN * HIGH_SPEED_TRAIN * INTERURBAN_ BUS * INTER_CITY * LIGHT_TRAIN_MASS_TRANSIT * LOCOMOTIVE * OTHER * PARA_TRANSIT * PARKING * POWERED_MOTOR_VEHICLE * REGIONAL_TRAIN * RURAL_BUS * SELF_DRIVE_VEHICLE * TAXI * TOLL * TRAILER * TRAIN * URBAN_BUS * WATER_BORNE_VEHICLE | ## Prerequisites {#prerequisites} Your payment service provider must enable you to: * Submit excessive [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) transactions. * Retrieve unmasked card numbers. ## Aggregation use cases {#aggregation-use-cases} The use cases for aggregated transit fare payments are: * [First tap within the travel period](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#first-tap-within-travel-period) * [Subsequent taps within the travel period](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#subsequent-taps-within-the-travel-period) * [End of travel period](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#end-of-travel-period) * [Merchant initiated debt recovery](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#merchant-initiated-debt-recovery) * [Payer or tap initiated debt recovery](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#payer-or-tap-initiated-debt-recovery) ### API Requests for Aggregated Fare in Transit Transactions {#api-requests-for-aggregated-fare-in-transit-transactions} API requests include the `transaction.transit.aggregatedFare` parameter, consisting of: * type * aggregationStartDate * transportationMode The API request type and values for each use case are tailored to align with the specific scheme requirements as detailed in the following sections. The posTerminal parameters detailed are the same for each aggregation use case. ## First tap within travel period {#first-tap-within-travel-period} ### Mastercard and Amex {#mastercard-and-amex} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` * `order.amount` - The nominal amount agreed with acquirer * `order.currency` * `order.certainty`=ESTIMATED * `transaction.id` - Unique value * `transaction.transit.aggregatedFare` * type - FARE * aggregationStartDate - yyyy/mm/dd * transportationMode - See the options in [.transportationMode](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/agg-transit-rules/index.md#transactiontransitaggregatedfare-parameter-group) * `sourceOfFunds.provided.card.emvRequest` with valid EMV tag data For a declined response: * Add to Deny List ### Visa {#visa} [Verify](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` * `order.amount` - 0.00 * `order.currency` * `transaction.id` - Unique value * `sourceOfFunds.provided.card.emvRequest` with valid EMV tag data For a declined response: * Add to Deny List ## Subsequent taps within the travel period {#subsequent-taps-within-the-travel-period} ### Mastercard, Amex, and Visa {#mastercard-amex-and-visa} Automated Fare Collection (AFC) tracks the aggregated fare for the card covering each journey. No gateway request is required. ## End of travel period {#end-of-travel-period} ### Mastercard and Amex {#mastercard-and-amex-1} [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) for successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) requests * order.id - Of the successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * transaction.id - Unique value * transaction.amount - The total aggregated fare * transaction.currency - Same as the successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) Warning: Do not resubmit any other payment details in the [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request as the gateway stores the payment details for each order. ### Visa {#visa-1} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - New value * `transaction.id` - Unique value * `transaction.transit.aggregatedFare.type` * `transaction.transit.aggregatedFare.aggregationStartDate` * `transaction.transit.aggregatedFare.transportationMode` * `sourceOfFunds.provided.card.emvRequest` with valid EMV tag data * `sourceOfFunds.provided.card.sequenceNumber` [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) for successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) requests * `order.id` - Of the successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) transaction * `transaction.id` - Unique value for the [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.amount` - Same as the successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.currency` - Same as the successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) Warning: Do not resubmit any other payment details in the [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request as the gateway stores the payment details for each order. ## Merchant initiated debt recovery {#merchant-initiated-debt-recovery} ### Mastercard and Amex {#mastercard-and-amex-2} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - New value * `transaction.id` - Unique value * `transaction.source` - MERCHANT * `transaction.amount` - xx.xx * `transaction.currency` * `transaction.transit.aggregatedFare` * `type`=DEBT_RECOVERY_MERCHANT_INITIATED * `aggregationStartDate` - Valid trip start date * `transportationMode` - Valid transportation mode used for the first trip If the [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) is successful, cards should be removed from the deny list in a timely manner. [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - Same as successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.id` - Unique value * `transaction.amount` - Same as [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.currency` - Same as [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) ### Visa {#visa-2} If the standalone [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request has not been submitted, you can attempt to recover the fare online within the applicable Visa rules. [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - New value * `transaction.id` - Unique value * `transaction.source` - MERCHANT * `transaction.amount` - xx.xx * `transaction.currency` * `transaction.transit.aggregatedFare` * `type`=DEBT_RECOVERY_MERCHANT_INITIATED * `aggregationStartDate` - Valid trip start date * `transportationMode`= - Valid transportation mode used for the first trip * `transaction.acquirer.customData`= uses the syntax: {"VisaTransitFailedAuthTransactionIdentifier":""} or provide `referenceOrderId` of the original order with failed authorization. If the [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) is successful, Visa rules state that the card must be removed from the deny list within 1 hour from the time authorization approval is received. If the debt recovery [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request fails, additional requests can be made as long as they do not exceed the number permitted within Visa rules. [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - Same as successful [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.id` - Unique value * `transaction.amount` - Same as [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `transaction.currency` - Same as [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) ## Payer or tap initiated debt recovery {#payer-or-tap-initiated-debt-recovery} ### Mastercard and Amex {#mastercard-and-amex-3} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) `transaction.transit.aggregatedFare` fields are required. If the [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) is successful, the cards should be removed from the deny list in a timely manner. ### Visa {#visa-3} Authorize `transaction.transit.aggregatedFare` fields are required. After the debt is recovered successfully, the Visa rules state that the card must be removed from the deny list within 1 hour from the time authorization approval is received. If the debt recovery [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request fails, additional requests can be made as long as they do not exceed the number permitted within the Visa rules. ## Aggregation clearing requirements {#aggregation-clearing-requirements} Clearing data, for transactions processed by the gateway, is provided in a Draft Capture File (DCF). The acquirers must ensure that their processing platform is able to process the card present data. The DCF specification document version 4.3.6 or later details the required records and fields. | Purpose | Record type | |--------------------------------------------------------------------------|---------------------| | All schemes: Mandatory 1 Mandatory 2 EMV Data Record 1 EMV Data Record 2 | 6220 6221 6225 6271 | | Mastercard only | 6222 | | Visa only | 6223 | ### Transit solutions-specific requirements {#transit-solutions-specific-requirements} This table describes the requirements of transit solutions. | Description | DCF Record, Field, and Position | Mastercard Integrated Product Messages (IPM) or Visa Base II | |----------------------------------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------| | Mastercard Transit Transaction Type Indicator DE48 SE64 SF1 | 6222, Field 11, Pos. 64-65 | PDS 0210 -- SF 1 * 02 Real-time Authorized * 03 Post-Authorized Aggregated * 07 Debt Recovery | | Mastercard Transit Transportation Mode Indicator DE48 SE64 SF2 | 6222, Field 12, Pos. 66-67 | PDS 0210 -- SF 2 | | Visa Date of First Tap in the travel period | 6223, Field 16, Pos. 85-90 | TCR0 Pos. 58-61 |