grants payment platform documentation threedsecure integration · 2015-05-09 · grants payment +44...

Grants Payment +44 (0) 845 299 6210

[email protected]

Grants Payment Asynchronous Workflow 1

Grants Payment Platform Documentation ThreeDSecure Integration Version 3.1.1

Grants Payment +44 (0) 845 299 6210

[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

Grants Payment +44 (0) 845 299 6210

[email protected]


Preface

PSP Platform Documentation – ThreeDSecure Integration

Copyright © 2011 Grants Payment - 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 Grants Payment and delete the material

from any computer.

Grants Payment +44 (0) 845 299 6210

[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 ..................................................................................................... 9

3.2.1 Dispute Resolution ................................................................................................................... 10 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

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

5 Integration for Merchant-Side Authentication (Merchant-MPI) ................................................................ 25 6 Integration for Payment Service Providers .............................................................................................. 27 7 References............................................................................................................................................... 29

Grants Payment +44 (0) 845 299 6210

[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 like Verified By Visa (VbV) or Mastercard

SecureCode (MSC).

This document provides a general outline of how 3DSecure workflows are implemented and shows how to integrate with XML.

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

Grants Payment +44 (0) 845 299 6210

[email protected]


2 Architecture Overview

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

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

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

.

Figure 1 Asynchronous Workflow Overview

Merchant

Grants Payment 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

Grants Payment +44 (0) 845 299 6210

[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.

Grants Payment +44 (0) 845 299 6210

[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:

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

Chapter 6.8 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 chapter

6.6 and 6.7 in (1)

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

chapter 6.10 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=ff8080813cae5d60013cf13bf7ad37d8&3dSecure=true

The following credit card numbers are configured to be enrolled for VbV and MSC:

Brand Number Month / Year Verification

VISA 4711 1000 0000 0000 10 / 2015 123

MASTER 5453 0100 0005 9543 10 / 2015 345

Grants Payment +44 (0) 845 299 6210

[email protected]


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 and Mastercard Transactions.

For Verified by VISA Transactions 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

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 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. 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

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

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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 23, 61, 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. 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 and Mastercard as of September 2008.

Description Return Code ECI-Code*

(VISA/MASTER)

Liability Shift

(VISA/MASTER)

DISPUTE

RESOLUTION** PROVE

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

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

Card Not

Participating

000.400.101 07 No/No STANDARD

User Not Enrolled

000.400.102 06/01 Yes/No Prove Data (XML) / STANDARD

(MC)

Technical Error in 3D System 000.400.103 /

100.390.106 ***

07 No/No STANDARD

Grants Payment +44 (0) 845 299 6210

[email protected]


Missing or invalid Configuration 100.390.105 /

000.400.104 ***

07 No/No STANDARD

3D Attempt Processing 000.300.000 06/01 Yes/No CAVV / STANDARD

* 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

06 Verified By VISA ATTEMPT

07 DEFAULT Ecommerce Transaction

Note: These are the values provided from VISA/Mastercard. 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 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 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 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

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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://test.ctpe.net/demoshop/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">

Grants Payment +44 (0) 845 299 6210

[email protected]


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

<Identification>

<TransactionID>MerchantAssignedID</TransactionID>

</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

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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.


<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>

Grants Payment +44 (0) 845 299 6210

[email protected]


</Clearing>

</Payment>

</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).



<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.

Grants Payment +44 (0) 845 299 6210

[email protected]


The following code snippet of an HTML page shows the simplest possibility of how this redirect in case of

VbV can 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 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

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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.

Grants Payment +44 (0) 845 299 6210

[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. To verify the merchant needs to send exactly the value of the parameter “response” to a URL containing

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.

Grants Payment +44 (0) 845 299 6210

[email protected]


Example:

https://ctpe.io/payment/threedsecure_verification;jsessionid=876df87gsd78gdfg65f67g5fdf67g5?ndcid=234875683945fgsd8s59dfg65s4dfg After assembling the URL the merchant needs to send the value of parameter “response” to this URL – again in a 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.

Grants Payment +44 (0) 845 299 6210

[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://test.ctpe.net/demoshop/specialcardnumbers.html

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 change 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>

<Number>4012001037141112</Number>

<Holder>bob kosel</Holder>

Grants Payment +44 (0) 845 299 6210

[email protected]


<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 <Authentication type="3DSecure">

<ResultIndicator>07</ResultIndicator>

</Authentication>

000.400.102 01 (MASTER Attempt), 06 (VISA Attempt)

<Authentication type="3DSecure">


</Authentication>

000.400.103 07 <Authentication type="3DSecure">


</Authentication>

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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

Grants Payment +44 (0) 845 299 6210

[email protected]


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.

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.

Grants Payment +44 (0) 845 299 6210

[email protected]


4.1.4 Asynchronous Response Message

After the user has entered the VbV or MSC 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>

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.

Grants Payment +44 (0) 845 299 6210

[email protected]


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

In case a merchant can do the authentication for VbV or MSC 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>

Grants Payment +44 (0) 845 299 6210

[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.

Grants Payment +44 (0) 845 299 6210

[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 Grants Payment 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 Grants Payment 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 Grants Payment 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

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

Grants Payment +44 (0) 845 299 6210

[email protected]


response URL and session ID

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.

Grants Payment +44 (0) 845 299 6210

[email protected]


7 References

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

www.visa.com/verifiedmerchants

(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

http://www.visa.com/verifiedmerchants

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

grants payment platform documentation threedsecure integration · 2015-05-09 · grants payment +44...

Documents