Aggregated Transit Rules in the North American Region
Overview
Use the aggregation model when the final fare is not known at the time of travel. 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.
Familiarize yourself with the scheme rules and comply with all the requirements.
Supported schemes
The aggregated transit rules in the North American region support these card schemes:
- Mastercard
- Visa
- American Express
- Discover
- Diners
API version and parameters
Mastercard Gateway supports transit aggregation from version 100 onward of the Gateway API. This applies to the Mastercard, Visa, American Express, Discover, and Diners scheme rules in the North American region.
posTerminal parameters
This table describes the most common posTerminal parameters.
| 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 each device.
Do not use the same terminal ID value across the estate. |
inputCapability |
CONTACTLESS_CHIP |
pinEntryCapability |
PIN_NOT_SUPPORTED |
panEntryMode |
CONTACTLESS |
| onlineReasonCode | N/A |
transaction.transit.aggregatedFare parameter group
Aggregation also requires the transaction.transit.aggregatedFare parameter group.
This table describes the transaction.transit.aggregatedFare parameters.
| Gateway API field | Value |
|---|---|
.type |
|
.aggregationStartDate |
Date of the first trip, in yyyy-mm-dd format |
.transportationMode |
|
Aggregation use cases
The use cases for aggregated transit fare payments are:
- First tap within the travel period
- Subsequent taps within the travel period
- End of travel period
- Merchant initiated debt recovery
- Payer or tap initiated debt recovery
API requests for aggregated fare in transit transactions
The transaction.transit.aggregatedFare parameter group in an API request contains the
type, aggregationStartDate, and transportationMode fields.
The API request type and values for each use case align with the specific scheme requirements.
The posTerminal parameters are the same for each aggregation use case.
First tap within the travel period
This applies to Mastercard, Visa, and American Express cardholders.
Mastercard and Visa
Submit a Verify request with these fields:
order.idorder.amount- 0.00order.currencytransaction.id- Unique valuesourceOfFunds.provided.card.emvRequestwith valid EMV® tag datasourceOfFunds.provided.card.expirysourceOfFunds.provided.card.expiry.monthsourceOfFunds.provided.card.expiry.yearsourceOfFunds.provided.card.numbersourceOfFunds.type- CARDtransaction.source- CARD_PRESENTposTerminal.attended- UNATTENDEDposTerminal.cardholderActivated- NOT_CARDHOLDER_ACTIVATEDposTerminal.location- MERCHANT_TERMINAL_ON_PREMISESposTerminal.panEntryMode- CONTACTLESSposTerminal.inputCapability- CONTACTLESS_CHIPposTerminal.laneposTerminal.pinEntryCapability- PIN_NOT_SUPPORTED
For a declined response, add the card to the deny list.
American Express
Submit a Verify request with these fields:
order.idorder.amount- 0.00order.currencytransaction.id- Unique valuesourceOfFunds.provided.card.emvRequestwith valid EMV tag datasourceOfFunds.provided.card.expirysourceOfFunds.provided.card.expiry.monthsourceOfFunds.provided.card.expiry.yearsourceOfFunds.provided.card.numbersourceOfFunds.type- CARDtransaction.source- CARD_PRESENTposTerminal.attended- UNATTENDEDposTerminal.cardholderActivated- NOT_CARDHOLDER_ACTIVATEDposTerminal.location- MERCHANT_TERMINAL_ON_PREMISESposTerminal.panEntryMode- CONTACTLESSposTerminal.inputCapability- CONTACTLESS_CHIPposTerminal.laneposTerminal.pinEntryCapability- PIN_NOT_SUPPORTEDtransaction.transit.aggregatedFare.type- FARE, which is required for American Express
For a declined response, add the card to the deny list.
Discover and Diners
Submit an Authorize request with these fields:
order.idorder.amount- The nominal amount agreed with the acquirerorder.currencyorder.certainty- ESTIMATEDtransaction.id- Unique valuetransaction.transit.aggregatedFare.type- FAREtransaction.transit.aggregatedFare.aggregationStartDate- yyyy-mm-ddtransaction.transit.aggregatedFare.transportationMode- Refer to the transportationMode valuessourceOfFunds.provided.card.emvRequestwith valid EMV tag data
For a declined response, add the card to the deny list.
Subsequent taps within the travel period
Mastercard, Visa, American Express, Discover, and Diners
Automated fare collection tracks the aggregated fare for the card covering each journey.
No gateway request is required.
End of travel period
Mastercard, Visa, and American Express
Submit an Authorize request with these fields:
order.id- Either the same value as in the Verify request or a new valuetransaction.id- Unique valuetransaction.transit.aggregatedFare.typetransaction.transit.aggregatedFare.aggregationStartDatetransaction.transit.aggregatedFare.transportationModeposTerminal.address.countrysourceOfFunds.provided.card.emvRequestwith valid EMV tag data, including all the EMV tags that are mandatory for transaction processingsourceOfFunds.provided.card.sequenceNumber
Submit a Capture request for successful Authorize requests with these fields:
order.id- Of the successful Authorize transactiontransaction.id- Unique value for the Capturetransaction.amount- Same as the successful Authorizetransaction.currency- Same as the successful Authorize
Discover and Diners
Submit a Capture request for successful Authorize requests with these fields:
order.id- Of the successful Authorizetransaction.id- Unique valuetransaction.amount- The total aggregated faretransaction.currency- Same as the successful Authorize
Merchant initiated debt recovery
Mastercard, Visa, American Express, Discover, and Diners
If the Standalone Capture 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.
Submit an Authorize request with these fields:
order.id- A new valuetransaction.id- Unique valuereferenceOrderId- The unique reference ID of the previous failed authorization transactiontransaction.resubmission- TRUEtransaction.source- MERCHANTtransaction.amount- xx.xxtransaction.currencytransaction.transit.aggregatedFare.type- DEBT_RECOVERY_MERCHANT_INITIATEDaggregationStartDate- The valid trip start datetransportationMode- The valid transportation mode used for the first trip
If the Authorize request is successful, remove the card from the deny list promptly.
If the debt recovery Authorize request fails, you can submit additional requests as long as they do not exceed the number permitted within the scheme rules.
Submit a Capture request with these fields:
order.id- Same as successful Authorizetransaction.id- Unique valuetransaction.amount- Same as Authorizetransaction.currency- Same as Authorize
Payer or tap initiated debt recovery
Mastercard, Visa, American Express, Discover, and Diners
Submit an Authorize
request. The transaction.transit.aggregatedFare fields are required.
If the Authorize request is successful, remove the card from the deny list promptly.
Visa
Submit an Authorize
request. The transaction.transit.aggregatedFare fields are required.
After the debt is recovered successfully, the Visa rules state that you must remove the card from the deny list within 1 hour of receiving the authorization approval.
If the debt recovery Authorize request fails, you can submit additional requests as long as they do not exceed the number permitted within the Visa rules.
First ride risk
Refer to First ride risk for more details about the first ride risk rules.
Aggregation clearing requirements
The gateway provides clearing data for processed transactions in a Draft Capture File (DCF). Acquirers must ensure that their processing platform can process the card present data.
The DCF specification document version 4.3.6 or later details the required records and fields.
This table describes the record types required for each scheme.
| 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
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
|
|
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 |
| Visa
Mastercard Gateway record 6290 Transit transaction type indicator DE 48 SE64 SF1 |
6290, Field 9, Pos. 127-128 | |
| Visa
Mastercard Gateway record 6290 Transit transportation mode indicator DE 48 SE64 SF2 |
6290, Field 10, Pos. 129-130 |
Gateway API examples
Refer to these topics for Gateway API examples of the aggregation use cases for each scheme: