# Transit Debt Recovery and First Ride Risk using referenceOrderId
source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/ref-order-id/index.md

## Overview {#overview}

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.

## Mastercard Gateway API support {#mastercard-gateway-api-support}

The API field referenceOrderId is available from version 100.

## referenceOrderId {#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                |
|---------------------------------|-------------------------------------------|
| `orderReferenceId`              | Example: 1234                             |
| `transaction.resubmission` flag | TRUE for Merchant Initiated Debt Recovery |

* **First Ride Risk request**   
  The usage of referenceOrderId allows you to use payment instrument details from the failed authorization transaction without needing to provide the `sourceOfFunds.provided.card`.

## Mastercard Merchant Initiated Debt Recovery {#mastercard-merchant-initiated-debt-recovery}

```json
{
    "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"
            }
        }
    }
}
```

```json
{
    "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 {#visa-merchant-initiated-debt-recovery}

```json
{
    "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"
            }
        }
    }
}
```

```json
{
    "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 {#mastercard-first-ride-risk}

```json
{
    "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"
    }
}
```

```json
{
    "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 {#visa-first-ride-risk}

```json
{
    "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"
    }
}
```

```json
{
    "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"
}
```