Payment Protocols > XML Hosted 3D Secure Protocol > Payment

Payment

The first phase of the payment consists og transmitting the preliminary payment data to the Gateway, such as amount, currency, order reference and url to continue the payment.

To improve and speed up the shopping experience, the 3DSecure 2.2 protocol has been adopted. To use the service, refer to section 3D Secure 2.2.

After receiving this data, the Gateway returns an output in XML format, a unique PaymentId, a security token, and the page url to enter the credit card details.

Example of HTTP Payment Initialisation message

id=99999999&password=99999999&tenantId=10&operationType=initialize&amount=1.00&currencyCode=978& language=ITA&responseToMerchantUrl=http://www.merchant.it/notify.jsp& recoveryUrl=http://www.merchant.it/error.jsp&merchantOrderId=TRCK0001&description=Description& cardHolderName=NameSurname&cardHolderEmail=name@domain.com& customField=customField

Call parameters of HTTP payment message for Payment Initialisation

NAME

DESCRIPTION

FORMAT

id	Id associated with terminal	N Max. length: 8
password	Terminal id password	AN Max. length: 50
tenantId	Identification code of the acquiring service to which the merchant belongs. In the case of a merchant having an agreement with Intesa enter "10", otherwise enter "20".	N
operationType	"initialize": to make a normal payment. "initializecardverification": to perform a card verification (ASI) without charge, in order to verify the validity of a card. In this mode it will be necessary to value the "amount" field to 0. "initializepreauthorization": to perform a preauthorization, ie a temporary block of a specific amount on a payment card. It will then be necessary to perform a total or partial accounting operation, if this operation is not performed within the time limit set in the back office, the Gateway will unlock the pre-authorized amount.	AN Max. length: 50
amount	Transaction amount using the point as decimal separator (e.g. 1428,76€ = "1428.76"). The decimal portion may vary depending on the currency	N Int. 18 - Dec. 4
language	Language in which the Hosted Page will be displayed. The possible values are those shown in the table Language codes	AN Max. length: 3
responseToMerchantUrl	Url to which the transaction outcome must be notified	AN Max. length: 2048
merchantOrderId	Transaction reference sent by the merchant during Initialization (can contain only letters and numbers and must be absolutely unique)	AN Max. length: 18
currencyCode	Currency numeric code (optional – default '978' [euro])	N Max. length: 3
recoveryUrl	Url to which the holder must be redirected if you cannot obtain a resultUrl in notification phase	AN Max. length: 2048
description	Payment description that will be displayed on the payment page at the homonymous field	AN Max. length: 255
cardHolderName	Cardholder name	Object Max. length: 125
cardHolderEmail	Cardholder's e-mail address to which the payment outcome must be notified	AN Max. length: 125
customField	Custom field that will be returned in notification phase	AN Max. length: 255

                                        Example of XML message for Payment Initialisation response                                    

                                    <?xml version="1.0" encoding="UTF-8"?>
<response>
 <paymentid>123456789012345678</paymentid>
 <securitytoken>80957febda6a467c82d34da0e0673a6e</securitytoken>
 <hostedpageurl>https://www.monetaonline.it/monetaweb/...</hostedpageurl>
</response>
                                

Parameters of response to Payment Initialisation message

NAME

DESCRIPTION

FORMAT

paymentid	Id associated to the payment session	AN Max. length: 18
securitytoken	Security token	AN Max. length: 32
hostedpageurl	Payment page url to which the cardholder is directed	AN Max. length: 255

Cardholder redirection to payment page

After receiving an initialisation message response, the web session of the cardholder must be redirected to the url specified in the hostedPageUrl tag to which the paymentid parameter must be appended. This url must not be set as fixed parameter for redirection but must be retrieved dynamically for every payment from the appropriate tag.

PAY ATTENTION: this url can not be inserted into an i-frame.

Once the cardholder is on the payment page, he will enter the data for his credit card and, if the card is part of the 3D Secure program, he will also be prompted to enter the relevant 3D Secure password.

<?php

// XML Hosted 3D Secure Protocol - Payment Initialisation

$merchantDomain = 'http://127.0.0.1';

