1 About 3-D Secure

1.1 Regulatory Requirements

1.1.1 EBA Mandate

The European Banking Authority (EBA) mandated that all payer who access their payment account online and initiate electronic payment transactions through a remote channel must be strongly authenticated (aka Strong Customer Authentication (SCA)) commencing September 14, 2019. The card organizations seized this opportunity to overhaul the established 3D-Secure protocol for cardholder authentication and to address several issues that curbed adoption in the market.

1.1.2 3DS 2.0

Previously, internet merchants had the choice to either present a cardholder challenge (e.g. TAN / password) or to give 3DS a pass entirely. Some adopted a dynamic approach based on PSP or own risk assessment, but many merchants valued a frictionless checkout and high conversion rates more than the potential benefits of a liability shift. The card organization’s overall strategy for 3DS 2.0 is to reduce friction through an improved cardholder experience (device awareness) and to leverage exemptions from SCA based on robust transaction risk analysis (TRA) with the ultimate goal of delivering optimal authorization performance and conversion rates. Thus, TRA is key to delivering frictionless payment experiences for low-risk remote transactions. Therefore the 3DS 2.0 protocol introduced a plethora of additional data points that can be transferred to the issuer to aid transaction risk analysis and to apply excemptions from SCA.

SCA will be required when:

• The transaction is not out of scope of the PSD2 RTS
• No PSD2 SCA exemption applies for a payment transaction
• Adding a card to a Merchant’s file (card-on-file)
• Starting a recurring payment arrangement for fixed and variable amounts, including setting the initial mandate for Merchant-Initiated Transactions
• Changing a recurring payment agreement for a higher amount (premium offering for example)
• Setup of white-listing (or viewing/amending white-lists)
• Binding a device to a Cardholder

1.1.3 Liability Shift

As a rule of thumb, when cardholder authentication was performed through 3-D Secure, merchants are typically protected against e-commerce fraud-related disputes and liabiliaty shifts from the merchant / acquirer to the issuer. There are exceptions to merchant dispute protection though. In the context of 3DS 2.0 merchants are regularily not protected if granted excemptions according to PSD2 RTS were actively requested by merchant / acquirer.

The following diagram depicts options and liabilities under PSD2 RTS requirements according to MasterCard.

1.1.4 3D Secure 2.0 and GDPR Compliance

Cardholders must be provided with detailed information about how their data is collected, used and processed. This can be ensured via a Privacy Notice including at a minimum the types of data being processed, the purposes of their processing, data uses, etc. Card organizations and Issuers will not use EMV 3DS data for other purposes than fraud prevention and authentication. It excludes the usage of personal data for other purposes, such as sales, marketing and data mining (other than fraud prevention as purpose) activities.

1.1.5 PSD2 SCA Exemptions and Exclusions

There are some important excemptions to SCA according to the regulatory technical standards (RTS) that may apply in various conditions which are depicted in the following digram.

1.2 The 1cs Online Payment System

1.2.1 Authentication Options

An acquirer may be allowed to not apply SCA due to to low fraud rates and TRA. For these excemptions there are various processing options available as depecited in the diagram below.

As a standard, First Cash Solution will submit (where supported) applicable excemptions through the EMV 3DS authentication flow to the issuer to achieve best possible authorization approval rates.

EBA-Op-2018-04, Paragraph 47 – Clarification on PSP (Acquirer Fraud Rates)

The fraud rate as defined in Annex A of the RTS is calculated for all credit transfer transactions and all card payment transactions and cannot be defined per individual payee (e.g. merchant) or per channel (whether app or web interface). The fraud rate that determines whether or not a PSP qualifies for the SCA exemption cannot be calculated for specific merchants only, i.e. where the payer wants to make a payment to a specific merchant and this specific merchant has a fraud risk that is below the threshold. While the payee’s PSP (acquirer) may contractually agree to ‘outsource’ its transaction risk analysis monitoring to a given merchant, or allow only certain predefined merchants to benefit from that PSP’s exemption (based on a contractually agreed low fraud rate), the fraud rate making a given PSP eligible for an exemption under Article 18 would still need to be calculated on the basis of the payee PSP’s executed or acquired transactions, rather than on the merchant’s transactions.

1.2.2 Message Version 2

To handle the amount of additional non-payment data and to maintain downward compatibility as much as possible First Cash Solution decided to version its the 1cs Online Payment System card interface via the additional data element MsgVer. The upgraded API is still based on key-value pairs but relies heavly on Base64 encoded JSON objects to aid readibility and client-side scripting.

Merchants will still be able to use our classic interface for requests even with 3DS 2.0 but there are some limitations:

• Many additional data points for issuer risk analysis are not available and thus, the frictionless ratio might be lower
• API responses and notifications do include new JSON objects to cater for 3DS 2.0 protocol specifications and require modification of existing merchant integrations

For these reasons it is highly recomended to upgrade to version 2.

1.2.3 Soft decline handling

In case a transaction is missing SCA, issuers might respond with so-called soft declines. This means that the transaction authorization request is declined by the issuer, however, the same transaction can be initiated again. The main reason for soft declines emerging in the context of 3D Secure is that issuers are not accepting SCA exemptions requested by the merchant when such is sent directly to authorization or when the merchant requests payment without authentication being carried out beforehand. The best practice is to restart the payment including 3DS. With Automated Soft Decline Handling feature, configuration based, the 1cs Online Payment System (1cs OPS) will react to the soft decline response by automatically restarting the payment forcing SCA. The 1cs OPS will then automatically create a new payment on behalf of the merchant and include 3DS flow.

IMPORTANT:

• From a user’s point of view, customers will not notice any difference and will not need to re-enter their credit card data. The whole process is managed by the First Cash Solution GmbH.
  
• Please note that this solution is not available for server-to-server integrations, as 1cs OPS does not have the client (browser) in control to start the 3-D Secure flow. For server-to-server integration, the merchant is responsible to re-trigger the payment with 3-D Secure flow and most important forcing the SCA challenge through the available parameter JSON threeDSPolicy (challengePreference = mandateChallenge).

1.2.3.1 Whitelisting of trusted beneficiaries

A cardholder might opt to add a merchant to a list of trusted benficiaries maintained at the issuer to excempt this particular merchant from SCA with future payments. This will usually occur during a cardholder challenge but cardholder’s might also be able to manage a list of trusted beneficiaries through their banking app for instance.

Merchants may benefit from a whitelist excemption if requested and if a cardholder challenge is not required otherwise.

Please note that whitelisting is available with 3DS version 2.2 and higher. Currently issuer most support 3DS 2.1.

Notice: Please note that whitelisting is available with 3-D Secure version 2.2 and higher. Currently issuer most support 3-D Secure 2.1.

1.2.3.2 Recurring transactions

Recurring transactions are a series of transactions processed following an agreement between a cardholder and a merchant where the cardholder purchases goods or services over a period of time and through a number of separate transactions with the same amount. The initial transaction must be authenticated (i.e. cardholder initiated transaction (CIT)). Subsequent recurring payments are out of scope of RTS SCA since they are regularily merchant initiated (i.e. without customer beeing in session).

1.2.3.3 Low-value transactions

Issuers may exempt transactions from SCA provided that the following conditions are met:

• the payment amount does not exceed EUR 30,
• the cumulative amount of previous payment transactions without SCA does not exceed EUR 100,
• the number of previous payment transactions without SCA does not exceed five consecutive payment transactions.

Please note that low-vale exemptions must be requested to be considered for a frictionless authentication flow.

1.2.3.4 Transaction risk analysis

Acquirers and issuers are allowed not to apply SCA provided the overall fraud rate is not higher than the reference fraud rate for the exemption threshold value (ETV) specified in the table below and where the risk-based assesment of each individual transaction can be considered as low risk.

1.2.3.5 One-leg out transactions

One-leg out transactions are such transactions where either the payer’s payment service provider or the payee’s payment service provider are located outside the European Union.

Payment service provider in the context of a card based transaction and in the spirit of the PSD2 are regularily acquirer and issuer.

Thus, neither the nationality of the cardholder nor the merchant’s business location are relevant for the assessment wether a transaction is out of scope due to the ‘one-leg out’ rule.

2 Integration Methods

2.1 Card processing – Credit Card Form

When requesting card payments via First Cash Solution hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation.

From a merchant point of view the sequence itself does not differ between 3DS authenticated and non-authenticated payments though 3DS requires consideration of additional data elements in the request and response.

Notice about Cookie-/Session Handling: Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additial information and different solution approaches.

When requesting card payments via 1cs OPS hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation.

From a merchant point of view the sequence itself does not differ between 3DS authenticated and non-authenticated payments though 3DS requires consideration of additional data elements in the request and response.

Notice about Cookie-/Session Handling: Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additional information and different solution approaches.

2.1.1 Simplified Sequence Diagram

2.1.2 Payment Request

To retrieve a First Cash Solution card form please submit the following data elements via HTTP POST request method to https://www.computop-paygate.com/payssl.aspx.

Notice: For security reasons, 1cs Online Payment System rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

The 1cs Online Payment System will return an HTML document in the response body representing the requested card form. The form may be included in the merchant checkout page or used as a standalone page to redirect the cardholder to.

Cardholder authentication and payment authorization will take place once the cardholder entered all required card details and submitted the form data to the 1cs Online Payment System.

Note: In case you are using your own templates (Corporate Payment Page), please make sure you include Cardholder name on your custom template. Cardholder name is mapped to the 1cs Online Payment System API parameter “CreditCardHolder”. Cardholder name field must not contain any special characters and must have minimal length of 2 characters and maximum length of 45 characters.

When the payment is completed the 1cs Online Payment System will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess resepctively to the URLFailure.

The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.

Notice: Please notice that in case of Fallback to 3-D Secure 1.0 the URLSuccess or URLFailure is called with GET. Therefore your systems should be able to receive parameters both via GET and via POST.

The credit card form can be highly customized by using your own template. 

Details are available here: Corporate PayPage and templates

2.1.3 HTTP POST to URLSuccess / URLFailure / URLNotify

The following table gives the result parameters which the 1cs Online Payment System transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

2.1.4 Credit card payments with separate authorisation

For credit card payments the ORDER can be separated from the subsequent authorisation and the following steps. Therefore initially the SSL credit card payment is initiated via 1cs Online Payment System form or via Server-to-Server-connection like in the chapters above with an additional parameter. Later it is authorised using the interface authorize.aspx via server-to-server connection. For initialising visit the following URL:

https://www.computop-paygate.com/payssl.aspx

For Server-to-Server-connection it is the following URL:

https://www.computop-paygate.com/direct.aspx

The following table describes the encrypted payment request parameters:

Additional parameters for credit card payments with separate authorisation

