referenceOrderId
for the Debt Recovery and First Ride Risk
WS API support
The referenceOrderId
field usage for the purpose of sourcing customer payment instrument details from the original transaction on the order, such as failed authorization or initial verification transaction is available from the WS API version 100 onwards.
referenceOrderId
This is the reference to an order that you previously submit to the gateway.
It applies to the following scenarios.
- Tokenization requests:
The identifier for the order which is used to generate the gateway token. The gateway attempts tokenization of payment credentials linked to order ID. The order identifier provided in this field must be linked to a successfully processed order that has a card (FPAN or DPAN) as the payment method. When providing this field, you must not provide card details in the
sourceOfFunds.provided.card
parameter group. - Payment transactions when submitting:
- An Industry Practice Payment: This is the reference to the initial cardholder-initiated transaction.
- A Resubmission Transaction: This is the reference to the order that is being resubmitted.
Debt Recovery with referenceOrderId
Example 1: Known Fare Transit Debt Recovery Authorization with referenceOrderId
Request
{ "apiOperation": "AUTHORIZE", "order": { "amount": "510", "currency": "AUD" }, "referenceOrderId": "AKS_319759689", "sourceOfFunds": { "type": "CARD" }, "transaction": { "source": "MERCHANT", "resubmission": true, "transit": { "knownFare": { "type": "DEBT_RECOVERY_MERCHANT_INITIATED" } } } }
Response
{ "authorizationResponse": { "commercialCard": "123", "commercialCardIndicator": "1", "date": "1111", "financialNetworkCode": "MCC", "posData": "2031104000600", "posEntryMode": "012", "processingCode": "003000", "responseCode": "00", "stan": "313968", "time": "053057", "transactionIdentifier": "667402207", "transactionIntegrityClass": "A1" }, "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-11T05:30:56.774Z", "currency": "AUD", "id": "AKS_354369982", "lastUpdatedTime": "2024-11-11T05:30:57.065Z", "merchantAmount": 510.00, "merchantCategoryCode": "4111", "merchantCurrency": "AUD", "status": "AUTHORIZED", "totalAuthorizedAmount": 510.00, "totalCapturedAmount": 0.00, "totalDisbursedAmount": 0.00, "totalRefundedAmount": 0.00 }, "referenceOrderId": "AKS_319759689", "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-11T05:30:57.065Z", "timeOfRecord": "2024-11-11T05:30:56.839Z", "transaction": { "acquirer": { "batch": 20241111, "date": "1111", "id": "CYG_TESTACQ_S2I", "merchantId": "9808", "transactionId": "667402207" }, "amount": 510.00, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "112233", "currency": "AUD", "id": "AKS_471378549", "receipt": "431605313968", "resubmission": true, "source": "MERCHANT", "stan": "313968", "terminal": "0002", "transit": { "knownFare": { "type": "DEBT_RECOVERY_MERCHANT_INITIATED" } }, "type": "AUTHORIZATION" }, "version": "100" }
Example 2: Aggregated Fare Transit Debt Recovery Authorization transaction with referenceOrderId
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" }
First Ride Risk with referenceOrderId
Example 1: Mastercard Known Fare Transit First Ride Risk with referenceOrderId
Request
{ "apiOperation": "CAPTURE", "referenceOrderId": "AKS_269638983", "transaction": { "authorizationCode": "123456", "amount": 7, "currency": "AUD", "source": "CARD_PRESENT", "transit": { "knownFare": { "type": "FIRST_RIDE_RISK" } } }, "authorizationResponse": { "date": "1111", "financialNetworkCode": "MCC", "transactionIdentifier": "990001915" } }
Response
{ "authorizationResponse": { "date": "1111", "financialNetworkCode": "MCC", "processingCode": "003000", "responseCode": "00", "stan": "317019", "transactionIdentifier": "990001915" }, "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:45:16.139Z", "currency": "AUD", "id": "AKS_83222381", "lastUpdatedTime": "2024-11-11T06:45:16.403Z", "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:45:16.403Z", "timeOfRecord": "2024-11-11T06:45:16.188Z", "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_826221426", "receipt": "431606317019", "source": "CARD_PRESENT", "stan": "317019", "terminal": "0001", "transit": { "knownFare": { "type": "FIRST_RIDE_RISK" } }, "type": "CAPTURE" }, "version": "100" }
Example 2: Mastercard Aggregated Fare Transit First Ride Risk with referenceOrderId
Request
{ "apiOperation": "CAPTURE", "referenceOrderId": "AKS_704717981", "transaction": { "authorizationCode": "123456", "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", "authorizationCode": "123456", "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" }
Example 3: Visa Known Fare Transit First Ride Risk with referenceOrderId
Request
{ "apiOperation": "CAPTURE", "referenceOrderId": "AKS_232166351", "transaction": { "authorizationCode": "123456", "amount": 7, "currency": "AUD", "source": "CARD_PRESENT", "transit": { "knownFare": { "type": "FIRST_RIDE_RISK" } } }, "authorizationResponse": { "transactionIdentifier": "559093547331264", "returnAci": "Y" } }
Response
{ "authorizationResponse": { "processingCode": "003000", "responseCode": "00", "returnAci": "Y", "stan": "321178", "transactionIdentifier": "559093547331264" }, "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:32:07.708Z", "currency": "AUD", "id": "AKS_654877019", "lastUpdatedTime": "2024-11-11T06:32:08.017Z", "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:32:08.017Z", "timeOfRecord": "2024-11-11T06:32:07.766Z", "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_645810770", "receipt": "431606321178", "source": "CARD_PRESENT", "stan": "321178", "terminal": "0002", "transit": { "knownFare": { "type": "FIRST_RIDE_RISK" } }, "type": "CAPTURE" }, "version": "100" }
Example 4: Visa Aggregated Fare Transit First Ride Risk with referenceOrderId
Request
{ "apiOperation": "CAPTURE", "referenceOrderId": "AKS_168789193", "transaction": { "authorizationCode": "123456", "amount": 7, "currency": "AUD", "source": "CARD_PRESENT", "transit": { "aggregatedFare": { "type": "FIRST_RIDE_RISK", "aggregationStartDate": "2024-05-14", "transportationMode": "OTHER" } } }, "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" }