XML Payment Features

Table of Contents


In this feature you can find many different subfeatures which are used to create and manage the transactions performed by merchants' terminals. They are useful in a scenario where your application needs full control of the payment process.

The following resources are the same for all the requests and responses you find on this page:

TYPE URL
Request URL https://testpayments.worldnettps.com/merchant/xmlpayment
XML XSD descriptor https://testpayments.worldnettps.com/merchant/gateway.xsd

Use the Request URL and the Request Body Fields to perform a request for this feature, then prepare your integration to receive the response, as defined by the Response Body Fields.

Payment

This feature allows you to perform payments.

  • Main Request body Tag: <PAYMENT>
  • Main Response body Tag: <PAYMENTRESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Worldnet.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
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 Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
GOOGLEPAYLOAD N When using google pay for payments, instead of the TRACKDATA or CARDNUMBER, you pass this field, with the Google Pay user data, received from your request, converted to Hexadecimal.
APPLEPAYLOAD N When using apple pay for payments, instead of the TRACKDATA or CARDNUMBER, you pass this field, with the Apple Pay user data, received from your request, converted to Hexadecimal.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is 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.
This field should not be informed if the CARDTYPE is SECURECARD.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND004 - Using eDCC, for more details on this field.
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 paricipate 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 Cardholder's e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the 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. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
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. Take a look at 3D Secure.
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 City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code. Required for MaxMind MinFraud fraud scoring complementary service.
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, visit Special Fields and Parameters.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND005 - Level II Data Validation.
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 the ND003 - Using ThreatMetrix, in the next section.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
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'.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using ThreatMetrix

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 user's 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.

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


ND004 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if the wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.


ND005 - Level II Data Validation

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on the Processing Terminal “Features” section.

A few things to consider when using this field:

  • All the fields associated with the feature “Level II Data”, except for SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory” is checked in the Processing Terminal “Features” section.
  • This feature is only available for specific acquirers. Contact our support team to know more.

The request component LEVEL_2_DATA is composed by the following nested elements:

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER Y Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT Y Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY Y Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


ND006 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
	<ORDERID>115010922465</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</PAYMENT>


  • Scenario: Payment using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
	<ORDERID>1150109224656</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>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>6.67</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PAYMENT>  


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding..
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
AUTHORIZEDAMOUNT Only sent for specific acquirers. Partial amount authorized for some transactions.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
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.
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 ND002 - ThreatMetrix Response for more details.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
DATETIME Response date and time for 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.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.



Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET


ND002 - ThreatMetrix Response

In case the request of a transaction required the ThreatMetrix verification, and the Terminal allowed, the result is then sent back in the FRAUDREVIEWRESPONSE field with the following subelements:

FIELD NAME DESCRIPTION
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NE UTRAL or TRUST.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk).
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk.

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>

If a transaction is returned with “FRAUDREVIEWSTATUS” or “REVIEW”, this transaction can be changed to “APPROVE” or “REJECT”. For that, you have two options: let your users do that on the Self Care System, using the new report feature or,through integration, they can use the Transaction Status Update feature, present on this page. Attention to those transactions which stay as “REVIEW”: they are not going to be settled until the transaction status is changed to “APPROVE” or “REJECT”. So, take a look at the Transaction Status Updatee or remind your users to review the transactions constantly/regularly.


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND004 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.


ND005 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?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> 

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Offline Payment

This feature allows you to perform payments.

  • Main Request body Tag: <OFFLINEPAYMENT>
  • Main Response body Tag: <OFFLINEPAYMENTRESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Worldnet.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
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 Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is 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.
This field should not be informed if the CARDTYPE is SECURECARD.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND003 - Using eDCC, for more details on this field.
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 paricipate 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 Cardholder's e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the Terminal Setup settings “Disable Cardholder Receipt”.
ADDRESS1 N The first address. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
BILLTOFIRSTNAME N First name of the “Bill To” part of a sale
BILLTOLASTNAME N Last name of the “Bill To” part of a sale
DESCRIPTION N A description of the transaction.
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 City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code. Required for MaxMind MinFraud fraud scoring complementary service.
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, visit Special Fields and Parameters.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND004 - Level II Data Validation.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
APPROVALCODE Y Approval code provided by the Acquirer for the specific transaction
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if the wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.