In order to authorise a previously with TxType=Order initiated SSL credit card payment, please visit the following URL:

https://www.computop-paygate.com/authorize.aspx

Notice: Please note, that for an initial order KPN/CVC/CVV-check is not possible. For the subsequent reservation request this ID also cannot be passed on.

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameters for credit card payments via authorize.aspx

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

2.1.5 Extended Sequence Diagram

2.2 Server-2-Server Integration EN

2.2.1 Card processing – Server-2-Server integration

A 3DS 2.0 payment sequence may comprise the following distinct activities:

• Versioning
  • Request ACS and DS Protocol Version(s) that correspond to card account range as well as an optional 3DS Method URL
• 3-D Secure Method
  • Connect the cardholder browser to the issuer ACS to obtain additional browser data
• Authentication
  • Submit authentication request to the issuer ACS
• Challenge
  • Challenge the carholder if mandated
• Authorization
  • Authorize the authenticated transaction with the acquirer

2.2.2 Server-2-Server Diagram

Notice: Please note that the communication between client and Access Control Server (ACS) is implemented through iframes. Thus, responses arrive in an HTML subdocument and you may establish correspondent event listeners in your root document.
Alternatively you could solely rely on asynchronous notifications delivered to your backend. In those cases you may have to consider methods such as long polling, SSE or websockets to update the client.

2.2.3 Payment Initiation

The initial request to the 1cs Online Payment System will be the same regardless of the underlying 3-D Secure Protocol.

In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to https://www.computop-paygate.com/direct.aspx.

2.2.4 Call of interface: general parameters

Notice: For credit card payments with 3-D Secure, please note the different cases as explained separately in the chapter at the start of the handbook. If the credit card is registered for Verified or SecureCode or SafeKey, the next phase is divided into two steps of authentication and payment. However it always begins in the same way via the direct.aspx interface. The first response however is the receipt of Javascript code or other parameters in order to carry out a second call up of the direct3d.aspx interface. Only after that, do you receive the listed parameter as a response.

To carry out a credit card payment via a Server-to-Server connection, please use the following URL:

https://www.computop-paygate.com/direct.aspx

Request Elements

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Notice: In case of a merchant initiated recurring transaction the JSON objects (besides credentialOnFile and card), the URLNotify and TermURL are not mandatory parameters, because no 3-D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.

General parameters for credit card payments via socket connection

Please note the additional parameter for a specific credit card integration in the section “Specific parameters”

Response Elements (authentication)

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

versioningData

The versioningData object will indicate the EMV 3-D Secure protocol versions (i.e. 2.1.0 or higher) that are supported by Access Control Server of the issuer.

If the corresponding protocol version fields are NULL it means that the BIN range of card issuer is not registered for 3-D Secure 2.0 and a fallback to 3-D Secure 1.0 is required for transactions that are within the scope of PSD2 SCA.

When parsing versioningData please also refer to the subelement errorDetails which will specify the reason if some fields are not pupoluated (e.g. Invalid cardholder account number passed, not available card range data, failure in encoding/serialization of the 3-D Secure Method data etc).

BASEURL= https://www.computop-paygate.com/

{

    "threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c",

    "acsStartProtocolVersion": "2.1.0",

    "acsEndProtocolVersion": "2.1.0",

    "dsStartProtocolVersion": "2.1.0",     "dsEndProtocolVersion": "2.1.0",     "threeDSMethodURL": "http://www.acs.com/script",     "threeDSMethodDataForm": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cuY29tcHV0b3AtcG
F5Z2F0ZS5jb20vY2JUaHJlZURTLmFzcHg_YWN0aW9uPW10aGROdGZuIiwidGhyZWVEU1Nlcn
ZlclRyYW5zSUQiOiIxNGRkODQ0Yy1iMGZjLTRkZmUtODYzNS0zNjZmYmY0MzQ2 OGMifQ==",     "threeDSMethodData": {         "threeDSMethodNotificationURL": "https://www.computop-paygate.com/cbThreeDS.aspx?action=mthdNtfn",         "threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c"     } }

2.2.5 3-D Secure Method

The 3-D Secure Method allows for additional browser information to be gathered by an ACS prior to receipt of the authentication request message (AReq) to help facilitate the transaction risk assessment. Support of 3DS Method is optional and at the discretion of the issuer.

The versioningData object contains a value for threeDSMethodURL. The merchant is supposed to invoke the 3DS Method via a hidden HTML iframe in the cardholder browser and send a form with a field named threeDSMethodData via HTTP POST to the ACS 3-D Secure Method URL.

3-D Secure Method: threeDSMethodURL

Please not that the threeDSMethodURL will be populated by the 1cs Online Payment System if the issuer does not support the 3DS Method. The 3DS Method Form Post as outlined below must be performed independently from whether it is supported by the issuer. This is necessary to facilitate direct communication between the browser and the 1cs Online Payment System in case of a mandated challenge or a frictionless flow.

3-D Secure Method: No issuer threeDSMethodURL

3-D Secure Method Form Post

<form name="frm" method="POST" action="Rendering URL">

    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsI
nRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">

</form>

The ACS will intercat with the Cardholder browser via the HTML iframe and then store the applicable values with the 3-D Secure Server Transaction ID for use when the subsequent authentication message is received containing the same 3-D Secure Server Transaction ID.

Netcetera 3DS Web SDK: You may use the operations init3DSMethod or createIframeAndInit3DSMethod at your discreation from the nca3DSWebSDKin order to iniatiate the 3-D Secure Method. Please refer to the Integration Manual at https://mpi.netcetera.com/3dsserver/doc/current/integration.html#Web_Service_API.

Once the 3-D Secure Method is concluded the ACS will instruct the cardholder browser through the iFrame response document to submit threeDSMethodData as a hidden form field to the 3-D Secure Method Notification URL.

Once the 3DS Method is concluded the ACS will instruct the cardholder browser through the iFrame response document to submit threeDSMethodData as a hidden form field to the 3DS Method Notification URL.

ACS response document

<!DOCTYPE html>

<html lang="en"> <head>     <meta charset="UTF-8"/>     <title>Identifying...</title> </head> <body> <script>     var tdsMethodNotificationValue = 'eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9';       var form = document.createElement("form");     form.setAttribute("method", "post");     form.setAttribute("action", "notification URL");       addParameter(form, "threeDSMethodData", tdsMethodNotificationValue);       document.body.appendChild(form);     form.submit();       function addParameter(form, key, value) {         var hiddenField = document.createElement("input");         hiddenField.setAttribute("type", "hidden");         hiddenField.setAttribute("name", key);         hiddenField.setAttribute("value", value);         form.appendChild(hiddenField);     } </script> </body> </html>

3-D Secure Method notification form

<form name="frm" method="POST" action="3DS Method Notification URL">

    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9"> </form>

Notice: Please note that the threeDSMethodNotificationURL as embedded in the Base64 encoded threeDSMethodData value points to the 1cs Online Payment System and must not be modified. The merchant notification is delivered to the URLNotify as provided in the original request or as configured for the MerchantID in the 1cs Online Payment System.

2.2.6 Authentication

If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant, the 1cs Online Payment System will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3DS Method Notification).

The authentication result will be transferred via HTTP POST to the URLNotify. It may indicate that the Cardholder has been authenticated, or that further cardholder interaction (i.e. challenge) is required to complete the authentication.

In case a cardholder challenge is mandated the 1cs Online Payment System will transfer a JSON object within the body of HTTP browser response with the elements acsChallengeMandated, challengeRequest, base64EncodedChallengeRequest and acsURL. Otherwise, in a frictionless flow, the 1cs Online Payment System will automatically continue and respond to the cardholder browser once the authorization completed.

Cardholder Challenge: Browser Response

Browser Challenge Response

Data Elements

Schema: Browser challenge response

{

    "$schema": "http://json-schema.org/draft-07/schema#",

    "type": "object",

    "properties": {

        "acsChallengeMandated": {"type": "boolean"},

        "challengeRequest": {"type": "object"},

        "base64EncodedChallengeRequest": {"type": "string"},

        "acsURL": {"type": "string"}

    },

    "required": ["acsChallengeMandated", "challengeRequest", "base64EncodedChallengeRequest", "acsURL"],

    "additionalProperties": false

}

Sample: Browser Challenge Response

{

    "acsChallengeMandated": true,

    "challengeRequest": {

        "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",

        "acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",

        "messageType": "CReq",

        "messageVersion": "2.1.0",

        "challengeWindowSize": "01",

        "messageExtension": [

            {

                "name": "emvcomsgextInChallenge",

                "id": "tc8Qtm465Ln1FX0nZprA",

                "criticalityIndicator": false,

                "data": "messageExtensionDataInChallenge"

            }

        ]

    },

    "base64EncodedChallengeRequest": "base64-encoded-challenge-request",

    "acsURL": "acsURL-to-post-challenge-request"

}

Authentication Notification

The data elements of the authentication notification are listed in the table below:

Browser Challenge

If a challenge is mandated (see acsChallengeMandated) the browser challenge will occur within the cardholder browser. To create a challenge it is required to post the value base64EncodedChallengeRequest via an HTML iframe to the ACS URL.

Challenge Request

<form name="challengeRequestForm" method="post" action="acsChallengeURL">

    <input type="hidden" name="creq" value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYj
I2ZSIsCiAgICAiYWNzVHJhbnNJRCI6ICJkN2MxZWU5OS05NDc4LTQ0YTYtYjFmMi0zOTFlMjljNmIzNDAiLAogICAgIm1
lc3NhZ2VUeXBlIjogIkNSZXEiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMS4wIiwKICAgICJjaGFsbGVuZ2VXaW5k
b3dTaXplIjogIjAxIiwKICAgICJtZXNzYWdlRXh0ZW5zaW9uIjogWwoJCXsKCQkJIm5hbWUiOiAiZW12Y29tc2dleHRJb
kNoYWxsZW5nZSIsCgkJCSJpZCI6ICJ0YzhRdG00NjVMbjFGWDBuWnByQSIsCgkJCSJjcml0aWNhbGl0eUluZGljYXRvci
I6IGZhbHNlLAoJCQkiZGF0YSI6ICJtZXNzYWdlRXh0ZW5zaW9uRGF0YUluQ2hhbGxlbmdlIgoJCX0KICAgIF0KfQ==">

</form>

You may use the operations init3DSChallengeRequest or createIFrameAndInit3DSChallengeRequest from the nca3DSWebSDK in order submit the challenge message through the cardholder browser.

Init 3-D Secure Challenge Request – Example

