cliq platform documentation threedsecure integration · 2015-09-18 · [email protected]...

[email protected]

CLIQ ThreeD Secure 1

CLIQ Platform Documentation ThreeDSecure Integration Version 3.2.2

[email protected]


Release History

Release Description Date Changes

0.9 Beta Version 24-Sep-2005 Initial Workflow Description

1.0.0 Initial Version 20-Nov-2005 3D-Secure Workflow Description

[...] [...] [...] [...]

3.0.0 Major Release 09-Dec-2010 Major text revision and clarification

3.1.0 Minor Release 20-Apr-2011 Added UTF-8 encoding rules

3.1.1 Minor Release 09-Jun-2011 Minor corrections

3.1.2 Minor Release 25-Jun-2013 Minor corrections

3.1.3 Minor Release 12-Nov-2013 Minor corrections

3.2.0 Major Release 26-Jan-2014 American Express SafeKey ECI flags and liability shift

3.2.1 Minor Release 28-Mar-2014 3D Scenarios updated, 3D Secure test cards added

3.2.2 Minor Release 12-Aug-2014 Minor corrections

[email protected]


Preface

PSP Platform Documentation – ThreeDSecure Integration

Copyright © 2014 CLIQ Payments - All rights reserved. Printed in Germany / European Union

The information contained in this document is intended only for the person or entity to which it is addressed

and contains confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended

recipient is prohibited. If you received this in error, please contact CLIQ Payments and delete the material

from any computer.

[email protected]


Content

1 Introduction .................................................................................................................... 5 2 Architecture Overview ...................................................................................................... 6 3 3-D Secure ...................................................................................................................... 8

3.1 Recommendations and Requirements to 3Dsecure-enabled Merchants ........................... 8 3.2 Liability Shift for PSPs/Merchants ................................................................................ 8

3.2.1 Dispute Resolution .............................................................................................. 9 3.2.2 3D Scenarios .................................................................................................... 10

3.3 Request Encoding .................................................................................................... 11 3.4 Payment Request .................................................................................................... 12 3.5 Synchronous Response Message ............................................................................... 14

3.5.1 Direct Payment Response .................................................................................. 14 3.5.2 Response with Redirect Information ................................................................... 15

3.6 Asynchronous Response Message ............................................................................. 16 3.7 Handling Timeouts ................................................................................................... 18 3.8 Verifying 3DSecure Results ....................................................................................... 18 3.9 3D Secure Test Scenarios ......................................................................................... 19

4 Standalone 3D-Secure Transactions ................................................................................. 22 4.1.1 Risk Management 3D Request ............................................................................ 22 4.1.2 Direct Response ................................................................................................ 23 4.1.3 Response with Redirect Information ................................................................... 24 4.1.4 Asynchronous Response Message ....................................................................... 26

5 Integration for Merchant-Side Authentication (Merchant-MPI) ............................................ 28 6 Integration for Payment Service Providers ........................................................................ 30 7 References .................................................................................................................... 32

[email protected]


1 Introduction

There are different scenarios that require an asynchronous workflow from a merchant’s perspective.

Typical examples are Online Bank Transfer or 3DSecure such as Verified By Visa (VbV), Mastercard

SecureCode (MSC) or American Express SafeKey.

This document provides a general outline of how 3DSecure workflows are implemented and integrated via the XML APIs.

Important Note: In case you are integrating COPYandPAY only, it is not necessary to implement the workflows described in this document as the entire 3DSecure workflow is handled within COPYandPAY automatically.

[email protected]


2 Architecture Overview

Figure 1 shows the general overview of how asynchronous workflows are covered.

In comparison to standard transaction processing this process, especially due to the external shopper

authentication, is asynchronous and requires the merchant to provide an additional interface to accept the transaction result.

.

Figure 1 Asynchronous Workflow Overview

Merchant

CLIQ Payment Platform

Bank /

Acquirer

Bank / Issuer

Access

Control

Server

Authorization

System

Acquirer

Domain

Interoperability

Domain

Issuer Domain

1

2

3

4

5

6

7 8 9

10

12

11

13

[email protected]


Step 1 Shopper browses at merchant site, adds items to shopping cart, then finalizes purchase. (Note: Merchant now has all necessary data, including Credit Card / Bank

Account Number and user device information.)

Step 2 Merchant sends payment request to the Payment Platform.

Step 3 If the channel is configured for an aynchrounous workflow and the payment data is

sufficient for the workflow, the payment transaction gets switched into asynchronous mode. The payment system sends a request to the ACS and inquires if the

authentication process can be executed for this transaction.

Step 4 ACS response is returned to the payment system.

If neither authentication nor proof of authentication attempt is available, asynchronous

processing ends and a synchronous authorization request, if appropriate, is executed. If the authentication attempt was successful, a URL and some transaction specific data

is returned to the payment system.

Step 5 In case of positive response from the ACS a synchronous a response to the original

merchant request containing the redirect URL for the user takes place. Besides that a

number of parameters are returned as part of the XML response so that the merchant only has to add these parameters to the redirect to the user.

Step 6 Merchant redirects the end user’s browser to the redirect URL received in step 5. This might be done trough a JavaScript-based redirect. Merchant may use inline windows or

frames instead of pop-up windows to avoid confusion with shopper (as e.g. pop-ups

may be blocked).

Step 7 ACS receives Payer Authentication Request.

Step 8 ACS authenticates shopper using processes applicable to PAN (password, TAN, PIN, etc.). Alternatively, ACS may produce a proof of authentication attempt.

Step 9 Payer Authentication Response gets sent to the payment system via redirect from ACS.

Step 10 In case the Authentication was successful, the original payment transaction gets sent

to the authorization system (typically a bank or acquirer)

