Online Payments / Payment Features / 3D-Secure 2 / Compliance Guide

3-D Secure 2 Compliance Guide

The guide helps you prepare for PSD2 SCA compliance using 3-D Secure 2. It provides all the information you need on how to adapt your existing CCV Pay integration. For more information about PSD2, SCA, and 3-D Secure 2, refer to our 3-D Secure 2 overview.

3-D Secure 2 is only applicable for card transactions.For CCV Pay it affects the following payment methods:

• card
• landingpage: if you allow to complete these with a card payment
• vault

3-D Secure 2 requires information about each payment. This document describes the fields providing this information. Issuers will put in place 3-D Secure 2 therefore recommend to provide as much information as possible. It will ensure a higher payment acceptance rate.

The 3-D Secure 2 fields have a strict format. Integrators can choose to let CCV Pay validate the data it receives. We encourage integrators to use this feature.

Consequences of not being 3-D Secure 2 compliant

CCV Pay provides a solution for being 3-D Secure 2 compliant. It is up to you to ensure that the information per transaction conforms to the 3-D Secure 2 specification. Schemes like Visa and MasterCard state that they will enforce this specification in the future. Non-compliant implementations can result in issuers declining your transactions, leading to lower conversion rates.

Use Cases

Card payment

Using our Card Payment Page

This is a standard card payment extended with the new 3-D Secure 2 data. The flow between your integration and CCV Pay does not change. However, the customer journey will be different in case of 3-D Secure 2 authentication. Instead of a redirect, CCV Pay shows a pop-up with the challenge.

1. You initiate a new transaction with the 3-D Secure 2 compliant data

   {
       "amount" : 10.99,
       "currency" : "eur",
       "method" : "card",
       "returnUrl" : "https://shop.merchant.com/return?order=123456",
       "merchantOrderReference" : "123456",
       "description" : "Order 123456",
       "language" : "nld",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingState": "GE",
       "billingPostalCode" :"6827 AT",
       "billingCountry": "NL",
       "billingHouseNumber": "55",
       "accountInfo": {
           "accountIdentifier": "7cec0016-0bf3-45c7-bc1a-7916750a39a2",
           "accountCreationDate": "20190101",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "email": "john.doe@ccvlab.eu",
           "workPhoneCountry": "31",
           "workPhoneNumber": "11193500",
           "authenticationMethod": "OWN_CREDENTIALS"
       },
       "merchantRiskIndicator": {
           "deliveryEmailAddress": "johny.doe@ccvlab.eu",
           "deliveryTimeframe": "SAME_DAY",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "shippingIndicator": "BILLING_ADDRESS"
       },
       "threeds2RequestInfo": {
           "challengeIndicator": "NO_PREFERENCE",
           "transactionType": "GOODS_AND_SERVICES_PURCHASE"
       }
   }
   

2. CCV Pay responds with a generated transaction containing a unique payUrl

   {
        "method": "card",
        "reference": "C200603121922297CB87E190.2",
        "currency": "eur",
        "created": 1591179562332,
        "language": "nld",
        "billingAddress": "Westvoortsedijk",
        "billingCity": "Arnhem",
        "billingPostalCode": "6827 AT",
        "billingCountry": "NL",
        "amount": 10.99,
        "billingState": "GE",
        "merchantOrderReference": "123456",
        "billingHouseNumber": "55",
        "returnUrl": "https://shop.merchant.com/return?order=123456",
        "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C200603121922297CB87E190.2",
        "lastUpdate": 1591179562332,
        "cancelUrl": "https://onlinepayments.ccv.eu/card/cancel/merchant?reference=C200603121922297CB87E190.2",
        "description": "Order 123456",
        "status": "pending",
        "type": "sale"
   }
   

3. You redirect the customer to the payUrl

4. The customer submits their/her card data

