Identifiers
Various identifiers are used to reconcile and track transactions moving through the payment systems. These identifiers are used in the settlement report from your acquirer to help you identify each transaction.
You provide identifiers when sending requests to the Mastercard Gateway. Ideally, the same identifier can be used in all systems, that is, your own, the gateway, and your acquirer. However, the different systems have different requirements, and often a combination of identifiers are needed. Each order you create can have three different kinds of identifiers:
Types of identifiers
Each order you create can have three different kinds of identifiers:
- Order ID:
This is a mandatory identifier that you need to define as part of the first transaction on each order. The value is provided as the orderID field in request and response bodies, or as an
orderIDquery parameter, depending on the operation. The value must be unique within all orders sent from your merchant account, as the gateway uses it to identify a particular order submitted by you. For convenience, use a natural key within your own system as theorder ID, such as the shopping cart ID or invoice number. This makes it easy to track orders between your system and the gateway. As the gateway also attempts to use the order ID in acquirer messages when possible, all three systems, that is, yours, the gateway, and your bank can be linked by a common identifier. - Order reference:
In some situations, the order IDs you use in your own system cannot be used in the gateway, as they do not meet the gateway’s requirements. For example, if your system rolls order IDs, wraps around when exceeding a set upper limit, or groups multiple tenders under one order, the order ID within your system does not work as a unique identifier in the gateway.
In this case, you must create a new unique
order IDto use for the gateway. In addition, you can provide an optional value,order.reference, which contains the identifier you use in your own system and allows you to track orders between your system and the gateway. - Identifier for the acquirer:
As the gateway must pass an identifier to the acquirer, it attempts to use your
order ID. However, if that is not suitable for your acquirer, the gateway transforms the value into something that matches the acquirer’s field length and format requirements. If you want to control the value that the gateway provides to the acquirer, you can provide a transaction.acquirer.transactionId value in the request. However, if that value does not match the acquirer requirements, the gateway transforms that too before sending it. In either case, you can find the identifier that the gateway actually sent to the acquirer in the transaction.acquirer.transactionId field of the request response. If the gateway has had to transform the identifier, store the response value to be able to match the acquirer payment details to the orders in your system.
Transactions
To identify the individual transactions within an order, the gateway uses transaction IDs. The value is provided as the transaction.id field in request and response bodies, or as a transactionID query parameter for specific operations. If your system tracks transactions using a unique identifier, use it. Otherwise, use any sequential or random number, as long as it is unique for each transaction within the same order.
To identify the transaction at the card acquirer, use the receipt. This value is returned in the transaction.receipt field of the request response, however, this value may not be unique.