Knowing Your Input Fields

Before performing a test transaction, you must be prepared with the values for the fields that require your input. Whatever method you choose to generate these values, manual or auto-generated using a script, appropriate values for these fields can simplify the process of managing orders and transactions, specifically, retrieving lost transactions.

Transaction/Order Identifiers and References

For more information about field types, validation rules, and what operations require the following fields, see the API Reference.

[Mandatory] Order Identifier

The unique identifier for an order (included in the URL for REST), to distinguish itself from any other orders you create. This field is mandatory and must be unique for every order you create against your merchant profile. When attempting to perform a subsequent transaction against an order, for example, refund, capture, or void, you must supply the Order ID that corresponds to the initial Authorization or Pay.

Reusing Order Identifier

From API v15 onwards, if the initial transaction for an order fails, you can submit another initial transaction for this order without having to create a new order. This is useful in scenarios where the payer may wish to retry a failed transaction with different payment details, for example, a different credit card or an alternative payment method (PayPal).

Order ID API Reference[REST][NVP]

[Mandatory] Transaction Identifier

The identifier for a transaction (included in the URL for REST) to distinguish itself from the other transactions within this order. This field is mandatory and must be unique for transactions you create within an order. A unique Transaction ID is useful for retrieving transactions at a later stage. However, a Transaction ID must always be qualified with the Order ID for a successful retrieve operation.

The Transaction ID is displayed in the Financial Transaction Details page in Merchant Administration as Transaction ID.

Transaction Identifier API Reference[REST][NVP]

[Optional] Order Reference

An optional identifier used to provide some meaningful business-based identifier in the Mastercard Payment Gateway. For example, a shopping cart number, an order number, or an invoice number. Order Reference can be used as a search criteria in Merchant Administration.

It's mandatory to have a unique value for the Order Reference field only if "Enforce Unique Order Reference" privilege is enabled for your merchant profile.

Order Reference API Reference[REST][NVP]

[Optional] Transaction Reference

An optional identifier used to identify the transaction within the Mastercard Payment Gateway. This value is set at the transaction level, and does not have any uniqueness constraints so may be used to suit your requirements. You can search for a transaction using this field in Merchant Administration.

It's mandatory to have a unique value for the Transaction Reference field only if "Enforce Unique Merchant Transaction Reference" privilege is enabled for your merchant profile.

Transaction Reference API Reference[REST][NVP]

[Optional] Correlation ID

A transient identifier used to identify that can be used to match up your requests to the Mastercard Payment Gateway with the responses. The value you provide does not persist in the gateway and is returned as provided in the response to the request. You can use the Correlation ID with all API requests.

You can use this value to match entries in response files with corresponding entries in request files, even when the responses are returned in a different order to the requests.

Copyright © 2023 Mastercard