# Payment Instrument Reference ID
source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/cardholder-present-data/transit/payment-inst-ref-id/index.md

## Overview {#overview}

The Payment Instrument Reference ID is a PCI compliant, non-sensitive unique identifier that links a specific payment method such as a Funding Primary Account Number (FPAN) or Device Primary Account Number (DPAN) to a transaction.

This identifier supports these use cases:

* Automated Fare Collection (AFC) back-end transaction aggregation.
* AFC back-end portal trip history retrieval.   

To generate a Payment Instrument Reference ID, the customer must initiate the operation:

    apiOperation=CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID

The request can be submitted using:

* A Point-to-point encryption (P2PE) payload.
* An existing order reference ID of an order from the gateway. This is used for trip history retrieval through the portal.

## Use cases {#use-cases}

These are the two use cases.

### Trip aggregation {#trip-aggregation}

The customers who want to generate a unique Payment Instrument Reference ID for trip aggregation using DPAN or FPAN can initiate the request through Mastercard Gateway.

### Trip history retrieval {#trip-history-retrieval}

The customers can retrieve trip history data by querying the Payment Instrument Reference ID within the AFC back-office trip management system.

## Supported schemes {#supported-schemes}

The Payment Instrument Reference ID support is available for all schemes.

## WS API fields {#ws-api-fields}

The table describes the API fields and its requirement.

|                          Field                          |                        Field requirement                        |
|---------------------------------------------------------|-----------------------------------------------------------------|
| `apiOperation`=CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID   | Mandatory                                                       |
| `correlationId`                                         | Optional                                                        |
| `sourceOfFunds`                                         | Optional                                                        |
| `sourceOfFunds.type`                                    | Optional                                                        |
| `sourceOfFunds.provided`                                | Optional                                                        |
| `sourceOfFunds.provided.card`                           | Optional                                                        |
| `sourceOfFunds.provided.card.expiry`                    | Optional                                                        |
| `sourceOfFunds.provided.card.expiry.month`              | Mandatory if `sourceOfFunds.provided.card.expiry` is used       |
| `sourceOfFunds.provided.card.expiry.year`               | Mandatory if `sourceOfFunds.provided.card.expiry` is used       |
| `sourceOfFunds.provided.card.number`                    | Optional                                                        |
| `sourceOfFunds.provided.card.p2pe`                      | Optional                                                        |
| `sourceOfFunds.provided.card.p2pe.encryptionState`      | Mandatory if `sourceOfFunds.provided.p2pe` is used              |
| `sourceOfFunds.provided.card.p2pe.initializationVector` | Mandatory if `sourceOfFunds.provided.p2pe` is used              |
| `sourceOfFunds.provided.card.p2pe.keySerialNumber`      | Mandatory if `sourceOfFunds.provided.p2pe` is used              |
| `sourceOfFunds.provided.card.p2pe.payload`              | Mandatory if `sourceOfFunds.provided.p2pe` is used              |
| `referenceOrderId`                                      | Optional                                                        |
| `posTerminal`                                           | Optional                                                        |
| `posTerminal.serialNumber`                              | Optional, but required if `sourceOfFunds.provided.p2pe` is used |

## WS API examples {#ws-api-examples}

These are the sample WS API requests and responses for Payment Instrument Reference ID.

## Payment Instrument Reference ID generation with sourceOfFunds.provided.card {#payment-instrument-reference-id-generation-with-sourceoffundsprovidedcard}

#### Request {#request}

```json
{
    "apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
    "correlationId": "ABCD",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "10",
                    "year": "31"
                },
                "number": "345678000000007"
            }
        },
        "type": "CARD"
    }
}
```

#### Response {#response}

```json
{
    "correlationId": "ABCD",
    "paymentInstrumentReferenceId": "aqgGBizz8E8D30l74Zuo5FVOiSav1app/TcauAwb4dM=",
    "result": "SUCCESS"
}
```

## Payment Instrument Reference ID generation with sourceOfFunds.provided.p2pe {#payment-instrument-reference-id-generation-with-sourceoffundsprovidedp2pe}

#### Request {#request-1}

```json
{
    "apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
    "correlationId": "ABCD",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "p2pe": {
                    "encryptionState": "VALID",
                    "initializationVector": "0000000000000000",
                    "keySerialNumber": "FFFF0000000004100499",
                    "payload": "A323153EF0B2C417904537454DDE5EA6E3548DEAE9EBB12887251595200BAABC0D8892A0A7C13581"
                }
            }
        },
        "type": "CARD"
    },
    "posTerminal": {
        "serialNumber": "12345678"
    }
}
```

#### Response {#response-1}

```json
{
    "correlationId": "ABCD",
    "paymentInstrumentReferenceId": "gtJUGNKz6oSFqAC6ZkbpqX5UhGyRs30a911oPiEnmfY=",
    "result": "SUCCESS"
}
```

## Verify transaction for generating referenceOrderId or OrderId using DPAN {#verify-transaction-for-generating-referenceorderid-or-orderid-using-dpan}

#### Request {#request-2}

```json
{
    "sourceOfFunds": {
        "tokenRequestorID": "01234567890",
        "provided": {
            "card": {
                "devicePayment": {
                    "eciIndicator": "05",
                    "onlinePaymentCryptogram": "VGVzdDQwQ2hhcnNDcnlwdG9ncmFtRXhhY3RGaXRGb3JBTUVYSXNHbw=="
                },
                "number": "371881245560002",
                "expiry": {
                    "month": "1",
                    "year": "29"
                }
            }
        },
        "type": "CARD"
    },
    "posTerminal": {
        "location": "PAYER_TERMINAL_ON_PREMISES",
        "serialNumber": "12345678"
    },
    "apiOperation": "VERIFY",
    "order": {
        "amount": "1",
        "walletProvider": "APPLE_PAY",
        "currency": "USD"
    }
}
```

