Knowledge Base

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

5.1.1 XML Payments

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

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
	<ORDERID>115010922465</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
	<CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD>
</PAYMENT>


For testing purposes, this piece of XML code can be posted to:

https://testpayments.worldnettps.com/merchant/xmlpayment


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

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<APPROVALCODE>475318</APPROVALCODE>
	<DATETIME>2005-11-14T12:53:18</DATETIME>
	<CVVRESPONSE>M</CVVRESPONSE>
	<HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH>
</PAYMENTRESPONSE> 


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:MM:SS:SSS.
TRACKDATA N Track 2 data should be present for a swiped cardholder present (CHP) transaction. If this is present then TERMINALTYPE should be set to 3 and TRANSACTIONTYPE should be set to 0.
CARDNUMBER N The payment card number, required if TRACKDATA is not being sent.
CARDTYPE Y See section 3.2 above.
CARDEXPIRY N 4 digit expiry field (MMYY), required if TRACKDATA is not being sent and not using a SecureCard.
CARDHOLDERNAME N The name of the card holder, required if TRACKDATA is not being sent and not using a SecureCard. It should be as displayed on the front of the card.
HASH Y An MD5 HASH. See Note 1 below.
CURRENCY Y A 3 character currency code of the transaction. ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION 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 terminal:
1 - MOTO (Mail Order/Telephone Order)
2 - eCommerce
3 - Cardholder Present.
TRANSACTIONTYPE Y Normally:
0 - Cardholder Present (CHP) transaction
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
AUTOREADY N Y or N - If this is set to Y Worldnet will automatically set the transaction to READY in the batch. If set to N then the transaction will go to a PENDING status. If not present the terminal default will be used.
EMAIL N Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by Self Care Terminal Setup settings “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.
XID N The XID for a 3D Secure transaction.
CAVV N The CAVV for a 3D Secure transaction.
MPIREF N 3d-Secure Worldnet Transaction Reference supplied in Worldnet MPI transactions.
MOBILENUMBER N Used for SMS receipts. International format, numeric only.
DEVICEID N The unique identifier string for a connecting device. Mandatory for non-server based devices such as handheld devices/cash register etc.
PHONE N Card Holder Phone Number stored against transaction. International format, numeric only.
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 fraud scoring.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
SIGNATURE N Optional field if processing Cardholder Present (CHP) transactions using the TRACKDATA field. For format see Appendix B.
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 UNIQREREF returned in a Payment response for 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 section 3.3 above) this should be:

TERMINALID+ORDERID+CURRENCY+AMOUNT+DATETIME+secret


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 (Approved or Declined or Referral).
RESPONSETEXT The text of the authorization.
APPROVALCODE Six digit AuthCode.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorisation response.
AUTHORIZEDAMOUNT Only sent for specific acquirers. Partial amount authorised for some transactions.
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. See 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 [[developer:integrator_guide:5._xml_integration:5.2._transaction_status_updates|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”.

Error 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.1._xml_payments.txt · Last modified: 2017/11/13 12:13 by fernando