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.

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.eyJ0eElkIjoiMTM4NDc1MTExIg0KCQkJCQksIm1lcmNoYW50R3VpZCI6IjhCNjdCRjg4LUJCOEQtNEVCNS1BREZDLTBGNUM5N0M3RUQ2NyINCgkJCQkJLCJ0cmFuc2FjdGlvbklEIjoiMGY3NTBkNmUtNTMzNi00ZGExLTljZDUtMTg5Njc5N2Y1ZjU0Ig0KCQkJCQksIm1kIjoiMTg1RDcyRDQtODVFNC00NTRBLTgwQ0MtREE2QUUzMDUxQzc2Ig0KCQkJCQksIm1kU3RhdHVzIjoiNTAiDQoJCQkJCSwidGRzTWV0aG9kQ29udGVudCI6IjxpZnJhbWUgaWQ9XCJ0ZHNNbWV0aG9kVGd0RnJhbWVcIiBuYW1lPVwidGRzTW1ldGhvZFRndEZyYW1lXCIgc3R5bGU9XCJ2aXNpYmlsaXR5OiBoaWRkZW47IHdpZHRoOiAxcHg7IGhlaWdodDogMXB4O1wiIHhtbG5zPVwiaHR0cDpcL1wvd3d3LnczLm9yZ1wvMTk5OVwveGh0bWxcIj5cbiAgICA8IS0tLi0tPlxuPFwvaWZyYW1lPjxmb3JtIGlkPVwidGRzTW1ldGhvZEZvcm1cIiBuYW1lPVwidGRzTW1ldGhvZEZvcm1cIiBhY3Rpb249XCJodHRwczpcL1wvYWNzYWJ0ZXN0LmJhbmtzZXJ2LmNvLnphXC9tZHBheWFjc1wvM2RzLW1ldGhvZFwiIG1ldGhvZD1cInBvc3RcIiB0YXJnZXQ9XCJ0ZHNNbWV0aG9kVGd0RnJhbWVcIj5cbiAgICA8aW5wdXQgdHlwZT1cImhpZGRlblwiIG5hbWU9XCIzRFNNZXRob2REYXRhXCIgdmFsdWU9XCJleUFpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaUlEb2dJamd6TURRMVpXVTJMV013TkRZdE5Ua3dPUzA0TURBd0xUQXdNREF3T0RRd1pqWTJOeUlzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlpQTZJQ0pvZEhSd2N6b3ZMM1ZoZEM1bFkyVnVkSEpwWXk1amJ5NTZZUzlJVUZBdmRHUnpNaTlVYUhKbFpVUlRUYwYUc5a1RtOTBhpwWTJGMGFXOXVWVkpNSWlCOVwiPjxpbnB1dCB0eXBlPVwiaGlkZGVuXCIgbmFtZT1cInRocmVlRFNNZXRob2REYXRhXCIgdmFsdWU9XCJleUFpZEdoeVpXVkVVMU5sY25abGNsUnlZVzV6U1VRaUlEb2dJamd6TURRMVpXVTJMV013TkRZdE5Ua3dPUzA0TURBd0xUQXdNREF3T0RRd1pqWTJOeUlzSUNKMGFISmxaVVJUVFdWMGFHOWtUbTkwYVdacFkyRjBhVzl1VlZKTUlpQTZJQ0pvZEhSd2N6b3ZMM1ZoZEM1bFkyVnVkSEpwWXk1amJ5NTZZUzlJVUZBdmRHUnpNaTlVYUhKbFpVUlRUYwYUc5a1RtOTBhpwWTJGMGFXOXVWVkpNSWlCOVwiPjxzY3JpcHQgdHlwZT1cInRleHRcL2phdmFzY3JpcHRcIj5cblx0XHRcdFx0ZG9jdW1lbnQuZ2V0RWxlbWVudEJ5SWQoXCJ0ZHNNbWV0aG9kRm9ybVwiKS5zdWJtaXQoKTtcblx0XHRcdDxcL3NjcmlwdD5cbjxcL2Zvcm0-Ig0KCQkJCQksInJlZGlyZWN0VG9BQ1NGb3JtIjoiIg0KCQkJCQksIm9yZGVyTnVtYmVyIjoiTVI2NDUwMzk5OCINCgkJCQkJLCJ0ZXJtVXJsIjoiaHR0cDpcL1wvbG9jYWxob3N0OjMwMDBcL3Rlcm0tdXJsIn0.OPTY8fdCx7Wn7oklKtbsV3zio5W7Brg4hy8yaFdSdv4</PAReqPayload>
			<SecureCodeId xsi:nil="true"/>
			<MdStatus>50</MdStatus>
			<TxId>138475111</TxId>
			<TDSMethodContent xsi:nil="true"/>
			<RedirectToACSForm xsi:nil="true"/>
		</Secure3DLookupResponse>
	</s:Body>
</s:Envelope>