<!DOCTYPE html> <html lang="en"> <head>     <meta charset="UTF-8">     <script src="nca-3ds-web-sdk.js" type="text/javascript"></script>     <title>Init 3DS Challenge Request - Example</title> </head> <body> <!-- This example will show how to initiate Challenge Reqeuests for different window sizes. --> <div id="frameContainer01"></div> <div id="frameContainer02"></div> <div id="frameContainer03"></div> <div id="frameContainer04"></div> <div id="frameContainer05"></div> <iframe id="iframeContainerFull" name="iframeContainerFull" width="100%" height="100%"></iframe>   <script type="text/javascript">     // Load all containers     iFrameContainerFull = document.getElementById('iframeContainerFull');     container01 = document.getElementById('frameContainer01');     container02 = document.getElementById('frameContainer02');     container03 = document.getElementById('frameContainer03');     container04 = document.getElementById('frameContainer04');     container05 = document.getElementById('frameContainer05');         // nca3DSWebSDK.init3DSChallengeRequest(acsUrl, creqData, container);     nca3DSWebSDK.init3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', iFrameContainerFull);       // nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest(acsUrl, creqData, challengeWindowSize, frameName, rootContainer, callbackWhenLoaded);     nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '01', 'threeDSCReq01', container01);     nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '02', 'threeDSCReq02', container02);     nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '03', 'threeDSCReq03', container03);     nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '04', 'threeDSCReq04', container04);     nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '05', 'threeDSCReq05', container05, () => {         console.log('Iframe loaded, form created and submitted');     }); </script>   </body> </html>

Once the cardholder challenge is completed, was cancelled or timed out the ACS will instruct the browser to post the results to the notfication URL as specified in the challenge request and to send a Result Request (RReq) via the Directory Server to the 3-D Secure Server.

Notice: Please note that the notification URL submited in the challenge request points to the 1cs Online Payment System and must not be changed.

2.2.7 Authorization

After succefull cardholder authentication or proof of attempted authentication/verification is provided the 1cs Online Payment System will automatically continue with the payment authorization.

In case the cardholder authentication was not succesfull or proof proof of attempted authentication/verification cannot be provided the 1cs Online Payment System will not continue with an authorization request.

In both cases the 1cs Online Payment System will deliver a final notification to the merchant specified URLNotify with the data elements as listed in the table below.

Payment Notification

Browser Payment Response

Additionally the JSON formated data elements as listed below are trasferred in the HTTP response body to the cardholder browser. Please note that the data elements (i.e. MID, Len, Data) are base64 encoded.

Data Elements

{     "$schema": "http://json-schema.org/draft-07/schema#",     "type": "object",     "properties": {         "MID": {             "type": "string"         },         "Len": {             "type": "integer"         },         "Data": {             "type": "string"         }     },     "required": ["MID", "Len", "Data"],     "additionalProperties": false }

Merchants are supposed to forward these data elements to their server for decryption and mapping agianst the payment notification. Based on the payment results the merchant server may deliver an appropriate response to the cardholder browser (e.g. success page).

Decrypted Data

Sample of the decrypted data:

MID=YourMID&PayID=PayIDassignedby1csOPS&TransID=YourTransID

2.3 3DS 1.0 Fallback

In case the Access Control Server (ACS) of the cardholder’s bank does not support any EMV 3DS protocol version (i.e. 2.0 or higher, see acsStartProtocolVersion) the threeDSMethodDataForm element of the versioningData object in the payment response will be Null.

Sequence Diagram

2.3.1 3DS 1.0 Authentication

In order to a 3DS 1.0 authentication request through the cardholder browser it is required to construct a form with the data elements provided in threeDSLegacy and to post it to the acsURL.

The form fields that are sent to the ACS are listed in the table below:

Sample: PAReq form passed through the Cardholder to the ACS URL

<html>

    <head>

        <script language=\"javascript\">

            <!--

                function sendpareq()

                    { 

                        document.pareq_form.submit();                    }             // -->         </script>     </head>          <body onload="javascript:sendpareq();">         <form action="https://pit.3dsecure.net/VbVTestSuiteService/pit1/acsService/paReq?summary=ZTIwOWMwYmEtNTVhOC00NDExLThkZDktYzllODk1NmZlNDQ0" method="POST" name="pareq_form">             <input type="hidden" name="PaReq" value="eJxVUst22jAQ/RUfL7rpMZKFiQ0dK4dXgAVOTmuSpjvVGsApfkSWA+TrK/Fo0t29M6M7M3cEt4di57yhavKqjF2/Q10Hy6ySebmJ3VV650Wu02hRSrGrSozdIzbuLYd0qxAnPzBrFXJYYtOIDTq5jN1aCIEioyzywkhILwh7gddnFD1JMVyv
15HfYz2Xw8PwO75yuPTmpnWHAblSo6myrSg1B5G9jhYJD266jHWBXCgUqBYTPk4fR4+M+jdAzgEoRYG8zrXGRn+dFb/nz
hdR1N+ccQXklIOsakutjpyF5tWVQKt2fKt1PSBkv993sqqoW13VHYlAbA7Ix0gPrUWN0Trkkv+aLVnyvjkuZ6tD8vS8Ty
a7l/unBXt+n8ZAbAVIoZGbMSPaY4HjB4MuHQR9IKc4iMIOwX1KzXpnDLVtMfyU+BwA47sydzryfhiZHa4M8FCbM5kKY+U/DBKbjKfGD9PQQiAfC4zn1uFMG+vm+V06bad/Zi+rn6rrJ20xWt4P49h6fiqw8rnxyo/8s74lQKwEuZyTXP6CQf/9kb8b1MvQ">             <input type="hidden" name="TermUrl" value="http://localhost:40405/test/3DTermURL.aspx?PayID=dc67820e15f049c9b6c1f0420729da8a&TransID=20180524-162741-084&MID=gustav">             <input type="hidden" name="MD" value="Optional merchant session data">         </form>     </body> </html>

Once the authentication has been completed or the cancelled by the cardholder the ACS will redirect the cardholder through the cardholder’s browser to the TermURL as specified in the initail payment request.

Notice: The Payer Authentication Response (PaRes) will be transferred via HTTP POST method while MID, PayID and TransID are sent in the HTTP query string (i.e. HTTP GET).

Data Elements transferred to the TermURL

2.3.2 Authorization

In order to authorize an 3DS 1.0 authenticated payment you must POST the parameter as listed in the table below unencrypted to https://www.computop-paygate.com/direct3d.aspx. The response always is encrypted (Len + Data).

Request Elements

Response Elements

2.3.2.1 Payer Authentication Request Message Fields

The Payer Authentication Request (PAReq) message field is a data element constructed by First Cash Solution’s Merchant Server Plug-in (MPI).

The MPI builds the XML PAReq, in canonical format according to the DTD. It passes the XML stream to an RFC1951-compliant compressor, which produces an RFC1950-compliant output stream which turn is Base64 encoded.

For eductaional purposes the PAReq data elements are listed in the table below.
 

PAReq

2.4 Silent Order Post (PayNow)

2.4.1 Overview

A Silent Order Post or Direct Post is a transmission method where form data from a merchant website are getting directly posted to a third-party server. This is commonly achieved through the formaction attribute that specifies the URL the data are sent to.

Notice: Sensitive data such as card details can be captured within a merchant’s website without being processed by the merchant server as the POST is submitted silently. The URL endpoint in the 1cs Online Payment System to receive Silent Order Post requests is referred to as PayNow.

<form action=”../payNow.aspx” method=”post”>

This approach is very similar to First Cash Solution hosted payment forms and leaves the merchant in full control of the checkout experience as all website elements are delivered from the merchant’s server.

PCI-DSS Considerations: Merchants processing card transactions using the Silent Post model must submit the PCI DSS Self-Assessment Questionnaire (SAQ) A-EP. This SAQ is more comprehensive and thus might require more time and resources in comparison to SAQ A applicable to merchants that use hosted payment pages. However, merchants should always consult with their acquirer to evaluate the level of compliance required and refer to the PCI DSS guidelines. This does not affect the use of pseudo card numbers which is possible without submitting the SAQ questionaire.

Notice about Cookie-/Session Handling: about Cookie-/Session Handling: Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additial information and different solution approaches.

Sequence Diagram

2.4.2 Payment Request

Please POST the form data as outlined in table below to https://www.computop-paygate.com/payNow.aspx.

Form elements

(- First Cash Solution will continue to support the legacy form data fields that are currently in use. -)

Data

Sample HTML form:

BASEURL= https://www.computop-paygate.com/

<!DOCTYPE html>

<html>

    <head>

        <title>Merchant Checkout</title>

    </head>

    <body>

        <form name="card form" action="https://www.computop-paygate.com/payNow.aspx" method="post">

            <input type="hidden" name="MerchantID" value="MerchantID">

            <input type="hidden" name="Len" value="Length of the Blowfish encrypted data">

            <input type="hidden" name="Data" value="Blowfish encrypted data">

            Cardholder:

            <input type="text" name="cardholder"><br>

            Card number:

            <input type="text" name="number"><br>

            Expiry date:

            <input type="text" name="expiryDate"><br>

            CVV2:

            <input type="text" name="securityCode"><br>

            Card brand:

            <input type="text" name="brand"><br>

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

        </form>

    </body>

</html>

When the payment is completed the 1cs Online Payment System will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess resepctively to the URLFailure.

The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.

Notice: Please note that the call of URLSuccess or URLFailure takes place with a GET in case of fallback to 3-D Secure 1.0. Therefore your systems should be able to receiver parameters both via GET and via POST.

2.4.3 HTTP POST to URLSuccess / URLFailure / URLNotify

3 JSON objects

Notice: Please note that the data within all JSON objects is encoded using UTF-8 and then must be also Base64 encoded. This applies in particular to special characters such as “Umlaute” and diactrics.  

1cs Online Payment System validates JSON objects on all requests which contain parameter “MsgVer=2.0”. This is independently of the fact whether 3DSecure2 is activated for your MerchantID.

Please make sure no empty parameters or objects are submitted. Under such circumstandes 1cs Online Payment System assumes an error and rejects the transaction.

• accountInfo
• acsRenderingType
• address
• authenticationResponse
• Basics of Base64-encoding
• browserInfo
• card:request
• card:response
• challengeRequest
• country
• credentialOnFile
• customerInfo
• externalPaymentData
• ipInfo
• merchantRiskIndicator
• phone
• priorAuthenticationInfo
• resultsResponse
• subMerchantPF
• threeDSData:request
• threeDSData:response
• threeDSLegacy
• threeDSPolicy
• versioningData

4 Important notes

4.1 3DS authentication hosting

Payment platform also supports scenarios where merchants wish to use BNP’s 3DS Server (3DS 2.0) respectively 3DS MPI (3DS 1.0) as a hosted solution and subsequently authorize the transaction via an integration to a third-party.

Notice: Please contact the First Cash Solution Support Team to request neccessary configuration changes at your Merchant ID.