Step 11 Acquirer responds based on Authentication information and account data.

Step 12 The payment system sends the asynchronous response message as XML to the

ResponseUrl the merchant provided in the initial XML payment request and redirects the end user’s browser to it.

Step 13 Merchant presents shopper information about the authorization outcome.

[email protected]


3 3-D Secure

The most popular 3-D Secure Methods are Verified by VISA („VbV“) and Mastercard Secure Code („MSC“).

3.1 Recommendations and Requirements to 3Dsecure-enabled Merchants

Merchants must train their customer support staff on 3DSecure so that they can respond effectively to

customer inquiries. See chapter 7 of this document for links to the reference numbers mentioned below.

Good starting points are: Appendix A in Merchant Customer Service in (2)

Online resources in (3) and (4)

For using Mastercard SecureCode and Verified by VISA Logos and Program Identifier check:

MasterCard: Appendix D in MasterCard SecureCode Program Identifier Usage Guidelines (2) and (5)

Visa: Chapter 7 in (1)

Merchants should be aware of some Guidelines and Best Practices set by Mastercard and VISA concerning

their 3D Secure Implementation towards the end users. Those guidelines include: display authentication not as a popups since browser nowadays usually block popups - see chapters

7.4 and 7.5 in (1)

how to respond to Failed Authentication Processing (code 100.380.401 or 100.390.103) - see

chapter 7.8 in (1) for further information check (1) and (2)

Mastercard requests merchants to notify customers about 3D Secure attempts processing (e.g.

when user tries to enroll during the transaction workflow).

To integrate and test on the test system, get your access data from https://test.ctpe.io/payment/DemoMerchantInfo?id=8a8294184f1d2f31014f25d1b003098d&3dSecure=true

3.2 Liability Shift for PSPs/Merchants

Although there are some general rules for 3D secure liability shift and dispute resolution, the procedures do

vary from region to region and even sometimes among different acquirers. The rules are also different among VISA, Mastercard and American Express Transactions.

For Verified by VISA Transactions and American Express SafeKey the liability usually can shift for successful

3D transactions and also for 3D attempts (i.e. when a user or card number not enrolled attempts 3DSecure

processing). With Mastercard Securecode full liability shift usually can apply to successful 3D transactions only*.

For detailed rules and regulations regarding the liability shift please contact your acquirer

[email protected]


directly. He can provide you with accurate and up-to-date information suiting your business

case.

If the liability has shifted successfully: Depending on the region an incoming chargeback gets then either

automatically rejected by VISA/Mastercard/American Express or needs to be resolved manually. On top of that acquirers may decide to offer extra services e.g. rejecting chargebacks that were not automatically

rejected by VISA/Mastercard/American Express. Contact your acquirer for details.

The following table shows an example of the liablity shift eligibility for the different regions woldwide. Please note that the rules regarding your business case may differ. Contact your acquirer for a respective

statement.

Authentication

Result

Authentica-

tion Type

Card

Scheme

Is the Transaction usually eligible for liability shift?

Location where card was issued and where merchant resides Glo

bal Intra Europe

Intra USA

Intra Asia Pac

South Asia, Middle East & Africa

South America

Inter Europe, AP, SA, ME & Africa

Cardholder Authenticated

Full Authentication

Visa N/A N/A N/A N/A N/A N/A

MC N/A N/A N/A N/A N/A N/A

Amex N/A N/A N/A N/A N/A N/A

Cardholder or

Issuing Bank not

enrolled for Authentication

Merchant

Only

Visa N/A N/A N/A N/A N/A N/A

MC x x x

Amex N/A N/A N/A N/A N/A N/A

*Note: Some MasterCard regions have implemented intraregional liability shift programs as well as

MasterCard has implemented a global merchant-only liability shift for interregional transactions. These programs apply to the commercial cards and will be eliminated for transactions authorized on or after 11

April 2014. Please ask your Acquirer for more information.

3.2.1 Dispute Resolution

If there you receive a chargeback on a transaction which you expected to be covered by the liability shift, please contact your acquirer for information on how to resolve the issue.

[email protected]


For example the following steps could be required depending on the information request you receive from your acquirer:

Check if there was a risk management transaction with the debit in the Business Intelligence

Platform (BIP). Even on 3D Secure channels, non 3D transactions can occur, e.g. Virtual Terminal transactions. Such transactions are normal ecommerce transactions with no liability shift and

therefore existing procedures apply. Check the chargeback reason. If the reason is 75 or 83 (VISA) or 4837, 4863 (Mastercard) a

chargeback should usually have been prevented due to a attempted/succesful 3D transaction. The

reasons stated here are cases like "No Cardholder Authorization" and are the chargeback reasons in 50-70% of all ecommerce transactions according to VISA/Mastercard/American Express.

If there is a risk management transaction extract the Authentication "ResultIndicator" value via the

Transaction Details/Processing in BIP. This value corresponds to the 3D ECI value. The exception is

the value "00" which is mapped to "07" for the acquirer. Besides that you have to extract the values for VERIFICATION_ID which represents 3D CAVV/AAV, VERIFICATION_TYPE and XID.

Provide your acquirer with all this information to resolve the dispute.

In certain cases e.g. user not enrolled (VISA attempt processing) the acquirer/VISA may request

additional proof for the 3D communication. Such information is not directly available from BIP but can be provided as (MPI) Log Files on request.

3.2.2 3D Scenarios

The following table is based on information from VISA, Mastercard and American Express:

Description Return Code ECI-Code*

(VISA/MASTER)

Liability Shift

(VISA/MASTER/Amex)

DISPUTE

RESOLUTION** PROVE

Successful 3D Authentication 000.300.000 05/02/05 Yes/Yes/Yes CAVV/AAV/CAVV

