First Ride Risk
WS API support
- For Mastercard, First Ride Risk support is available from the version 85 onwards of the WS API.
- For Visa, First Ride Risk support is available from the version 40 onwards of the WS API.
Mastercard
According to Mastercard First Ride Risk rules, a Capture is submitted for a declined Authorization if:
- The issuer declines the first Authorization request since the previous successful authorization for an aggregated or known fare.
- The transaction amount is less than equal to the chargeback threshold of the country.
Capture for a declined Authorize
- An identifier for the order in the field
order.id- This is a neworder.id. You cannot use the sameorder.idas used for the declined Authorize request. - An unique identifier 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=FIRST_RIDE_RISKortransaction.transit.knownFare.type=FIRST_RIDE_RISKtransaction.transit.aggregatedFare.aggregationStartDatewith the date of first tap.transaction.transit.aggregatedFare.transportationModewith a valid enumeration value that reflects the transportation mode used by the payer for the first trip.sourceOfFunds.provided.card.emvRequestwith a valid EMV data from the failed auth transaction.sourceOfFunds.provided.card.sequenceNumbertransaction.source=CARD_PRESENTposTerminal.attended=UNATTENDEDposTerminal.location= MERCHANT_TERMINAL_ON_PREMISESposTerminal.cardholderActivated=NOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability=CONTACTLESS_CHIPposTerminal.panEntryMode=CONTACTLESSposTerminal.pinEntryCapability=PIN_NOT_SUPPORTEDauthorizationResponse.datewith a valid settlement date returned in the failed auth transaction response.authorizationResponse.financialNetworkCodewith a valid financial network code.authorizationResponse.transactionIdentifiera numeric value returned in the failed authorization response.
The startDate and transportationMode must reflect those used for the first tap.
After the Capture is submitted, the card still remains on the deny list.
Merchant initiated debt recovery determines if the card has returned to good standing and should be removed from the deny list.
To check if the card has returned to good standing and can be removed from the deny list, you can submit an Authorize request for the amount of the Capture. If the Authorize request is approved, the card should be removed from the deny list and the authorization should be voided.
Void
Submit a Void request on the same order as the one for the successful Authorize.
order.idsame as successful Authorize.transaction.idUnique value.transaction.target.TransactionIDsame as successful Authorize.
Standalone Capture - Mastercard
At the end of the travel period, wherever the Authorization is declined but is permitted to be captured within Mastercard Scheme rules. Submit the standalone capture request with the following details:
- An identifier for the order in the field
order.id- This is a neworder.id. You cannot use the sameorder.idas used for the declined Authorize request. - An unique identifier 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=FIRST_RIDE_RISKortransaction.transit.knownFare.type=FIRST_RIDE_RISKtransaction.transit.aggregatedFare.aggregationStartDatewith the date of first tap.transaction.transit.aggregatedFare.transportationModewith a valid enumeration value that reflects the transportation mode used by the payer for the first trip.sourceOfFunds.provided.card.emvRequestwith a valid EMV data from the failed auth transaction.sourceOfFunds.provided.card.sequenceNumbertransaction.source=CARD_PRESENTposTerminal.attended=UNATTENDEDposTerminal.location= MERCHANT_TERMINAL_ON_PREMISESposTerminal.cardholderActivated=NOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability=CONTACTLESS_CHIPposTerminal.panEntryMode=CONTACTLESSposTerminal.pinEntryCapability=PIN_NOT_SUPPORTEDauthorizationResponse.datewith a valid settlement date returned in the failed auth transaction response.authorizationResponse.financialNetworkCodewith a valid financial network code.authorizationResponse.transactionIdentifiera numeric value returned in the failed authorization response.
Sample request for Standalone Capture
{
"apiOperation": "CAPTURE",
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"5A": "5555555555554444",
"5F2A": "826",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "240822",
"9B": "0101",
"9C": "00",
"9F02": "000000001099",
"9F03": "000000000000",
"9F06": "010101010101",
"9F07": "0101",
"9F09": "0101",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "826",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F41": "0123",
"9F53": "A",
"9F6E": "0101"
},
"expiry": {
"month": "12",
"year": "24"
},
"number": "5555555555554444"
}
},
"type": "CARD"
},
"transaction": {
"amount": 7,
"currency": "AUD",
"source": "CARD_PRESENT",
"transit": {
"aggregatedFare": {
"type": "FIRST_RIDE_RISK",
"aggregationStartDate": "2024-05-14",
"transportationMode": "TRAIN"
}
}
},
"posTerminal": {
"attended": "UNATTENDED",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"panEntryMode": "CONTACTLESS",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "street1",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"authorizationResponse": {
"date":"0904",
"financialNetworkCode": "MCC",
"transactionIdentifier": "943427341"
}
}
Sample response for Standalone Capture
{
"authorizationResponse": {
"date": "0904",
"financialNetworkCode": "MCC",
"processingCode": "003000",
"responseCode": "00",
"stand": "79188",
"transactionIdentifier": "943427341"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "CYG_S2I_MER2",
"order": {
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"chargeback": {
"amount": 0,
"currency": "AUD"
},
"creationTime": "2024-09-04T09:32:03.907Z",
"currency": "AUD",
"id": "AKS_908420493",
"lastUpdatedTime": "2024-09-04T09:32:04.198Z",
"merchantAmount": 7.00,
"merchantCategoryCode": "4111",
"merchantCurrency": "AUD",
"status": "CAPTURED",
"totalAuthorizedAmount": 7.00,
"totalCapturedAmount": 7.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"posTerminal": {
"address": {
"country": "GBR"
},
"attended": "UNATTENDED",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "street1",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED",
"serialNumber": "0123ABCD"
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"emvRequest": {
"5F2A": "826",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "240822",
"9B": "0101",
"9C": "00",
"9F02": "000000001099",
"9F03": "000000000000",
"9F06": "010101010101",
"9F07": "0101",
"9F09": "0101",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "826",
"9F1E": "0123ABCD",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F35": "12",
"9F36": "0002",
"9F37": "2A4E1690",
"9F41": "0123",
"9F53": "A",
"9F6E": "0101"
},
"expiry": {
"month": "12",
"year": "24"
},
"fundingMethod": "DEBIT",
"number": "555555xxxxxx4444",
"scheme": "MASTERCARD",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-09-04T09:32:04.198Z",
"timeOfRecord": "2024-09-04T09:32:03.946Z",
"transaction": {
"acquirer": {
"batch": 20240904,
"date": "0904",
"id": "CYG_TESTACQ_S2I",
"merchantId": "9808",
"settlementDate": "2024-09-04",
"timeZone": "+1000"
},
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"currency": "AUD",
"id": "AKS_627692027",
"receipt": "424809079188",
"source": "CARD_PRESENT",
"stan": "79188",
"terminal": "0002",
"transit": {
"aggregatedFare": {
"aggregationStartDate": "2024-05-14",
"transportationMode": "TRAIN",
"type": "FIRST_RIDE_RISK"
}
},
"type": "CAPTURE"
},
"version": "85"
}
The capture of a failed Authorization is permitted within Mastercard scheme rules if:
- The issuer declines the first Authorization request for the card.
- The issuer declines the first Authorization request for the card since the previous successful Authorization for an aggregated transit fare.
- The transaction amount is less than or equal to the chargeback threshold of your country.
After you have submitted the Capture request, the card still remains on the deny list. You can use the merchant-initiated debt recovery to determine if the card has returned to good standing and should be removed from the deny list. Submit the Authorization request on a new order with the following details:
order.id- This is a neworder.id.transaction.idorder.amount- This is zero amount auth for Mastercard.- the currency in the field
order.currency. transaction.transit.aggregatedFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDortransaction.transit.knownFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDtransaction.transit.aggregatedFare.transportationModemandatory with a valid enumeration value.transaction.source=MERCHANTtransaction.transit.aggregatedFare.aggregationStartDatemandatory with the date of first tap.- payment details including card number, expiration date, and so on.
If the Authorization request is successful, 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 the same order as the one for the successful Authorization with:
order.id- This must be theorder.idof the successful Authorization.transaction.id- This is a new transaction ID on the order.transaction.targetTransactionId- This is thetransaction.idof 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, see the merchant-initiated debt recovery section. 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.
Visa
According to Visa First Ride Risk rules, a Capture can be submitted for a declined Authorization if:
- The issuer has declined the first Authorization request since the previous successful Authorization for an aggregated fare.
- The transaction amount is less than equal to the chargeback threshold of the country.
Capture for a declined Authorize
order.id- This is a new value and cannot be the same as used for the declined Authorize request.transaction.id- Unique valueorder.amount- same as the declined Authorize request.order.currency- same as the declined Authorize request.transaction.transit.aggregatedFare.type=FIRST_RIDE_RISKortransaction.transit.knownFare.type=FIRST_RIDE_RISKtransaction.transit.aggregatedFare.aggregationStartDatetransaction.transit.aggregatedFare.transportationModesourceOfFunds.provided.card.emvRequestsourceOfFunds.provided.card.sequenceNumberauthorizationResponse.transactionIdentifier- as returned in the response to the declined Authorize request.authorizationResponse.returnACI- as provided in the response to the declined Authorize requesttransaction.authorizationCode=VFT000- the Authorization code defined by Visa for this specific purpose.
The startDate and transportationMode must reflect those used for the first tap.
After the Capture is submitted, the card still remains on the deny list.
Merchant initiated debt recovery determines if the card has returned to good standing and should be removed from the deny list.
To check if the card has returned to good standing and can be removed from the deny list, you can submit an Authorize request for the amount of the Capture. If the Authorize request is approved, the card should be removed from the deny list and the authorization should be voided.
Void
Submitted a Void request on the same order as the one for the successful Authorize.
order.idsame as successful Authorize.transaction.idUnique value.transaction.target.TransactionIDsame as successful Authorize.
Standalone Capture - Visa
Where the Authorization at the end of the travel period is declined, but is permitted to be captured within the Visa rules, submits a standalone Capture request with the following details:
- An identifier for the order in
order.id- You can submit this request with the same order ID that you used for the failed Authorization request on the first tap with the card or a new order ID. - An unique identifier 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=FIRST_RIDE_RISKortransaction.transit.knownFare.type=FIRST_RIDE_RISKtransaction.transit.aggregationStartDatewith the date of first tap.sourceOfFunds.provided.card.emvRequestwith a valid EMV data from the last tap within the travel period.sourceOfFunds.provided.card.sequenceNumbertransaction.source=CARD_PRESENTposTerminal.attended=UNATTENDEDposTerminal.location=ON_CARD_ACCEPTOR_PREMISESposTerminal.cardholderActivated=SELF_SERVICE_TERMINALposTerminal.inputCapability=CONTACTLESS_CHIPposTerminal.panEntryMode=CONTACTLESSposTerminal.pinEntryCapability=PIN_NOT_SUPPORTED- The 15-digit numeric value returned in the failed Authorization response in
authorizationResponse.transactionIdentifierin fieldauthorizationResponse.transactionIdentifier - The 1-letter value returned in the failed Authorization response in field
authorizationResponse.returnAciauthorizationResponse.returnAciin field. transaction.authorizationCode=VFT000- This is the Authorization code defined by Visa for this specific purpose.
Sample request for Standalone Capture
| URL | https://ap-gateway.mastercard.com/api/rest/version/63/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP Method | PUT |
{
"apiOperation": "CAPTURE",
"authorizationResponse": {
"returnAci": "N",
"transactionIdentifier": "658652148",
"financialNetworkCode": "fin",
"commercialCard": "com",
"commercialCardIndicator": "I",
"transactionIntegrityClass": "BE"
},
"posTerminal": {
"address": {
"country": "AUS",
"postcodeZip": "4000"
},
"attended": "UNATTENDED",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "test",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "CONTACTLESS",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"sourceOfFunds": {
"provided": {
"card": {
"emvRequest": {
"57": ";4005550000000019=39011019681143384001?",
"82": "1ac4",
"95": "123456abcf",
"5F2A": "125",
"9A": "201005",
"9C": "21",
"9F02": "000000000100",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "321",
"9F26": "0123456789abcdef",
"9F27": "21",
"9F36": "12ac",
"9F37": "654321fa"
},
"expiry": {
"month": "05",
"year": "21"
},
"number": "4005550000000019",
"securityCode": "015",
"sequenceNumber": "000"
}
},
"type": "CARD"
},
"transaction": {
"amount": "8.00",
"currency": "AUD",
"source": "CARD_PRESENT",
"reference": "MerchantReference",
"authorizationCode": "VFT000",
"transit": {
"aggregatedFare": {
"type": "FIRST_RIDE_RISK",
"aggregationStartDate": "2024-05-14",
"transportationMode": "TRAIN"
}
}
}
The Capture of a failed Authorization is permitted within the Visa rules if:
- The issuer declines the very first Authorization request for the card.
- The issuer declines the first Authorization request for the card since a previous successful Authorization for an aggregated transit fare was declined
- The transaction amount is less than or equal to the chargeback threshold for your country.
Once submitted the Capture request, you must submit an Authorization request with the following details:
- An identifier for the order in
order.id- This is a new order ID. - An unique identifier within the order for the Authorization transaction in
transaction.id - The same amount as submitted on the standalone Capture request in
order.amount - The order currency as provided in the standalone Capture request in field
order.currency transaction.transit.aggregatedFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDortransaction.transit.knownFare.type=DEBT_RECOVERY_MERCHANT_INITIATEDtransaction.source=MERCHANTtransaction.transit.aggregationStartDatewith the date of first tap within the travel period.- The 15-digit numeric value returned in the failed Authorization response in
authorizationResponse.transactionIdentifierin fieldtransaction.acquirer.customDatausing the syntax:{"VisaTransitFailedAuthTransactionIdentifier":"<value>"} - The payment details including the card number, expiration date, and so on.
Sample request for an Authorization of aggregate transit fares
| URL | https://ap-gateway.mastercard.com/api/rest/version/63/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP Method | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "15.00",
"currency": "AUD"
},
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "01",
"year": "39"
},
"number": "4909654321012344",
"securityCode": "015",
"sequenceNumber": "099"
}
},
"type": "CARD"
},
"transaction": {
"acquirer": {
"customData": "{\"VisaTransitFailedAuthTransactionIdentifier\":\"658652148\"}"
},
"source": "MERCHANT",
"transit": {
"aggregationStartDate": "2021-06-16",
"type": "MERCHANT_INITIATED_DEBT_RECOVERY",
}
}
}
If the Authorization request is successful, remove the card from the deny list within 1 hour and immediately void the Authorization.
To void the Authorization, submit a Void request on a same order for which you submitted the successful Authorization with the following details:
- The Order ID of the successful Authorization in
order.id - An unique identifier within the order for the Void Authorization transaction in
transaction.id - The
transaction.idof the successful Authorization intransaction.targetTransactionId
Sample request for a Void on a successful Authorization
| URL | https://ap-gateway.mastercard.com/api/rest/version/63/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| HTTP Method | PUT |
{
"apiOperation": "VOID",
"transaction": {
"targetTransactionId": "933674638"
}
}
- You can repeat the Authorization request up to the allowed attempts count or frequency for merchant-initiated debt recovery requests. For more information, see the merchant-initiated debt recovery section.
- 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.