5. CCV Pay verifies if 3-D Secure 2 is applicable. If so:

   • If the issuer allows frictionless authentication: CCV Pay redirects the customer to your returnUrl
   • If the issuer asks for authentication: CCV Pay shows a challenge in a pop-up to the customer on the hosted page. After the customer completes the challenge, CCV Pay redirects the customer to your returnUrl

Using a Vault Access Token

This is a standard card payment extended with the new 3-D Secure 2 data. The flow between your integration and CCV Pay does not change. However, the customer’s journey will be different in case of a 3-D Secure 2 authentication. Instead of a redirect, CCV Pay shows a pop-up with the challenge.

1. You initiate a new transaction with a vaultAccessToken

   {
       "details": {
           "vaultAccessToken": "48EC3B2DF1EF84D0D1737629"
       },
       "amount" : 10.99,
       "currency" : "eur",
       "method" : "card",
       "returnUrl" : "https://shop.merchant.com/return?order=123456",
       "merchantOrderReference" : "123456",
       "description" : "Order 123456",
       "language" : "nld",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingState": "GE",
       "billingPostalCode" :"6827 AT",
       "billingCountry": "NL",
       "billingHouseNumber": "55",
       "accountInfo": {
           "accountIdentifier": "7cec0016-0bf3-45c7-bc1a-7916750a39a2",
           "accountCreationDate": "20190101",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "email": "john.doe@ccvlab.eu",
           "workPhoneCountry": "31",
           "workPhoneNumber": "11193500",
           "authenticationMethod": "OWN_CREDENTIALS"
       },
       "merchantRiskIndicator": {
           "deliveryEmailAddress": "johny.doe@ccvlab.eu",
           "deliveryTimeframe": "SAME_DAY",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "shippingIndicator": "BILLING_ADDRESS"
       },
       "threeds2RequestInfo": {
           "challengeIndicator": "NO_PREFERENCE",
           "transactionType": "GOODS_AND_SERVICES_PURCHASE"
       }
   }
   

2. CCV Pay responds with a generated transaction containing a unique payUrl

   {
       "method": "card",
       "reference": "C200603124543752CB87E195.2",
       "currency": "eur",
       "created": 1591181143828,
       "language": "nld",
       "brand": "visa",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingPostalCode": "6827 AT",
       "billingCountry": "NL",
       "amount": 10.99,
       "details": {
           "cardholderFirstName": "j",
           "maskedPan": "4111XXXXXXXX1111",
           "cardholderLastName": "l"
       },
       "billingState": "GE",
       "merchantOrderReference": "123456",
       "billingHouseNumber": "55",
       "returnUrl": "https://shop.merchant.com/return?order=123456",
       "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C200603124543752CB87E195.2",
       "lastUpdate": 1591181143828,
       "cancelUrl": "https://onlinepayments.ccv.eu/card/cancel/merchant?reference=C200603124543752CB87E195.2",
       "description": "Order 123456",
       "status": "pending",
       "type": "sale"
   }
   

3. Depending on your account configuration there are 2 options

   1. If 3-D Secure is enabled for your account,
      1. You must redirect the customer to the payUrl
      2. CCV Pay verifies if 3-D Secure 2 is applicable. If so:
         • If the issuer allows frictionless authentication: CCV Pay redirects the customer to your returnUrl
         • If the issuer asks for authentication: CCV Pay shows a challenge in a pop-up to the customer on the hosted page. After the customer completes the challenge, CCV Pay redirects the customer to your returnUrl
   2. If 3-D Secure is not enabled for your account, you don’t need to redirect the customer.
   • If you do, CCV Pay immediately redirects the customer to your returnUrl

4. CCV Pay sends the authorisation to the issuer for completion

Vault enrollment

This is a standard vault enrollment extended with the new 3-D Secure 2 data. The flow between your integration and CCV Pay does not change. However, the customer’s journey will be different in case of a 3-D Secure 2 authentication. Instead of a redirect, CCV Pay shows a pop-up with the challenge.

