An order is the concept that the MasterCard Payment Gateway uses to link all the transactions that relate to one instance of a sale between you and your payer. It is broadly intended to represent the classical paper 'order' concept, where you sell a bill of goods to your customers. As such it has all the classical order data — the line items for the goods that were bought, who paid for them and how, where they are to be shipped, and most importantly the amount paid.
An order can contain one or more transactions. Some orders have just one transaction, a 'purchase' where the goods are paid in full and dispatched straight away. Others have two transactions, an 'authorization' where you check that the payer's bank account has enough money and reserve the money, and then a 'capture', where you move the money from their account to yours. The authorize/capture model is usually used when you cannot guarantee that the goods can be dispatched at the time they were requested by the payer. There may be times when you will also need to refund some or all of the order money, or maybe deliver the goods in several partial deliveries. All those movements of money represent transactions against the one order.
When you use the MasterCard Payment Gateway, you usually provide all the information about the order in the initial transaction — the billing, shipping, payment details, full amount and so on. Then on subsequent transactions, for example, Capture, Refund, or Void, you do not need to repeat this data, just reference the original order. For example, if you want to refund, then just provide the order identifier and the amount you want to refund, and the gateway will provide all the details that the bank needs to move the money.
The MasterCard Payment Gateway has a single unique identifier that it uses to identify a particular order submitted by you. You must assign that identifier as part of the first transaction on the order. This identifier is called the order.id (provided as orderID in the URL for REST). It's recommended that you supply the natural key for the order (shopping cart id, invoice number) within your system to the gateway. This makes it easy to track between your system and the gateway. The gateway also attempts to use the order.id in acquirer messages. That way all three systems — yours, the gateway, and your bank — will be linked by a common identifier. However, this ideal situation might not be feasible due to limitations of the various systems.
The order identifier might not be suitable as the reference into your system. For example, if your system rolls orders IDs, or groups multiple tenders under the one order, then the order identifier will not be suitable. In this case, you can provide an additional value, the order.reference, to trace between your system and the MasterCard Payment Gateway.
The gateway needs to pass an identifier to the acquirer. It will try to use your order identifier, possibly in combination with your transaction identifier (see below). However, if that is not suitable for your acquirer, the gateway will transform them into a suitable value. In all cases, the gateway returns the identifier that was used, in the transaction.acquirer.transactionId field.
However, if you want to control the value that the gateway provides to the acquirer, then you can provide a transaction.acquirer.transactionId value in the request.
order.id and either or both of order.reference and transaction.acquirer.transactionId to get fine control over the identity in each system.The MasterCard Payment Gateway has a unique identifier that it uses to identify each transaction within the order. This identifier is called the transaction.id (provided as transactionID in the URL for REST). Typically you will not have a natural key for this, but if you do, then it's recommended that you use it. If not, a sequential or random number is suitable.
Copyright © 2023 MasterCard