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.
This feature allows you to perform payments.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
ORDERID | Y | A unique identifier for the order created by the merchant. Maximum 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. |
DATETIME | Y | Request date and time. 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 | 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 Token. |
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. |
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. |
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 Token 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. |
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. |
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. |
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. |
BILLTOLASTNAME | N | First name of the “Bill To” part of a sale |
BILLTOFIRSTNAME | N | Last name of the “Bill To” part of a sale |
DESCRIPTION | N | A description of the transaction. |
XID | N | The XID for a 3D Secure transaction. It should only be provided in case you are not using Worldnet 3D Secure service. If you are, use MPIREF instead to perform a 3DS transaction. |
CAVV | N | The CAVV for a 3D Secure transaction. It should only be provided in case you are not using Worldnet 3D Secure service. If you are, use MPIREF instead to perform a 3DS transaction. |
MPIREF | N | 3D Secure Worldnet Transaction Reference. If you are using the Worldnet 3D Secure service, the response of your request, when successful, will contain this field. |
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. |
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'. |
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 2 Data Validation. |
LEVEL_3_DATA | N | Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See ND006 - Level 3 Data Validation. |
ENHANCED_DATA_TEMPLATE | N | Enhanced Data template name to be used when creating the transaction. It fills up any not provided transaction's enhanced data fields. Note that if you use a template, but inform the data during the request, the gateway is just going to use the template to fill the gaps of whatever you didn't inform in your original request. Also, if you inform at least one item in LEVEL_3_DATA component, no item from template is going to be applied. This field should only be used if you desire to use one of your Enhanced Data Templates (see Merchant Enhanced Data Templates for more details. This field is only available for terminals with Transaction Enhanced Data feature enabled. |
FRAUDREVIEWSESSIONID | N | This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with Sentinel Defence. See the ND003 - Using Sentinel Defence, in the next section. |
THREEDS_PROTOCOL_VERSION | N | For 3rd party MPI only. This can be either 1 or 2. |
DS_TRANS_ID | N | For 3rd party MPI only. String value. |
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 Sentinel Defence
If a merchant wishes to use Sentinel Defence on its website, it must insert the Sentinel Defence scripts to its website. These scripts create a profile on Sentinel Defence servers and are used to validate the user's device..
<!-- Sentinel Defence 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 | Sentinel Defence orgId which is set in their terminal settings on the gateway and/or from their Sentinel Defence 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 2 Data Validation
This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.
To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
CUSTOMER_REF_NUMBER | N | 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 | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
SHIPPING_ADDRESS | N | A subcomponent with all the data related to the shipping address of a purchase. |
FULL_NAME | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
ADDRESS1 | N | 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 | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
REGION | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
POSTCODE | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. |
COUNTRY | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
Quick example:
<LEVEL_2_DATA> <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER> <TAX_AMOUNT>151.27</TAX_AMOUNT> <SHIPPING_ADDRESS> <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME> <ADDRESS1>Unit 001, Street X</ADDRESS1> <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2> <CITY>City "Y"</CITY> <REGION>Region 1</REGION> <POSTCODE>A00B0001</POSTCODE> <COUNTRY>Country "Z"</COUNTRY> </SHIPPING_ADDRESS> </LEVEL_2_DATA>
ND006 - Level 3 Data Validation
This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level III” on the Processing Terminal “Features” section.
To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
SUMMARY | N | Subcomponent of Level 3. Agregates the sums of different values within the transaction. |
TOTAL_DISCOUNT_AMOUNT | N | Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discunts rates (unit price x quantity x discount rate) and any other additional discount applied after that. Decimal value, allowing max of 13 digits with min value of 0. |
TOTAL_FREIGHT_AMOUNT | N | Subfield of SUMMARY. Represents the freight amount applied to the sale. Decimal value, allowing max of 13 digits with min value of 0. |
TOTAL_DUTY_AMOUNT | N | Subfield of SUMMARY. Represents the duty amount applied to the sale. Decimal value, allowing max of 13 digits with min value of 0. |
LINE_ITEMS | N | Subcomponent of Level 3. List of all items in which the sale is broken down. |
LINE_ITEM | N | Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale. |
COMMODITY_CODE | N | Subfield of LINE_ITEM. Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial aggrements level. Consult your Acquirer for more details. |
PRODUCT_CODE | N | Subfield of LINE_ITEM. This is the merchant’s identifier for the product, also known as Universal Product code (UPC). |
DESCRIPTION | N | Subfield of LINE_ITEM. This is the merchant’s description for the product. |
QUANTITY | N | Subfield of LINE_ITEM. Quantity of the specific item for the sale. |
UNIT_OF_MEASURE | N | Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets. |
UNIT_PRICE | N | Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale. |
DISCOUNT_RATE | N | Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes. |
TAX_RATE | N | Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts. |
TOTAL_AMOUNT | N | Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied. |
Quick example:
<LEVEL_2_DATA>...</LEVEL_2_DATA> <LEVEL_3_DATA> <SUMMARY> <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT> <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT> <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT> </SUMMARY> <LINE_ITEMS> <!-- As many as necessary --> <LINE_ITEM> <COMMODITY_CODE>PDX001</COMMODITY_CODE> <PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE> <DESCRIPTION>General services</DESCRIPTION> <QUANTITY>10</QUANTITY> <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE> <UNIT_PRICE>105.50</UNIT_PRICE> <DISCOUNT_RATE>5.00</DISCOUNT_RATE> <TAX_RATE>12.50</TAX_RATE> <TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT> </LINE_ITEM> <LINE_ITEM> <COMMODITY_CODE>PDX002</COMMODITY_CODE> <PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE> <DESCRIPTION>General services</DESCRIPTION> <QUANTITY>2</QUANTITY> <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE> <UNIT_PRICE>85.50</UNIT_PRICE> <DISCOUNT_RATE>5.00</DISCOUNT_RATE> <TAX_RATE>16.00</TAX_RATE> <TOTAL_AMOUNT>188.44</TOTAL_AMOUNT> </LINE_ITEM> </LINE_ITEMS> </LEVEL_3_DATA>
DON'T FORGET
If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a fully qualification for enhanced data.
ND007 - 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'.
<?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> <MPIREF>d01656cf0ec3e62e3754</MPIREF> <HASH>d04c3bab519095ecb046eff91722e8df</HASH> </PAYMENT>
<?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> <MPIREF>d01656cf0ec3e62e3754</MPIREF> <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.
The response body fields will be:
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 Sentinel Defence feature is in use for the Terminal processing the Payment. See ND002 - Sentinel Defence 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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND004 - Secure Token Auto Registration. |
MERCHANTREF | This field represents the merchant reference that is going to be considered for the token generated for the Secure Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND004 - Secure Token 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. |
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 - Sentinel Defence Response
In case the request of a transaction required the Sentinel Defence 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 SelfCare 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 Token Auto Registration
This field is returned when a Secure Token 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 Tokens, and the request in place sends the details for a Secure Token (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>
<?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.
This feature allows you to perform payments.
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 2 Data Validation
This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.
To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
CUSTOMER_REF_NUMBER | N | 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 | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
SHIPPING_ADDRESS | N | A subcomponent with all the data related to the shipping address of a purchase. |
FULL_NAME | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
ADDRESS1 | N | 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 | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
REGION | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
POSTCODE | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. |
COUNTRY | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
Quick example:
<LEVEL_2_DATA> <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER> <TAX_AMOUNT>151.27</TAX_AMOUNT> <SHIPPING_ADDRESS> <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME> <ADDRESS1>Unit 001, Street X</ADDRESS1> <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2> <CITY>City "Y"</CITY> <REGION>Region 1</REGION> <POSTCODE>A00B0001</POSTCODE> <COUNTRY>Country "Z"</COUNTRY> </SHIPPING_ADDRESS> </LEVEL_2_DATA>
The response body fields will be:
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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND004 - Secure Token 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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND003 - Secure Token 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. |
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 Token Auto Registration
This field is returned when a Secure Token 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 Tokens, and the request in place sends the details for a Secure Token (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>
<?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.
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 SelfCare System.
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 Sentinel Defence
If a merchant wishes to use Sentinel Defence on its website, it must insert the Sentinel Defence scripts to its website. These scripts create a profile on Sentinel Defence servers and are used to validate the user's device..
<!-- Sentinel Defence 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 | Sentinel Defence orgId which is set in their terminal settings on the gateway and/or from their Sentinel Defence 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 2 Data Validation
This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.
To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
CUSTOMER_REF_NUMBER | N | 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 | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
SHIPPING_ADDRESS | N | A subcomponent with all the data related to the shipping address of a purchase. |
FULL_NAME | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
ADDRESS1 | N | 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 | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
REGION | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
POSTCODE | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. |
COUNTRY | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
Quick example:
<LEVEL_2_DATA> <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER> <TAX_AMOUNT>151.27</TAX_AMOUNT> <SHIPPING_ADDRESS> <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME> <ADDRESS1>Unit 001, Street X</ADDRESS1> <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2> <CITY>City "Y"</CITY> <REGION>Region 1</REGION> <POSTCODE>A00B0001</POSTCODE> <COUNTRY>Country "Z"</COUNTRY> </SHIPPING_ADDRESS> </LEVEL_2_DATA>
ND007 - 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'.
<?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>
<?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.
The response body fields will be:
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 Sentinel Defence feature is in use for the Terminal processing the Payment. See ND002 - Sentinel Defence 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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND004 - Secure Token Auto Registration. |
MERCHANTREF | This field represents the merchant reference that is going to be considered for the token generated for the Secure Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at ND004 - Secure Token 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. |
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 - Sentinel Defence Response
In case the request of a transaction required the Sentinel Defence 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 SelfCare 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 Token Auto Registration
This field is returned when a Secure Token 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 Tokens, and the request in place sends the details for a Secure Token (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>
<?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.
This feature allows you to perform a completion of a pre-authorization.
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. |
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.
<?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>
<?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.
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. |
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>
<?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.
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.
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. |
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.
<?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.
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. |
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
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. |
<?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.
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.
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. |
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
<?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.
The response body fields will be:
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. |
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.
<?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 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.
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. |
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'.
<?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.
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. |
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.
<?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 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 Token (use the CARDREFERENCE tag).
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 Token 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. |
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. |
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 Token (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 Token (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 Token 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 Token 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'.
<?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>
<?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.
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. |
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.
<?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 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.
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. |
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 |
<?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.
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. |
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>
<?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.
This update feature allows you to add enhanced data to transactions already processed, before they are settled. You need to know the existing transaction before sending your request.
This feature allows you to retrieve a transaction already processed. You need to know the existing transaction before sending your request.
FIELD | REQUIRED | DESCRIPTION |
---|---|---|
TERMINALID | Y | A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID. |
UNIQUEREF | Y/N | Refers the UNIQUEREF generated for the original transaction response.The field is required when ORDERID is ommitted from the request. |
ORDERID | Y/N | Required when UNIQUEREF is not populated.A search can be made using the ORDERID of the transaction. This requires the target terminal to have the setting 'Force Unique Order ID' enabled. |
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. |
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 UNIQUEREF
TERMINALID:UNIQUEREF:DATETIME:SECRET
When using ORDERID
TERMINALID:ORDERID:DATETIME:SECRET
ND002 - Data Encoding for Requests
All data sent to us should be correctly encoded using UTF-8 as the character encoding.
<?xml version="1.0" encoding="UTF-8"?> <GET_TRANSACTION_DETAILS> <TERMINALID>6491002</TERMINALID> <UNIQUEREF>GCNQAWUUVZ</UNIQUEREF> <DATETIME>06-03-2018:17:41:08:273</DATETIME> <HASH>73e340cfb2b7424252d1ced917e4f74704aaa66a9600039f4800434cefe87d721c342d2b915c6e2aeea88b34e749ba97665f7d9e50b1144ca0f0745361fc4896</HASH> </GET_TRANSACTION_DETAILS>
<?xml version="1.0" encoding="UTF-8"?> <GET_TRANSACTION_DETAILS> <TERMINALID>6491002</TERMINALID> <ORDERID>GCNQAWUUVZ</ORDERID> <DATETIME>06-03-2018:17:41:08:273</DATETIME> <HASH>73e340cfb2b7424252d1ced917e4f74704aaa66a9600039f4800434cefe87d721c342d2b915c6e2aeea88b34e749ba97665f7d9e50b1144ca0f0745361fc4896</HASH> </GET_TRANSACTION_DETAILS>
FIELD | DESCRIPTION |
---|---|
TERMINALID | Terminal to which the transaction was submitted. |
UNIQUEREF | Transaction's unique referenced. Same as provided at the request. |
TRANSACTION_STATUS | Current status of the transaction. |
TRANSACTION_DATE | Date time of the transaction's processing. |
OPERATOR | An identifier for who executed this transaction. |
TRANSACTION_TYPE | Indicates if the transaction is a SALE, a REFUND, a PREAUTH or a pre-auth COMPLETION. |
CURRENCY | Transaction's currency. |
AUTHORIZEDAMOUNT | Amount authorized for the transaction. |
ADDITIONAL_DETAILS | Additional details on the transaction, like the result information, custom fields, batch, among other. |
BATCH_NUMBER | Subfield of ADDITIONAL_DETAILS. Indicates the batch number of the transaction, if not in open batch anymore. |
BULK_NUMBER | Subfield of ADDITIONAL_DETAILS. Indicates the number of the bulk in which the transaction was send (only if the transaction was part of a bulk). |
PROCESSINGTERMINAL | Subfield of ADDITIONAL_DETAILS. Indicates the number of the processing terminal of this transaction. Might differ from the TERMINALID if the transaction was submitted to a routing terminal (once the transaction is routed, it goes to a processing terminal). |
RESPONSECODE | Subfield of ADDITIONAL_DETAILS. 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 | Subfield of ADDITIONAL_DETAILS. The text of the authorization. |
APPROVALCODE | Subfield of ADDITIONAL_DETAILS. A six digit AuthCode. |
FOREIGNCURRENCYINFORMATION | Subfield of ADDITIONAL_DETAILS. Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions. |
CARDCURRENCY | Subfield of FOREIGNCURRENCYINFORMATION. Cardholder card's currency code. |
CARDAMOUNT | Subfield of FOREIGNCURRENCYINFORMATION. Amount which is supposed to be charged in the home currency. |
CONVERSIONRATE | Subfield of FOREIGNCURRENCYINFORMATION. Value of the Conversion Rate on original request. |
DESCRIPTION | Subfield of ADDITIONAL_DETAILS. |
TRANSACTION_CUSTOM_FIELDS | Subfield of ADDITIONAL_DETAILS. List of TRANSACTION_CUSTOM_FIELD used with the transaction. |
NAME | Subfield of each TRANSACTION_CUSTOM_FIELD. Name of the custom field used. |
VALUE | Subfield of each TRANSACTION_CUSTOM_FIELD. Value provided for the custom field used. |
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. |
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:TRANSACTION_STATUS:TRANSACTION_DATE:OPERATOR:TRANSACTION_TYPE:CURRENCY:AUTHORIZEDAMOUNT:BATCH_NUMBER:BULK_NUMBER:PROCESSINGTERMINAL:RESPONSECODE:RESPONSETEXT:APPROVALCODE:CARDCURRENCY:CARDAMOUNT:CONVERSIONRATE:DESCRIPTION:DATETIME:SECRET
ND002 - Error Handling
If there is an error processing the request, the error string is returned in an XML message with the simple tags:
<ERROR> <ERRORSTRING>This is the error generated!</ERRORSTRING> </ERROR>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <GET_TRANSACTION_DETAILS_RESPONSE> <TERMINALID>3614008</TERMINALID> <UNIQUEREF>E4RGZYVCME</UNIQUEREF> <TRANSACTION_STATUS>REVIEW</TRANSACTION_STATUS> <TRANSACTION_DATE>26-04-2019:17:19:18:000</TRANSACTION_DATE> <OPERATOR>CardHolder Payment</OPERATOR> <TRANSACTION_TYPE>SALE</TRANSACTION_TYPE> <CURRENCY>USD</CURRENCY> <AUTHORIZEDAMOUNT>52.03</AUTHORIZEDAMOUNT> <ADDITIONAL_DETAILS> <RESPONSECODE>A</RESPONSECODE> <RESPONSETEXT>APPROVAL</RESPONSETEXT> <APPROVALCODE>VVVVWM</APPROVALCODE> <TRANSACTION_CUSTOM_FIELDS> <TRANSACTION_CUSTOM_FIELD> <NAME>Promocode</NAME> <VALUE>sevr9w409vw4v59w45v</VALUE> </TRANSACTION_CUSTOM_FIELD> </TRANSACTION_CUSTOM_FIELDS> </ADDITIONAL_DETAILS> <DATETIME>30-04-2019:14:34:47:707</DATETIME> <HASH>61a587361fa4631a72af9d47395ad0ab81cb6b5928ed8b41ab0860e7cd52c4bc55361f3d3c0b8cf52add999c0c5c07acd6f8f26c0b045d33c0d97489b3f6be9a</HASH> </GET_TRANSACTION_DETAILS_RESPONSE>
REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.
Not all the transaction will return the same fields. Mostly they are similar, but some of them might have less data than what is described by the response field table.