1. You initiate a new transaction

   {
       "dataType": "card",
       "returnUrl" : "https://shop.merchant.com/return?order=123456",
       "merchantOrderReference" : "123456",
       "description" : "Order 123456",
       "language" : "nld",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingState": "GE",
       "billingPostalCode" :"6827 AT",
       "billingCountry": "NL",
       "billingHouseNumber": "55",
       "accountInfo": {
           "accountIdentifier": "7cec0016-0bf3-45c7-bc1a-7916750a39a2",
           "accountCreationDate": "20190101",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "email": "john.doe@ccvlab.eu",
           "workPhoneCountry": "31",
           "workPhoneNumber": "11193500",
           "authenticationMethod": "OWN_CREDENTIALS"
       },
       "merchantRiskIndicator": {
           "deliveryEmailAddress": "johny.doe@ccvlab.eu",
           "deliveryTimeframe": "SAME_DAY",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "shippingIndicator": "BILLING_ADDRESS"
       },
       "threeds2RequestInfo": {
           "transactionType": "GOODS_AND_SERVICES_PURCHASE"
       }
   }
   

2. CCV Pay responds with a generated transaction containing a unique payUrl

   {
       "method": "vault",
       "reference": "V200603125210957CB87E19A.2",
       "created": 1591181531005,
       "language": "nld",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingPostalCode": "6827 AT",
       "billingCountry": "NL",
       "billingState": "GE",
       "merchantOrderReference": "123456",
       "billingHouseNumber": "55",
       "returnUrl": "https://shop.merchant.com/return?order=123456",
       "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C200603125210968CB87E19B.2",
       "lastUpdate": 1591181531005,
       "description": "Order 123456",
       "status": "pending",
       "type": "token"
   }
   

3. You redirect the customer to the payUrl
4. The customer submits their/her card data
5. CCV Pay verifies if 3-D Secure 2 is applicable. If so:
   • If the issuer allows frictionless authentication, CCV Pay redirects the customer to your returnUrl
   • If the issuer asks for authentication, CCV Pay shows a challenge in a pop-up to the customer on the hosted page. After the customer completes the challenge, CCV Pay redirects the customer to your returnUrl
6. CCV Pay sends the authorisation to the issuer for completion
7. You read the transaction to get the status and the Vault Access Token

Landing page payments

This is a standard landing page payment extended with the new 3-D Secure 2 data. The flow between your integration and CCV Pay does not change. However, the customer’s journey will be different in case of a 3-D Secure 2 authentication. Instead of a redirect, CCV Pay shows a pop-up with the challenge.

1. You initiate a new transaction with the 3-D Secure 2 compliant data

   {
       "amount" : 10.99,
       "currency" : "eur",
       "method" : "landingpage",
       "returnUrl" : "https://shop.merchant.com/return?order=123456",
       "merchantOrderReference" : "123456",
       "description" : "Order 123456",
       "language" : "nld",
       "billingAddress": "Westvoortsedijk",
       "billingCity": "Arnhem",
       "billingState": "GE",
       "billingPostalCode" :"6827 AT",
       "billingCountry": "NL",
       "billingHouseNumber": "55",
       "accountInfo": {
           "accountIdentifier": "7cec0016-0bf3-45c7-bc1a-7916750a39a2",
           "accountCreationDate": "20190101",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "email": "john.doe@ccvlab.eu",
           "workPhoneCountry": "31",
           "workPhoneNumber": "11193500",
           "authenticationMethod": "OWN_CREDENTIALS"
       },
       "merchantRiskIndicator": {
           "deliveryEmailAddress": "johny.doe@ccvlab.eu",
           "deliveryTimeframe": "SAME_DAY",
           "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
           "shippingIndicator": "BILLING_ADDRESS"
       },
       "threeds2RequestInfo": {
           "challengeIndicator": "NO_PREFERENCE",
           "transactionType": "GOODS_AND_SERVICES_PURCHASE"
       }
   }
   

