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.
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 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 Suncorp 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 Suncorp 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.
For information on field types and validation rules, see the API Reference.
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.
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.
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.
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 IDAPI PasswordThese 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.
Copyright © 2023 Suncorp