Secure3DLookup Method

Description

The Secure3DLookup method allows merchants to authenticate cards through 3D Secure.

Providing richer contextual data significantly improves the ability to assess risk accurately, which in turn helps to increase frictionless authentication rates and overall transaction success. It is increasingly important to pass as many relevant data points as are available at the merchant during Secure3DLookup, such as the fields listed below:

BankCard.CardholderName
Email
HomePhone
MobilePhone
WorkPhone
BillingAddress
ShippingAddress
AddressMatchIndicator

Action

http://www.ecentricswitch.co.za/paymentgateway/v1/Secure3DLookup

Style

Document

Input (Literal)

The input of this method is the document element Secure3DLookupRequest having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader Required
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
Secure3DLookup Required
MerchantID	string	50	A unique identifier to identify the merchant. Also known as Merchant GUID.
TransactionID Required	string	50	A unique identifier provided by the merchant on the API call to identify the transaction.
TransactionDateTime	datetime		The transaction timestamp.
SaleReconID	string	100	A unique sale identifier for reconciliation purposes.
ReconID	string	50	A unique identifier for reconciliation purposes. This is required to be Base64-encoded and is posted as the MD (Merchant Data) value by the ACS as part of the form post data to the TermUrl.
Amount Required	long		The authorization or payment amount in the lowest monetary unit.
CurrencyCode	string	3	The currency code according to the ISO 4217 standard. The default for South Africa is ZAR
OrderNumber	string	50	The transaction order or reference number. Only 0-9, A-Z or a-z allowed. Spaces are not allowed.
Card Required	BankCard		The card details.
PaymentService	PaymentServiceType		The target payment service.
TermUrl	string	1024	After completing 3D Secure verification on the card issuer site, the shopper is redirected back to the merchant site. This URL value specifies which merchant page the shopper is returned to.
VerificationAction	VerificationActionType		The VerificationAction to be applied to the card. If left blank when the PaymentService is CardVerification, it will default to NonPaymentAuthentication. The amount used will be R0 (Zero Rand).
BrowserIP Required	string	45	MANDATORY (Browser) IP address of customer browser (IPv4 or IPv6 format).
ScreenHeight Required	string	6	MANDATORY (Browser) Screen height of customer’s screen (in pixels)
ScreenWidth Required	string	6	MANDATORY (Browser) Screen width of the customer’s screen (in pixels)
DigitalWalletPayload	string		This is the encrypted payload from the digital wallet provider. Base64-encoded digital wallet payload
BillingAddress	Address		The billing address.
ShippingAddress	Address		The shipping address.
Email	string	254	The customer email.
MobilePhone	string	20	The customer mobile phone number.
HomePhone	string	20	The customer home phone number.
WorkPhone	string	20	The customer work phone number.	AddressMatchIndicator	string	1	Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same (values accepted:Y/N).

Output (Literal)

The output of this method is the document element Secure3DLookupResponse having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader Required
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
Secure3DLookupResponse Required
TransactionID Required	string	50	A unique identifier to identify the transaction.
TransactionDateTime Required	datetime		The transaction timestamp.
SaleReconID	string	100	A unique sale identifier for reconciliation purposes.
ReconID Required	string	50	A unique identifier for reconciliation purposes, this is posted as the MD (Merchant Data) value by the ACS as part of the form post data to the TermUrl.
TransactionStatus Required	TransactionStatusType		The transaction status (Success and Failure)
ResponseDetail Required	ResponseDetail		The transaction result code.
Enrolled Required	boolean		Indicates whether the cardholder is enrolled for 3D Secure.
AcsUrl	string		The fully qualified Issuer ACS URL. This is used by the merchant to redirect the cardholder. Returned if the cardholder is enrolled.
PAReqPayload	string		The encoded PAReq generated by MAPS. Returned if the cardholder is enrolled.
MdStatus	string		The returned MdStatus
TxId	string		The returned TxId

Sample Message

Request (Customer Browser Application)

Body

<soapenv:Envelope
 	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 	xmlns:="http://www.ecentricswitch.co.za/paymentgateway/v1">
 	<soapenv:Header>
 		<MessageHeader></MessageHeader>
 	</soapenv:Header>
 	<soapenv:Body>
 		<Secure3DLookupRequest
 			xmlns="http://www.ecentricswitch.co.za/paymentgateway/v1">
 			<MerchantID>8B67BF88-BB8D-4EB5-ADFC-0F5C97C7ED67</MerchantID>
 			<MerchantUserID>978e566b-d62a-42c0-9843-381b3588f333</MerchantUserID>
 			<TransactionID>0f750d6e-5336-4da1-9cd5-1896797f5f54</TransactionID>
 			<Amount>50</Amount>
 			<CurrencyCode>ZAR</CurrencyCode>
 			<OrderNumber>MR64503998</OrderNumber>
 			<Card>
 			 <Token>BF392BCE-6DE4-4134-85D1-EA02F7EB633C</Token>
 			 <SecurityCode>360</SecurityCode>
 			</Card>
 			<PaymentService>CardNotPresent</PaymentService>
 			<TermUrl>http://localhost:3000/term-url</TermUrl>
 		</Secure3DLookupRequest>
 	</soapenv:Body>
 </soapenv:Envelope>

