Payment Instrument Reference ID
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 the following 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 following 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
The following are the two use cases.
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
The customers can retrieve trip history data by querying the Payment Instrument Reference ID within the AFC back-office trip management system.
Supported schemes
The Payment Instrument Reference ID support is available for all schemes.
WS API fields
The following 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
The following are the sample WS API requests and responses for Payment Instrument Reference ID.
Payment Instrument Reference ID generation with sourceOfFunds.provided.card
Request
{
"apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
"correlationId": "ABCD",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "10",
"year" : "31"
},
"number":"345678000000007"
}
},
"type": "CARD"
}
}
Response
{
"correlationId": "ABCD",
"paymentInstrumentReferenceId": "aqgGBizz8E8D30l74Zuo5FVOiSav1app/TcauAwb4dM=",
"result": "SUCCESS"
}
Payment Instrument Reference ID generation with sourceOfFunds.provided.p2pe
Request
{
"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
{
"correlationId": "ABCD",
"paymentInstrumentReferenceId": "gtJUGNKz6oSFqAC6ZkbpqX5UhGyRs30a911oPiEnmfY=",
"result": "SUCCESS"
}
Verify transaction for generating referenceOrderId or OrderId using DPAN
Request
{
"sourceOfFunds": {
"tokenRequestorID": "01234567890",
"provided": {
"card": {
"devicePayment": {
"eciIndicator": "05",
"onlinePaymentCryptogram": "VGVzdDQwQ2hhcnNDcnlwdG9ncmFtRXhhY3RGaXRGb3JBTUVYSXNHbw=="
},
"number": "345678901234564",
"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
{
"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
Request
{
"apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
"correlationId": "ABCD",
"referenceOrderId": "AKS_26033149",
"sourceOfFunds": {
"type": "CARD"
}
}
Response
{
"correlationId": "ABCD",
"paymentInstrumentReferenceId": "4BEalICzd9w4RijLOkRNOY7l9y5rpALn/CsVuOtdUXw=",
"result": "SUCCESS"
}
Hosted Checkout transaction performed to check ride travel history on web portal
Request
{
"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
{
"checkoutMode": "WEBSITE",
"merchant": "3DS12AUTH",
"result": "SUCCESS",
"session": {
"id": "SESSION0002547780765H1027002G16",
"updateStatus": "SUCCESS",
"version": "315c0cc501"
},
"successIndicator": "70e49e0e9b9f430b"
}
PaymentInstrumentReferenceId generation using the Hosted Checkout orderId
Request
{
"apiOperation": "CREATE_PAYMENT_INSTRUMENT_REFERENCE_ID",
"correlationId": "ABCD",
"referenceOrderId": "ORDER-518675486",
"sourceOfFunds": {
"type": "CARD"
}
}
Response
{
"correlationId": "ABCD",
"paymentInstrumentReferenceId": "5KOtIhlOvidj7riw0uFAS39oERzBYtxVOMhnb+QN0yA=",
"result": "SUCCESS"
}