Attempt Processing 000.300.000 06/01/06 Yes/Yes/Yes CAVV/AAV/CAVV

Card Not

Participating

000.400.101 07/00/07 No/No/No STANDARD

User Not Enrolled

000.400.102 06/01/06 Yes/No/Yes Prove Data

(XML) / STANDARD (MC)

/ Prove Data

Technical Error in 3D System 000.400.103 /

100.390.105 ***

07/00/07 No/No/No STANDARD

Missing or invalid Configuration

000.400.104 / 100.390.106 ***

07/00/07 No/No/No STANDARD

[email protected]


Invalid payer authentication

response(PARes) in 3DSecure Transaction

000.400.106 07/00/07 No/No/No CAVV /

STANDARD / CAVV

* ECI-Codes

00 internal code which doesn’t get submitted to the acquirer. "00" transactions are either

submitted as 07 or as standard transactions without 3D data depending on the acquirer.

01 Mastercard Securecode ATTEMPT

02 Mastercard Securecode SUCCESS

05 Verified By VISA SUCCESS; American Express SafeKey SUCCESS

06 Verified By VISA ATTEMPT; American Express SafeKey ATTEMPT

07 DEFAULT Ecommerce Transaction

Note: These are the values provided from VISA/Mastercard/American Express. Some Acquirers have decided

that they want these values to be mapped to others e.g. Mastercard values mapped to VISA values. Some

only accept ECI as one digit e.g. "6" instead of "06".

** Dispute Resolution

CAVV/AAV Cardholder Authentication Verification Value (CAVV) used with Verified by VISA and American

Express Safekey in Authorization Message, Accountholder Authentication Value (AAV) used

with Mastercard Securecode in Authorization Message. Both are encrypted values containing information on the transaction so that VISA/Mastercard/American Express can validate the

authentication.

STANDARD Merchants/PSPs have to resolve disputes just like with other standard transactions.

Proof Data

(XML)

Communication Messages with VISANet/MastercardNet/AmericanExpressNet to prove that

Attempt was made.

*** Transaction Workflow in case of technical or configuration errors

Technical Error in 3D System By default the risk transaction will be neutral, the debit will be processed as

non-3DSecure (ECI=07). It is possible to configure the payment system to decline the payment transaction in this case (due to the lack of liability shift)

Missing or Invalid

Configuration

By default config errors will result in declined risk and debit transactions. It is

possible to configure the payment system to process the payment transaction in case of configuration problems. This means that the risk transactions will

be neutral, and the debit will be processed as non-3DSecure (ECI=07).

3.3 Request Encoding

For all payment requests containing shopping and possibly payment data, the request header must contain the Content-Type / charset parameter with the charset encoding set to “UTF-8”. The actual content type

may differ; the decisive information is the charset value.

[email protected]


Accordingly, all request data must be encoded using the UTF-8 character set.

For XML data, please use the following Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Examples:

Integration via PHP/cURL: http://php.net/manual/de/book.curl.php

$ch = curl_init(); curl_setopt($ch, CURLINFO_HEADER_OUT, true);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(

"Content-Type: application/x-www-form-urlencoded;charset=UTF-8" ));

// attach parameter curl_exec($ch);

Integration via Java: UrlRequest req = new UrlRequest(UrlRequest.POST, CORE_URL );

// attach parameter to request req.addHeaderParam("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");

req.send();

3.4 Payment Request

If the provided channel is configured for 3DSecure, the XML payment request must contain the Frontend

subgroup.

To test 3DSecure you must use the mode CONNECTOR_TEST. If you use INTEGRATOR_TEST, the

transaction will be handled synchronously without any 3D redirection.

Test cards for special scenarios testing are available here:

https://shop01.ctpe.ws/demopsp/specialcardnumbers.html

A typical XML payment request for 3-D Secure looks like this: <?xml version="1.0" encoding="UTF-8"?>

<Request version="1.0">

<Header>

<Security sender="123a456b789c123d456e789f012g345"/>

</Header>

<Transaction mode="CONNECTOR_TEST" channel="678a456b789c123d456e789f012g432">

<User login="421a456b789c123d456e789f012g098" pwd="56b789c123d456e789f"/>

<Identification>

<TransactionID>MerchantAssignedID</TransactionID>

https://shop02.ctpe.ws/demopsp/specialcardnumbers.html

[email protected]


</Identification>

<Payment code="CC.DB">

<Presentation>

<Amount>1.00</Amount>

<Currency>EUR</Currency>

<Usage>Order Number 1234</Usage>

</Presentation>

</Payment>

<Account>

<Holder>Joe Doe</Holder>

<Number>1234 1234 1234 1234</Number>

<Brand>VISA</Brand>

<Month>09</Month>

<Year>2005</Year>

<Verification>123</Verification>

</Account>

<Customer>

<Name>

<Salutation>Herr</Salutation>

<Title>Dr.</Title>

<Given>Joe</Given>

<Family>Doe</Family>

<Company>SampleCompany</Company>

</Name>

<Address>

<Street>Leopoldstr. 1</Street>

<Zip>80798</Zip>

<City>München</City>

<State>BY</State>

<Country>DE</Country>

</Address>

<Contact>

<Phone>+49-89-1234566</Phone>

<Mobile>+49-172-1234566</Mobile>

<Email>[email protected]</Email>

<Ip>123.123.123.123</Ip>

</Contact>

</Customer>

<RiskManagement process="AUTO"/>

<Analysis>

<Criterion name="affiliate">ExternalShopXY</Criterion>

</Analysis>

<Frontend>

<ResponseUrl>https://myshop.com/payment/result.php</ResponseUrl>

<SessionID>89asdg89sdg98sfksdf8907</SessionID>