Authentication hosting only is supported for

• Hosted Forms (paySSL) and
• Server-2-Server

integrations.

All messages, sequences and data elements exchanged between the merchant environment and the 1cs Online Payment System remain the same as for regular payments except that the 1cs Online Payment System does not authorize the transaction with an acquirer. Authentication data (e.g. authenticationValue and eci) necessary for subsequent authorization transactions are provided via threeDSData and resultsResponse (challenge flows only).

Please see below a sample payment notification for a succesful authentication only transaction:

MID=ACME& PayID=9e944d5d56f3461da39380a666d346d1& TransID=V3DSTestSuite_001& XID=334ce1701a5b444db4e2296a680ae330& Code=00000000& Status=OK& Description=Authentication completed correctly& card= {     "number": "400001XXXXXX8323",     "brand": "VISA",     "country": {         "countryName": "United Kingdom of Great Britain and Northern Ireland",         "countryA2": "GB",         "countryA3": "GBR",         "countryNumber": "826"     } }& threedsdata= {     "authenticationStatus":true,     "acsProtocolVersion":"2.1.0",     "authenticationValue":"JAmi21makAifmwqo2120cjq1AAA=",     "eci":"05",     "threeDSServerTransID":"9e944d5d-56f3-461d-a393-80a666d346d1" }& resultsResponse= {     "threeDSServerTransID":"9e944d5d-56f3-461d-a393-80a666d346d1",     "acsTransID":"1e43b52f-3623-4e5d-8917-41c5c15b7218",     "acsRenderingType":{         "acsInterface":"native",         "acsUiTemplate":"text"     },     "authenticationType":"02",     "authenticationValue":"JAmi21makAifmwqo2120cjq1AAA=",     "challengeCancel":"",     "dsTransID":"c626e8a0-f2ba-42b3-aa6d-620658421f3a",     "eci":"05",     "interactionCounter":"01",     "messageCategory":"01",     "messageExtension":"",     "messageVersion":"2.1.0",     "sdkTransID":"",     "transStatus":"Y",     "transStatusReason":"" }& MAC=AE6E011454EB54858006007D73D766B7A0306AB8FD925D08C3BF222D4A366123

4.2 Account Verification  

An account verification also known as a zero value authorization is a request to check whether a card account is in good standing (i.e. the card is not stolen and the card account can be used for payments).

3DS and Account Verification

Please note that if an account verification (i.e. AccVerify=Yes) in combination with 3DS is requested the authorization will be always performed with a zero-value. The authentication however will be carried out with the amount correspondent to the value submitted in the Amount field. If the transferred Amount is a zero-value the related liability shift will be also for a zero amount.

Credential on File

Please note that non-payment transactions that establish a credentialOnFile (aka Card Add) require an account verification.

Standalone Account Verification

If you request an account verification without adding a card on file the data element browserInfo becomes optional for Server-2-Server and Silent Order Post integrations. Other conditional data elements might also be not applicable.

4.3 Amazon Payments MFA

Overview

In order to be compliant with the PSD2, Amazon Pay introduced SCA for their transactions.

The SCA Upgrade introduces a “Confirmation Flow” to handle Multi-Factor Authentication (MFA) when it is required.

When MFA is required, the Confirmation Flow shows the credit card issuer’s MFA challenge to the buyer. After the buyer interacts with the Confirmation Flow (for example, completes the MFA challenge), the buyer is returned to the merchant’s site (for example, order confirmation page).

Please update the AmazonPay checkout workflow after a buyer initiates their order completion and before you call the Authorize Operation.

Changes

New JavaScript function confirmationFlow()

Due to MFA, it is necessary after a succesful confirmation of an order to start a new call, the ConfirmationFlow.

To start the workflow, please

• execute a Confirm on the order on the 1cs Online Payment System, after you receive a result
• start the confirmationFlow in case of success with “confirmationFlow.success()”
• in case of failure “confirmationFlow.error()” aborts the process.

Implementation of the new Javascript call is shown below. This has been optimized for our First Cash Solution merchants.

Notice: This action should be triggered by clicking on the “Buy Now” button!

function confirmationFlow() {     // Get resultCode from First Cash Solution call AmazonAPA.aspx, EventToken: COD     var resultCode_First Cash Solution = the 1cs Online Payment System call to get the ResultCode from the Confirm, AP call COD or SCO.     // Your AmoazonSellerID / AmazonMerchantID     var amazonSellerId = 'Your_SellerID';     // Amazon order reference generated by Address Widget     var orderReferenceId = 'Your_Order_Reference';     //Initiate confirmation flow     OffAmazonPayments.initConfirmationFlow(amazonSellerId, orderReferenceId, function (confirmationFlow)         {             if(resultCode_First Cash Solution = '00000000')             {                 confirmationFlow.success();             }             else             {                 confirmationFlow.error();             }         }     ); }

Please also refer to https://developer.amazon.com/de/docs/eu/amazon-pay-onetime/sca-upgrade.html for additional guidance.

Merchant should be able to handle First Cash Solution’s redirection (URLSuccess / URLFailure) with the result of the MFA Challenge.

URLSuccess / URLFailure for ConfirmOrderDetails (COD) and SetOrderDetails and ConfirmOrder (SCO) call

On “Order Now” the merchant has to send the URLSuccess and URLFailure in the calls (EventToken=SCO | COD), because the redirect is executed after the MFA challenge.

After “Order Now” the Confirm (EventToken=SCO | COD) is executed on the payment and then the redirect to the challenge takes place using the JavaScript code shown above.

AmazonAPA.aspx

The following event calls at the 1cs Online Payment System are affected by the changes. Please make sure to include the new parameters.

User Flow and Sequences

Flow

1.     Clicks on AmazonPay button to sign-in

2.     Chooses an address from the widget

3.     Chooses payment method from the widget

4.     Confirms the order

Option 1: SCO

This is the recommended option.

Option 2: SOD and COD

1.     The first call is to be made to ConfirmationFlow – with this, AmazonPay can handle the MFA if required. Here is confirmationFlow error/success to be set. Reference to the Amazon Pay Widgets.js file already used for the other widgets.

2.     Call SetOrderDetails (SOD) including OrderTotal

3.     Call ConfirmOrderDetails (COD) set URLSuccess/URLFailure parameter with a returnURL value

Notice: As shown above, we recommend the SCO call that is a single step to set the order details and also to confirm the order Details.

Option 3: MFA Failure

Notice: We recommend our merchants to only work with the the 1cs Online Payment System status or the 1cs Online Payment System response code in these cases.

Status =>Abandoned:

Status =>Failure:

1.     If the customer fails or abandons the challenge, the customer is redirected to the URLFailure.

2.     Logout the user.

3.     Cancel the order by calling “Reverse.aspx”

Cancel Order by Calling “Reverse.aspx“

In order to reverse a complete order with Amazon Pay with the function „CancelOrderReference“, please request to https://www.computop-paygate.com/reverse.aspx

More and detailed information is found in the official First Cash Solution documentation here: Amazon Pay Manual

Status

If the MFA is successful, the redirection is done to URLSuccess, if not the redirection is done to URLFailure.

Notice: The Amazon Authentication Response is given back to the shop  via the the 1cs Online Payment System in the, Response Parameter = amazonstatus.
Example: amazonstatus=Abandoned

Notice: In the Amazon SCA manual point 3 (Amount consistency)
The AuthorizationAmount value (in the Authorize operation) must always match the CaptureAmount value (in the Capture operation).
If not the Capture operation call response will be handled asynchronously; the Capture object State value is set to Pending and may not be processed in real time, even if it is requested within seven days of the Authorize operation call!

4.4 Dynamic billing descriptors

General Requirements

The billingDescriptor element is used to override the merchant name that is sent to a cardholder’s bank where applicable.

The merchant name is the most important factor in cardholder recognition of a transaction record typically printed on a cardholder statement. It should reflect the operating name of a company (i.e. ‘Doing Business As’ (DBA) name), as opposed to the legal name, by which a cardholder would recognize the merchant to avoid any confusion and to minimize copy requests.

As a standard, acquirers usually forward the merchant name they got on file with the merchant’s account. Please note that the card organizations established strict rules around merchant names on cardholder statements.

However, there are a number of specific exceptions where supplementary data can be added to the DBA name depending on the use case and industry (e.g. airlines, railway services, car rental, fuel stations etc.).

Formatting the merchant name

The authorization and clearing systems of the card organizations provide varying sizes for merchant names. The smallest common denominator is 22 characters. Thus, merchant names longer than 22 characters will not fit into the merchant name field and must be abbreviated in a way that it is still recognizable to the cardholder.

Purchase of Goods or Services

For regular purchases of goods and services additional information may be included after the merchant name and an asterisk (*) to indicate an order number, reference number, or other information to identify a transaction.

No-Show Transactions

May also include the words “NO SHOW” after the merchant name.

Purchase of an airline Ticket (or passenger railway tickets in the US Region)

Must contain all of the following:

• An abbreviated airline (or US railway) name in the first 11 or 12 positions
• A blank in position 12 if applicable
• Airline (or US railway) ticket identifier beginning position 13

4.5 Mandatory and Conditional Required Data Elements for EMV 3DS

Please note that some data elements in EMV 3DS that are marked as conditional required are further specified as:

Required unless market or regional mandate restricts sending this information.

This applies for instance to data elements such email, phone number or billing address.

Considering the legal landscape and depending on the issuer (or more precisely on the vendor of the issuer Access Control Server (ACS)) this specification might be interpreted as strictly required within the European Economic Area (EEA).

Contrary to the EMV 3DS protocol specification:

A.1 Missing Required Fields

. . .

Unless explicitly noted, if a required field is missing, the receiving component returns an Error Message . . . This applies whether the field is always Required or Conditionally required.

The card schemes mandated that issuers must not decline EMV 3DS messages when one or more of conditional fields are absent. But the card schemes also stipulate that merchants must send conditional fields in EMV 3DS messages in accordance with the applicable data protection law.

The following elements are considered key and it is strongly advised to provide these data points:

• Cardholder Information
  • Name
  • Email address
  • Home phone number
  • Mobile phone number
  • Billing address
  • Shipping address
• Browser Information (depending on the integration type)
  • IP Address

Notice: As a general rule it is strongly recommended to always send conditional required data elements to avoid unnecessary friction and declines.

4.6 Multi-party e-commerce / agent model

In some scenarios cardholder data are captured and processed (e.g. authentication and authorization) through third-party websites on behalf of one or multiple merchants. The third-party website operartor is usually reffered to as an Agent. Because the cardholder is interacting with the Agent’s environment it is the Agent’s obligation to perform payment authentication.

The requirements for Agent processing models are described in the following paragraphs.

VISA

Travel and Hospitality Merchants

Scenario 1: Authentication performed by a Travel Agent on behalf of one single merchant

When the Travel Agent is facilitating authentication on behalf of a single merchant at the time of booking the process is as follows:

• The Travel Agent discloses to the cardholder appropriate T&Cs and follows other requirements associated with the potential future MIT type the merchant may have to process.
• The Travel Agent authenticates the transaction for the total booking amount (Merchant descriptor name = “Travel Agent Name * name of merchant ” )
• The Travel Agent may optionally perform an account verification to check validity of the card before passing the card details to the merchant (If an account verification is performed, it must not include the CAVV as this is required by the end merchant )
• The Travel Agent passes the authentication data to the merchant.
• The Merchant submits a normal authorization request to the 1cs Online Payment System including the required data in the threeDSData [Request] JSON object.

In case the merchant wants to perform the payment at a later time than he should:

1.     Perform an Account Verification(i.e. AccVerify=Yes)with the authentication data received from the Agent within 24 hours.

2.     Subsequently when the amount is due send an authorization flagged as MIT including the schemeReferenceID from the previous account verification transaction.

Scenario 2: Authentication performed by a Travel Agent on behalf of several other merchants.

This scenario covers the case when a customer makes a travel reservation online via a Travel Agent which includes the delivery of services by multiple merchants.

• The Travel Agent discloses to the cardholder appropriate T&Cs and follows other requirements associated with the potential future MIT type the merchant may have to process
• The Travel Agent then authenticatesthe transaction for the total booking amount ( Merchant descriptor name = “Travel Agent Name” )
• An additional 3DS 3RI authentication requestis required to provide CAVVs for each further merchant who will perform an authorization.
• The Travel Agent submits authentication data to the merchant.
• The Merchant submits a regular authorization request to the 1cs Online Payment System including the required data in the threeDSData [Request]JSON object.

In case the merchant wants to perform the payment at a later time than he should:

1.     Perform a zero-value account verification with the authentication values received from the Agent
within 24 hours.

2.     Subsequently when the amount is due send an authorization flagged as MIT including the schemeReferenceID from the previous account verification transaction.

Other Merchants

Scenario 3: Authenticated CIT from the Agent and subsequent MIT transaction from the merchant

This is the case when the Agent performs the authentication and subsequently uses the VISA CAVV for its own authorization payload. In such a case as the Agent already used the CAVV and he may not be able to use the 3DS/3RI feature (for having a new CVV for the merchant) than he can provide to the merchant only the schemeReferenceID of the initial CIT together with the payload so that the merchant may initiate his authorizations flagged as an subsequent MIT (i.e UCOF, Delayed Auth)

As a difference worthy to be highlighted between VISA and MC is such use cases is that:

a) Authentication Value (CAVV/AAV)

