Aggregated Transit
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
Mastercard Gateway supports transit aggregation from version 66 onwards of the WS API.
posTerminal parameters
This table describes the most common posTerminal parameters.
WS API Field | Value |
---|---|
cardPresenceCapability | CARD_PRESENT |
Attended | UNATTENDED |
cardholderActivated | SELF_SERVICE_TERMINAL |
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 |
transaction.transit.aggregatedFare parameter group
Additionally, the transaction.transit.aggregatedFare
is required for aggregation.
WS API Field | Value |
---|---|
.type |
|
.aggregationStartDate |
<Date> of first trip yyyy-mm-dd |
.transportationMode |
|
Prerequisites
Your payment service provider must enable you to:
- Submit excessive Capture transactions.
- Retrieve unmasked card numbers.
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
API requests require the inclusion of 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 later will be the same for each aggregation use case.
First tap within travel period
Mastercard and Amex
order.id
order.amount
(nominal amount agreed with acquirer)order.currency
transaction.id
(unique value)transaction.transit.aggregatedFare
type=FARE
aggregationStartDate=yyyy/mm/dd
transportationMode=
(see options in .transportationMode)
sourceOfFunds.provided.card.emvRequest
with valid EMV tag data
For a declined response:
- Add to Deny List
Visa
VERIFY
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
Mastercard, Amex, and Visa
AFC tracks the aggregated fare for the card covering each journey.
No gateway request is required.
End of travel period
Mastercard and Amex
Capture for successful Authorize requests
order.id
- of the successful Authorizetransaction.id
- unique valuetransaction.amount
- the total aggregated faretransaction.currency
- same as the successful Authorize
Visa
order.id
(either the same as in VERIFY or a new one)transaction.id
(unique value)transaction.transit.aggregatedFare.type
transaction.transit.aggregatedFare.aggregationStartDate
transaction.transit.aggregatedFare.transportationMode
sourceOfFunds.provided.card.emvRequest
with valid EMV tag datasourceOfFunds.provided.card.sequenceNumber
Capture for successful Authorize requests
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
Merchant initiated debt recovery
Mastercard and Amex
order.id
- This is a new valuetransaction.id
- unique valuetransaction.source=MERCHANT
transaction.amount=xx.xx
transaction.currency
transaction.transit.aggregatedFare
type=DEBT_RECOVERY_MERCHANT_INITIATED
aggregationStartDate
- valid trip start datetransportationMode=
- valid transportation mode used for the first trip
If the Authorize is successful, cards should be removed from the deny list in a timely manner.
order.id
- same as successful Authorizetransaction.id
- unique valuetransaction.amount
- same as Authorizetransaction.currency
- same as Authorize
Visa
If the standalone Capture request has not been submitted, you can attempt to recover the fare online within the applicable Visa rules.
order.id
- must be a new valuetransaction.id
- unique valuetransaction.source=MERCHANT
transaction.amount=xx.xx
transaction.currency
transaction.transit.aggregatedFare.
type=DEBT_RECOVERY_MERCHANT_INITIATED
aggregationStartDate
- valid trip start datetransportationMode=
- valid transportation mode used for the first trip
If the Authorize 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 request fails, additional requests can be made as long as they do not exceed the number permitted within Visa rules.
order.id
- same as successful Authorizetransaction.id
- unique valuetransaction.amount
same as Authorizetransaction.currency
- same as Authorize
Payer or tap initiated debt recovery
Mastercard and Amex
transaction.transit.aggregatedFare
fields not required.
If the Authorize is successful, cards should be removed from the deny list in a timely manner.
Visa
transaction.transit.aggregatedFare
fields not required.
After the debt is recovered successfully, 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 Authorizerequest fails, additional requests can be made as long as they do not exceed the number permitted within Visa rules.
Aggregation Clearing Requirements
Clearing data, for transactions processed by the gateway, is provided in a Draft Capture File (DCF). 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 records and fields required.
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 specifically require:
Description | DCF Record, Field/Position | Mastercard IPM/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 |