Transit Debt Recovery and First Ride Risk using referenceOrderId
The referenceOrderId field is used to source customer payment instrument details from the original transaction on the order, such as a failed authorization or initial verification transaction.
WS API support
The WS API fieldreferenceOrderId is available from version 100 onwards.
referenceOrderId
This is the reference to the payment instrument details of an order previously submitted by you to the gateway. When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group.
It applies to the following use cases within the cardholder present and transit processing.
- Merchant Initiated Debt Recovery request
- Allows you to use payment instrument details from the failed authorization transaction without needing to provide the
sourceOfFunds.provided.card. - Ensures to set the resubmission flag for Merchant Initiated Debt Recovery processing with
orderReferenceId.Field Description orderReferenceIdExample: 1234 transaction.resubmissionflagTRUE for Merchant Initiated Debt Recovery
- Allows you to use payment instrument details from the failed authorization transaction without needing to provide the
- First Ride Risk request
The usage of
referenceOrderIdallows you to use payment instrument details from the failed authorization transaction without needing to provide thesourceOfFunds.provided.card.
Mastercard Merchant Initiated Debt Recovery
Request
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "510",
"currency": "AUD"
},
"referenceOrderId": "AKS_551364916",
"sourceOfFunds": {
"type": "CARD"
},
"transaction": {
"source": "MERCHANT",
"resubmission": true,
"transit": {
"aggregatedFare": {
"type": "DEBT_RECOVERY_MERCHANT_INITIATED",
"aggregationStartDate": "2022-05-05",
"transportationMode": "TRAIN"
}
}
}
}
Response
{
"authorizationResponse": {
"date": "1111",
"financialNetworkCode": "ACT",
"financialNetworkDate": "2024-11-11",
"posData": "2031104000600",
"posEntryMode": "012",
"processingCode": "003000",
"responseCode": "00",
"stan": "7234",
"time": "070322",
"transactionIdentifier": "VQ3BR5"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "CYG_S2I_MER2",
"order": {
"amount": 510.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"certainty": "FINAL",
"chargeback": {
"amount": 0,
"currency": "AUD"
},
"creationTime": "2024-11-11T07:03:22.102Z",
"currency": "AUD",
"id": "AKS_978575407",
"lastUpdatedTime": "2024-11-11T07:03:22.424Z",
"merchantAmount": 510.00,
"merchantCategoryCode": "4111",
"merchantCurrency": "AUD",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 510.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"referenceOrderId": "AKS_551364916",
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "12",
"year": "14"
},
"fundingMethod": "CREDIT",
"number": "541333xxxxxx3560",
"scheme": "MASTERCARD",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-11-11T07:03:22.424Z",
"timeOfRecord": "2024-11-11T07:03:22.130Z",
"transaction": {
"acquirer": {
"batch": 20241111,
"date": "1111",
"id": "CYG_TESTACQ_S2I",
"merchantId": "9808",
"transactionId": "VQ3BR5"
},
"amount": 510.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "112233",
"currency": "AUD",
"id": "AKS_324887232",
"receipt": "431607007234",
"resubmission": true,
"source": "MERCHANT",
"stan": "7234",
"terminal": "0001",
"transit": {
"aggregatedFare": {
"aggregationStartDate": "2022-05-05",
"transportationMode": "TRAIN",
"type": "DEBT_RECOVERY_MERCHANT_INITIATED"
}
},
"type": "AUTHORIZATION"
},
"version": "100"
}
VISA Merchant Initiated Debt Recovery
Request
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "27",
"currency": "AUD",
"certainty": "ESTIMATED"
},
"referenceOrderId": "AKS_555808986",
"sourceOfFunds": {
"type": "CARD"
},
"transaction": {
"resubmission": "true",
"source": "MERCHANT",
"transit": {
"knownFare": {
"type": "DEBT_RECOVERY_MERCHANT_INITIATED"
}
}
}
}
Response
{
"authorizationResponse": {
"cardLevelIndicator": "XX",
"commercialCard": "123",
"commercialCardIndicator": "1",
"date": "0212",
"marketSpecificData": "A",
"posData": "2031104000600",
"posEntryMode": "012",
"processingCode": "003000",
"responseCode": "00",
"returnAci": "Y",
"stan": "99023",
"time": "102743",
"transactionIdentifier": "693133751154212"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "CYG_S2I_MER2",
"order": {
"amount": 27.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"certainty": "ESTIMATED",
"chargeback": {
"amount": 0,
"currency": "AUD"
},
"creationTime": "2025-02-12T10:27:43.095Z",
"currency": "AUD",
"id": "AKS_436425506",
"lastUpdatedTime": "2025-02-12T10:27:43.376Z",
"merchantAmount": 27.00,
"merchantCategoryCode": "4111",
"merchantCurrency": "AUD",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 27.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"referenceOrderId": "AKS_555808986",
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "VISA",
"deviceSpecificExpiry": {
"month": "12",
"year": "30"
},
"deviceSpecificNumber": "454742xxxxxx0978",
"fundingMethod": "UNKNOWN",
"number": "454742xxxxxx0978",
"paymentAccountReference": "12345678901234567TC020VSADE56",
"scheme": "VISA",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2025-02-12T10:27:43.376Z",
"timeOfRecord": "2025-02-12T10:27:43.171Z",
"transaction": {
"acquirer": {
"batch": 20250212,
"date": "0212",
"id": "CYG_TESTACQ_S2I",
"merchantId": "9808",
"transactionId": "693133751154212"
},
"amount": 27.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "112233",
"currency": "AUD",
"id": "AKS_649023621",
"receipt": "504310099023",
"resubmission": true,
"source": "MERCHANT",
"stan": "99023",
"terminal": "0002",
"transit": {
"knownFare": {
"type": "DEBT_RECOVERY_MERCHANT_INITIATED"
}
},
"type": "AUTHORIZATION"
},
"version": "100"
}
Mastercard First Ride Risk
Request
{
"apiOperation": "CAPTURE",
"referenceOrderId": "AKS_704717981",
"transaction": {
"amount": 7,
"currency": "AUD",
"source": "CARD_PRESENT",
"transit": {
"aggregatedFare": {
"type": "FIRST_RIDE_RISK",
"aggregationStartDate": "2024-05-14",
"transportationMode": "OTHER"
}
}
},
"authorizationResponse": {
"date": "1111",
"financialNetworkCode": "MCC",
"transactionIdentifier": "999191302"
}
}
Response
{
"authorizationResponse": {
"date": "1111",
"financialNetworkCode": "MCC",
"processingCode": "003000",
"responseCode": "00",
"stan": "320169",
"transactionIdentifier": "999191302"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "CYG_S2I_MER2",
"order": {
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"chargeback": {
"amount": 0,
"currency": "AUD"
},
"creationTime": "2024-11-11T06:54:33.498Z",
"currency": "AUD",
"id": "AKS_45361228",
"lastUpdatedTime": "2024-11-11T06:54:33.704Z",
"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": "SELF_SERVICE_TERMINAL",
"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": "161021",
"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"
},
"encryption": "DUKPT",
"expiry": {
"month": "12",
"year": "24"
},
"fundingMethod": "DEBIT",
"number": "555555xxxxxx4444",
"scheme": "MASTERCARD",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-11-11T06:54:33.704Z",
"timeOfRecord": "2024-11-11T06:54:33.532Z",
"transaction": {
"acquirer": {
"batch": 20241111,
"date": "1111",
"id": "CYG_TESTACQ_S2I",
"merchantId": "9808",
"settlementDate": "2024-11-11",
"timeZone": "+1000"
},
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"currency": "AUD",
"id": "AKS_324887232",
"receipt": "431606320169",
"source": "CARD_PRESENT",
"stan": "320169",
"terminal": "0002",
"transit": {
"aggregatedFare": {
"aggregationStartDate": "2024-05-14",
"transportationMode": "OTHER",
"type": "FIRST_RIDE_RISK"
}
},
"type": "CAPTURE"
},
"version": "100"
}
VISA First Ride Risk
Request
{
"apiOperation": "CAPTURE",
"referenceOrderId": "AKS_297678680",
"transaction": {
"authorizationCode": "123456",
"amount": 7,
"currency": "AUD",
"source": "CARD_PRESENT",
"transit": {
"aggregatedFare": {
"type": "FIRST_RIDE_RISK",
"aggregationStartDate": "2024-05-14",
"transportationMode": "OTHER"
}
}
},
"posTerminal": {
"attended": "UNATTENDED",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"panEntryMode": "CONTACTLESS",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "street1",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"authorizationResponse": {
"transactionIdentifier": "856133326259392",
"returnAci": "Y"
}
}
Response
{
"authorizationResponse": {
"processingCode": "003000",
"responseCode": "00",
"returnAci": "Y",
"stan": "312969",
"transactionIdentifier": "856133326259392"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "CYG_S2I_MER2",
"order": {
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"chargeback": {
"amount": 0,
"currency": "AUD"
},
"creationTime": "2024-11-11T06:38:47.177Z",
"currency": "AUD",
"id": "AKS_509365036",
"lastUpdatedTime": "2024-11-11T06:38:47.368Z",
"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": "SELF_SERVICE_TERMINAL",
"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": "VISA",
"emvRequest": {
"5F2A": "826",
"82": "0000",
"84": "010101010101",
"95": "0000000000",
"9A": "161021",
"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"
},
"encryption": "DUKPT",
"expiry": {
"month": "12",
"year": "24"
},
"fundingMethod": "CREDIT",
"number": "444433xxxxxx1111",
"scheme": "VISA",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-11-11T06:38:47.368Z",
"timeOfRecord": "2024-11-11T06:38:47.211Z",
"transaction": {
"acquirer": {
"batch": 20241111,
"date": "1111",
"id": "CYG_TESTACQ_S2I",
"merchantId": "9808",
"settlementDate": "2024-11-11",
"timeZone": "+1000"
},
"amount": 7.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "123456",
"currency": "AUD",
"id": "AKS_515758705",
"receipt": "431606312969",
"source": "CARD_PRESENT",
"stan": "312969",
"terminal": "0001",
"transit": {
"aggregatedFare": {
"aggregationStartDate": "2024-05-14",
"transportationMode": "OTHER",
"type": "FIRST_RIDE_RISK"
}
},
"type": "CAPTURE"
},
"version": "100"
}