2. CCV Pay responds with a generated transaction containing a unique payUrl

   {
        "method": "landingpage",
        "reference": "L200603161403114CB87E19E.2",
        "currency": "eur",
        "created": 1591193643343,
        "language": "nld",
        "billingAddress": "Westvoortsedijk",
        "billingCity": "Arnhem",
        "billingPostalCode": "6827 AT",
        "billingCountry": "NL",
        "amount": 10.99,
        "details": {
            "expirationDuration": "P0Y2M1DT0H0M0.000S"
        },
        "billingState": "GE",
        "merchantOrderReference": "123456",
        "billingHouseNumber": "55",
        "returnUrl": "https://shop.merchant.com/return?order=123456",
        "payUrl": "https://onlinepayments.ccv.eu/landingpage/payment.html?reference=L200603161403114CB87E19E.2",
        "lastUpdate": 1591193643343,
        "description": "Order 123456",
        "status": "pending",
        "type": "sale"
    }
   

3. You redirect the customer to the payUrl

4. The customer selects Card as the payment method

5. The customer submits their/her card data

6. CCV Pay verifies if 3-D Secure 2 is applicable. If so:

   • If the issuer allows frictionless authentication, CCV Pay redirects the customer to your returnUrl
   • If the issuer asks for authentication, we show a challenge in a pop-up to the customer on the hosted page. After the customer completes the challenge, CCV Pay redirects the customer to your returnUrl

7. CCV Pay sends the authorisation to the issuer for completion

Test and go live

The validation rules apply for test and live transactions. You can use a test api key to verify your changes before executing any live transactions.

API Changes

3-D Secure 2 has a significant impact on the API for both existing and new fields. The following section highlights these changes on format and validation. A complete overview of our API is located at the API-reference page.

Each field consists of the following specification to construct a valid request message.

• Name: the JSON field name of the data element,
• Type: the JSON type of the data element,
• Size: if applicable, the minimum and/or maximum character length of the data element,
• Format: if applicable, the format or allowed values of the element data,
• Inclusion: determines if the data element in the message is required or optional,
• Description: describes the purpose of the field and provides additional information if available.

Validation

The 3-D Secure 2 fields have a strict format. Merchants can choose to let CCV Pay validate these fields using the scaReady flag. By default this feature is disabled.

Setting the scaReady flag to yes has the following repercussions:

• Strict validation of the format and size of the fields,
• Validation on inclusion of required fields,
• Any data element that does not comply with the specification results in one or more input error.

Inclusion

• Required: the data element must be included. If not present, an input error is returned,
• Optional: the data element may be included but not required. If present, it must conform to the specification.

Transaction Request

The following fields are applicable for both payment and vault transactions.

More on Billing & Shipping Information

If your integration already provides billing and shipping information, it might require some changes:

• If you provide any fields, you must provide them within the size limits. In practice most integrations provide them within these bounds so we expect little impact,
• If you provide the state, you must provide it as a Country Subdivision Code - ISO 3166-2 ,
• If you provide the house number or extension in the separate fields, CCV Pay will add them to the address,
• If you do not provide any shipping fields, CCV Pay uses the billing information as shipping information,
• If you provide one or more shipping fields, the billing default will not apply. You must provide all shipping fields,
• If you provide a phone number, you must provide the country code in a separate field e.g.: billingPhoneCountry.

Billing example with explicit house number and extension

{
    "billingAddress": "Westvoortsedijk",
    "billingCity": "Arnhem",
    "billingState": "GE",
    "billingPostalCode" :"6827 AT",
    "billingCountry": "NL",
    "billingHouseNumber": "55",
    "billingHouseExtension": "Bus 1",
    "billingPhoneNumber": "11193500",
    "billingPhoneCountry": "31"
}

Billing example with house number and extension as part of the address