$PaymentGatewayDomain = 'https://ngwecomm-stg.nexi.it';
$terminalId = '44000001';
$terminalPassword = 'Password1';
$tenantId = '10';

if ($_SERVER['REQUEST_METHOD'] === 'GET') {
?>
	<!DOCTYPE html>
	<html>
		<body>
			<form action="" method="POST">
				<input type="submit" value="Buy Now" name="button">
			</form>
		</body>
	</html>
<?php
} else {
  $parameters = array(
	  'id' => $terminalId,
	  'password' => $terminalPassword,
          'tenantId' => $tenantId, //  In the case of a merchant having an agreement with Intesa enter "10", otherwise enter "20"
	  'operationType' => 'initialize',
	  'amount' => '1.00',	  
	  'language' => 'ITA',
	  'responseToMerchantUrl' => $merchantDomain.'/notify.php',
          'merchantOrderId' => 'TRCK0001',<currencyCode>
          'currencyCode' => '978',</currencyCode><recoveryUrl>
	  'recoveryUrl' => $merchantDomain.'/recovery.php',</recoveryUrl><description>
          'description' => 'Descrizione',</description><cardHolderName>
          'cardHolderName' => 'Tom Smith',</cardHolderName><cardHolderEmail>
          'cardHolderEmail'  => 'tom.smith@test.com',</cardHolderEmail><customField>	  
          'customField' => 'Custom Field'</customField>
  );

$curlHandle = curl_init();
  curl_setopt($curlHandle, CURLOPT_URL, $PaymentGatewayDomain.'/monetaweb/payment/2/xml');
  curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($curlHandle, CURLOPT_POST, true);
  curl_setopt($curlHandle, CURLOPT_POSTFIELDS, http_build_query($parameters));
  $xmlResponse = curl_exec($curlHandle);
  curl_close($curlHandle);

$response = new SimpleXMLElement($xmlResponse);
  $paymentId = $response->paymentid;
  $paymentUrl = $response->hostedpageurl;

$securityToken = $response->securitytoken;

$PaymentPageUrl = "$paymentUrl?PaymentID=$paymentId";
  header("Location: $PaymentPageUrl");
}
?>

package sample;

import sample.utils.SampleHttpClient;
import sample.utils.InitResponse;

// XML Hosted 3D Secure Protocol - Payment Initialisation

public class Buy {

public String performInit(InitData initData) throws Exception {
		MerchantData dataToSend = new MerchantData();

dataToSend.id = initData.Id;
		dataToSend.password = initData.password;
                dataToSend.tenantId= initData.tenantId;
		dataToSend.operationType = initData.operationType;
		dataToSend.amount = initData.amount;
		dataToSend.language = initData.language;
		dataToSend.responseToMerchantUrl = initData.responseToMerchantUrl;
		dataToSend.merchantOrderId = initData.merchantOrderId;
                dataToSend.description = initData.description;	<currencyCode>
                dataToSend.currencyCode = initData.currencyCode;</currencyCode><recoveryUrl>
                dataToSend.recoveryUrl = initData.recoveryUrl;</recoveryUrl><cardHolderName>
                dataToSend.cardHolderName = initData.cardHolderName;</cardHolderName><cardHolderEmail>
                dataToSend.cardHolderEmail = initData.cardHolderEmail;</cardHolderEmail><customField>
                dataToSend.customField = initData.customField;</customField>

String xmlResponse = SampleHttpClient.sendPost(initData.initURL, dataToSend.getFormattedParameters());
		System.out.println("xmlResponse:\n" + xmlResponse);

InitResponse initResponse = new InitResponse(xmlResponse);
		if (!initResponse.containsErrors()) {
			// il security token è una misura di sicurezza ulteriore:
			// è un codice casuale che verrà spedito anche nelle fasi successive
			// del
			// pagamento per assicurare la genuinità della risposta.
			@SuppressWarnings("unused")
			String securityToken = initResponse.getSecuritytoken();

String paymentPageUrl = initResponse.getCardholderRedirectUrl();

// la GUI poi farà una redirect al paymentPageUrl

return paymentPageUrl;
		} else
			throw new Exception("Payment initialization failure");
	}

}