Response

Body

<s:Envelope
	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Header>
		<h:MessageHeader
			xmlns:h="http://www.ecentricswitch.co.za/paymentgateway/v1"
			xmlns="http://www.ecentricswitch.co.za/paymentgateway/v1"
			xmlns:xsd="http://www.w3.org/2001/XMLSchema"
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
			<MessageDateTime>2024-11-14T12:14:36.11</MessageDateTime>
			<MessageID>54AEE2E4-E1C5-4747-AD0E-5A3418A04DA9</MessageID>
			<Channel xsi:nil="true"/>
		</h:MessageHeader>
	</s:Header>
	<s:Body
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
		<Secure3DLookupResponse
			xmlns="http://www.ecentricswitch.co.za/paymentgateway/v1">
			<TransactionID>0f750d6e-5336-4da1-9cd5-1896797f5f54</TransactionID>
			<TransactionDateTime>2024-11-14T12:14:34.657</TransactionDateTime>
			<SaleReconID xsi:nil="true"/>
			<ReconID>185D72D4-85E4-454A-80CC-DA6AE3051C76</ReconID>
			<TransactionStatus>Success</TransactionStatus>
			<ResponseDetail>
				<Source>3DSecure</Source>
				<Code>50</Code>
				<Description>3DS Method</Description>
				<ClientMessage>Success. Please provide TDSMethodContent</ClientMessage>
			</ResponseDetail>
			<Enrolled>true</Enrolled>
			<AcsUrl>https://uat.ecentric.co.za/HPP/tds2/process</AcsUrl>		<PAReqPayload>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eElkIjoiMTM4NDc1MTExIg0KCQkJCQksIm1lcmN
oYW50R3VpZCI6IjhCNjdCRjg4LUJCOEQtNEVCNS1BREZDLTBGNUM5N0M3RUQ2NyINCgkJCQkJLCJ0cmFuc2FjdGlvbklEI
joiMGY3NTBkNmUtNTMzNi00ZGExLTljZDUtMTg5Njc5N2Y1ZjU0Ig0KCQkJCQksIm1kIjoiMTg1RDcyRDQtODVFNC00NTR
BLTgwQ0MtREE2QUUzMDUxQzc2Ig0KCQkJCQksIm1kU3RhdHVzIjoiNTAiDQoJCQkJCSwidGRzTWV0aG9kQ29udGVudCI6I
jxpZnJhbWUgaWQ9XCJ0ZHNNbWV0aG9kVGd0RnJhbWVcIiBuYW1lPVwidGRzTW1ldGhvZFRndEZyYW1lXCIgc3R5bGU9XCJ
2aXNpYmlsaXR5OiBoaWRkZW47IHdpZHRoOiAxcHg7IGhlaWdodDogMXB4O1wiIHhtbG5zPVwiaHR0cDpcL1wvd3d3LnczL
m9yZ1wvMTk5OVwveGh0bWxcIj5cbiAgICA8IS0tLi0tPlxuPFwvaWZyYW1lPjxmb3JtIGlkPVwidGRzTW1ldGhvZEZvcm1
cIiBuYW1lPVwidGRzTW1ldGhvZEZvcm1cIiBhY3Rpb249XCJodHRwczpcL1wvYWNzYWJ0ZXN0LmJhbmtzZXJ2LmNvLnphX
CJ0ZHNNbWV0aG9kRm9ybVwiKS5zdWJtaXQoKTtcblx0XHRcdDxcL3NjcmlwdD5cbjxcL2Zvcm0Ig0KCQkJCQksInJlZGly
ZWN0VG9BQ1NGb3JtIjoiIg0KCQkJCQksIm9yZGVyTnVtYmVyIjoiTVI2NDUwMzk5OCINCgkJCQkJLCJ0ZXJtVXJsIjoiaH
</PAReqPayload>
			<MdStatus>50</MdStatus>
			<TxId>138475111</TxId>
		</Secure3DLookupResponse>
	</s:Body>
</s:Envelope>