Transit - Aggregated Transit Fare Payments
Aggregated transit fare provides support in scenarios where you are unaware of the final fare that will be charged at the beginning of the travel. In such scenarios, the final fare is calculated at the end of a travel period, typically 24 hours, based on journeys made during that period. This page describes the aggregated transit fare use cases and the process to submit a valid request to the gateway. Submit different requests for Mastercard and Visa cards. For American Express cards, follow the instructions provided for Mastercard. Through the aggregated transit fare payments scheme,
- you can aggregate the payer's transaction fares across the multiple trips for a certain time period and up to a certain amount, and
- you can charge flat, distance, or time-based fares for each trip within the period.
The Mastercard Gateway services provide support for the aggregated transit fare functionality for
- Process an EMV Transaction and contactless mobile payments from version 66 of the WS API
- Mastercard, excluding Maestro cards according to the Mastercard scheme rules
- Visa cards according to the Visa scheme rules, and
- American Express cards according to the Mastercard scheme rules.
Prerequisites
To submit aggregated transit fare transactions, your Merchant Category Code (MCC) must be one of the following:
Mastercard
- 4111 - Transportation-Suburban and Local Commuter Passenger, including Ferries
- 4131 - Bus Lines
- 4784 - Bridge and Road Fees, Tolls
- 7523 - Automobile Parking Lots and Garages
Visa
- 4111 - Local and Suburban Commuter Passenger Transportation, including Ferries
- 4112 - Passenger Railways
- 4131 - Bus Lines
American Express
- 4111 - Local and Suburban Commuter Passenger Transportation, including Ferries
- 4112 - Passenger Railways
- 4131 - Bus Lines
- 4784 - Tolls and Bridge Fees
- 7523 - Parking Lots and Garages
Perform an EMV certification according to the applicable scheme rules. Your payment service provider must enable you to
- submit excessive Capture transactions, and
- retrieve unmasked card numbers.
Contactless EMV versus contactless mobile payments
Support for the aggregated transit fare functionality is provided for
- Contactless EMV payments, where payers present their credit card at the terminal.
- Contactless mobile payments, where payers present their devices such as mobile phone or watch at the terminal.
Contactless mobile payments
For contactless mobile payments, you will only receive the device-specific Primary Account Number (DPAN) details and not the Funding Primary Account Number (FPAN) details from the terminal. Wherever the Authorization contains a DPAN, the transaction response will contain
- the DPAN as provided in the request in the
sourceOfFunds.provided.card.deviceSpecificNumberfield - the DPAN expiry year and month as provided in the request in the
sourceOfFunds.provided.card.deviceSpecificExpiry.yearandsourceOfFunds.provided.card.deviceSpecificExpiry.monthfields - the FPAN as returned by scheme in the
sourceOfFunds.provided.card.numberfield, and - the FPAN expiry year and month as returned by scheme in the
sourceOfFunds.provided.card.expiry.yearandsourceOfFunds.provided.card.expiry.monthfields.
responseControls.sensitiveData=UNMASK in the Retrieve Transaction request.
Payment account identification
The gateway support for populating the Payment Account Reference (PAR) in the transaction response was added from the API version 65 onward.
For Transaction responses, RETRIEVE_TRANSACTION and RETRIEVE_ORDER: PAR is returned in the sourceOfFunds.provided.card.paymentAccountReference field.
Scenarios
These are multiple scenarios to process the aggregated fare transit payments according to the scheme rules.
First tap with a new card
Mastercard or American Express Card
Treat this scenario like the First tap within the travel period scenario.
Visa Card
To verify that the card is valid, submit the Verify request with the following details.
- an identifier for the order in
order.id - an identifier unique within the order for the Verification transaction in
transaction.id - no order amount in
order.amountororder.amount=0 - the order currency in
order.currency sourceOfFunds.provided.card.emvRequestwith valid EMV tag data from the first tap within the travel periodtransaction.source=CARD_PRESENTposTerminal.attended=UNATTENDEDposTerminal.location=MERCHANT_TERMINAL_ON_PREMISESposTerminal.cardholderActivated=SELF_SERVICE_TERMINALposTerminal.inputCapability=CONTACTLESS_CHIPposTerminal.panEntryMode=CONTACTLESSposTerminal.pinEntryCapability=PIN_NOT_SUPPORTEDposTerminal.lane=99991111posTerminal.cardPresenceCapability=CARD_PRESENT
Here is the REST example for card verification before the start of a travel period.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "VERIFY",
"order": {
"amount": "0.00",
"currency": "AUD"
},
"posTerminal": {
"address": {
"country": "AUS",
"postcodeZip": "4000"
},
"attended": "UNATTENDED",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "99991111",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"5F2A": "036",
"5F34": "099",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "161021",
"9B": "0101",
"9C": "00",
"9F02": "000000010000",
"9F03": "000000000000",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "036",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F6E": "0101"
},
"expiry": {
"month": "12",
"year": "39"
},
"track2": "400555xxxxxx0019=391220xxxx06711"
}
},
"type": "CARD"
},
"transaction": {
"source": "CARD_PRESENT"
}
}
You can submit this request
- when a card is used for the first time
- at regular intervals to ensure that the card is still valid, or
- the first time a card is used after it is removed from the deny list.
First tap within the travel period
Mastercard or American Express Card
To authorize the payment for the aggregated transit fare for this card, submit the Authorization request with the following details.
- an identifier for the order in
order.id - an identifier unique within the order for the Authorization transaction in
transaction.id - a nominal amount in
order.amount - the order currency in
order.currency transaction.transit.aggregatedFare.type=FAREtransaction.transit.aggregatedFare.transportationMode with a valid enumeration value that reflects the transportation mode used by the payer for the first triptransaction.transit.aggregatedFare.aggregationStartDatewith a valid start date for the tripsourceOfFunds.provided.card.emvRequestwith valid EMV data from the first tap within the travel periodtransaction.source=CARD_PRESENTposTerminal.attended=UNATTENDEDposTerminal.location=MERCHANT_TERMINAL_ON_PREMISESposTerminal.cardholderActivated=SELF_SERVICE_TERMINALposTerminal.inputCapability=CONTACTLESS_CHIPposTerminal.panEntryMode=CONTACTLESSposTerminal.pinEntryCapability=PIN_NOT_SUPPORTEDposTerminal.lane=99991111posTerminal.cardPresenceCapability=CARD_PRESENT
Here is the REST example for a nominal Authorization to aggregate transit fares.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "1.00",
"currency": "AUD"
},
"posTerminal": {
"address": {
"country": "AUS",
"postcodeZip": "4000"
},
"attended": "UNATTENDED",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "99991111",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"5F2A": "036",
"5F34": "099",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "161021",
"9B": "0101",
"9C": "00",
"9F02": "000000010000",
"9F03": "000000000000",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "036",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F6E": "0101"
},
"expiry": {
"month": "12",
"year": "39"
},
"track2": "545721xxxxxx0012=391220xxxxx6711"
}
},
"type": "CARD"
},
"transaction": {
"source": "CARD_PRESENT",
"transit": {
"aggregatedFare": {
"type": "FARE",
"aggregationStartDate": "2020-05-05",
"transportationMode": "TRAIN"
}
}
}
"responseControls":{
"sensitiveData": "UNMASK"
}
}
If the request is successful, aggregate the transit fare for this card. If the request fails, add the card to the deny list and initiate a debt recovery for the fare for this trip.
Visa Card
Aggregate the transit fare for this card and ensure you collect the tap data for this trip.
Subsequent taps within the travel period
Mastercard or American Express Card
Add the transit fare for each trip to the aggregated transit fare for this card. At the end of the travel period, submit the Capture request for the total aggregated transit fare.
Visa Card
Add the transit fare for each trip to the aggregated transit fare for this card. At the end of the travel period, submit an Authorization for the total aggregated transit fare. Ensure you collect the tap data for each trip.
End of travel period
Mastercard or American Express Card
At the end of the travel period, you can capture the total aggregated transit fare within the travel period by submitting the Capture request with the following details.
- the order identifier of the successful Authorization in order.id
- a transaction identifier unique within the order for the Capture transaction in transaction.id
- the total aggregated transit fare for this travel period in transaction.amount, and
- the order currency same as for an Authorization intransaction.currency.
Here is the REST example for the Capture request of the aggregate transit fares.
Do not resubmit any other payment details in the Capture request as the gateway stores the payment details for each order.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "15.00",
"currency": "AUD"
}
}
Payer can use the card again within the next travel period. There are different limits to the amount that you can capture and apply depending on your country. For more information about the rules, see the Mastercard scheme rules.
Visa Card
At the end of the travel period, you can authorize the total aggregated transit fare within the travel period by submitting the Authorization request with the following details.
- an identifier for the order in field order.id - You can submit this request with the same order ID that you use for the Verify request on the first tap with this card or a new order ID.
- an identifier unique within the order for the Authorization transaction in transaction.id
- the total aggregated transit fare for this travel period in order.amount
- the currency of the order in order.currency
- transaction.transit.aggregatedFare.type=FARE
- transaction.transit.aggregatedFare.transportationMode with a valid enumeration value that reflects the transportation mode used by the payer for the first trip
- transaction.transit.aggregatedFare.aggregationStartDate with a valid start date for the trip
- sourceOfFunds.provided.card.emvRequest with valid EMV data from the last tap within the travel period
- sourceOfFunds.provided.card.sequenceNumber
- transaction.source=CARD_PRESENT
- posTerminal.attended=UNATTENDED
- posTerminal.location=MERCHANT_TERMINAL_ON_PREMISES
- posTerminal.cardholderActivated=SELF_SERVICE_TERMINAL
- posTerminal.inputCapability=CONTACTLESS_CHIP
- posTerminal.panEntryMode=CONTACTLESS
- posTerminal.pinEntryCapability=PIN_NOT_SUPPORTED
- posTerminal.lane=99991111
- posTerminal.cardPresenceCapability=CARD_PRESENT
Here is the REST example for Authorization of total aggregated transit fare.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "15.00",
"currency": "AUD"
},
"posTerminal": {
"address": {
"country": "AUS",
"postcodeZip": "4000"
},
"attended": "UNATTENDED",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "99991111",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"5F2A": "036",
"5F34": "099",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "161021",
"9B": "0101",
"9C": "00",
"9F02": "000000010000",
"9F03": "000000000000",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "036",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F6E": "0101"
},
"expiry": {
"month": "12",
"year": "39"
},
"track2": "400555xxxxxx0019=391220xxxxx6711"
}
},
"type": "CARD"
},
"transaction": {
"source": "CARD_PRESENT",
"transit": {
"aggregatedFare": {
"type": "FARE",
"aggregationStartDate": "2020-05-05",
"transportationMode": "TRAIN"
}
}
}
}
If the request is successful, submit the Capture request with the following details
- order identifier of the successful Authorization transaction in
order.id - transaction identifier unique within the order for the Capture transaction in
transaction.id - successfully authorized amount in
transaction.amount - order currency same as for Authorization in
transaction.currency
Here is the REST example for the Capture request of aggregate transit fares.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "15.00",
"currency": "AUD"
}
}
Payer can use the card again within the next travel period. If the Authorization request fails, proceed with the First ride risk scenario.
First ride risk
Mastercard or American Express Card
The gateway does not provide support for the Mastercard First ride risk framework yet.
Visa Card
At the end of the travel period wherever the Authorization is declined but is permitted to be captured under the Visa rules, submit the standalone Capture request with the following details:
- an identifier for the order in field order.id - This must be a new order.id. You cannot use the same order.id as used for the declined Authorize request.
- an identifier unique within the order for the Capture transaction in transaction.id
- the total aggregated fare amount as provided in the failed Authorization request in order.amount
- the order currency as provided in the failed Authorization request in order.currency
- transaction.transit.aggregatedFare.type=FARE
- transaction.transit.aggregatedFare.aggregationStartDate with date of first tap
- transaction.transit.aggregatedFare.transportationMode with a valid enumeration value that reflects the transportation mode used by the payer for the first trip
- sourceOfFunds.provided.card.emvRequest with valid EMV data from the last tap within the travel period
- sourceOfFunds.provided.card.sequenceNumber
- transaction.source=CARD_PRESENT
- posTerminal.attended=UNATTENDED
- posTerminal.location= MERCHANT_TERMINAL_ON_PREMISES
- posTerminal.cardholderActivated=SELF_SERVICE_TERMINAL
- posTerminal.inputCapability=CONTACTLESS_CHIP
- posTerminal.panEntryMode=CONTACTLESS
- posTerminal.pinEntryCapability=PIN_NOT_SUPPORTED
- the 15-digit numeric value returned in the failed Authorization response in authorizationResponse.transactionIdentifier in field authorizationResponse.transactionIdentifier
- the 1-letter value returned in the failed Authorization in field authorizationResponse.returnAci in field authorizationResponse.returnAci
- transaction.authorizationCode=VFT000 - This is the Authorization code that Visa defines for this specific purpose
Here is the REST example for the Standalone Capture of aggregate transit fares.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"posTerminal": {
"address": {
"country": "AUS",
"postcodeZip": "4000"
},
"attended": "UNATTENDED",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "teapost",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"5F2A": "036",
"5F34": "099",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "161021",
"9B": "0101",
"9C": "00",
"9F02": "000000010000",
"9F03": "000000000000",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "036",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F6E": "0101"
},
"expiry": {
"month": "05",
"year": "25"
},
"track2": "400555xxxxxx0019=391220116006711"
}
},
"type": "CARD"
},
"transaction": {
"amount": "8.00",
"currency": "AUD",
"source": "CARD_PRESENT",
"authorizationCode": "VFT000",
"transit": {
"aggregatedFare": {
"type": "FARE",
"aggregationStartDate": "2022-05-05",
"transportationMode": "TRAIN"
}
}
},
"authorizationResponse": {
"transactionIdentifier": "140929101914398",
"returnAci": "Y"
}
}
The Capture of a failed Authorization is permitted under the Visa rules if the:
- issuer has declined the first Authorization request for this card
- issuer has declined the first Authorization request for this card since the previous successful Authorization for an aggregated transit fare, and
- the transaction amount is less than or equal to the chargeback threshold of your country.
After you have submitted the Capture request, the card will still be on the deny list. You can use merchant-initiated debt recovery to determine if the card has returned to good standing and therefore should be removed from the deny list. Submit the Authorization request on a new order with the following details:
- order.id - This must be a new order.id
- transaction.id
- order.amount - This must be the same amount as the one in the standalone Capture
- the currency in field order.currency
- transaction.transit.aggregatedFare.type=DEBT_RECOVERY_MERCHANT_INITIATED
- transaction.transit.aggregatedFare.transportationMode (mandatory) with a valid enumeration value
- transaction.source=MERCHANT
- transaction.transit.aggregatedFare.aggregationStartDate (mandatory) with date of first tap
- 15-digit numeric value returned in the failed Authorization response in the fields authorizationResponse.transactionIdentifier and transaction.acquirer.customData using the following syntax:{"VisaTransitFailedAuthTransactionIdentifier":"<value>"}
- payment details including card number, expiry date, and so on.
If the Authorization request is successful, you must remove the card from the deny list within an hour and immediately void the Authorization.
Void Authorization
You must subsequently submit a WS API VOID request on a same order as the one for the successful Authorization with:
- order.id- This must be the order.id of the successful Authorization
- transaction.id - This must be a new transaction ID on the order
- transaction.targetTransactionId - This must be the transaction.id of the the successful Authorization
You can repeat the Authorization request up to the allowed attempts count or frequency for the merchant-initiated debt recovery requests. For more information about the merchant-initiated debt recovery, see the Debt Recovery scenario below. The issuer is liable for the standalone Capture request. This means that a successful Capture does not indicate that the payer's account is in good standing and the card can be removed from the deny list.
Merchant-initiated debt recovery
The schemes allow you to attempt to recover outstanding debts for transit fares without involving the payer. A successful debt recovery will enable the card to be accepted for travel again once the payer's account returns to good standing.
To submit debt recovery transactions, provide the payment details that a payer uses.
- Contactless EMV payment: Provide the FPAN details.
- Contactless mobile payment:
- For Mastercard: Provide the FPAN details. The gateway will provide the FPAN details in the transaction response to the original transaction.
- For the Visa card: Provide the DPAN details. Ensure to store these details as the gateway does not allow you to retrieve them.
Mastercard or American Express card
If the Authorization that you had submitted for the first trip within the travel period fails, then you can attempt to recover the total fare for this trip inline with the applicable Mastercard scheme rules. Submit an Authorization request with the following details:
- an identifier for the order in
order.id- This must be a new order.id. It cannot be the same order.id as used for the VERIFY request, declined AUTHORIZE request, or CAPTURE request. - an identifier unique within the order for the
Authorizationtransaction in thetransaction.id transaction.transit.aggregatedFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDtransaction.transit.aggregatedFare.transportationModewith a valid enumeration value that reflects the transportation mode that the payer uses for the first triptransaction.transit.aggregatedFare.aggregationStartDatewith a valid start date for the triptransaction.source=MERCHANT- the payment details including the FPAN and FPAN expiry
Here is the REST example for the Authorization of aggregate transit fares for debt recovery.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "15.00",
"currency": "AUD"
},
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "12",
"year": "39"
},
"number": "512345xxxxxx1234",
"sequenceNumber": "099"
}
},
"type": "CARD"
},
"transaction": {
"source": "MERCHANT",
"transit": {
"aggregatedFare": {
"type": "DEBT_RECOVERY_MERCHANT_INITIATED",
"aggregationStartDate": "2020-05-05",
"transportationMode": "TRAIN"
}
}
}
}
If the request is successful, submit the Capture request with the following details:
- the order identifier of the successful Authorization transaction in order.id
- a transaction identifier unique within the order for the Capture transaction in transaction.id
- the successfully authorized amount in transaction.amount
- the order currency same as for the Authorization in transaction.currency
Here is the REST example for the Capture of aggregate transit fares for debt recovery.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "15.00",
"currency": "AUD"
}
}
After the debt is recovered successfully, remove the card from the deny list. The Authorization for the debt recovery will only be successful if payers have sufficient funds in their account. Issuers are not assuming liability for the debt recovery transactions. If the Authorization request fails, you can reattempt the debt recovery inline with the applicable Mastercard scheme rules. Mastercard defines the allowed amount for the debt recovery transaction and the frequency of the debt recovery attempts. The allowed amount must be less than or equal to the contactless transit aggregated transaction ceiling limit that Mastercard defines. You must not attempt a debt recovery if you have sufficient information to determine that the Authorization for the first trip in the travel period was declined because of the lost or stolen card, that is a hard decline. You cannot recover the funds if the card is lost or stolen; that is a hard decline or all the allowed attempts for the debt recovery have failed.
Visa Card
If you have not submitted the standalone Capture request, you can attempt to recover the fare inline with the applicable Visa scheme rules. For more information about the first declined transaction on the Visa Contactless card up to a defined Mobility and Transport Transaction shared liability limit, see the First Ride Risk scenario.
Submit the Authorization request with the following details:
- an identifier for the order in order.id -This must be a new order.id. It cannot be the same order.id as used for the VERIFY request, declined AUTHORIZE request, or CAPTURE request
- an identifier unique within the order for this Authorization transaction in
transaction.id transaction.source=MERCHANTtransaction.transit.aggregatedFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDtransaction.transit.aggregatedFare.transportationModewith a valid enumeration value that reflects the transportation mode that the payer uses for the first triptransaction.transit.aggregatedFare.aggregationStartDatewith a valid start date for the trip- the 15-digit numeric value returned in the failed Authorization response in the
authorizationResponse.transactionIdentifier and the transaction.acquirer.customDatafields using the following syntax: {"VisaTransitFailedAuthTransactionIdentifier":"<value>"} - the payment details including either the FPAN and FPAN expiry where the original transaction was a contactless EMV payment or the DPAN and DPAN expiry where the original transaction was a contactless mobile payment
Here is the REST example for the Authorization of aggregate transit fares for debt recovery.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "15.00",
"currency": "AUD"
},
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "12",
"year": "39"
},
"number": "400555xxxxxx0019",
"sequenceNumber": "099"
}
},
"type": "CARD"
},
"transaction": {
"source": "MERCHANT",
"transit": {
"aggregatedFare": {
"type": "DEBT_RECOVERY_MERCHANT_INITIATED",
"aggregationStartDate": "2020-05-05",
"transportationMode": "TRAIN"
}
}
}
}
If the request is successful, submit the Capture request with the following details:
- the order identifier of the successful Authorization transaction in
order.id - a transaction identifier that is unique within the order for the Capture transaction in
transaction.id - the successfully authorized amount in
transaction.amount - the order currency that is same as for the Authorization in
transaction.currency
Here is the REST example for the Capture of aggregate transit fares for debt recovery.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/66/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "15.00",
"currency": "AUD"
}
}
After the debt is recovered successfully, according to the Visa rules, you must remove the card from the deny list within one hour from the time you received the Authorization approval. If the Authorization request fails, you can reattempt the debt recovery inline with the applicable Visa scheme rules. Visa defines the allowed number of debt recovery attempts.
Payer-initiated debt recovery
This scenario is applicable for Mastercard, Visa, and American Express. For the payer-initiated debt recovery payments, you must not submit any fields in the transaction. transit parameter group. Payer-initiated debt recovery transaction will be treated like a normal transaction in which the payer makes a purchase with the merchant.
Tap-initiated debt recovery
This scenario is applicable for Mastercard, Visa, and American Express.
For the tap-initiated debt recovery payments, you must not submit any fields in the transaction.transit parameter group. Tap-initiated debt recovery transaction will be treated like a normal transaction in which the payer makes a purchase with the merchant.
Testing your integration
For information about testing your integration, contact your account representative.