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. For a basic understanding of orders and transactions, see Orders and Transactions.

Order Identifier

The 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 (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 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.

Order ID API Reference[REST][NVP]

Order Reference

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.

Order Reference API Reference[REST][NVP]

Order Identifier for the Acquirer

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.

Contact your payment service provider to see if this is supported for your acquirer.

Acquirer Order Identifier API Reference[REST][NVP]

You can provide the and either or both of order.reference and transaction.acquirer.transactionId to get fine control over the identity in each system.
Transaction Identifier

The Mastercard Payment Gateway has a unique identifier that it uses to identify each transaction within the order. This identifier is called the (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.

Transaction Identifier API Reference[REST][NVP]

For information on field types and validation rules, see the API Reference.

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).

Field Constraints in the HTML Form

Not every field can be displayed in the HTML form hence you must take care on what to display, what to calculate in the code, and what not to tag as hidden fields.

What Fields Should I Display?

It is very important to the security of your integration to ONLY expose the minimum amount of data to your payer. With this in mind, you should only ever render form fields that require input from the payer.

Do NOT ever use hidden form fields (<input type="hidden" />) to pass information relevant to processing a transaction, especially for fields like amount, Merchant ID and API Password.

It is an industry best practice (and potentially a security requirement) to only include form fields that require user input. Using hidden fields to store or pass any data is not acceptable, as these fields are exposed to the payer and can be edited by someone with a malicious intent to potentially process fraudulent transactions or worse.

What Fields Should I Never Expose and Always Calculate?

The previous section outlined the best practice of only using form fields that require user input. Most importantly, you should NEVER expose the following fields to a payer (including using a hidden field):

  • Merchant ID
  • API Password

These values should be stored securely by your application/website in a configuration file or database. If a fraudulent user were to gain access to this data, your account would be susceptible to a potential attack.

In addition to the above fields, other fields should also be treated with extreme care. For example, amount should always be calculated immediately before sending the transaction. If you store amount as a hidden field, then a fraudulent payer could alter the amount, and without the right checks in your integration, the payer may manipulate the transaction for $1 instead of $100.
As a best practice, you should only use form fields that require input from the payer.

Merchant ID API Reference[REST][NVP]

API Password API Reference[REST][NVP]

Copyright © 2023 Mastercard