In case of VISA, the Agent who is performing authentication on behalf of several merchants needs through the 3DS/3RI request (only possible with EMV 3DS 2.2 version) to provide separate CAVV’s values for each merchant separately.
MasterCard on the other hand is stating that for the Agent Model where a single authentication is linked to multiple authorizations the same authentication code/ AVV could be used for multiple transactions.

b) schemeReferenceID

Under the third scenario the Agent can provide to the merchant together with the payload only the ‘schemeReferenceID’ from the initial CIT with no Authentication data in such a way that the merchant is able to initiate subsequent MIT transactions referring to the initial establishment.
For VISA the “schemeRefernceID” (transactionID) is usually provided as a single response parameter while for Mastercard the “schemeReferenceID” is a concatenation of fields like: *(SettlementDate+FinancialNetworkCode& BanknetReference).

-SettlementDate -> n..4
-FinancialNetworkCode -> an..3
-BanknetReference -> an..9

* Agents using this type of scenario (with CIT/MIT) are recommended to provide their merchants with the required MasterCard reference data where the merchant can subsequently submit it to the 1cs Online Payment System “schemeReferenceID” during MIT transactions.

Please also be advised that the above approach for handling each of these scenarios serves only as recommendation, therefore, merchants and Acquirers can choose alternative options that complement their business model, as long as they remain compliant with the key principles of the PSD2 SCA.

4.7 Non-payment authentications for Card Add

Please use AccVerify to request an Account Verification when adding a card to COF without a payment.

Non-payment authentications for Card Add transactions always require step-up authentication (i.e. challenge).

Provisioning, such as Card Add is generally considered as an

action through a remote channel which may imply a risk of payment fraud or other abuses

pursuant to article 97(1)(C) PSD2. There are no exemptions provided for these actions.

When a card is added to COF and a payment is requested at the same time, only one SCA is needed.

4.8 Stored Credentials

Whenever card credentials (i.e. cardholder name, card number/token and/or expiry date) are stored for future use a prior consent by the cardholder is required.

During the establishment of such a mandate the cardholder should be informed about the exact reason for storage of the credentials with the merchant. That means an authorization request that establishes a mandate for stored credentials also must indicate the kind of potential subsequent transactions.

These subsequent transactions with a stored payment credential that the cardholder has consented to are broadly categorized into Customer Initiated Transactions (CITs) and Merchant Initiated Transactions (MITs).

Notice: The decisive difference between CITs and MITs is that the latter are out of scope of the RTS for SCA. This is because the Cardholder regularily is off-session and thus, practically not available for an authentication.

There are various use cases for MITs that can be generally categorized into transactions following a certain Industry Practice and Standing Instructions.

In the 1cs Online Payment System CITs and MITs for Standing Instructions are flagged via the JSON object credentialOnFile.

Notice: Please note that all unscheduled MIT transactions are not supported in 3DS 2.0 and thus, will be directly sent for authorization without entering the the 1cs Online Payment System 3DS sequence.

MIT Recurring transactions however will be sent through the 3DS 2.0 protocol to the issuer in order to garantuee best possible acceptance rates.

Please note that with each initial CIT that establishes a mandate for subsequent MITs you will receive a schemeReferenceID that must be included in follow-up transactions in order to link the sequence.

Once SCA becomes mandatory on September 14, 2019 existing MITs covered by cardholder agreements can continue to be processed without a schemeReferenceID if the mandates were setup before that date (i.e. grandfathering). Please do not submit any dummy values. the 1cs Online Payment System will automatically apply appropriate values in the authorization protocol to indicate so called grandfathering.

4.8.1 Real-time service via mobile app with payment after service completion

In many scenarios within the sharing economy such as car sharing or bike sharing a customer’s mobile device is an essential part in the service delivery and payment system. Card credentials are often getting stored with the cardholder’s account at the service provider for optimal user experience.

The sequence of actions to be performed are outlined in the diagrams below.

Card Add as part of a none payment transaction (NPA)

Notice: If the Card Add is NOT part of a payment transaction it is mandatory to perform an account verification (see AccVerify).

Card Add as part of a payment transaction

Service Provisioning

Notice: Unscheduled Credential-on-File (UCOF) MITs are not applicable in scenarios where the cardholder is on-session at the time of service completion and thus, is available for authentication. This is regularily the case for car sharing or ride hailing apps for example.

Notice: If the estimated amount is lower than the final amount it is recommended to perform a full reversal on the originally authorized amount and to submit a new authorization for the final amount.

Amount

Card Add

A zero amount or any estimated amount. Please note that the amount is usually displayed to the cardholder during an authentication challenge and thus, should be within the customer’s reasonable expectation.

Service Provisioning

The amount in the authorization request should be an estimated for the service provision according to resonable customer expectations. Once the service has been completed incremental authorizations may be used before the final amount is captured.

credentialOnFile

Card Add

The UCOF flag is submitted to establish a mandate for storing the credentials and to obtain an initial schemeReferenceID. The card issuer is obliged to perform a step-up during authentication.

{     "type": {         "unscheduled": "CIT"     },     "initialPayment": true }

Service Provisioning

The CIT flag is submitted in order to enable UCOF transactions without card security value.

{

    "type": {

        "unscheduled": "CIT"

    },

    "initialPayment": false

}

AccVerify

All Card Adds that are not performed as part of a payment transaction require and account verification.

5 Test cards

Card numbers

One-time Passwords (OTPs)

Notice: Please confirm the One-Time-Password in case of a challenge with mouseclick instead of Enter key, because otherwise the “Cancel”-button is selected and the authenfication is terminated.

transStatus

transStatusReason

6 Terms and Definitions

Mandatory and conditional data elements

Conditions in 3DS 2.0 are often described as ‘Required unless market or regional mandate restricts sending this information.’

This applies for example to the email address of the cardholder. Please note that some vendors of ACS software and some issuer might consider these data elements technically as mandatory within the EEA since there are currently no known restrictions. Thus, it is highly recommended to submit these data elements if possible.

Condition Codes

Definitions

7 Response codes

Common notes on 1cs Online Payment System error codes

The 1cs Online Payment System response codes are 8 digits and are coded (i.e.: they consist of digits 0..9 and characters A..Z) in this format: AN8,  (NNNNAAAA), e.g. 22060203 or 2206014H.

The structure of the error codes is always:

Digits 1: Status code or error code

Category 2 .. 4: Common modules

Category (2-4)

Please note that some modules may be deprecated or still under development.  

Detail (5-8)

8 ECI Codes EN

The ECI value is provided by the issuer ACS. It indicates the level of authentication that was performed on the transaction. The ECI value received from authentication is forwarded in the authorization request and also determines whether a transaction recieves liability protection.

Visa, American Express, Discover/Diners, JCB, Cartes Bancaires (VISA), UPI

MasterCard, Cartes Bancaires (Mastercard)

9 3DS 2.0 Merchant Use-Cases & Testing of 3D-Secure 2.0

What can you expect in this area?
Due to various scenarios that can arise with 3-D Secure 2.X, we will subdivide the following into three thematic areas:

1. General technical adjustments (relevant for all merchants)
2. Use cases for transaction flagging (different handling depending on merchant scenario)
3. Test 3-D Secure 2.X via Computop

General technical adjustments

Which request types does 3D-Secure 2.0/SCA affect?

• Affected request types are: Authorisation and Sale
• Capture (booking) and credit notes are excluded from changes

How will data transfer look like with 3-D Secure 2.x?

REQUEST: During the implementation of 3-D Secure 2.0 and the necessary delivery of larger amounts of data, we recommend you to call our forms via Form-POST Method. Please note that the option iFrame is still available. Background are possible browser restrictions, which can lead to the fact that the sent data string is cut off.
Example:

RESPONSE:
Please also note a change to the final redirect to the URLSuccess | URLFailure.
This will be excecuted as a body POST in the case of a 3D Secure 2.0 transactions. Therefore, you should be able to receive both a GET and a POST response on the URLSuccess | URLFailure.

How can I choose between 3-D Secure 1.0 or 2.0?