using System;
using System.Collections.Generic;
//using System.Linq;
using System.Web;
using System.Xml;
using System.Net;

// XML Hosted 3D Secure Protocol - Payment Initialisation

namespace AspNetAntiguaHosted
{
    public class Buy
    {

public string PerformInit()
        {
            string htmlRes = string.Empty;
            MerchantData dataToSend = new MerchantData();
            InitData initData = new InitData();

dataToSend.id = initData.Id;
	    dataToSend.password = initData.password;
            dataToSend.tenantId= initData.tenantId;
            dataToSend.operationType = initData.operationType;
            dataToSend.amount = initData.amount;
	    dataToSend.language = initData.language;
            dataToSend.responseToMerchantUrl = initData.responseToMerchantUrl;
            dataToSend.merchantOrderId = initData.merchantOrderId;
            dataToSend.description = initData.description;<currencyCode>
            dataToSend.currencyCode = initData.currencyCode;</currencyCode><recoveryUrl>
            dataToSend.recoveryUrl = initData.recoveryUrl;</recoveryUrl><cardHolderName>
            dataToSend.cardHolderName = initData.cardHolderName;</cardHolderName><cardHolderEmail>
            dataToSend.cardHolderEmail = initData.cardHolderEmail;</cardHolderEmail><customField>
            dataToSend.customField = initData.customField;</customField>

using (WebClient wc = new WebClient())
            {
                wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";

htmlRes = wc.UploadString(initData.initURL, dataToSend.GetFormattedParameters());
            }

XmlDocument xml = new XmlDocument();
            xml.LoadXml(htmlRes);
            String paymentid = (xml.GetElementsByTagName("paymentid").Item(0)).InnerText;
            String hostedpageurl = (xml.GetElementsByTagName("hostedpageurl").Item(0)).InnerText;
            String securityToken = (xml.GetElementsByTagName("securitytoken").Item(0)).InnerText;

string paymentPageUrl = hostedpageurl + "?paymentid=" + paymentid;
            
            // the GUI must perform something like Response.Redirect(paymentPageUrl);

return paymentPageUrl;
        }
    }
}

<%@ Language=vbScript%>

' XML Hosted 3D Secure Protocol - Payment Initialisation

dim xmlhttp, DataToSend, DataToSend1, DataToSend2, DataToSend3, URL, varResponse, varPaymentID, varRedirectURL, varSecurityToken
dim initURL, Id, password, operationType,amount, language, currencyCode, responseToMerchantUrl, recoveryUrl, merchantOrderId, cardHolderName, cardHolderEmail, description, customField

initURL = "https://test.monetaonline.it/monetaweb/payment/2/xml"
id = "44000001"
password = "Password1"
tenantId = "10" ' In the case of a merchant having an agreement with Intesa enter "10", otherwise enter "20"
operationType = "initialize"
amount = "1.00"
language = "ITA"
responseToMerchantUrl = "http://127.0.0.1/response.asp"
merchantOrderId = "TRCK0001"<currencyCode>
currencyCode = "978"</currencyCode><recoveryUrl>
recoveryUrl = "http://127.0.0.1/error.asp"</recoveryUrl><cardHolderName>
cardHolderName = "Tom Smith"</cardHolderName><cardHolderEmail>
cardHolderEmail  = "tom.smith@test.com"</cardHolderEmail><description>
description = "Description"</description><customField>
customField = "Custom Field"</customField>

DataToSend1 = "id=" + id + "&password=" + password + "&tenantId=" + tenantId + "&operationType=" + operationType + "&amount=" +amount + "&language=" + language
DataToSend2 = <currencyCode>"&currencycode=" + currencyCode + </currencyCode>"&responseToMerchantUrl=" + responseToMerchantUrl + <recoveryUrl>"&recoveryUrl=" + recoveryUrl + </recoveryUrl>"&merchantOrderId=" + merchantOrderId
DataToSend3 = <cardHolderName>"&cardHolderName=" + cardHolderName + </cardHolderName><cardHolderEmail>"&cardHolderEmail=" + cardHolderEmail + </cardHolderEmail><description>"&description=" + description + </description><customField>"&customField=" + customField</customField>