ND004 - Level II Data Validation

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on the Processing Terminal “Features” section.

A few things to consider when using this field:

  • All the fields associated with the feature “Level II Data”, except for SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory” is checked in the Processing Terminal “Features” section.
  • This feature is only available for specific acquirers. Contact our support team to know more.

The request component LEVEL_2_DATA is composed by the following nested elements:

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER Y Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT Y Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY Y Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


ND005 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<OFFLINEPAYMENT>
	<ORDERID>115010922465</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<APPROVALCODE>DSIC234Fsdsfc35</APPROVALCODE>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<HASH>33e51227ab83222cea0cc1f03532149319dae3ab8839ad278a82b16d0d15d49bec9e90df00b6504564e3075cb3d984e21471469315526f376a256c557b175a07</HASH>
</PAYMENT>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding..
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
MASKEDCARDNUMBER Customer's card obfuscated card number.
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.
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND002 - Additional Information on Response
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND003 - Secure Card Auto Registration.
DATETIME Response date and time for 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.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET


ND002 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND003 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.


ND004 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<OFFLINEPAYMENTRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<MASKEDCARDNUMBER>4111******111111</MASKEDCARDNUMBER>
	<APPROVALCODE>475318</APPROVALCODE>
	<DATETIME>2005-11-14T12:53:18</DATETIME>
	<CVVRESPONSE>M</CVVRESPONSE>
	<HASH>3a540c54da7a6697cc61d3111a7024b8b8ae9a3d862b859c41a252b188d5d73ecfebc429ca809f60130c5e37b47b0d4494ebfb5f34c244f78c62a7d7a5896dd2</HASH>
</OFFLINEPAYMENTRESPONSE> 

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Pre-Authorization

This feature allows you to perform pre-authorization.

Pre-authorization transactions are supported only by certain Acquirers. 3D Secure pre-auth transactions are not supported due to scheme restrictions.

Check the details with our support team!

Remember that this type of transaction needs to be complemented by the Pre-Authorization Completion! That can be done also by another request (following section) or directly at the Self Care System.

  • Main Request body Tag: <PREAUTH>
  • Main Response body Tag: <PREAUTHRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Worldnet.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
CARDNUMBER N Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is 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.
This field should not be informed if the CARDTYPE is SECURECARD.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND004 - Using eDCC, for more details on this field.
TERMINALTYPE Y The type of 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 paricipate 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 Cardholders e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the 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. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
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. Take a look at 3D Secure.
CITY N City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code . Required for MaxMind MinFraud fraud scoring complementary service.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND005 - Level II Data Validation.
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 the ND003 - Using ThreatMetrix, in the next section.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
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'.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using ThreatMetrix

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 user's 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.

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


ND004 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.


ND005 - Level II Data Validation

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on a/the Processing Terminal “Features” section.

A few things to consider when using this field:

  • All the fields associated with the feature “Level II Data”, except for SHIPPING_ADDRESS2, are mandatory when the “Level II Data Compulsory” is checked in the Processing Terminal “Features” section.
  • This feature is only available for specific acquirers. Contact our support team to know more.

The request component LEVEL_2_DATA is composed by the following nested elements:

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER Y Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT Y Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 Y Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE Y Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY Y Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


ND006 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?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>


  • Scenario: Pre-auth using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTH>
	<ORDERID>100028374319</ORDERID>
	<TERMINALID>6491002</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>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>10.42</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PREAUTH> 


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding. Also used for pre-auth completion, in case the unique ref configuration is enabled.
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
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.
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 ND002 - ThreatMetrix Response for more details.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
DATETIME Response date and time for 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.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.



Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

ND002 - ThreatMetrix Response

In case the request of a transaction required the ThreatMetrix verification, and the Terminal allowed, the result is then sent back at the FRAUDREVIEWRESPONSE field with the following subelements:

FIELD NAME DESCRIPTION
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NEUTRAL or TRUST.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk).
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk.

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>

If a transaction is returned with “FRAUDREVIEWSTATUS” or “REVIEW”, this transaction can be changed to “APPROVE” or “REJECT”. For that, you have two options: let your users do that on the Self Care System, using the new report feature or,through integration, they can use the Transaction Status Update feature, present on this page. Attention to those transactions which stay as “REVIEW”: they are not going to be settled until the transaction status is changed to “APPROVE” or “REJECT”. So, take a look at the Transaction Status Updatee or remind your users to review the transactions constantly/regularly.


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND004 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.

ND005 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<APPROVALCODE>475318</APPROVALCODE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<PROCESSINGTERMINAL>6491002</PROCESSINGTERMINAL>
	<DATETIME>2008-12-18T09:24:17</DATETIME>
	<HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH>
</PREAUTHRESPONSE>  

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Pre-Auth Completion

This feature allows you to perform a completion of a pre-authorization.

  • Main Request body Tag: <PREAUTHCOMPLETION>
  • Main Response body Tag: <PREAUTHCOMPLETIONRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y Refers the UNIQUEREF generate for the original pre-autorization. In case the unique ref configuration is enabled, it's mandatory, otherwise, the system is going to accept the original ORDERID used for the pre-authorization.
TERMINALID Y A Terminal ID provided by Worldnet.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND003 - Using eDCC, for more details on this field.
DESCRIPTION N A description of the transaction.
CVV N The security code entered by the card holder. It should be available when CVV is enabvled for the terminal and completing out of the 15% margin transaction.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.

Examples for a Request

  • Scenario: Simple request to complete a pre-auth, only mandatory fields.
  • Terminal: 6491002.
  • Unique Ref of the original pre-authorization: JJCVGCTOV3.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETION>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>12.31</AMOUNT>
	<DATETIME>19-12-2008:14:47:51:307</DATETIME>
	<CVV>785</CVV>
	<HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH>
</PREAUTHCOMPLETION>


  • Scenario: Pre-auth completion using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Unique Ref of the original pre-authorization: JJCVGCTOV3.
  • Terminal Secret: x4n35c32RT.
  • Important: The foreign currency information in the completion request is useful when completing an “out of 15% tolerance” transaction, because the original pre-auth transaction will be reversed and a new PAYMENT transaction will be authorized instead, and the foreign currency details provided will be used for the new transaction. The original pre-auth exchange rate is used when an eDCC transaction within the 15% tolerance is completed.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETION>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>1001</TERMINALID>
	<AMOUNT>22.38</AMOUNT>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>14.93</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<DATETIME>19-12-2008:14:47:51:307</DATETIME>
	<CVV>785</CVV>
	<HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH>
</PREAUTHCOMPLETION>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding. Also used for pre-auth completion, in case the unique ref configuration is enabled.
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
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.
DATETIME Response date and time for 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.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

ND002 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial pre-auth completion request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
 <?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETIONRESPONSE>
    <UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
    <RESPONSECODE>A</RESPONSECODE>
    <RESPONSETEXT>APPROVAL</RESPONSETEXT>
    <APPROVALCODE>515658</APPROVALCODE>
    <DATETIME>2008-12-18T14:47:51</DATETIME>
    <HASH>93527dbb00534a4b33546161aefe5222</HASH>
</PREAUTHCOMPLETIONRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


eDCC Exchange Rate

Direct XML transactions (Payment, Pre-Auth and Pre-Auth Completion) can be DCC (Dynamic Currency Conversion) enabled. This is useful when card and terminal currencies are different. Our Payment Gateway supports Currency Conversion Rate requests. Merchant applications can request Conversion Rate for the card then the cardholder has to decide if he/she would like to use the eDCC service after which the appropriate request to the TPS will be sent. All eDCC enabled XML transaction requests should include the additional FOREIGNCURRENCYINFORMATION tag with all required nested tags.