• IMPORTANT: To be able to use and test 3-D Secure 1.0 or 3-D Secure 2.0, we have to configure 3D Secure on our the 1cs Online Payment System on your behalf. Please contact support@1cs.de if you have not yet started this process.
• By default, each payment is made following the 3D Secure 1.0 process.
• If you want to follow the 3D Secure procedure 2.0, please use the request parameter MsgVer=2.0. This applies to tests as well as in production at a later stage.
  • Parameter: MsgVer
    Value: 2.0

Use of JSON objects becomes mandatory

Please note that a mandatory extension of existing parameters comes with the implementation of 3D Secure 2.0 . For this reason, the 1cs Online Payment System expects and returns relevant additional data as JSON Object.
The JSON Object must be Base64 encoded and regularly transmitted with all other parameters in the encrypted Blowfish data to the 1cs Online Payment System.

Please pass JSON Objects with values only. Empty or zero-filled objects/parameters lead to a rejection.

JSON Example request – encrypted data

BASEURL=https://www.computop-paygate.com/

{{BASEURL}}payssl.aspx?MerchantID=Generic3DSTest&len=1800&
data=CDC44E5A9D2C8A559CEDF1CCA97C9FBD3D90E046BFBF96F06ADA9A00FB0BC3494317E8D924FF44729671B93348B477F880541AC
FF12C8E3A868CD55FEA95219C245CF7F4716FCF3462167A8B63D11424FA7BD30891504F8465C56805975115EB71C0A04E5D7466D77149
5035749FFF94D3087529F578DEF518003EA1422F6DE7B7DFD78A0DD695550623A42BF41A422EC219012318FE26D2B757F12BDFE046EA4
CB8D35079ABAB6859691FEE1B03483471495035749FFF94D3087529F578DEF518003EA1422F6DE7D4E20259A484D23A9EFC7F4ADB209D
D67D8EDE5BD2AC0CB2682D7CF26A6624A54BCF4E93219ADD89ABA6214820D4BAA5A9A184DD7F8AF3E2BE98C5B63113276B023B92DA5
AADCCD7387B71B6651A0E7E4E42F8790122386AA9A184DD7F8AF3E23CFEC0086B59B6A9D98EB96DFDA496D97D85706A4A810056FE48
AB878EFC1E976DB7504D402F4B96778B45ADE1DF3E217EFFBA566359677AB73F514F1E75F11DBE3E15983BA530E7D5B13A87D1A2ED19
A9A184DD7F8AF3E21D32D652A71B2A49A58F3A30256097DA11388C26E7CBEB12E65B31C485C94DE8179CEACDE9237EF4C426A05E594
E28069E10B19AE173D25A93A546845C5D78C44112031D6D5DE9B4ABA6214820D4BAA5A9A184DD7F8AF3E260C35EC59CD2FAA2435CD
631BFC801AA7C72A1BAE39879C0BF733EDC45DD99F3A9A184DD7F8AF3E2DDA25A6458507ACE3B3CAAC3A4B293A9C6177F7F00EBFB6
924050D9DF661DE8EC204863D819ABF9564498E9F2D72BEFF2E040214C4961D8737821BA1F638BE05FB01E1B382733FC42D6B04AB80D
66218C75E691B9475C5F6CF13AD357057BC6B5864EE113DF2272EF6572101D5E45CB634F3E941FA7B3EA7E636EAEF751C67C82F8E8D9
B618E69826221B2A42D7F694D9E10B19AE173D25A6EB48BD63BFFE0FAFC78722BD9FFA39623B5D40494B96D2A9E10B19AE173D25A188
DA61C8E3401850C400A3144C3547808A0C82C7B8E9863D017852B02FBFE6D62983EBC372B1A8108D832C13F92E88535C213D0FDA1B1A
5C426A05E594E28069E10B19AE173D25A92AD74641E23F21D1D66F1B352AFCCD408B1727FACC2405AA9A184DD7F8AF3E29B3106F31EE
7D473A854D99576FDD5620141A96DEF638FCE4362F90866AED8044E42F8790122386AA9A184DD7F8AF3E20F6BF2E070199426696A900F
EEBC7848B6F72D445F2CB9F0ED160CC32B1A3C40C426A05E594E28069E10B19AE173D25A201E55FC81E8F7CD78FFD98E342897C11AB2B
E505B3E8421C63E936DCCF29058C31D72A3697DA2C89EFC7F4ADB209DD67D8EDE5BD2AC0CB2682D7CF26A6624A54BCF4E93219ADD89
ABA6214820D4BAA5A9A184DD7F8AF3E2BE98C5B63113276B023B92DA5AADCCD7387B71B6651A0E7E4E42F8790122386AA9A184DD7F8
AF3E23CFEC0086B59B6A9D98EB96DFDA496D93F669AB8A34E11706F7B3F762241F749A9A184DD7F8AF3E286587E20CD9A354709F67B1
501183CFC5D6FD3FD6E23B0D4FA9746B8925D4A4FA9A184DD7F8AF3E21D32D652A71B2A49A58F3A30256097DA11388C26E7CBEB1207
58D07B77A47DB34E359C7AE383D69BC426A05E594E28069E10B19AE173D25A93A546845C5D78C44112031D6D5DE9B4ABA6214820D4B
AA5A9A184DD7F8AF3E260C35EC59CD2FAA2435CD631BFC801AA7C72A1BAE39879C0BF733EDC45DD99F3A9A184DD7F8AF3E2DDA25A
6458507ACE3B3CAAC3A4B293A9C6177F7F00EBFB6924050D9DF661DE8EC204863D819ABF9564498E9F2D72BEFF2E040214C4961D873
7821BA1F638BE05FB01E1B382733FC46AA58C2847221D78069144B06DE3755A6C88EADD3B3FCCD6F6572101D5E45CB634F3E941FA7B
3EA7B08783F57D9AD1BAB2071FAB9B93B3C13FF102AD44B6A493B5C341FB37BF525B0A0E4F490BE1D46A4C5B8F691A2020868119A0A
EB9E9BCD4F9D783FEA316723E17976FBB4909040AE279D66AF13B8441582CB00BB30835AB6401E5CDDF295F533AEE31D2677314D288
F2C15BFB16837EF4A779C1E39E4AA1CEE13FABDB2B89D9A7A89ED81EC005BCD416330CFCE5CF716A316FDF29A9CFF3F25490656C80
0BCA582CB00BB30835ABABD19D247E68289A52F1387D978126C967F9BBB890618AF5A0E5136C7DC2892D2460687217D2779B5836D3F
1FFAE8F3B582CB00BB30835ABEE02C59E0AAF8C913339B61F9DDFB7DAC4FF2460869E4876C5DFD5D39E79330D427654226D9E37E72D
7A4C332F59563DF70B3A840877E2B1BF739A2347A73347F7DA9F100EEBC189ADE92F98BE65BCBE29FE1A3DFE89E44EEEBF9C902BBAA
7C2F68CBC48C724B889A53EA148988B56CC52D52743C045F57844F6607DDEA75FE613EAC80E2C02BCEA89B71E52E64D7538DC9B82E
B2740B82C698F43B6A62D770935233D5F10E593D0519511BAAD615B0035D7524B097C29BA39EBEBEDB93425EB7824B9CCDB1397E716
993ED326500615B4B1853A59F760A0E06373BDFE1CC6695A93B15851F56428&template=ct_responsive_ch&language=en
 

JSON Example request – request parameter before encryption

MerchantID=Generic3DSTest

&MsgVer=2.0

&TransID=1234567890

&RefNr=20200124

&Amount=100

&Currency=EUR

&URLNotify=https://www.computop.com

&URLSuccess=https://www.computop.com

&URLFailure=https://www.computop.com

&billToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIk5hcG9sZW9uIiwNCiAgICAgICAgImxhc3ROYW1lIjogIkJvbmFwYXJ0ZSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc2OS0wOC0xNSINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIm5hcG9sZW9uLmJvbmFwYXJ0ZUBmcmFuY2UuY29tIg0KfQ==

&billingAddress=ew0KICAgICJjaXR5IjogIkFqYWNjaW8iLA0KICAgICJjb3VudHJ5Ijogew0KICAgICAgICAiY291bnRyeUEzIjogIkZSQSINCiAgICB9LA0KICAgICJhZGRyZXNzTGluZTEiOiB7DQogICAgICAgICJzdHJlZXQiOiAiRXhpbGVzdHJlZXQiLA0KICAgICAgICAic3RyZWV0TnVtYmVyIjogIjI3MCINCiAgICB9LA0KICAgICJwb3N0YWxDb2RlIjogIjIwMTY3Ig0KfQ==

&shipToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIkx1ZHdpZyIsDQogICAgICAgICJsYXN0TmFtZSI6ICJYVklJSSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc1NS0xMS0xNyINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIkx1ZHdpZ0Byb3lhbC5mcmFuY2UuY29tIg0KfQ==

&shippingAddress=ew0KICAgICJjaXR5IjogIlBhcmlzIiwNCiAgICAiY291bnRyeSI6IHsNCiAgICAgICAgImNvdW50cnlBMyI6ICJGUkEiDQogICAgfSwNCiAgICAiYWRkcmVzc0xpbmUxIjogew0KICAgICAgICAic3RyZWV0IjogIlBsYWNlIGRlIGxhIENvbmNvcmRlIiwNCiAgICAgICAgInN0cmVldE51bWJlciI6ICIxIg0KICAgIH0sDQogICAgInBvc3RhbENvZGUiOiAiNzUwMDEiDQp9

&credentialOnFile=ew0KICAgICJ0eXBlIjogew0KICAgICAgICAidW5zY2hlZHVsZWQiOiAiQ0lUIg0KICAgIH0sDQogICAgImluaXRpYWxQYXltZW50IjogdHJ1ZQ0KfQ==

&OrderDesc=Test:0000

——

where:

billToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIk5hcG9sZW9uIiwNCiAgICAgICAgImxhc3ROYW1lIjogIkJvbmFwYXJ0ZSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc2OS0wOC0xNSINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIm5hcG9sZW9uLmJvbmFwYXJ0ZUBmcmFuY2UuY29tIg0KfQ==

is base64-encoding of

{

“consumer”:

{ “salutation”: “Mr”, “firstName”: “Napoleon”, “lastName”: “Bonaparte”, “birthDate”: “1769-08-15” },

“mobilePhone”: { “countryCode”: “33”, “subscriberNumber” : “12345678910” },

“email”: “napoleon.bonaparte@france.com”

}