</Frontend>

</Transaction>

</Request>

The Frontend tag group contains two subtags, called ResponseUrl and SessionID.

The ResponseUrl is the URL that is called at the end of the asynchronous workflow to post the result of the

payment to the merchant. The payment server will use this URL to redirect the end user’s browser to some kind of payment confirmation page: Because the merchant receives all response parameters of a payment

transaction he can generate this page accordingly.

[email protected]


Please note: The ResponseUrl must use either port 443 (https) or port 80 (http). Other ports

are not supported and will not work!

The SessionID is a tag that can be used by the merchant to identify the session of the end users’s browser.

It is part of the asynchronous response message at the end enabling the merchant to reload the correct session for the end user.

3.5 Synchronous Response Message

If the user is not enrolled for 3D-Secure the payment transaction will be processed synchronously, meaning

the merchant receives an immediate direct response message like in the normal payment workflow.

If the user is enrolled for 3D-Secure the payment transaction gets switched to asynchronous mode. In this case the attribute “response” of the <Transaction> tag in the response message is “ASYNC” and the

response contains redirect information for the client browser in order to enter the Verified by Visa (VbV) or Mastercard SecureCode (MSC) Passwords.

3.5.1 Direct Payment Response

In case the transaction can be handled synchronously without a redirect to a 3D-Secure page, the response message already contains the final payment result.

<?xml version="1.0" encoding="UTF-8"?>

<Response version="1.0">

<Transaction mode="CONNECTOR_TEST" response="SYNC"

channel="678a456b789c123d456e789f012g432">

<Identification>


<UniqueID>h987i654j321k098l765m432n210o987</UniqueID>

<ShortID>1234.5678.9876</ShortID>

</Identification>

<Processing code="CC.DB.90.00">

<Timestamp>2003-02-12 14:58:07</Timestamp>

<Result>ACK</Result>

<Status code="90">NEW</Status>

<Reason code="00">Successful Processing</Reason>

<Return code="000.000.000">Transaction succeeded</Return>

</Processing>


<Clearing>



<Descriptor>shop.de 1234.1234.1234 +49 (89) 12345 678 Order Number

1234</Descriptor>

<Date>2003-02-13</Date>

<Support>+49 (89) 1234 567</Support>

</Clearing>

</Payment>

[email protected]


</Transaction>

</Response>

3.5.2 Response with Redirect Information

In case the transaction is handled asynchronously, the response message contains the redirect information

and is marked as “ASYNC” in the response attribute of the <Transaction> tag.

NOTE: Although the result of this transaction is successful (ACK), it does not automatically mean that the payment transaction itself will be successful. You are required to wait for the asynchronous response message containing the final payment result (see chapter 3.5). <?xml version="1.0" encoding="UTF-8"?>


<Transaction mode="CONNECTOR_TEST" response="ASYNC"

channel="678a456b789c123d456e789f012g432">

<Identification>




</Identification>




<Status code="80">WAITING</Status>

<Reason code="00">Transaction Pending</Reason>

<Return code="000.200.000">Transaction succeeded</Return>

<Redirect url="https://www.mybank.com/3D_validation“>

<Parameter

name="TermUrl">https://ctpe.io/payment/3D_response</Parameter>

<Parameter name="PAReq">m123n456o789p876q543r22323145346576</Parameter>

<Parameter name="MD">24358432975908324758904327589434</Parameter>

</Redirect>

</Processing>

</Transaction>

</Response>

The important part of the return message is the Redirect tag group containing redirect information of the

client browser and the Status tag that shows that the transaction is in WAITING status.

IMPORTANT: The redirect is a simple POST to the URL specified in the Redirect tag attribute “url”. All parameters specified in the tag <Parameter> are post parameters in the POST to the redirect URL. The number of <Parameter> Tags may vary, so its best to iterate over the <Parameter> tags and add them one by one. Don't look for certain names in the <Parameter> Tags since those names may change e.g. due to changes in the 3D specification.

The following code snippet of an HTML page shows the simplest possibility of how this redirect in case of VbV can look like:

[email protected]


<html>

<head>

<title>Title for Page</title>

</head>

<body OnLoad="OnLoadEvent();">

<form name="downloadForm" action="REDIRECT_URL_HERE" method="POST">

<input type="hidden" name="PaReq" value="BASE-64_ENCODED_PAREQ_HERE" />

<input type="hidden" name="TermUrl" value="TERM_URL_HERE" />

<input type="hidden" name="MD" value="MERCHANT_DATA_HERE" />

<noscript>

<br />

<br />

<center>

<h1>Processing your 3D-Secure Payment Transaction</h1>

<h2>JavaScript is currently disabled or is not supported by your

browser.<br />

</h2>

<h3>Please click Submit to continue the processing of your 3D-Secure

Payment transaction.</h3>

<input type="submit" value="Submit" />

</center>

</noscript>

</form>

<SCRIPT LANGUAGE="Javascript">



</SCRIPT>

</body>

</html>

The <noscript> Section in the redirect form is used for users having JavaScript disabled or not supported

so that they can manually redirect themselves.

Note: Display the 3D authentication inline - do not use popups or separate windows for the authentication

because popups/separate windows may be blocked by the shopper’s browser settings. Even when the window is not blocked (e.g. by using target="_blank") it is still confusing for the shopper to

face multiple windows. 3D Secure Best Practices strongly encourage you to use the inline approach - for U.S.

merchants this is even a „must have“-requirement.

After this redirect the merchant has no longer any control over the client browser and therefore awaits the asynchronous response message from the payment server about the final result of the payment transaction.

3.6 Asynchronous Response Message

After the user has entered the VbV or MSC password, the payment server gets notified if the end user has

