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"?>
<PREAUTH>
	<ORDERID>100028374319</ORDERID>
	<TERMINALID>6491999</TERMINALID>
	<AMOUNT>15.62</AMOUNT>
	<DATETIME>18-12-2008:09:24:16:105</DATETIME>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>1109</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<HASH>9c58e8d7ff9eb98db4ece2af75dec6ae</HASH>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PREAUTH>


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

<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHRESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<APPROVALCODE>475318</APPROVALCODE>
	<DATETIME>2008-12-18T09:24:17</DATETIME>
	<CVVRESPONSE>M</CVVRESPONSE>
	<HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH>
	<PROCESSINGTERMINAL>6491002</PROCESSINGTERMINAL>
</PREAUTHRESPONSE>  


The Payment request fields are:

Filter:

Field Name Required Description
ORDERID Y A unique identifier for the order created by the merchant. (Max 12 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.
DATETIME Y Format: DD-MM-YYYY:HH:SS:SSS.
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
TRANSACTIONTYPE Y Normally:
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.


Notes:

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

TERMINALID+ORDERID+AMOUNT+DATETIME+secret

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

TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+secret

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="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORD_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></script>
<noscript>
    <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORG_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></iframe>
</noscript>

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:

Filter:

Field Name Description
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding.
RESPONSECODE A or D or R (Approval or Declined or Referral).
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.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NEUTRAL or TRUST. See Note 2 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.



Notes:

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

TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+BANKRESPONSECODE+secret

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

TERMINALID+UNIQUEREF+CURRENCY+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+secret

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:

<FRAUDREVIEWRESPONSE>
    <FRAUDREVIEWSTATUS>PASS</FRAUDREVIEWSTATUS>
    <FRAUDREVIEWRISKRATING>LOW</FRAUDREVIEWRISKRATING>
    <FRAUDREVIEWSCORE>-10</FRAUDREVIEWSCORE>
    <FRAUDREVIEWREASONCODE>Profiling Blocked,Profiling Incomplete</FRAUDREVIEWREASONCODE>
</FRAUDREVIEWRESPONSE>

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



Errors handling

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

<ERROR><ERRORSTRING></ERRORSTRING></ERROR>
Copyright © 2017 Worldnet Knowledge Base | Powered by DokuWiki
developer/integrator_guide/5._xml_integration/5.1._request_types/5.1.2._preauth_request.txt · Last modified: 2017/10/26 10:01 by tleite