Implementation
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 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:
- Collecting data from your customers during the checkout process in your webshop environment.
- 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 methods, 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.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
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 method 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:
- Rollout 3-D Secure with your external MPI.
- 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. |