successfully entered the password or not.

[email protected]


If he successfully entered the password the payment server continues to process the payment transaction to the Credit Card Acquirer. If the password was not entered successully or the password has not been entered

within 10 minutes, the payment transaction gets aborted.

In both cases the merchant gets notified with an asynchronous response message about the result of the

payment transaction. Via this response message the end user’s browser is redirected back to the merchant shop. Read more about special handling of timeouts (the user has not entered the password wihin 10

minutes) in chapter 3.7.

The following XML snippet shows a sample response message:



<Transaction mode="CONNECTOR_TEST" response="SYNC"

channel="678a456b789c123d456e789f012g432">

<Identification>




</Identification>




<Status code="00">SUCCESS</Status>

<Reason code="00">Successful Processing</Reason>

<Return code="000.000.000">Transaction succeeded</Reason>

</Processing>

<Clearing>



<Descriptor>shop.de 1234.1234.1234 +49 (89) 12345 678 Order Number

1234</Descriptor>

<Date>2003-02-13</Date>

<Support>+49 (89) 1234 567</Support>

</Clearing>

<Frontend>


</Frontend>

</Transaction>

</Response>

This response message gets posted to the server as a redirect within the parameter “response” and is URL encoded. The tag SessionID allows the merchant to retrieve the original session of the end user’s browser

for a correct redirect. Like in any normal response the merchant interprets the result received in the Processing sub tag and can therefore show the correct payment result page to the end user.

[email protected]


3.7 Handling Timeouts

A customer may quit the payment process during authentication without the processing system being able to

notice it. In case of a timeout (the customer does not enter a password within 10 minutes) the merchant

gets notified just like in normal processing with the error code "100.380.501". That code requires special handling though since there is no customer browser involved anymore. This message should not be

forwarded or redirected.

In cases of PSP Integration (see chapter 5) this message needs to be forwarded to the merchant as well. But again a HTTP redirect cannot be used since there is no customer browser to redirect with. If the

merchant URL is not responding the PSP might consider some kind of notification reflecting this case since

the transaction remains in WAITING state for the merchant.

3.8 Verifying 3DSecure Results

Due to network errors in the redirect workflow or customer fraud attempts the merchant may - in rare

cases - not actually receive the correct result of the 3D workflow.

In order to verify the 3D Secure result in asynchronous processing a service is provided. With such a verification the merchant can make sure he really got the correct transaction status in the asnychronous

redirect process.

We highly recommend to implement and use this optional part at the end of the workflow for a

fully secure 3Dsecure process!

Note: The verification needs to be done immediately after the merchant gets the response. The verification is not intended for batch processing.

The response that the merchant receives has two parameters, the first parameter key is ‘response’ and the

value is the URL encoded XML response string. The second parameter key is ‘threedsecure_verificationpath’ and the value is the verificationpath which contains the sessionid and the ndcid.

To verify the 3Dsecure result the merchant needs to send the exact value of the parameter “response” to a

URL which is constructed with the following 2 parts: <processing_server> + <dynamic_part>^

<processing_server> either https://ctpe.io (LIVE) or https://test.ctpe.io for test and

integration purposes

<dynamic_part> a dynamic part received in the parameter

"threedsecure_verificationpath"

The first parts needs to be hardcoded by the merchant for security reasons since parameters may be

manipulated in the user redirect.

[email protected]


Example:

https://ctpe.io/payment/threedsecure_verification;jsessionid=876df87gsd78gdfg65f67g5fdf67g5?ndcid=234875683945fgsd8s59dfg65s4dfg After assembling the URL the merchant needs to post the value of parameter “response” to this URL – again in a POST parameter called “response”.

There are 4 possible answers to this verification request received in the response body:

VERIFIED request was successfully verified

NOT_VERIFIED request could not be verified either due to a network error in the redirect

workflow or a fraud attempt by the customer. The correct transaction status needs to be verified using the BIP.

PARAM_ERROR The merchant did not send in a parameter "response" to verify. This indicates a merchant integration problem. The correct transaction status needs to be

verified using the BIP.

SESSION_ERROR The user session is invalid or has timed out. That usually means the verification was not done immediately by the merchant. The correct

transaction status needs to be verified using the BIP.

Note: In case of 3D timeouts the "threedsecure_verificationpath" is not set, since the timeout notification request directly comes from the processing platform. So in the 3D timeout scenario verification is

neither possible nor necessary. What that means for the merchant implementation in such cases is that it

also needs to check that the return code indicates a timeout (code 100.380.501). If the return code is not 100.380.501 but e.g. a successful transaction (and the "threedsecure_verificationpath" is not set) a

fraud attempt by the customer/or technical problem in 3D final redirect is most likely.

3.9 3D Secure Test Scenarios

The following credit card numbers can be used for 3D Secure tests to trigger certain response scenarios:

Visa Test Cards:

Card Number Result and Return Code ECI flag

4711100000000000 gives Successful 3D Authentication, return code 000.300.000 05

4200000000000000 gives Card Not Participating, return code 000.400.101 07

4012001037484447 gives Technical Error in 3D System (first synchronous step) return code

000.400.103 / 100.390.105 / 100.390.112 07

4441795841431616 gives Technical Error in 3D System (second asynchronous step) return code

000.400.103 / 100.390.105 07

[email protected]


Card Number Result and Return Code ECI

flag

4267146605677385 gives Invalid payer authentication response, return code 000.400.106 06

4929626518276854 gives Attempt Processing, return code 000.300.000 06

4681868784735514 gives User Not Enrolled, return code 000.400.102 06

4716319370304553 gives Risk Management timeout, return code 100.380.501 07

4024007173381889 gives PARes Validation failed - problem with signature, return