#### Response {#response-2}

```json
{
    "authorizationResponse": {
        "transactionIdentifier": "342025965853097"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "CYG_S2I_MER2",
    "order": {
        "amount": 1,
        "chargeback": {
            "amount": 0,
            "currency": "USD"
        },
        "creationTime": "2025-09-26T05:35:02.511Z",
        "currency": "USD",
        "id": "AKS_26033149",
        "lastUpdatedTime": "2025-09-26T05:35:02.790Z",
        "merchantAmount": 1,
        "merchantCategoryCode": "4111",
        "merchantCurrency": "USD",
        "status": "VERIFIED",
        "totalAuthorizedAmount": 0,
        "totalCapturedAmount": 0,
        "totalDisbursedAmount": 0,
        "totalRefundedAmount": 0,
        "walletProvider": "APPLE_PAY"
    },
    "posTerminal": {
        "location": "PAYER_TERMINAL_ON_PREMISES",
        "serialNumber": "12345678"
    },
    "response": {
        "acquirerCode": "00",
        "gatewayCode": "APPROVED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "AMEX",
                "deviceSpecificExpiry": {
                    "month": "1",
                    "year": "29"
                },
                "deviceSpecificNumber": "345678xxxxx4564",
                "expiry": {
                    "month": "1",
                    "year": "29"
                },
                "fundingMethod": "UNKNOWN",
                "issuerCountryCode": "IND",
                "number": "345678xxxxx4564",
                "paymentAccountReference": "1234567890123456TC020AMEXDE56",
                "scheme": "AMEX",
                "storedOnFile": "NOT_STORED"
            }
        },
        "type": "CARD"
    },
    "timeOfLastUpdate": "2025-09-26T05:35:02.790Z",
    "timeOfRecord": "2025-09-26T05:35:02.540Z",
    "transaction": {
        "acquirer": {
            "id": "CYG_TESTACQ_S2I",
            "merchantId": "9808"
        },
        "amount": 1,
        "currency": "USD",
        "id": "AKS_80926504",
        "receipt": "526905131367",
        "source": "INTERNET",
        "stan": "131367",
        "terminal": "0001",
        "type": "VERIFICATION"
    },
    "version": "100"
}
```

## PaymentInstrumentReferenceId generation using referenceOrderId {#paymentinstrumentreferenceid-generation-using-referenceorderid}

#### Request {#request-3}

```json
{
    "apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
    "correlationId": "ABCD",
    "referenceOrderId": "AKS_26033149",
    "sourceOfFunds": {
        "type": "CARD"
    }
}
```

#### Response {#response-3}

```json
{
    "correlationId": "ABCD",
    "paymentInstrumentReferenceId": "4BEalICzd9w4RijLOkRNOY7l9y5rpALn/CsVuOtdUXw=",
    "result": "SUCCESS"
}
```

## Hosted Checkout transaction performed to check ride travel history on a web portal {#hosted-checkout-transaction-performed-to-check-ride-travel-history-on-a-web-portal}

#### Request {#request-4}

```json
{
    "apiOperation": "INITIATE_CHECKOUT",
    "checkoutMode": "WEBSITE",
    "interaction": {
        "operation": "VERIFY",
        "merchant": {
            "name": "The Company Co",
            "url": "https://www.merchant-site.com",
            "logo": "https://upload.wikimedia.org/wikipedia/commons/2/21/Verlagsgruppe_Random_House_Logo_2016.png"
        }
    },
    "order": {
        "currency": "AUD",
        "amount": "0",
        "id": "ORDER-518675486",
        "description": "Goods and Services"
    },
    "billing": {
        "address": {
            "city": "St Louis",
            "stateProvince": "MO",
            "country": "USA",
            "postcodeZip": "63102",
            "street": "11 N 4th St",
            "street2": "The Gateway Arch"
        }
    },
    "customer": {
        "email": "peteMorris@mail.us.com",
        "firstName": "John",
        "lastName": "Doe",
        "mobilePhone": "+1 5557891230",
        "phone": "+1 1234567890"
    }
}
```

#### Response {#response-4}

```json
{
    "checkoutMode": "WEBSITE",
    "merchant": "3DS12AUTH",
    "result": "SUCCESS",
    "session": {
        "id": "SESSION0002547780765H1027002G16",
        "updateStatus": "SUCCESS",
        "version": "315c0cc501"
    },
    "successIndicator": "70e49e0e9b9f430b"
}
```

## PaymentInstrumentReferenceId generation using the Hosted Checkout orderId {#paymentinstrumentreferenceid-generation-using-the-hosted-checkout-orderid}

#### Request {#request-5}

```json
{
    "apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
    "correlationId": "ABCD",
    "referenceOrderId": "ORDER-518675486",
    "sourceOfFunds": {
        "type": "CARD"
    }
}
```

#### Response {#response-5}

```json
{
    "correlationId": "ABCD",
    "paymentInstrumentReferenceId": "5KOtIhlOvidj7riw0uFAS39oERzBYtxVOMhnb+QN0yA=",
    "result": "SUCCESS"
}
```