{
    "billingAddress": "Westvoortsedijk 55, Bus 1",
    "billingCity": "Arnhem",
    "billingState": "GE",
    "billingPostalCode" :"6827 AT",
    "billingCountry": "NL",
    "billingPhoneNumber": "11193500",
    "billingPhoneCountry": "31"
}

Payment Sequence Information Object

This is applicable if you want to inform the card issuer if this payment is part of a sequence. The information is optional.

Instalment Example

{
    "sequenceInfo": {
      "type": "INSTALMENT",
      "mode": "INITIAL",
      "source": "CIT",
      "instalmentMaxAuthorisations": "12"
    }
}

Recurring Example

{
    "sequenceInfo": {
      "type": "RECURRING",
      "mode": "INITIAL",
      "source": "CIT",
      "recurringExpiry": "20211231",
      "recurringFrequency": "12"
    }
}

Account information Object

The Account Information contains optional information about the account of the cardholder with the merchant.

Note: Time periods can be defined with an exact date or with an approximate indicator. You can choose either, a date or an indicator.

Example

{
    "accountInfo": {
        "accountIdentifier": "7cec0016-0bf3-45c7-bc1a-7916750a39a2",
        "accountCreationDate": "20190101",
        "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
        "email": "john.doe@ccvlab.eu",
        "workPhoneCountry": "31",
        "workPhoneNumber": "11193500",
        "authenticationMethod": "OWN_CREDENTIALS"
    }
}

3-D Secure 2 Request Information Object

The 3-D Secure 2 Request Information contains optional information about the merchants 3-D Secure 2 related requirements for this transaction.

Example

{
    "threeds2RequestInfo": {
        "challengeIndicator": "NO_CHALLENGE",
        "transactionType": "CHECK_ACCEPTANCE"
    }
}

Challenge Indicator

Dependent on the use case, a different challenge indicator should be used

Liability

In general, if 3-D Secure 2 is used, the issuer is liable in case of charge backs by the cardholder or fraudulent transactions. However, as a merchant you can indicate if you want your customer to be challenged or not with an exemption. In general, when an exemption is requested by the merchant, the liability shifts towards the merchant.

The challenge indicator can be used to indicate if you want an exemption or not.

Merchant Risk Indicator Object

The Merchant Risk Indicator contains optional information about the specific purchase by the cardholder.

Example

{
    "merchantRiskIndicator": {
        "deliveryEmailAddress": "johny.doe@ccvlab.eu",
        "deliveryTimeframe": "SAME_DAY",
        "passwordChangeIndicator": "CHANGED_DURING_TRANSACTION",
        "shippingIndicator": "BILLING_ADDRESS",
        "giftCardAmount": "10.99",
        "giftCardCount": "1",
        "giftCardCurrency": "978"
    }
}

Shipping indicator

Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business.

If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.

Browser Information Object

Accurate Browser Information is obtained for the issuer to determine the ability to support authentication on a particular cardholder browser for each transaction.

This information will be required if you are capturing the card data on your own PCI compliant environment.

If you redirect the customer to CCV Pay, we obtain the information from the cardholder’s browser. In that case the browser object-field is optional.

You can extract this information partially from the browser using JavaScript

function BrowserInfo() {
    this.language = navigator.language;
    this.screenColorDepth = window.screen.colorDepth;
    this.screenHeight = window.screen.height;
    this.screenWidth = window.screen.width;
    this.timeZone = new Date().getTimezoneOffset();
}

The fields acceptHeaders, userAgent can be extracted from the incoming web request.

Example

{
    "browserInfo": {
        "javaEnabled": false,
        "acceptHeaders": "application/json, text/javascript, */*; q=0.01",
        "ipAddress": "127.0.0.1",
        "language": "nl",
        "screenColorDepth": "24",
        "screenHeight": "2160",
        "screenWidth": "3840",
        "timeZone": "-120",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:68.0) Gecko/20100101 Firefox/68.0",
        "challengeWindowSize": "500X600"
    }
}