code 100.390.103 07

Mastercard Test Cards:


flag


5405531070110469 gives should give Risk Management timeout, return code 100.380.501 07


5386024192625914 gives should give Technical Error in 3D System (first synchronous step) return

code 000.400.103 / 100.390.105 / 100.390.112 07


5245018215178191 gives should give User Not Enrolled, return code 000.400.102 01

5215203694927708 gives should give Technical Error in 3D System (second asynchronous step) return code 000.400.103 / 100.390.105

07


American Express Test Cards:

Card Number Result and Return Code ECI flag




373953192354008 gives Technical Error in 3D System (first synchronous step) return code

000.400.103 / 100.390.105 / 100.390.112 07


374500261001009 gives Technical Error in 3D System (second asynchronous step) return code

000.400.103 / 100.390.105 07

[email protected]



flag

375705004001005 gives Risk Management timeout, return code 100.380.501 07

[email protected]


4 Standalone 3D-Secure Transactions

Standalone 3D-Secure Transactions allow you to use the MPI only and to get the final results of the 3D-

Secure process only. This result can then be submitted in a synchronous payment transaction.

The parameters you received as the result of the 3D-Transaction need to be submitted with this payment transaction. See chapter 3.6 for details.

Test cards for special scenarios testing are available here:

https://paymentservices.atlassian.net/wiki/pages/?os_username=merchant.login&os_password=HHHUXWT7z7eJ&login=Log+in&os_destination=%2Fpages%2Fviewpage.action%3FpageId%3D11927842

4.1.1 Risk Management 3D Request

To test 3-D Secure you must use the CONNECTOR_TEST mode. If you use INTEGRATOR_TEST instead, the transaction will be handled synchronously without any 3D redirection.

If the provided channel is configured for 3D-Secure, the XML risk management request must contain the Frontend subgroup.

The RiskManagement transaction is very similar to a payment transaction.

Basically, all you need to do is that you replace the Payment code CC.DB with RM.3D.

Customer information and the Verification code for the credit card are not mandatory.

A typical XML risk management request for 3-D Secure looks like this: <?xml version="1.0" encoding="UTF-8"?>


<Header>

<Security sender="ff80808113fcd30b0113fcd31ac10005" type="MERCHANT" />

</Header>

<Transaction mode="CONNECTOR_TEST" channel="ff80808113fcd30b0113fcd31cca000c"

response="SYNC" source="XML">

<Identification>

<TransactionID>1174</TransactionID>

</Identification>

<User login="ff80808113fcd30b0113fcd31cc6000b" pwd="geheim" />

<Payment code="RM.3D">

<Presentation>



<Usage>TPX_order #222</Usage>

</Presentation>

</Payment>

<Account>



[email protected]


<Number>4012001037141112</Number>

<Holder>bob kosel</Holder>

<Brand>VISA</Brand>

<Expiry month="12" year="2014" />

</Account>

<Frontend>

<ResponseUrl>https://www.myshop.com/payment/result.jsp</ResponseUrl>

<SessionID>87as6df87asddfjasdf786asdfa8s7d6f</SessionID>

</Frontend>

</Transaction>

</Request>

4.1.2 Direct Response

In case the transaction will be handled synchronously without a redirect to a 3D-Secure page, the response message already contains the final result. Typically this happens if the credit card is not enrolled or the card

is not participating for 3D-Secure.



<Transaction mode="CONNECTOR_TEST" channel="ff80808113fcf2990113fcf2a7ad000c"

response="SYNC">

<Identification>


<UniqueID>ff80808113fc61260113fcf2b02f003d</UniqueID>


</Identification>

<Payment code="RM.3D" />

<Processing code="RM.3D.40.10">


<Result>NOK</Result>

<Status code="40">NEUTRAL</Status>

<Reason code="10">3DSecure Not Applied</Reason>

<Return code="000.400.101">card not participating</Return>

</Processing>

</Transaction>

</Response>

In case you receive a direct response you still MUST send the correct ECI value with the upcoming payment

request. The ECI value (ResultIndicator) depends on the return code you receive with the direct response of the RM.3D transaction.

Return Code ECI Value Authentication tag group sample for the

upcoming payment transaction (see 3.6)

000.400.101 07/00 (VISA/MASTER/Amex no liability shift)

<Authentication type="3DSecure">

<ResultIndicator>07</ResultIndicator>

</Authentication>

000.400.102 06/01 (VISA/MASTER/Amex

Attempt)



</Authentication>

[email protected]


000.400.103 07/00 <Authentication type="3DSecure">


</Authentication>

In case you receive 000.400.404 (3D-Secure configuration problems): Do not submit any payment transactions as there will be no liablity shift for those transactions! If you receive this error, please contact

your account manager.

4.1.3 Response with Redirect Information

In case the transaction will be handled asynchronously, the response message contains the redirect

information and is marked as “ASYNC” in the response attribute of the <Transaction> tag. <?xml version="1.0" encoding="UTF-8"?>


<Transaction mode="INTEGRATOR_TEST" channel="ff80808113fcd30b0113fcd31cca000c"

response="ASYNC">

<Identification>


<UniqueID>ff80808113fc61260113fcd32985002d</UniqueID>


</Identification>





<Status code="80">WAITING</Status>

<Reason code="00">Transaction Pending</Reason>

<Return code="000.200.000">Transaction pending</Return>

<Redirect

url="http://ccbank.com/payment/threedsecure/authenticationSimulation.jsp">

<Parameter name="TESTCC">**** **** **** 0000</Parameter>

<Parameter

name="PaReq">eJxVUltPwjAU/iuEZ10v627k0AQkERJRFGL0iZSujEW2QVcE/PW246Z9Ot/5zvU7hdlKKzWYKrnT

