Sign up

Read all about the 3-D Secure statuses of your processed transactions and basics of 3-D Secure/SCA in our dedicated guides.

Introduction

With the exception of integration mode 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.

For Hosted Checkout Page, we will collect the mandatory data for you and roll 3-D Secure for you. However, you can still add recommended and/or optional properties to raise the chance of turning the 3-D Secure authentication into a frictionless flow.

For all other integration modes, check our dedicated guides for code samples/JSON covering the mandatory properties:

Hosted Tokenization Page
Server-to-server/Mobile/Client Integration

Refer to our test cases to simulate different authentication/transaction result scenarios for any card scheme.

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.acceptHeaders
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 modes:
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

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

Find detailed information about these properties in our CreatePaymentAPI / CreateHostedCheckoutAPI.

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.

This feature is available for Server-to-server integration mode only. Make sure to check with your MPI provider that you meet both their technical and security requirements.

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.

If you process transactions for Carte Bancaire, make sure to add the following mandatory properties as well:
cavvAlgorithm
schemeRiskScore
appliedExemption

Was this page helpful?

Do you have any comments?

Thank you for your response.