DCC transactions are allowed for the eDCC-enabled terminals only. DCC support for the terminal can be enabled or disabled by our support team only, and it's not available on multi-currency Terminals.

This feature allows you to obtain eDCC exchange rates for specific terminals, depending on the Terminal's settings.

  • Main Request body Tag: <GETCARDCURRENCYRATE>
  • Main Response body Tag: <CARDCURRENCYRATERESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
CARDBIN Y BIN. The first 6 digits from the Card Number.
BASEAMOUNT N Transaction amount in the base currency. If sent Worldnet will return the correctly formatted and calculated FOREIGNAMOUNT.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:CARDBIN:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


Examples for a Request

  • Scenario: Simple request.
  • Terminal: 1001.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<GETCARDCURRENCYRATE>
	<TERMINALID>1001</TERMINALID>
	<CARDBIN>411111</CARDBIN>
	<DATETIME>27-06-2007:16:50:02:123</DATETIME>
	<HASH>15f6c0f0b51faff9cbb77220ab8ddfce</HASH>
</GETCARDCURRENCYRATE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
TERMINALCURRENCY Terminal's currency code. ISO 4217 Currency Code.
CARDCURRENCY Card's currency code. ISO 4217 Currency Code.
CONVERSIONRATE Conversion rate. See note 2 below.
EXCHANGERATESOURCENAME Source of rates. Display on decision page.
MARGINPERCENTAGE Margin percentage applied.
COMMISSIONPERCENTAGE Commission percentage applied.
FOREIGNAMOUNT Converted amount.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALCURRENCY:CARDCURRENCY:CONVERSIONRATE[1]:DATETIME:SECRET

  • [1] - CONVERSIONRATE: In this string CONVERSIONRATE must be a decimal value with 6 decimal places separated by dot character (‘.’), example: ‘0.123000’.


ND002 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


ND003 - Response Codes - Errors

Error Code Description
101 Terminal not found.
102 BIN not found.
103 Currencies are not the same.
104 eDCC is not allowed for the terminal.
105 Invalid card currency/Unknown currency.
106 Conversion rate not found.
107 Invalid Request format.
108 Invalid hash in the request.
109 Other error.
110 Internal error.
111 Unsupported card currency.


Examples for the Response

  • Scenario: Response to the simple request.
  • Terminal: 1001.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CARDCURRENCYRATERESPONSE>
	<TERMINALCURRENCY>EUR</TERMINALCURRENCY>
	<CARDCURRENCY>GBP</CARDCURRENCY>
	<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	<EXCHANGERATESOURCENAME>Imaginary Bank</EXCHANGERATESOURCENAME>
	<MARGINPERCENTAGE>1.50</MARGINPERCENTAGE>
	<COMMISSIONPERCENTAGE>1.00</COMMISSIONPERCENTAGE>
	<FOREIGNAMOUNT>15.98</FOREIGNAMOUNT>
	<DATETIME>27-06-2007:16:50:02:999</DATETIME>
	<HASH>a12a10322f5af4a8a419f7dc1c6dd39f</HASH>
</CARDCURRENCYRATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Multi Currency Exchange Rate

Some Acquiring Banks support Multi-currency Terminals. They allow Merchants processing transactions in one of a number of pre-defined currencies for a Terminal. This option allows Merchants to retrieve rates daily when using MCP Terminals, making possible to verify the accurate pricing of the currencies they desire to process transactions on.

This option is only available for TSYS Saratoga terminals, but if have any questions, Worldnet will inform you if your Terminal ID supports multi-currency. Contact our integration team if you have any questions relating to multi-currency terminals.

  • Main Request body Tag: <GETFXCURRENCYRATE>
  • Main Response body Tag: <FXCURRENCYRATERESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
FXCURRENCY Y Configured currency (at terminal level) to which you desire to know the current conversion rate.
BASEAMOUNT N Transaction amount in the base currency of your terminal (not related to the FXCURRENCY). If sent, Worldnet will return the correctly formatted and calculated FOREIGNAMOUNT, and only for informational purpose, the terminal base currency.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:FXCURRENCY:DATETIME:SECRET