isNY1bXIVCtPu+3Dsgjm0Zx4PqOY4jaHSe9NbTl8K13nVcmJhz0K6AJtspYrURoOQm77o2fOIkYYBnSGUCg9GnDcv

AAHYZJgEt0nDhI/AXTioRSF4sOqNmtRpq0nkwJqXCCrXWn0kbPYFr0A2Ok1Xxmz6SC03++9grKFyGpPVgUgxwG6DT

bZOau2tQ55yunj4mc5VdlsSNE7GUj6kY0nva9R//WzC8hFQCqM4hTjCIckaBHW8aMOjQE1fhCFG4ITjO+w2/MEYeO

69K6co/66wGqtVSmPPHbqXBGow6YqlY2wql5tSFUt+ct0bJs6C9BtiYeh01oaq1oYB3HkUxL5hFAWUKd6Q7iqudWJ

EBw2ZR0A5FLR+aDofHZr/fsOv54Frac=</Parameter>

<Parameter name="MD">ff80808113fc61260113fcd32985002d</Parameter>

<Parameter

name="TermUrl">http://termurl.org/payment/threedsecure?ndcid=ff80808113fcd30b0113fcd31cca

000c_1174_INTERNALTESTTX</Parameter>

</Redirect>

</Processing>

</Transaction>

</Response>

The important part of the return message is the Redirect tag group containing redirect information for the

client browser and the Status tag showing that the transaction is in WAITING status.

[email protected]


IMPORTANT:

The redirect is a simple POST to the URL specified in the Redirect tag attribute “url”. All parameters specified in the tag <Parameter> are post parameters in the POST to the redirect URL. The number of <Parameter> tags may vary, so its best to iterate over the <Parameter> tags and add them one by one. Don't look for certain names in the <Parameter> Tags since those names may change e.g. due to changes in the 3D specification. The following code snippet of an HTML page shows the simplest possibility of how this redirect in case of

VbV could look like: <html>

<head>

<title>Title for Page</title>

</head>

<body OnLoad="OnLoadEvent();">

<form name="downloadForm" action="REDIRECT_URL_HERE" method="POST">

<input type="hidden" name="PaReq" value="BASE-64_ENCODED_PAREQ_HERE" />

<input type="hidden" name="TermUrl" value="TERM_URL_HERE" />

<input type="hidden" name="MD" value="MERCHANT_DATA_HERE" />

<noscript>

<br />

<br />

<center>

<h1>Processing your 3-D Secure Payment Transaction</h1>

<h2>JavaScript is currently disabled or is not supported by your

browser.<br />

</h2>

<h3>Please click Submit to continue the processing of your 3-D Secure

Payment transaction.</h3>

<input type="submit" value="Submit" />

</center>

</noscript>

</form>

<SCRIPT LANGUAGE="Javascript">



</SCRIPT>

</body>

</html>

The <noscript> section in the redirect form is used for users having JavaScript disabled or not supported

so that they can manually redirect themselves.

Note: Display the 3D authentication inline – do not use popups or seperate windows for the authentication

because popups/separate windows may be blocked by the shopper’s browser settings. Even when the window is not blocked (e.g. by using target="_blank") it is still confusing for the shopper to

face multiple windows. 3D-Secure Best Practices strongly encourage you to use the inline approach - for U.S. merchants this is even a MUST HAVE requirement.

[email protected]


After this redirect the merchant has no longer any control over the client browser and therefore awaits the asynchronous response message from the payment server about the final result of the 3D-Secure

transaction.

4.1.4 Asynchronous Response Message

After the user has entered the VbV, MSC or Amex SafeKey password, the payment server gets notified

whether the end user has successfully entered the password or not.

This information is then sent back to the URL initially specified in the tag <ResponseUrl>.

The merchant gets notified with an asynchronous response message about the result of the 3D-Secure

transaction. Via this response message the end user’s browser gets redirected back to the merchant shop. Read more aboput special handling of timeouts (i.e. the user has not entered the password wihin 10

minutes) in chapter 3.7.

The following XML snippet shows a sample response message:



<Transaction mode="INTEGRATOR_TEST" channel="ff80808113fcd30b0113fcd31cca000c"

response="ASYNC">

<Identification>


<UniqueID>ff80808113fc61260113fcd32985002d</UniqueID>


</Identification>



<Parameter name="VERIFICATION_ID">AAACAgSRBklmQCFgMpEGAAAAAAA=</Parameter>

<Parameter name="VERIFICATION_TYPE">2</Parameter>

<Parameter name="XID">CAACCVVUlwCXUyhQNlSXAAAAAAA=</Parameter>


</Authentication>

<Frontend>

<SessionID>87as6df87asddfjasdf786asdfa8s7d6f</SessionID>

</Frontend>




<Status code="00">SUCCESS</Status>

<Reason code="00">Submission to Clearing Network</Reason>

<Return code="000.300.000">Two-step transaction succeeded</Return>

</Processing>

</Transaction>

</Response>

[email protected]


This response message is posted to the server as a redirect within the parameter “response” and is URL

encoded. The tag SessionID allows the merchant to retrieve the original session of the end user’s browser for a correct redirect.

Like in any normal response the merchant interprets the result received in the Processing sub tag and can therefore continue the payment process depending on this result.

The parameters received in the Authentication tag will then be used for the payment transaction, see

chapter 3.6.

[email protected]


5 Integration for Merchant-Side Authentication (Merchant-MPI)

In case a merchant can do the authentication for VbV, MSC or Amex SafeKey on his side, the gathered

authentication data can be submitted via XML as part of the payment request.

A typical XML payment request for that scenario looks like this: <?xml version="1.0" encoding="UTF-8"?>


<Header>

