Knowledge Base

Get help for payment solutions. Search our articles or browse by category below.

5.1.2 Pre-Authorisation Request

Pre-authorisation transactions are supported by the acquirer Elavon only. 3D Secure pre-auth transactions are not supported due to scheme restrictions.

The following code is a simple example of a payment request via an XML POST.

<?xml version="1.0" encoding="UTF-8"?>

A response for this transaction would look like the following piece of XML code.

<?xml version="1.0" encoding="UTF-8"?>

The Payment request fields are:


Field Name Required Description
ORDERID Y A unique identifier for the order created by the merchant. (Max 24 characters).
TERMINALID Y A Terminal ID provided by Worldnet. NB-Please contact Worldnet to be issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
CARDNUMBER N The payment card number.
CARDTYPE Y See section 3.2 above.
CARDEXPIRY N 4 digit expiry field (MMYY), required if not using a SecureCard.
CARDHOLDERNAME N The name of the cardholder, required if not using a SecureCard.
HASH Y AN MD5 HASH. See Note 1 below.
CURRENCY Y A 3 character currency code of the transaction. ISO 4217 Currency Code.
FOREIGNCURRENCY INFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions. See XML Payments with eDCC.
TERMINALTYPE Y The type of the terminal:
1 - MOTO (Mail Order/Telephone Order)
2 - eCommerce
4 - MOTO (Mail Order/Telephone Order)
7 - eCommerce
Recurring Payment Flagging:
2 - Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging.
For First Data Latvia terminal MOTO transactions:
4 - Telephone Order
9 - Mail order
If sending XID & CAVV from non Worldnet MPI on an eCommerce transaction use:
0 - not applicable
1 - Single transaction
2 - Recurring transaction
3 - Installment payment
4 - Unknown classification
5 - Fully authenticated transaction 3D Secure transaction.
6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not participate in 3D Secure.
7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted.
8 - Transaction in the clear, or Non Secure.
EMAIL N Cardholder e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by the Self Care terminal Setup setting “Disable Cardholder receipt”.
CVV N The security code entered by the card holder.
ISSUENO N The issue no. of the card (Solo).
ADDRESS1 N The first address field for AVS.
ADDRESS2 N The second address field for AVS.
POSTCODE N The postcode (required) for AVS. Also required for MaxMind MinFraud fraud scoring.
DESCRIPTION N A description of the transaction.
CITY N Required for maxMind MinFraud fraud scoring.
REGION N Required for MaxMind MinFraud fraud scoring. See MaxMind definition of this field as it is forwarded to them without modification.
COUNTRY N ISO 3166-1-alpha-2 code. Required for MaxMind MinFraud scoring.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
FRAUDREVIEWSESSIONID N This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with ThreatMetrix. See Note 2 below for more information.
CUSTOMFIELD'N' N Should also use the “NAME” XML attribute to assign the name of the custom field. See section 3.4 for more info.
RECURRINGTXNREF N Should be set to the value of a UNIQUEREF returned in a PAYMENT response for a non-recurring approved transaction on a matching card. TRANSACTIONTYPE should be set to 2.


1. The MD5 HASH is generated using the following as an input string:


For multi-currency Terminal IDs (see Multi-currency Terminal IDs section on this guide) this should be:


Many code examples on how to generate an MD5 HASH can be found in the Internet. For assistance, please contact Worldnet.

2. If a merchant wishes to use Threat Metrix on its website, it must insert the Threat Metrix scripts to its website. These scripts create a profile on Threat Metrix servers and are used to validate the users device.

<!-- ThreatMetrix Profiling Tags -->
<script type="text/javascript" src=""></script>
    <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src=""></iframe>

The parameters THEIR_ORG_ID and THEIR_SESSION_ID must be supplied by the merchant.

Pamareter Name Description
THEIR_ORG_ID ThreatMetrix orgId which is set in their terminal settings on the gateway and/or from their ThreatMetrix portal. - Up to 32 Chars.
THEIR_SESSION_ID Session Id used to identify session. This must be generated for every new transaction/sale. Do not use a persistent session id. - It can be up to 128 bytes long and must only consist of the following characters - upper and lowercase English letters, digits, underscore or hyphen ([a-z], [A-Z], 0-9, _, -).
PAGEID The pageid is an identifier to be used if you place the tags on multiple pages.

The following fields are returned in the response:


Field Name Description
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding.
RESPONSECODE “A” (APPROVED/ AUTHORIZED/ ACCEPTED, respectively), “D” (DECLINED), “R” (REFERRED, also considered as PICKUP), “C” (PICKUP, also known as Referral A or Referral B), and for more details, look at Transaction Responses.
RESPONSETEXT The text authorisation.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorisation response.
APPROVALCODE Six digit AuthCode.
DATETIME The time of the transaction created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
AVSRESPONSE The result of the AVS check. See Appendix A for more information.
CVVRESPONSE The result of the CVV check. See Appendix A for more information.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
HASH An MD5 HASH. Note 1 below.
FRAUDREVIEWRESPONSE Component of the response that is going to be added in case the Threat Metrix feature is in use for the Terminal processing the Payment. See Note 2.
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT. See Note 2, 3 and 4 below.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk). See Note 2 below.
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk. See Note 2 below.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. Currently two fields are possible to be returned (see note 5): ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.
CARDREFERENCE This field is going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment (see Note 6). This field represents the token generated for the Secure Card.
MERCHANTREF This field is going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment (see Note 6). This field represents the merchant reference that is going to be considered for the token generated for the Secure Card.


1. The MD5 HASH is generated using the following as an input string:


For multi-currency Terminal IDs (see section 3.3 above) this should be:


The DATETIME is the time returned by the bank for the transaction.

Many code examples on how to generate an MD5 HASH can be found in the Internet. For assistance, please contact Worldnet.

2. This field is associate with the feature “Threat Metrix”, and to be used must be enabled for your Gateway. Also, the Terminal used for processing the request needs to be enabled for ThreatMetrix feature so your response contains these fields.

The response component FRAUDREVIEWRESPONSE would look like this inside the response body:


3. If a transaction is returned with “FRAUDREVIEWSTATUS” as “REVIEW”, this transaction can be changed - manually (using the new report feature) or the using the transaction update XML gateway service - to “APPROVE” or “REJECT”.

4. Transactions returned with “FRAUDREVIEWSTATUS” as “REVIEW” are not going to be settled until the transaction status is changed (as defined on Note 3). See Transaction Status Updates page for more details on how to use the transaction update XML gateway service to change the transaction returned as “REVIEW” to “REJECT” or “APPROVE”.

5. This data is going to be retrieved when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings, enabling the “Integration” option “Enable original response in XML”.

6. Three setting can affect the automatic creation of Secure Cards within a payment. On Merchant Portfolio registration, it's possible to define 3 attributes that affect the automatic generation of Secure Cards. If the option When “Enable SC Auto Registration” is selected, then all payments will try to create a secure card during the transaction if the Secure Card doesn't exist withint the Terminal or between all the Merchants of this Merchant Portfolio (in this last case only if the option “Enable SC Uniqueness” is also enabled).

Errors handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

Copyright © 2018 Worldnet Knowledge Base | Powered by DokuWiki
developer/integrator_guide/5._xml_integration/5.1._request_types/5.1.2._preauth_request.txt · Last modified: 2018/02/22 17:48 by tleite