# Aggregated Transit Fare Payments source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/agg-transit-fare-pay/index.md 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. Ensure to familiarize yourself with the scheme rules and comply with all the regulations applicable to you. The Mastercard Gateway services provide support for the aggregated transit fare functionality to: * \[Process an EMV Transaction\] and \[contactless mobile\] payments from version 66 and later of the Mastercard Gateway 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 {#prerequisites} To submit aggregated transit fare transactions, you must have one of the following Merchant Category Codes: ### Mastercard {#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 {#visa} * 4111 - Local and Suburban Commuter Passenger Transportation, including Ferries * 4112 - Passenger Railways * 4131 - Bus Lines ### American Express {#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 {#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 a mobile phone or watch at the terminal. In both cases, when you submit a transaction request to the gateway, provide the payment details read from the chip in the card or mobile phone. For more information about contactless EMV versus Contactless mobile payments, see also \[Process an EMV Transaction\] and \[contactless mobile\] Payments. ### Contactless mobile payments {#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.deviceSpecificNumber` field * The DPAN expiry year and month as provided in the request in the `sourceOfFunds.provided.card.deviceSpecificExpiry.year` and `sourceOfFunds.provided.card.deviceSpecificExpiry.month` fields * The FPAN as returned by scheme in the `sourceOfFunds.provided.card.number` field, and * The FPAN expiry year and month as returned by scheme in the `sourceOfFunds.provided.card.expiry.year` and `sourceOfFunds.provided.card.expiry.month` fields. The DPAN and FPAN in the transaction response will be masked. To retrieve the full FPAN details, your payment services provider must enable you with the required privileges. Use the certificate authentication and submit `responseControls.sensitiveData`=UNMASK in the ***Retrieve*** Transaction request. ## Payment account identification {#payment-account-identification} The Gateway support for populating the Payment Account Reference (PAR) in the transaction response was added from Mastercard Gateway API version 65. For Transaction responses, RETRIEVE_TRANSACTION and RETRIEVE_ORDER: PAR is returned in the `sourceOfFunds.provided.card.paymentAccountReference` field. ## Scenarios {#scenarios} These are multiple scenarios to process the aggregated fare transit payments according to the scheme rules. ### First tap with a new card {#first-tap-with-a-new-card} #### Mastercard or American Express Card {#mastercard-or-american-express-card} Treat this scenario like the first tap within the travel period scenario. #### Visa Card {#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.amount` or `order.amount`=0 * The order currency in `order.currency` * `sourceOfFunds.provided.card.emvRequest` with valid EMV tag data from the first tap within the travel period * `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 card verification before the start of a travel period. ### Verify {#verify} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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" } } ``` Submit the request: * When a card is used for the first time. * At regular intervals to ensure that the card is still valid. * The first time a card is used after it is removed from the deny list. If the request is successful, aggregate the transit fare for this card and at the end of the travel period, submit an Authorization for the aggregated amount. If the request fails, add the card to the deny list and submit an Authorization for the fare for this trip at the end of the travel period. ### First tap within the travel period {#first-tap-within-the-travel-period} #### Mastercard or American Express Card {#mastercard-or-american-express-card-1} 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`=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 first tap within the travel period * `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 ### Authorization {#authorization} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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 {#visa-card-1} Aggregate the transit fare for this card and ensure you collect the tap data for this trip. ### Subsequent taps within the travel period {#subsequent-taps-within-the-travel-period} #### Mastercard or American Express Card {#mastercard-or-american-express-card-2} 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 {#visa-card-2} 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 {#end-of-travel-period} #### Mastercard or American Express Card {#mastercard-or-american-express-card-3} 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. ### Capture {#capture} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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 {#visa-card-3} 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. ### Authorization {#authorization-1} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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. ### Capture {#capture-1} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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 {#first-ride-risk} #### Mastercard or American Express Card {#mastercard-or-american-express-card-4} The gateway does not provide support for the Mastercard First ride risk framework yet. #### Visa Card {#visa-card-4} 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. ### Standalone Capture {#standalone-capture} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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":""} * Payment details including card number, expiration 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 {#void-authorization} Subsequently submit a Mastercard Gateway 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 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 {#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 {#mastercard-or-american-express-card-5} 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 Authorization transaction in the `transaction.id` * `transaction.transit.aggregatedFare.type`=DEBT_RECOVERY_MERCHANT_INITIATED * `transaction.transit.aggregatedFare.transportationMode` with a valid enumeration value that reflects the transportation mode that the payer uses for the first trip * `transaction.transit.aggregatedFare.aggregationStartDate` with a valid start date for the trip * `transaction.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. ### Authorization {#authorization-2} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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. ### Capture {#capture-2} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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. Do 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 {#visa-card-5} 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`=MERCHANT * `transaction.transit.aggregatedFare.type`=DEBT_RECOVERY_MERCHANT_INITIATED * `transaction.transit.aggregatedFare.transportationMode` with a valid enumeration value that reflects the transportation mode that the payer uses for the first trip * `transaction.transit.aggregatedFare.aggregationStartDate` with 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.customData` fields using the following syntax: {"VisaTransitFailedAuthTransactionIdentifier":""} * 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. ### Authorization {#authorization-3} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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. ### Capture {#capture-3} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version/100/merchant/CYG_S2I_MER2/order/{{order_id}}/transaction/{{transaction_id}} | ```json { "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 1 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 {#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 {#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 {#testing-your-integration} For information about testing your integration, contact your account representative.