billingAddress=ew0KICAgICJjaXR5IjogIkFqYWNjaW8iLA0KICAgICJjb3VudHJ5Ijogew0KICAgICAgICAiY291bnRyeUEzIjogIkZSQSINCiAgICB9LA0KICAgICJhZGRyZXNzTGluZTEiOiB7DQogICAgICAgICJzdHJlZXQiOiAiRXhpbGVzdHJlZXQiLA0KICAgICAgICAic3RyZWV0TnVtYmVyIjogIjI3MCINCiAgICB9LA0KICAgICJwb3N0YWxDb2RlIjogIjIwMTY3Ig0KfQ==

is base64-encoding of

{

“city”: “Ajaccio”,

“country”: { “countryA3”: “FRA” },

“addressLine1”: { “street”: “Exilestreet”, “streetNumber”: “270” },

“postalCode”: “20167”

}

shipToCustomer=ew0KICAgICJjb25zdW1lciI6IHsNCiAgICAgICAgInNhbHV0YXRpb24iOiAiTXIiLA0KICAgICAgICAiZmlyc3ROYW1lIjogIkx1ZHdpZyIsDQogICAgICAgICJsYXN0TmFtZSI6ICJYVklJSSIsDQogICAgICAgICJiaXJ0aERhdGUiOiAiMTc1NS0xMS0xNyINCiAgICB9LA0KICAgICJtb2JpbGVQaG9uZSI6IHsNCiAgICAgICAgImNvdW50cnlDb2RlIjogIjMzIiwNCiAgICAgICAgInN1YnNjcmliZXJOdW1iZXIiIDogIjEyMzQ1Njc4OTEwIg0KICAgIH0sDQogICAgImVtYWlsIjogIkx1ZHdpZ0Byb3lhbC5mcmFuY2UuY29tIg0KfQ==

is base64-encoding of

{

“consumer”: { “salutation”: “Mr”, “firstName”: “Ludwig”, “lastName”: “XVIII”, “birthDate”: “1755-11-17” },

“mobilePhone”: { “countryCode”: “33”, “subscriberNumber” : “12345678910” },

“email”: “Ludwig@royal.france.com”

}

shippingAddress=ew0KICAgICJjaXR5IjogIlBhcmlzIiwNCiAgICAiY291bnRyeSI6IHsNCiAgICAgICAgImNvdW50cnlBMyI6ICJGUkEiDQogICAgfSwNCiAgICAiYWRkcmVzc0xpbmUxIjogew0KICAgICAgICAic3RyZWV0IjogIlBsYWNlIGRlIGxhIENvbmNvcmRlIiwNCiAgICAgICAgInN0cmVldE51bWJlciI6ICIxIg0KICAgIH0sDQogICAgInBvc3RhbENvZGUiOiAiNzUwMDEiDQp9

is base64-encoding of

{

“city”: “Paris”,

“country”: { “countryA3”: “FRA” },

“addressLine1”: { “street”: “Place de la Concorde”, “streetNumber”: “1” },

“postalCode”: “75001”

}

credentialOnFile=ew0KICAgICJ0eXBlIjogew0KICAgICAgICAidW5zY2hlZHVsZWQiOiAiQ0lUIg0KICAgIH0sDQogICAgImluaXRpYWxQYXltZW50IjogdHJ1ZQ0KfQ==

is base64-encoding of

{

“type”: { “unscheduled”: “CIT” },

“initialPayment”: true

}

Key Parameter / Object

• If you do not use your own template, we a new template for the first tests for you. Alll you have to do is add “Template=ct_responsive_ch” to the encrypted data and the cardholderName entered by the customer will automatically be adopted by First Cash Solution for the 3D 2.0 process. For the planned / upcoming 3DS-2.0 rollout, First Cash Solution will adapt the standard templates accordingly and make them available to you.
• If you use your own merchant template and the cardholder query is not yet integrated in it, you need to integrate the cardholderName yourself.
• Example XSL file:

<!-- Cardholdername -->     <div class="row ccholder">         <span class="label">             <xsl:value-of select="paygate/language/strCCHolder"/>         </span>         <div class="input">             <input type="text" value="" id="creditCardHolder" name="creditCardHolder">                 <xsl:attribute name="value"><xsl:value-of select="paygate/creditCardHolder"/></xsl:attribute>             </input>         </div>     </div>

• Example XML file:

For each language used:

<strCCHolder>Cardholdername</strCCHolder>

• For PaySSL.aspx | PayNow.aspx, the cardholderName is a key value pair.
• For Direct.aspx, the cardholderName is a JSON Parameter of the JSON-Objects “Card“.

JSON Object – browserInfo

• For PaySSL.aspx | Paynow.aspx, First Cash Solution captures the browser data on your behalf and there is no need for you to take any action.
• For a server-to-server connection via Direct.aspx, the individual additional queries must be implemented in the shop.  

JSON Object – accountInfo

• The more data you transfer to us, the higher the probability that smooth payment processing (frictionless mode) will take effect.
  You should therefore check which data you already have and evaluate internally which data you would like to transfer.

JSON Object – customerInfo (billToCustomer | shipToCustomer)

• Please note that the transfer of address data is mandatory for 3D Secure 2.0.
  IMPORTANT: If the delivery address is not identical to the billing address, both addresses must be transferred! In the case of digital goods, the billing address is sufficient.

JSON Object – merchantRiskIndicator

• We strongly recommend to pass the merchantRiskIndicator (shipping method).
  The shipping type is transferred in the JSON object merchantRiskIndicator in the JSON parameter shippingAddressIndicator.
  This can have a positive effect on smooth payment processing (frictionless mode).

Use cases for transaction flagging

Scenario 01 – Credit Card One-Time Payment

• You offer your customers payment by credit card
• Each payment is a one-time payment, and therefore always a newly initiated payment
• You do not use a pseudo card number to store and reuse the card data

Credentials on File (CoF)

• You must use 3-D Secure
• No further adjustments are necessary

Scenario 02 – Credit Card Subscriptions

• You offer your customers payment by credit card
• Customers enter into a subscription with you that ALWAYS maintains the same amount and payment interval
• You use the pseudo card number to store and reuse the card data
• IMPORTANT: The following initial payment is subject to the liability shift for you as a merchant. In the case of the subsequent payment, however, this expires, so that there is no liability shift.

Credentials on File (CoF) – Initial Subscription Payment

• Applies to PaySSL.aspx + PayNow.aspx
• 3-D Secure is mandatory
• Necessary adjustments:
  • Example:
    • JSON object credentialOnFile with JSON parameter recurring (3 keys included)
    • JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
    • Example Initial Subscription Payment:

{

    “type”: {

        “recurring”: {

            “recurringFrequency”: 30,

            “recurringStartDate”: “2019-09-14”,

            “recurringExpiryDate”: “2020-09-14”

        }

    },

    “initialPayment”: true

}

CB2A – flexible Subscription

{

    “type”: {

        “recurring”: {

            “recurringFrequency”: 30,

            “recurringStartDate”: “2019-09-14”,

            “recurringExpiryDate”: “2020-09-14”

        }

    },

    “initialPayment”: true,

    “useCase”: “flexibleAmount”

}

Credentials on File (CoF) – Subsequent Subscription Payment

• Applies to Direct.aspx
• 3D Secure is NOT mandatory
• Necessary adjustments:
  • Example:
    • Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly.
    • JSON object credentialOnFile with JSON parameter recurring (3 keys included)
    • JSON object credentialOnFile with JSON parameter initialPayment and value “false”
    • Example Subsequent Subscription Payment:

{

    “type”: {

        “recurring”: {

            “recurringFrequency”: 30,

            “recurringStartDate”: “2019-09-14”,

            “recurringExpiryDate”: “2020-09-14”

        }

    },

    “initialPayment”: false

}

CB2A – flexible Subscription

{

    “type”: {

        “recurring”: {

            “recurringFrequency”: 30,

            “recurringStartDate”: “2019-09-14”,

            “recurringExpiryDate”: “2020-09-14”

        }

    },

    “initialPayment”: false,

    “useCase”: “flexibleAmount”

}

Scenario 03 – Credit Card Recurring Payment / Down Payment / Final Payment

• You offer your customers payment by credit card
• Customers shop repeatedly in your shop using the same credit card data
• You use the pseudo card number to store and reuse the card data
• IMPORTANT: The following initial payment is subject to the liability shift for you as a merchant. In the case of the subsequent payment, however, this expires, so that there is no liability shift.

Credentials on File (CoF) – Initial Recurring Payment

• Applies to PaySSL.aspx + PayNow.aspx
• 3D Secure is mandatory
• Necessary adjustments:
  • Example:
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
    • Example Initial Recurring Payment:

{

    “type”: {

        “unscheduled”: “CIT”

    },

    “initialPayment”: true

}

Credentials on File (CoF) – Subsequent Recurring Payment

• Applies to Direct.aspx
• 3D Secure is NOT mandatory
• Necessary adjustments:
  • Example:
    • Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and value “false”
    • Example Subsequent Recurring Payment:

{

    “type”: {

        “unscheduled”: “MIT”

    },

    “initialPayment”: false

}

Scenario 04 – Credit Card Account Verification

• You offer your customers payment by credit card
• In this scenario, you only want to validate the customer’s credit card
• You use the pseudo card number to store and reuse the card data
• IMPORTANT: Currently and in the future, schemes/card brands want to prevent merchants from carrying out card data validations with a minimum amount (e.g. 1 cent authorization). Therefore, the 1cs Online Payment System offers you the corresponding “ZeroValueAuthentication”. This is controlled by passing the additional parameter “AccVerify” in the encrypted data – see the example below for details.
  Please make sure that your credit card acquirer supports this function for you.

Credentials on File (CoF) – Validation Request

• Applies to PaySSL.aspx + PayNow.aspx
• 3D Secure is mandatory
• Necessary adjustments:
  • Example:
    • Please send the parameter AccVerify=Yes in the encrypted data (for further details please refer to our programming manual)
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
    • Example Account Verification:

{

    “type”: {

        “unscheduled”: “CIT”

    },

    “initialPayment”: true

}

Scenario 05 – Credit Card Token Storage / Form Prefill – PayNow interface

The processes described below are subject to the liability shift for you as a merchant.

• You offer your customers payment by credit card
• Customers buy in your shop and you store the credit card data in the form of the pseudo card number

A: When the customer returns, you prefill the credit card form with the saved data. In the case of CIT with initial=false, flagging is used if the merchant prefills the pseudo card number to the customer using a template prefill option.

B: When the customer returns, you prefill the credit card form with the saved data. If the customer deletes the existing card number and stores a new one or, if necessary, adds another card, then the flagging for CIT must be used again (initial=true), if the customer also wants this card to be preassigned.

Credentials on File (CoF) – Initial Payment for Token Storage

• Applies to PayNow.aspx
• 3-D Secure is mandatory
• Necessary adjustments:
  • Example:
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”.
    • JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
    • Example Initial Payment for Token Storage:

{

    “type”: {

        “unscheduled”: “CIT”

    },

    “initialPayment”: true

}

Credentials on File (CoF) – Subsequent Payment for Token Storage

• Applies to PayNow.aspx
• 3-D Secure is mandatory
• Necessary adjustments:
  • Example:
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “CIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and value “false”
    • Please always send the schemereferenceID from the initial payment (COF-CIT-TRUE) so that the downstream systems can link the two transactions accordingly
    • Example subsequent payment für Token Storage:

{

    “type”: {

        “unscheduled”: “CIT”

    },

    “initialPayment”: false

}

Scenario 05 – Credit Card Token Storage / Form Prefill – PaySSL interface (merchant template)

The obligatory control of the initial and recurring payments is managed by 1cs Online Payment System for you. So that we can activate this function for you, please contact the 1cs OPS Helpdesk.

Please note the following requirements in relation to merchant specific or the 1cs Online Payment System standard templates (ct_responsive, Cards_v1).

• Applies to PaySSL.aspx
• 3-D Secure is mandatory
• The shift in liability is subject to the liability shift for you as a merchant
• Necessary adjustments:
  • Please integrate a prefill checkbox using the code snippet provided below
  • Please activate (comment in) the code contained in the XSL file for preassigning the pseudo card number
  • To preassign the pseudo card number in the template you must transfer unencrypted data, e.g. “PCNrBrand=VISA&Background=VISA&PCNR=xxxxxxxxxxxxx123&PCNrMonth=09&PCNrYear=2025”. For the display to the customer we recommend that only the last three digits match the pseudo card number and thus also the customer’s real card number.
  • In order to process the card data at the 1cs OPS you must transfer the valid pseudo card number as request parameter “CCNr” in the encrypted part.
  • If the customer decides to save the card data the parameter “prefill=on” is sent to the 1cs Online Payment System. This indicator is reported back to your shop in the response message. You can see whether the customer has agreed to the prefill by the return parameter “prefill=on”.

Java-Script:

// Adds a Change-Event to the checkbox called 'cbPrefill'

$("#cbPrefill").change(function() {

 if($("#cbPrefill").is(':checked'))

{   // If the checkbox was activated, the value of hiddenfield with name 'prefill' is set to 'on'   $("input[type='hidden'][name='prefill']").val('on');  }

else

{   // If the checkbox was deactivated, the value of hiddenfield with name 'prefill' is deleted again   $("input[type='hidden'][name='prefill']").val('');  }

});

// In case of retries (If form gets called a second time due to errors),

// the last status will be set

if($("input[type='hidden'][name='prefill']").val() == 'on') {

 $("#cbPrefill").attr('checked', true);

}

XSL

<!-- Hiddenfield, which tells the 1cs OPS that prefill function should get activated -->

<!-- value="on" means that the 1cs OPS will return 'prefill=on' in the response to merchant -->

<!-- value=""  means that 1cs OPS will not return 'prefill=on' in the response to merchant -->

<inputtype="hidden"name="prefill"><xsl:attributename="value"><xsl:value-ofselect="paygate/prefill"/></xsl:attribute></input>

<!-- Checkbox to (de)activate prefill function -->

 <divid="div_cbPrefill"class="div_cbPrefill">

  <inputtype="checkbox"name="cbPrefill"id="cbPrefill"></input>

  <span><xsl:value-ofselect="paygate/language/strCCSaveData"disable-output-escaping="yes"/></span>

  <divclass="row"></div>

 </div>

Scenario 06 – Credit Card Recurring Payment incl. Liability Shift (e.g. Travel business)

• IMPORTANT: The following scenario only applies to PCI-certified systems
• There are several scenarios for the travel industry that allow recurring payments to also be subject to liability shift
• Example:
  • Customer books a hotel room via a booking platform, enters his card data and executes 3D Secure 2.0. This is processed via a separate PSP. This transaction only serves to validate the card data -ZeroValueAuthentication-.
  • This results in an Authenticate Status = CAVV, which the central booking platform then reports to the hotel operator (and any other service providers such as rental car agencies, insurance agencies, etc.). The hotel operator makes a NON-3DS 2.0 payment via the 1cs Online Payment System, but including the CAVV and any other data. The second transaction also contains the corresponding liability shift.
• The basis for this to work and for the liability shift to take place is the passing on of the Authenticate Status (CAVV). This is determined via a so-called “External 3DS Authentication”. Two steps are necessary:

a.     The external merchant system that initiated the first payment (AccVerify/ZeroValueAuthentication) stores the authentication status

b.     Subsequently, a recurring payment can be made via the 1cs Online Payment System. In this case, the merchant must include the JSON object threeDSData in the JSON data as well as the original card data of the initial authenticate (Card-JSON). The card data must therefore be transferred in its original form from the booking platform to all relevant service providers / agencies in compliance with PCI.
For this purpose a separate section explains the necessary steps.

• All necessary technical information can be found in the Multi-party Ecommerce / Agent Model section.

Scenario 07 – Credit Card MoTo (MailOrder / TelephoneOrder) via PaySSL, Direct or PayNow

• You offer your customers payment by credit card, which is collected by telephone.
• The credit card data is entered in a separate call centre application which triggers a payment via the 1cs Online Payment System using PaySSL.aspx, Direct.aspx or Paynow.aspx.
• You use the pseudo card number to store and reuse the card data
• IMPORTANT: MoTo payments are not subject to the liability shift as 3D Secure is not possible. (Out of Scope)

Credentials on File (CoF) – Initial MoTo Payment

• Applies to PaySSL.aspx, PayNow.aspx und Direct.aspx
• 3-D Secure is not possible (Out of Scope)
• Necessary adjustments:
  • Example:
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and the value “true”
    • Example Initial MoTo Payment:

{

    “type”: {

        “unscheduled”: “MIT”

    },

    “initialPayment”: true

}

Credentials on File (CoF) – Subsequent MoTo Payment

• Applies to automated payment initiation via Direct.aspx
• 3-D Secure is not possible (Out of Scope)
• Necessary adjustments:
  • Example:
    • Please always send the schemereferenceID from the initial payment so that the downstream systems can link the two transactions accordingly
    • JSON object credentialOnFile with JSON parameter unscheduled and the value “MIT”
    • JSON object credentialOnFile with JSON parameter initialPayment and value “false”
    • Example Subsequent MoTo Payment:

{

    “type”: {

        “unscheduled”: “MIT”

    },

    “initialPayment”: false,

“useCase”: “ucof”

}

Scenario 08 – Credit Card MoTo (MailOrder / TelephoneOrder) via Virtual Terminal

• You offer your customers payment by credit card, which is collected by telephone.
• The credit card data is entered via Virtual Terminal.
• IMPORTANT: MoTo payments are not subject to the liability shift as 3D Secure is not possible. (Out of Scope)

Credentials on File (CoF)

• By using the Virtual Terminal no further adjustments are necessary.

Scenario 09 – Batch Processing

The requirement of the card brands to mark recurring transactions correctly is already an older requirement; we provided information on this in January 2019. In the course of the PSD2-SCA implementation, this will become fully mandatory so that recurring transactions can be clearly identified and the downstream systems can recognize why 3D Secure was not processed in these cases. Since in those cases no end customer actively participates in the payment process, as consequence, the implementation is mandatory for all merchants.

Below you will find our descriptions & details, i.e. in the first step the initial payment from the store has to be marked as CredentialOnFile and based on that the recurring batch transactions will follow.

***initial shop transaction or AccountVerification:

On our application page the correct initial flagging (CredentialOnFile) is described for different use cases and the following chapter + scenario will apply to you.

3DS 2.0 Merchant Use-Cases & Testing of 3D-Secure 2.0 EN

Chapter: 2. use cases for transaction identification
Scenario 03 – Credit Card Recurring Payment / Deposit Payment / Final Payment

***Recurring batch submission
Since the schemeReferenceID was generated from the initial store request and reported back, that initial value must be used for all subsequent batch submissions + RTF=M (M=Merchant Initiated Transaction) needs to be included & specified.
Card+processing+EN

Chapter: Batch usage of the interface
affected batch format / action:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>
CC,Authorize,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<transactionID>,<schemeReferenceID>
In the batch request there exists the “transactionID” on the one hand and in addition the “schemeReferenceID” as well and we recommend that you take field schemeReferenceID.

Examples ‒ Batch Versions 1.2 ‒ schemeReferenceID field delivery:

CC,Sale,<Amount>,<Currency>,<TransID>,(<RefNr>),<CCBrand>,<CCNr|PCNr>,<CCExpiry>,<OrderDesc>,<textfeld1>,<textfeld2>,<RTF>,<cardholder>,<1234567890>

The Scheme Identifier must be transferred in batch format by using the TransactionID / schemeReferenceID, i.e. you will receive the schemeReferenceID / TransactionID for the initial 3DS-2.X transaction. This value must then be included in the batch format so that all recurring payments are correctly identified. The field cardHolder must be present but can also be submitted as an empty field and using schemeReferenceID the TransactionID field also empty.

Example:

CC,Sale,999,EUR,987456321,123456789,<VISA>,<0123456789123456>,<052029>,<mein Warenkorb>,,,M,,,<1234567890>

***Token/PCN Mandate – SchemeReferenceID

You can try to submit payments without using a schemeReferenceID, but we cannot prevent card transactions to be declined.
In case of a rejection, we recommend to execute a separate transaction as Card Check (AccVerify=YES) transaction via our …PaySSL.aspx, i.e. the customer receives a payment link which he can use to process an initial 3DS-2.X transaction and the schemeReferenceID is then reported back and can be included in the process of recurring payments again.

Scenario 10 – Extended Transaction Management (ETM)

• When using the First Cash Solution ETM, the 1cs Online Payment System takes care of the correct flagging of transactions for you.

Test 3D Secure 2.0 via First Cash Solution

Take the opportunity to test 3D Secure 2.0 now!

While not all downstream systems currently offer 3-D Secure for testing, you can perform a test simulation within the 1cs Online Payment System. This allows you to perform 3-D Secure authentication including different return values.

Please proceed as follows for testing:

• Activate 3D Secure 2.0 for your First Cash Solution MerchantID. If you are unsure whether it has already been activated, please contact support@1cs.de
• In the encrypted data request, use the default parameter OrderDesc with the value “Test:0000”. This will give you a correspondingly successful authorization after successful authentication.
  
  
• Perform 3D Secure Authentication
• Please ONLY use the available Testcards (expiration date always in the future + CVV/CVC may contain any value)
• Depending on the desired scenario (e.g. Browser 3D Secure 2.0 challenge, frictionless browser authentication, etc.), please use the appropriate One-Time Passwords.

10 transStatusReason Codes