# Aggregated Transit Rules in the North America Region source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/aggtrn-transit-rules-nam/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 within 24 hours, based on the journeys made during that time. You can charge flat, distance-based, 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. ## Supported schemes {#supported-schemes} The aggregated transit rules in the North American Region support the following card schemes: * Mastercard * Visa * American Express * Discover * Diners ## API version and parameters {#api-version-and-parameters} Mastercard Gateway supports transit aggregation from version 100 onwards of the Gateway Direct API for Mastercard, Visa, American Express, Discover, and Diners scheme rules processing in the North American Region. ### posTerminal parameters {#posterminal-parameters} This table describes the most common **posTerminal** parameters. | Gateway Direct 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. | Gateway Direct API Field | Value | |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | .type | * FARE * DEBT_RECOVERY_MERCHANT_INITIATED * DEBT_RECOVERY_PAYER_INITIATED * DEBT_RECOVERY_TAP_INITIATED ([Standalone Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction)) | | .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 | ## 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/aggtrn-transit-rules-nam/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/aggtrn-transit-rules-nam/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/aggtrn-transit-rules-nam/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/aggtrn-transit-rules-nam/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/aggtrn-transit-rules-nam/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 Visa {#mastercard-and-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 * `sourceOfFunds.provided.card.expiry` * `sourceOfFunds.provided.card.expiry.month` * `sourceOfFunds.provided.card.expiry.year` * `sourceOfFunds.provided.card.number` * `sourceOfFunds.type` - CARD * `transaction.source` - CARD_PRESENT * `posTerminal.attended` - UNATTENDED * `posTerminal.cardholderActivated` - NOT_CARDHOLDER_ACTIVATED * `posTerminal.location` - MERCHANT_TERMINAL_ON_PREMISES * `posTerminal.panEntryMode` - CONTACTLESS * `posTerminal.inputCapability` - CONTACTLESS_CHIP * `posTerminal.lane` * `posTerminal.pinEntryCapability` - PIN_NOT_SUPPORTED For a declined response: * Add to Deny List ### American Express, Discover, and Diners {#american-express-discover-and-diners} [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 * `sourceOfFunds.provided.card.expiry` * `sourceOfFunds.provided.card.expiry.month` * `sourceOfFunds.provided.card.expiry.year` * `sourceOfFunds.provided.card.number` * `sourceOfFunds.type` - CARD * `transaction.source` - CARD_PRESENT * `transaction.transit.aggregatedFare.type` = FARE * `posTerminal.attended` - UNATTENDED * `posTerminal.cardholderActivated` - NOT_CARDHOLDER_ACTIVATED * `posTerminal.location` - MERCHANT_TERMINAL_ON_PREMISES * `posTerminal.panEntryMode` - CONTACTLESS * `posTerminal.inputCapability` - CONTACTLESS_CHIP * `posTerminal.lane` * `posTerminal.pinEntryCapability` - PIN_NOT_SUPPORTED For a declined response: * Add to Deny List ## Subsequent taps within the travel period {#subsequent-taps-within-the-travel-period} ### Mastercard, Visa, American Express, Discover, and Diners {#mastercard-visa-american-express-discover-and-diners} 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, Visa, American Express, Discover, and Diners {#mastercard-visa-american-express-discover-and-diners-1} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - This is either the same as in VERIFY or a new value. * `transaction.id` - Unique value * `transaction.transit.aggregatedFare.type` * `transaction.transit.aggregatedFare.aggregationStartDate` * `transaction.transit.aggregatedFare.transportationMode` * `posTerminal.address.country` * `sourceOfFunds.provided.card.emvRequest` with valid EMV tag data * Containing all the mandatory for transaction processing emv tags * `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, Visa, American Express, Discover, and Diners {#mastercard-visa-american-express-discover-and-diners-2} If the [Standalone Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request is not submitted in line with the First Ride Risk rules, you can attempt to recover the online fare within the applicable scheme rules. [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) * `order.id` - This is a new value * `transaction.id` - Unique value * `referenceOrderId` - Unique reference id of the previous failed auth transaction * `transaction.resubmission` - True * `transaction.source` - MERCHANT * `transaction.amount` - xx.xx * `transaction.currency` * `transaction.transit.aggregatedFare.type` - DEBT_RECOVERY_MERCHANT_INITIATED * `type`=DEBT_RECOVERY_MERCHANT_INITIATED * `aggregationStartDate` - The valid trip start date * `transportationMode`= - The 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, the cards should be removed from the deny list in a timely manner. 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 scheme rules. ***Capture*** * `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, Visa, American Express, Discover, and Diners {#mastercard-visa-american-express-discover-and-diners-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 is successful, the cards should be removed from the deny list in a timely manner. ### Visa {#visa} [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) `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. ## First Ride Risk {#first-ride-risk} For more details about the First Ride Risk, see the [First Ride Risk](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/first-ride-risk/index.md) section. ## 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 Mastercard Gateway record | 6220 6221 6225 6271 6290 | | 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 | ### Refer the following for WS API examples of various scheme's aggregation use cases: {#refer-the-following-for-ws-api-examples-of-various-schemes-aggregation-use-cases} * [WS API examples of Mastercard and Visa](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/aggtrn-transit-rules-nam/wsapi-visa-mastercard-examples/index.md) * [WS API examples of American Express](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/aggtrn-transit-rules-nam/wsapi-amex-examples/index.md) * [WS API examples of Discover and Diners](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/aggtrn-transit-rules-nam/wsapi-discover-diners-examples/index.md)