Implementation

Introduction

With the exception of integration method Hosted Checkout Page, you need to adapt your integration to ensure 3-D Secure is rolled out during the payment flow.

You achieve this by following two steps:

1. Collecting data from your customers during the checkout process in your webshop environment.
2. Sending this data to our platform in the actual payment request. You need to send this data by adding:
   a. A fixed set of mandatory and,
   b. A selection of recommended and/or optional properties to your request.

The more mandatory/optional parameters you add to your request, the higher the chance that the 3-D Secure authentication check becomes a mere background process. The payment process follows the so-called “frictionless flow”, improving the overall payment experience, as it becomes more seamless. Read our dedicated chapter to learn more.

Mandatory properties

These are the basic properties you need to send for every card transaction in your CreatePayment request. If you are processing transactions via our Hosted Checkout Page solution, we will capture this data for you on our secure payment page.

cardPaymentMethodSpecificInput.card.cardholderName
cardPaymentMethodSpecificInput.threeDSecure.redirectionData.returnUrl
cardPaymentMethodSpecificInput.threeDSecure.skipAuthentication
order.customer.device.acceptHeader
order.customer.device.browserData.colorDepth
order.customer.device.browserData.javaEnabled
order.customer.device.browserData.screenHeight
order.customer.device.browserData.ScreenWidth
order.customer.device.locale
order.customer.device.timezoneOffsetUtcMinutes
order.customer.device.userAgent

If you process transactions for Visa, make sure to add the following mandatory properties as well:

For all integration methods:
order.customer.contactDetails.mobilePhoneNumber
or
order.customer.contactDetails.phoneNumber
or
order.customer.contactDetails.workPhoneNumber
or
order.customer.contactDetails.emailAddress

For Create Payment requests: 
order.customer.device.ipAddress

If you process transactions for Cartes Bancaires, make sure to add the following mandatory properties as well: 

For all integration methods: cardPaymentMethodSpecificInput.paymentProduct130SpecificInput.threeDSecure.useCase
For Create Payment requests: order.customer.device.ipAddress

Recommended properties

The major card schemes highly recommend including these, as they will enhance the chance of a frictionless flow.

order.customer.billingaddress.city
order.customer.billingAddress.countryCode
order.customer.billingAddress.street
order.customer.billingAddress.houseNumber
order.customer.billingAddress.additionalInfo
order.customer.billingAddress.zip
order.customer.contactDetails.emailAddress

Optional properties

In addition, you can send from these as many as you wish. The more parameters you send, the higher the chance of a frictionless flow.

cardPaymentMethodSpecificInput.priorThreeDSecureData.acsTransactionId
cardPaymentMethodSpecificInput.priorThreeDSecureData.utcTimestamp
cardPaymentMethodSpecificInput.threeDSecure.challengeIndicator
cardPaymentMethodSpecificInput.threeDsecure.priorThreeDSecureData.method
cardPaymentMethodSpecificInput.threeDSecure.secureCorporatePayment

cardPaymentMethodSpecificInput.threeDSecure.challengeCanvasSize
order.additionalInput.airlineData.flightIndicator
order.additionalInput.airlineData.passengers.airlineLoyaltyStatus
order.additionalInput.airlineData.passengers.passengerType
order.additionalInput.airlineData.ticketCurrency
order.additionInput.typeInformation.transactionType
order.customer.account.authentication.method
order.customer.account.authentication.utcTimestamp
order.customer.account.changeDate
order.customer.account.changedDuringCheckout
order.customer.account.createDate
order.customer.account.hadSuspiciousActivity
order.customer.account.passwordChangeDate
order.customer.account.passwordChangedDuringCheckout
order.customer.account.paymentAccountOnFile.createDate
order.customer.account.paymentAccountOnFile.numberOfCardOnFileCreationAttemptsLast24Hours
order.customer.account.paymentActivity.numberOfPaymentAttemptsLast24Hour
order.customer.account.paymentActivity.numberOfPaymentAttemptsLastYear
order.customer.account.paymentActivity.numberOfPurchasesLast6Months
order.customer.accountType
order.customer.contactDetails.mobilePhoneNumber
order.customer.contactDetails.phoneNumber
order.customer.contactDetails.workPhoneNumber
order.shipping.address.additionalInfo
order.shipping.address.city
order.shipping.address.countryCode
order.shipping.address.houseNumber
order.shipping.address.street
order.shipping.address.zip
order.shipping.addressIndicator
order.shipping.emailAddress
order.shipping.firstUsageDate
order.shipping.isFirstUsage
order.shipping.type
order.shoppingCart.giftCardPurchase.amountOfMoney.amount
order.shoppingCart.giftCardPurchase.amountOfMoney.currencyCode
order.shoppingCart.giftCardPurchase.numberOfGiftCards
order.shoppingCart.isPreorder
order.shoppingCart.preorderItemAvailabilityDate
order.shoppingCart.reorderIndicator

Implement external MPI for 3-D Secure check

Depending on your business model, you might prefer working with an external Merchant Plug-In (MPI) to process 3-D Secure-proof payments.

We have designed our platform in a way that allows you to split the transaction flow into two separate phases:

1. Rollout 3-D Secure with your external MPI.
2. Process the actual transaction via our platform. Add the following nested properties in object cardPaymentMethodSpecificInput.threeDSecure properties to a standard CreatePayment request:

{ 
{
  "cardPaymentMethodSpecificInput": {
    "card": {
      "cvv": "451",
      "cardNumber": "4012005616165343",
      "expiryDate": "1223",
      "cardholderName": "Wile E. Coyote"
    },
    "isRecurring": false,
    "paymentProductId": 1,
    "transactionChannel": "ECOMMERCE",
    "threeDSecure": {
      "externalCardholderAuthenticationData": {
        "cavv" : "AAABBEg0VhI0VniQEjRWAAAAAAA=",
        "cavvAlgorithm" : "X",
         "directoryServerTransactionId" : "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
        "eci" : "05",
        "threeDSecureVersion" : "2.1.0",
        "acsTransactionId" : "abcdefghijklmnopqrstuvwxyz0123456789",
        "flow" : "challenge"   
    }
    }
  },
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 2980
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    },
    "references": {
      "merchantOrderId": "123456",
      "merchantReference": "oGPc8xJURfpFitBa6ORrpkBuPoGpvD"
    }
  }
}

Property	Remarks
cavv	Mandatory
eci
threeDSecureVersion
directoryServerTransactionId
acsTransactionId
xid	Optional Your external MPI's reference to the authentication result.
flow	Optional If left out, our platform will populate this property with frictionless, which we will include in GetPaymentDetails responses. Therefore, to ensure our platform data matches the actual flow that took place, we strongly recommend sending this property.