Examples for a Request

  • Scenario: Simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<GETFXCURRENCYRATE>
	<TERMINALID>6491002</TERMINALID>
	<FXCURRENCY>EUR</FXCURRENCY>
	<BASEAMOUNT>12</BASEAMOUNT>
	<DATETIME>12-01-2018:11:47:04:656</DATETIME>
	<HASH>f7690c9ceaab0708415d370c8e28998cd29634985ef0cb036f969186a2c97a7934b8277c7153277180acfb61e78c1f37d70bf53d066362d9ebed8d1fca584575</HASH>
</GETFXCURRENCYRATE>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
TERMINALCURRENCY Base currency for the terminal.
FXCURRENCY Currency used to recover the conversion rate in relation to the terminal base currency.
CONVERSIONRATE Recovered relation between the (Response) Terminal Currency and the (Requested) Conversion currency.
FOREIGNAMOUNT Multiplication of the (Requested) Base Amount and the (Response) Conversion Rate recovered.
DATETIME Response date and time for the response.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALCURRENCY:FXCURRENCY:CONVERSIONRATE:DATETIME:SECRET


ND002 - Converting the Base Amount and Retrieving the

If the BASEAMOUNT is not informed on request, the FOREIGNAMOUNT is not generated, but the CONVERTIONRATE and the TERMINALCURRENCY are.


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<FXCURRENCYRATERESPONSE>
	<TERMINALCURRENCY>USD</TERMINALCURRENCY>
	<FXCURRENCY>EUR</FXCURRENCY>
	<CONVERSIONRATE>0.889639</CONVERSIONRATE>
	<FOREIGNAMOUNT>10.68</FOREIGNAMOUNT>
	<DATETIME>20-09-2018:07:23:56:416</DATETIME>
	<HASH>ec14da3eddccf97279a32a3e90bff487facaa19c22fc88c6ebd48a2c1cd29473c3c05044732784c295fd8ae49db8f2281bf8d16accbdab880ae94b2232fa259e</HASH>
</FXCURRENCYRATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Standard Refund

Standard refunds can be performed on any authorized transactions in the Worldnet system, either in the Open Batch or Closed Batch. By default you can refund any amount up to 100% of the original transaction value. If multiple partial refunds are performed then the sum total of them cannot exceed 100% either. This is to prevent fraud. This 100% value is configurable at a Terminal level and if you wish to alter it please contact support@worldnettps.com with a reason why you need it altered.

  • Main Request body Tag: <REFUND>
  • Main Response body Tag: <REFUNDRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y Refers the UNIQUEREF generate for the original payment response. In case the unique ref configuration is enabled, it's mandatory, otherwise, the system is going to accept the original ORDERID used for the pre-authorization. Either UNIQUEREF or ORDERID should be used, but never both.
TERMINALID Y A Terminal ID provided by Worldnet.
AMOUNT Y The amount of the transaction. A 2 digit decimal or an integer value for JPY amounts.
OPERATOR Y An identifier for who executed this transaction.
REASON Y The reason for the refund.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Simple request, only mandatory data.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<REFUND>
	<UNIQUEREF>Q8F40S2V</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
	<REASON>Faulty Goods</REASON>
</REFUND>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking this transaction.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
TERMINALID A Terminal ID provided by Worldnet.
AMOUNT The amount of the transaction. A 2 digit decimal or an integer value for JPY amounts.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET


ND002 - 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>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


Examples for the Response

  • Scenario: .
  • Terminal: .
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<REFUNDRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</REFUNDRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Unreferenced Refund

Unreferenced refunds are refunds that do not require a payment transaction to be referenced. They are only available on certain accounts by request to support@worldnettps.com and must also be approved by your Acquiring (merchant) bank. As an Unreferenced Refund does not refer to a payment transaction, it's necessary to inform the card on which the refund is going to. In this case, you have two possibilities: inform the card details (use the CARDDETAILS tag) or a valid Secure Card (use the CARDREFERENCE tag).

  • Main Request body Tag: <UNREFERENCEDREFUND>
  • Main Response body Tag: <UNREFERENCEDREFUNDRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant. Maximum of 24 characters.