DataToSend = DataToSend1 + DataToSend2 + DataToSend3

set xmlhttp = server.Createobject("MSXML2.ServerXMLHTTP") 'da usare solo se XMLParser è installato sulla macchina
'Set xmlhttp = Server.CreateObject("Microsoft.XMLHTTP") 'Altrimenti usare questo metodo

'Apro la connessione
xmlhttp.Open "POST",initURL,false

'Imposto gli headers HTTP
xmlhttp.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"

'Invio i dati
xmlhttp.send DataToSend

set objXML = server.CreateObject("microsoft.xmldom")
objXML.async=false
objXML.load(xmlhttp.responsebody)

varPaymentId = objXML.selectSingleNode("//paymentid").Text
varRedirectURL= objXML.selectSingleNode("//hostedpageurl").Text
varSecurityToken= objXML.selectSingleNode("//securitytoken").Text

'Creo l'URL di redirezione
varRedirectURL = varRedirectURL & "?PaymentID=" & varPaymentId

'Redirezione finale del browser sulla HPP
Response.Redirect varRedirectURL

class Buy < WEBrick::HTTPServlet::AbstractServlet

# XML Hosted 3D Secure Protocol - Payment Initialisation

# Returns the page with the BUY button
	def do_GET(request, response)
		response.status = 200
		response.content_type = 'text/html'
		payment_page = "
		<!DOCTYPE html>
		<html>
			<body>
				<form action='buy' method='POST'>
					<input type=submit value='Buy Now'>
				</form>
			</body>
		</html>
		"
		response.body = payment_page
	end

# Responds to the action called by the BUY button
	# Manages the transaction initialization and redirects the card holder to the XPay Total Acceptance payment page
	def do_POST(request, response)
		hosted_page_url = initialize_transaction()
		response.set_redirect(WEBrick::HTTPStatus[303], hosted_page_url)
	end

def initialize_transaction()
		require 'net/http'
		require 'rexml/document'

payment_gateway_domain = 'https://ngwecomm-stg.nexi.it'
		transaction_init_path = '/monetaweb/payment/2/xml'
		init_uri = URI(payment_gateway_domain + transaction_init_path)

# XPay Total Acceptance notifies the payment result to the merchant notify url
		# The merchant response, when the notify url is called, should contain the url where the card holder will be redirected to view the payment result (e.g. Payment Ok, Payment Failed)
		merchant_url_to_notify_payment_result = "#{MERCHANT_DOMAIN}/notify"
		# If the notify url is not reachable, XPay Total Acceptance will redirect the card holder to the merchant recovery url
		merchant_recovery_url = "#{MERCHANT_DOMAIN}/recovery"

parameters = {
			id: '44000001', # Terminal Id
			password: 'Password1',
            tenantId: '10', #  In the case of a merchant having an agreement with Intesa enter "10", otherwise enter "20"
			operationType: 'initialize',
			amount: '1.00',			
			laguage: 'ITA',
			responseToMerchantUrl: merchant_url_to_notify_payment_result,
                        merchantOrderId: 'TRCK0001',<currencyCode>
                        currencyCode: '978', #EUR</currencyCode><recoveryUrl>
                        recoveryUrl: merchant_recovery_url,</recoveryUrl><cardHolderName>		
                        cardHolderName: 'Tom Smith',</cardHolderName><cardHolderEmail>
                        cardHolderEmail: 'tom.smith@test.com',</cardHolderEmail><description>
                        description: 'Description',</description><customField>	
			customField: 'Custom Field'</customField>
		}

response = Net::HTTP.post_form(init_uri, parameters)
		raise "Payment initialization failed: #{response.body}" unless response.code == "200"

xmlResponse = REXML::Document.new(response.body)
		payment_id = xmlResponse.root.elements["paymentid"].text
		hosted_page_url = xmlResponse.root.elements["hostedpageurl"].text

"#{hosted_page_url}?PaymentID=#{payment_id}"
	end
end

COPY CODE

TEST AREA