<Security sender="123a456b789c123d456e789f012g345"/>

</Header>

<Transaction mode="CONNECTOR_TEST" channel="678a456b789c123d456e789f012g432">

<User login="421a456b789c123d456e789f012g098" pwd="56b789c123d456e789f"/>

<Identification>


</Identification>


<Presentation>



<Usage>Order Number 1234</Usage>

</Presentation>

</Payment>

<Account>

<Holder>Joe Doe</Holder>

<Number>1234 1234 1234 1234</Number>

<Brand>VISA</Brand>

<Month>09</Month>

<Year>2005</Year>

<Verification>123</Verification>

</Account>

<Customer>

<Name>

<Salutation>Herr</Salutation>

<Title>Dr.</Title>

<Given>Joe</Given>

<Family>Doe</Family>

<Company>SampleCompany</Company>

</Name>

<Address>

<Street>Leopoldstr. 1</Street>

<Zip>80798</Zip>

<City>München</City>

<State>BY</State>

<Country>DE</Country>

</Address>

[email protected]


<Contact>

<Phone>+49-89-1234566</Phone>

<Mobile>+49-172-1234566</Mobile>

<Email>[email protected]</Email>

<Ip>123.123.123.123</Ip>

</Contact>

</Customer>

<RiskManagement process="AUTO"/>

<Analysis>

<Criterion name="affiliate">ExternalShopXY</Criterion>

</Analysis>


<Parameter name="VERIFICATION_ID">AAACAgSRBklmQCFgMpEGAAAAAAA=</Parameter>

<Parameter name="VERIFICATION_TYPE">2</Parameter>

<Parameter name="XID">CAACCVVUlwCXUyhQNlSXAAAAAAA=</Parameter>


</Authentication>

</Transaction>

</Request>

The Authentication Tag contains all the information gathered from a 3D-Secure process on the merchant’s

side. See the specification “XML Transactions” chapter 1.17 „Authentication Group“ for more details on what to send and what the parameters mean.

This payment request will result in a synchronous payment response as there are no additional

authentications necessary.

[email protected]


6 Integration for Payment Service Providers

Note: The information provided in this chapter applies to Payment Service Providers only. If

you are a merchant you can skip it entirely.

Payment Service Providers (PSPs) who want to use the 3D-Secure process provided can do that with very

little changes to the 3D request they receive from their merchants.

From the perspective of the CLIQ payment platform the PSP has to act like a merchant. This means that the PSP typically receives a Response URL and a session ID from the merchant. To make

sure that the PSP gets also notified of the result of the payment and (due to the fact that only the PSP can

have the control over the end user’s browser) the PSP needs to do the following things:

- Replace the merchant’s response URL with a URL on the PSP’s server. - Replace the end user’s session ID with an ID that enables the PSP to match the response to the

correct transaction.

- Adjust Timeout Handling (see Chapter 3.6) - Map the data received from the merchant to the new data

The following sample workflow shows how this could look like:

1) PSP receives payment request with the following 3D-Secure related information:

a. sessionId = 1234567890

b. responseUrl = https://www.merchantshop.com/payment_response.url

2) PSP sends an XML request to the CLIQ payment platform with the following 3D-Secure related tags:

<Frontend>

<ResponseUrl>https://www.pspserver.com/payment/result.php</ResponseUrl>


</Frontend>

Internally the PSP maps those two parameters to the parameters received from the merchant.

3) The CLIQ payment platform will handle the transaction as described in the workflow in chapters 2

and 3.

4) At the end of the 3D-Secure process the PSP receives the asynchronous notification about the payment transaction containing the sessionId:

<Frontend>


</Frontend>

This will allow the PSP to find the original transaction in his database and get the original merchant’s

response URL and session ID

https://www.merchantshop.com/payment_response.url

[email protected]


5) The PSP updates the status of the transaction in its system.

6) The PSP notifies the merchant (depending on the implementation on the PSP’s platform) about the

result of the payment and makes sure that the end user’s browser gets redirected to the merchant shop.

[email protected]


7 References

(1) Verified by VISA - 3-D Secure Acquirer and Merchant - Implementation Guide - can be obtained from

www.visa.com/verifiedmerchants or directly accessed here:

http://usa.visa.com/download/merchants/verified-by-visa-acquirer-merchant-implementation-guide.pdf

(2) Mastercard Securecode - Merchant Implementation Guide - can be obatined from http://www.mastercard.com/us/merchant/security/what_can_do/SecureCode/getting_started.html

(3) Mastercard Securecode FAQ

http://www.mastercard.com/us/merchant/security/what_can_do/SecureCode/faq.html

(4) Verified by VISA FAQ - http://usa.visa.com/personal/security/visa_security_program/vbv/faq.html

and http://usa.visa.com/business/accepting_visa/support_center/faq.html

(5) Mastercard Securecode Logo and Artwork Usage Requirements

http://www.mastercardmerchant.com/securecode/artwork.html

(6) American Express SafeKey

https://network.americanexpress.com/uk/en/safekey/index.aspx?linknav=UK-mer-merchant-SafeKey-home

http://www.visa.com/verifiedmerchants

http://usa.visa.com/download/merchants/verified-by-visa-acquirer-merchant-implementation-guide.pdf

http://www.mastercard.com/us/merchant/security/what_can_do/SecureCode/getting_started.html

http://www.mastercard.com/us/merchant/security/what_can_do/SecureCode/faq.html

http://usa.visa.com/personal/security/visa_security_program/vbv/faq.html

http://usa.visa.com/business/accepting_visa/support_center/faq.html

http://www.mastercardmerchant.com/securecode/artwork.html

cliq platform documentation threedsecure integration · 2015-09-18 · [email protected]...

Documents