CURRENCY N Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
TERMINALID Y A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
CARDREFERENCE N Secure Card reference generated and returned by the Payment Gateway when created. Either CARDREFERENCE or CARDETAILS should be used on request, never both.
CARDDETAILS N Details of the card to which the refund is going to be done to. Take a look at ND003 - Card Details to see this tag's subelements. Either CARDREFERENCE or CARDETAILS should be used on request, never both.
AMOUNT Y The amount of the transaction. A 2 digit decimal or an Integer value for JPY amounts.
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 An email address to send a confirmation email to. Normally this is cardholder email address.
OPERATOR Y An identifier for who executed this transaction.
DESCRIPTION N The description for the refund.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Secure Card (CARDREFERENCE) and a Single Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Secure Card (CARDREFERENCE) and a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET

When NOT using a Secure Card and using a Single Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:AMOUNT:DATETIME:SECRET

When NOT using a Secure Card and using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Card Details

The CARDDETAILS tag has nested elements to represent the card information, as it follows:

FIELD REQUIRED DESCRIPTION
CARDNUMBER N Payment card number.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY).
CARDHOLDERNAME N The name of the card holder.


ND004 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Request to a specific card.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUND>
	<ORDERID>115073134</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<CARDDETAILS>
		<CARDTYPE>VISA</CARDTYPE>
		<CARDNUMBER>4111111111111111</CARDNUMBER>
		<CARDEXPIRY>0807</CARDEXPIRY>
		<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	</CARDDETAILS>
	<AMOUNT>10.00</AMOUNT>
	<EMAIL>cardholder_email@worldnettps.com</EMAIL>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
</UNREFERENCEDREFUND>


  • Scenario: Request to a valid Secure Card.
  • Terminal: 6491002.
  • Secure Card: 2967534771694736 (CARDREFERENCE).
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUND>
	<ORDERID>115073134</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<CARDREFERENCE>2967534771694736</CARDREFERENCE>
	<AMOUNT>10.00</AMOUNT>
	<EMAIL>cardholder_email@worldnettps.com</EMAIL>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
</UNREFERENCEDREFUND>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking this transaction.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with the processing terminal ID that the system selected to process the transaction.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

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


ND002 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUNDRESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<UNIQUEREF>G53D0M1S4</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</UNREFERENCEDREFUNDRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Transaction Status Update

Transaction updates allow you to update the status of a transaction in the Open Batch. You need to know the existing status of the transactions in order to update it.

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y The unique reference for the transaction being updated.
OPERATOR Y An identifier for who executed this update.
FROMSTATUS Y The current status of the transaction. Limited by ND003 - Status Changing Constraints.
TOSTATUS Y The status the transaction is going to assume. Limited by ND003 - Status Changing Constraints.
AUTHCODE N The approval code of the referral. Only required if changing a REFERRAL to PENDING or READY.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:OPERATOR:FROMSTATUS:TOSTATUS:APPROVALCODE:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Status Changing Constraints

Transactions' statuses can be updated as long as the change respect the following constraints:

FROMSTATUS > TOSTATUS READY PENDING DECLINED
READY NO YES NO
PENDING YES NO NO
REFERRAL YES YES NO
REVIEW YES YES YES


Examples for a Request

  • Scenario: Simple request, minimum data.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTIONUPDATE>
	<UNIQUEREF>Q8F40S2V</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<OPERATOR>Test Operator</OPERATOR>
	<FROMSTATUS>PENDING</FROMSTATUS>
	<TOSTATUS>READY</TOSTATUS>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
</TRANSACTIONUPDATE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
RESPONSECODE Updated transaction response code.
RESPONSETEXT Updated transaction response text.
UNIQUEREF The unique reference for the transaction being updated.
TERMINALID A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:RESPONSECODE:RESPONSETEXT:UNIQUEREF:DATETIME:SECRET


ND002 - 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>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTIONUPDATERESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</TRANSACTIONUPDATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International