Results for

icon-search-large No search results yet
Enter your search query above

3-D Secure version 2

3-D Secure version 2 is an evolution of the existing 3-D Secure version 1 programs: Verified by Visa, Mastercard SecureCode, AmericanExpress SafeKey, Diners/Discover ProtectBuy and JCB J/Secure. It is based on a specification that has been drafted by EMVco. EMVCo exists to facilitate worldwide interoperability and acceptance of secure payment transactions. It is overseen by EMVCo’s six member organizations—American Express, Discover, JCB, Mastercard, UnionPay, and Visa—and supported by dozens of banks, merchants, processors, vendors and other industry stakeholders who participate as EMVCo Associates.

To reflect current and future market requirements, EMVco recognized the need to create a new 3-D Secure specification that would support app-based authentication and integration with digital wallets, as well as traditional browser-based e-commerce transactions. This led to the development and publication of the EMV® 3-D Secure – Protocol and Core Functions Specification. The specification takes into account these new payment channels and supports the delivery of industry leading security, performance and user experience.

Besides the major global card brands we also see that some local card brands are also looking to adopt similar/identical means of authentication as defined in the 3-D Secure version 2 specifications.

Why a new version

Version 1 of 3-D Secure results in redirects for consumers, to pages that aren't always optimized for the device that the consumer is using. This increases the drop-off rate of the consumers during your checkout. Next to this, the way the consumer has to authenticate isn't always the best way from a usability point of view, again increasing the drop-off even further. Due to the drop-off impact not all merchants have adopted 3-D Secure, so consumers aren't always familiar with the flow and this again leads to increased drop-off. In short the user experience leaves a lot to desire and you are faced with a loss of revenue due to a reduction of conversion on your checkout. Below map shows the drop-off percentages for 3-D Secure version 1 we observed on Ingenico's Global Collect Payment Platform in the first half of 2018.

GlobalCollect 3-D Secure version 1 drop-off per region in 2018

The implementation of 3-D Secure version 1 historically has introduced more friction than necessary. As more and more transactions are app based and we see rapid development of new ways to make payments there was a need for an updated version of 3-D Secure that could deal with this, which is 3-D Secure version 2.

What will change

One of the core differences is that the issuer can use a lot of data-points from the transaction to determine the risk of the transaction (risk-based analysis). For low-risk transactions, issuers will not challenge the transaction (e.g. not sending an SMS to the cardholder) although authenticating the transaction (frictionless). Inversely, for high risk transaction, issuers will require the cardholder to authenticate with an SMS or biometric means (challenge). This can then result in a frictionless authentication, which doesn't involve the consumer to be redirected. In case the consumer is using an app this also applies. In case a challenge is required by the issuer this can be handled inside the app. This greatly improves the user experience and will increase conversion.

Separately the Strong Customer Authentication (SCA) required in Europe by September 14th, 2019 as specified in PSD2 will result in a substantial increase in the number of transactions requiring the use of 3-D Secure authentication. The use of 3-D Secure version 2 should limit the potential negative impact on conversion as much as possible.

In short 3-D Secure version 2 means:

  • You will need to implement 3-D Secure before September 14th, 2019 if your transactions fall within the EU PSD2 SCA guidelines (in case you don't already support 3-D Secure).
  • You are advised (and for some are required) to submit additional data points to support the risk assessment performed by the issuer in case of 3-D Secure version 2
  • You might need to update your privacy policy with regards to GDPR as you might be sharing additional data-points with 3rd parties
  • A much better user experience for your consumers

Benefits

The expectation in the market is that a substantial percentage of transactions using 3-D Secure version 2 will follow the frictionless flow, which doesn't require anything additional from the consumer compared to current non-3-D Secure checkout flows. This means that you benefit from the increased security and liability shift that is provided by the 3-D Secure programs, while the conversion in your checkout process shouldn't be negatively impacted.

According to card networks projections, with 3-D Secure version 2, merchants will be able to achieve the same performance levels as physical store merchants (using Chip & PIN):

  • Up to 10 percentage points higher approval rates
  • Up to 50% reduced fraud rates
  • Around 50% lower abandonment rates.

Timeline

3Dv2 Timeline

A couple of dates are important:

  1. April 2019: Mastercard issuers globally and Visa issuers from Europe can support 3-D Secure version 2 in their production environments, so you might be impacted as well as you can only benefit if you provide the right data points.
  2. August 2019: Visa issuers In North and South America can support 3-D Secure version 2.
  3. September 14th, 2019: PSD2 SCA goes into effect in the European markets requiring Strong Customer Authentication for each online transaction that match the criteria as set forth in the PSD2 SCA guidelines.
  4. April 2020: Issuers from the rest of the world can support 3-D Secure version 2.

For each of the above activations the following applies: If the issuer supports 3-D Secure version 2 for the card, you should use 3-D Secure version 2. If you do not support 3-D Secure version 2, falling back to 3-D Secure version 1 remains a possibility without any impact on the liability shift.

Technical implementation

We have done our best to limit the impact of 3-D Secure version 2 for you. This means that we have kept the existing 3-D Secure flow and statuses the same. The impact has been reduced to API changes that introduce the additional new properties that you can (and in some cases should) provide to increase the likelihood of your transactions being authenticated using the frictionless flow.

Flow

Below flow shows the high-level flow of both version 1 and version 2 of 3-D Secure. Please note that we show the browser flow specifically for 3-D Secure version 2 as version 1 doesn't support different flows besides the browser flow. The functional flow between the two versions is the same from your point of view. After the initial payment creation two flows are possible:

  • One flow requiring the redirection of the consumer
  • One flow not requiring the redirection of the consumer

3Dv2 flow v1.1

The flow with the redirection for 3-D Secure version 2 could potentially only involve a page that allows the issuer to collect data from the consumers device without any user interaction. This is called a MethodURL flow in the 3-D Secure version 2 documentation. We have chosen to handle this flow on our hosted payment pages to reduce the implementation impact on you. This means that redirection will not always result in a so called Challenge towards the consumer and could still be considered friction-less in the 3-D Secure version 2 terminology. The statuses for each of the flows are identical with REDIRECTED for the flow that involves redirection and all the other possible statuses, like REJECTED, PENDING_APPROVAL, CAPTURE_REQUESTED, etc. for the non-redirect flow. Please see below image showing the 3-D Secure specific status flow for the most common implementation (not using the 2-step 3-D setup that requires explicit approval from your side to continue with the authorization).

Payment Flow Credit Cards 3Dv2

Additional data elements

The key aspect of 3-D Secure version 2 is the ability of the issuing bank to better assess the risk involved of the transaction. The specification 3-D Secure version 2 contains a lot of data elements, some of them were already commonly used in fraud screening, but some are new and specific to 3-D Secure. In general the data elements can be categorized in the following categories:

  • Card details
  • 3-D Secure specific information
    • Previous 3-D Secure results
    • Specific 'settings' for this transaction
  • Transaction information
    • Billing address data
    • Shipping details
    • Meta information on what the transaction is for
  • Consumer
    • Device/browser data
    • Account of the consumer with you
      • Authentication used
      • Account on file
      • Payment history

Our existing APIs already capture a lot of the data elements, but we are adding a lot of new data elements. The reason is that we believe that everybody in the payments ecosystem benefits from increased security, with the least amount of negative impact to the experience of the consumer. Payments are based on trust and by providing more data it becomes easier for parties to trust one-another, without requiring additional challenges to authenticate the consumer. Almost all of the newly added data elements are optional, but we advise you to supply as much of them as possible. This increases the likelihood of your transactions following the frictionless flow, while you benefit from liability shift. In case you use the MyCheckout hosted payment pages we will capture the Device/browser related data automatically.

MyCheckout Hosted Payment Pages

When you use the MyCheckout hosted payment pages we will capture some of the required data-points regarding the device and browser used by the consumer on your behalf to reduce the implementation burden on your side. To keep our API logical and easy to understand we decided to change some of the existing object definitions. Our system will accept both the old definition and new definition, but you are advised not to mix old and new definitions in one API call, because our system will reject it if you try to submit multiple definitions of the same field.

It is important to note that even-tough we have added new properties and restructured the API your current implementation will keep working. In case you use the MyCheckout hosted payment pages all of the additional new properties are optional, but you are advised to supply as many of them to ensure the highest possible number of transactions follow the frictionless flow.

As the cardHolderName is a required property we will also automatically capture that property in case 3-D Secure version 2 has been enabled on your account.

Create Hosted Checkout API

The API that is used to initialize a hostedCheckout session has been updated. Please find below an overview of all the new properties that have been added as well as the changes to the object definitions. There are less new properties in this API vs the Create Payment API as we will capture all the device and browser related data ourselves. Next to this we also determine the size of the challenge area, based on the size of the window/iframe that the MyCheckout hosted payment pages are displayed in. In case you use an iframe to show the MyCheckout hosted payment pages note that the size of the iframe has a minimum width of 250 pixels and a minimum height of 400 pixels.

Minimal Frame size for Challenge

The below overview shows all properties in the input that are used in the 3-D Secure version 2 authentication. In the description it is mentioned if the property is required and under which conditions. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
fraudFields Existing property Object Object containing additional data that will be used to assess the risk of fraud
  addressesAreIdentical Deprecated property Boolean
  • true - the billing and shipping addresses are identical
  • false - the billing and shipping addresses are different

Deprecated - please use order.shipping.addressIndicator to indicate that the billing and shipping address are identical.

order Existing property Object Order object containing order related data
  additionalInput Existing property Object Object containing additional input on the order
    typeInformation Existing property Object Object containing specific classifications of the transaction
      transactionType New property Enum (string)

Required for merchants from Brazil if order.amountOfMoney.amount is not 0

Identifies the type of transaction being authenticated.

  • purchase = The purpose of the transaction is to purchase goods or services
  • check-acceptance = The purpose of the transaction is to accept a 'check'/'cheque'
  • account-funding = The purpose of the transaction is to fund an account
  • quasi-cash = The purpose of the transaction is to buy a quasi cash type product that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets or casino gaming chips.
  • prepaid-activation-or-load = The purpose of the transaction is to activate or load a prepaid card
  customer New property Object Object containing data related to the consumer
    account New property Object Object containing data related to the account the consumer has with you
      createDate New property AN8

The date (YYYYMMDD) on which the consumer created their account with you

We will calculate the CustomerAccountAgeIndicator using this property and the order.customer.accountType.

      changeDate New property AN8

The last date (YYYYMMDD) on which the consumer made changes to their account with you. These are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the changes are used.

      changedDuringCheckout New property Boolean
  • true = the consumer made changes to their account during this checkout
  • false = the consumer didn't change anything to their account during this checkout

The changes meant here are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changeDate to determine the 'age' of the changes. For 3-D Secure version 2 only the resulting 'age' of the changes is used.

      passwordChangeDate New property AN8

The last date (YYYYMMDD) on which the consumer changed their password for the account used in this transaction

We will use the data from this property and the order.customer.account.passwordChangedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the password change are used.

      passwordChangedDuringCheckout New property Boolean Property that indicates if the password of an account is changed during this checkout
  • true = the consumer made changes to their password of the account used during this checkout
  • false = the consumer didn't change anything to their password of the account used during this checkout

We will use the data from this property and the order.customer.account.passwordChangeDate to determine the 'age' of the password change. For 3-D Secure version 2 only the resulting 'age' of the password change is used.

      hasForgottenPassword Moved property Boolean

Specifies if the consumer (initially) had forgotten their password

  • true - The consumer has forgotten their password
  • false - The consumer has not forgotten their password

Moved (and renamed) existing property order.fraudFields.hasForgottenPwd to the order.customer.account object

This property is not used for 3-D Secure version 2.

      hadSuspiciousActivity New property Boolean

Specifies if you have experienced suspicious activity on the account of the consumer

  • true = you have experienced suspicious activity (including previous fraud) on the consumer account used for this transaction
  • false = you have experienced no suspicious activity (including previous fraud) on the consumer account used for this transaction
      authentication New property Object Object containing data on the authentication used by the consumer to access their account
        utcTimestamp New property AN12 Timestamp (YYYYMMDDHHmm) of the authentication of the consumer to their account with you
        method New property Enum (String)

Authentication used by the consumer on your website

  • guest = no login occurred, consumer is 'logged in' as guest
  • merchant-credentials = the consumer logged in using credentials that are specific to you
  • federated-id = the consumer logged in using a federated ID
  • issuer-credentials = the consumer logged in using credentials from the card issuer (of the card used in this transaction)
  • third-party-authentication = the consumer logged in using third-party authentication
  • fido-authentication = the consumer logged in using a FIDO authenticator
      paymentActivity New property Object Object containing data on the purchase history of the consumer with you
        numberOfPurchasesLast6Months New property N4 Number of successful purchases made by this consumer with you in the last 6 months
        numberOfPaymentAttemptsLast24Hours New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 24 hours
        numberOfPaymentAttemptsLastYear New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 12 months
      paymentAccountOnFileType New property Enum (String)

Required for merchants in Brazil

Indicates the type of account. For example, for a multi-account card product.

  • not-applicable = the card used doesn't support multiple card products
  • credit = the card used is a credit card
  • debit = the card used is a debit card
      paymentAccountOnFile New property Object Object containing information on the payment account data on file (tokens)
        numberOfCardOnFileCreationAttemptsLast24Hours New property N3 Number of attempts made to add new card to the consumer account in the last 24 hours
        createDate New property AN8

The date (YYYYMMDD) when the payment account on file was first created.

In case a token is used for the transaction we will use the creation date of the token in our system in case you leave this property empty.

    accountType New property Enum (String) Type of the customer account that is used to place this order. Can have one of the following values:
  • none = None (guest)
  • created = Account was created during this transaction
  • existing = Existing account was used for this transaction

We will try to automatically determine the value for this field:

  • in case cardPaymentMethodSpecificInput.tokenize is set to true or the consumer checks the Remember my details box, we will set the value of this property to created (even though there might be an existing token matching the card details)
  • in case a token is used for this transaction the value will be set to existing
  • in case cardPaymentMethodSpecificInput.tokenize is set to false and no token is used for this transaction we will default to none
    billingAddress Existing property Object Object containing the billing address details
      additionalInfo Existing property AN50 Additional address information
      city Existing property AN40 City
      countryCode Existing property AN2 ISI 3166-1 alpha-2 country code
      houseNumber Existing property AN15 House number
      stateCode Existing property AN9 State code
      street Existing property AN50 Streetname
      zip Existing property AN10 Zip code
    companyInformation Existing property Object Object containing information of the company in case the consumer is a company
      vatNumber Moved property AN17

Local VAT number of the 'consumer'

Moved from order.customer

This property is not used for 3-D Secure version 2.

    contactDetails   Object Object containing contact details of the consumer
      emailAddress Existing property AN70 Email address of the consumer
      mobilePhoneNumber New property AN20

International version of the mobile phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      phoneNumber Existing property AN20

International version of the home phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      workPhoneNumber New property AN20

International version of the work phone number of the consumer including the leading + (i.e. +31235671500)

Official max length is N15 making it AN16 to include the leading + sign

  shipping New property Object Object containing information regarding shipping / delivery
    type New property Enum (String) Indicates the merchandise delivery timeframe
  • electronic = electronic delivery (services or digital goods)
  • same-day = same day delivery
  • overnight = overnight delivery
  • 2-day-or-more = two day or more deliveries
    firstUsageDate New property AN8

Date (YYYYMMDD) when the shipping details for this transaction where first used

We will use the data from this property and the order.shipping.isFirstUsage to determine the 'age' of the shipping details. For 3-D Secure version 2 this property and the 'age' of the shipping details change are used.

    isFirstUsage New property Boolean Indicator if this shipping address is used for the first time to ship an order
  • true = the shipping details are used for the first time with this transaction
  • false = the shipping details have been used for other transactions in the past

We will use the data from this property and the order.shipping.firstUsageDate to determine the 'age' of the shipping details. For 3-D Secure version 2 only the resulting 'age' of the shipping details is used.

    addressIndicator New property Enum (String) Indicates shipping method chosen for the transaction.
  • same-as-billing = the shipping address and the billing address are identical
  • another-verified-address-on-file-with-merchant = another verified address of the consumer that is on file with you
  • different-than-billing = shipping address is different from the billing address
  • ship-to-store = goods are shipped to a store (shipping address = store address)
  • digital-goods = electronic delivery of digital goods
  • travel-and-event-tickets-not-shipped = travel and/or event tickets that are not shipped
  • other = other means of delivery
    emailAddress New property AN70 Email address linked to the shipping
    address New property Object Object containing address information
      additionalInfo Moved property AN50

Additional address information

Moved from order.customer.shippingaddress

      city Moved property AN40

City

Moved from order.customer.shippingaddress

      countryCode Moved property AN2

ISO 3166-1 alpha-2 country code

Moved from order.customer.shippingaddress

      houseNumber Moved property AN15

House number

Moved from order.customer.shippingaddress

      name Moved property Object

Object containing the name elements

Moved from order.customer.shippingaddress.name

        firstName Moved property AN15

Given name(s) or first name(s) of the consumer

Moved from order.customer.shippingaddress.name.firstName

This property is not used for 3-D Secure version 2.

        surname Moved property AN70

Surname(s) or last name(s) of the consumer

Moved from order.customer.shippingaddress.name.surname

This property is not used for 3-D Secure version 2.

        surnamePrefix Moved property AN15

Middle name - In between first name and surname - of the consumer

Moved from order.customer.shippingaddress.name.surnamePrefix

This property is not used for 3-D Secure version 2.

        title Moved property AN35

Title of consumer

Moved from order.customer.shippingaddress.name.title

This property is not used for 3-D Secure version 2.

      state Moved property AN35

State to which the shipment is being send

 

Moved from order.customer.shippingaddress.state

This property is not used for 3-D Secure version 2.

      stateCode Moved property AN9

State code

Moved from order.customer.shippingaddress.stateCode

      street Moved property AN50

Street name

Moved from order.customer.shippingaddress.street

      zip Moved property AN17

Zip code

Moved from order.customer.shippingaddress.zip

    trackingNumber Moved property AN19

Shipment tracking number

Moved from fraudFields and renamed (old name = shipmentTrackingNumber)

This property is not used for 3-D Secure version 2.

    comments Moved property AN160

Comments included during shipping

Moved from fraudFields and renamed (old name = shipComments)

This property is not used for 3-D Secure version 2.

  shoppingCart Existing property Object Object containing information on the item(s) in the shopping cart
    isPreOrder New property Boolean

The consumer is pre-ordering one or more items

    preOrderItemAvailabilityDate New property AN8 Date (YYYYMMDD) when the preordered item becomes available
    giftCardPurchase New property Object Object containing information on purchased gift card(s)
      amountOfMoney New property Object Object containing information on an amount of money
        amount New property N12 Amount in cents and always having 2 decimals
        currencyCode New property AN3 Three-letter ISO currency code representing the currency for the amount
      numberOfGiftCards New property N2 Number of gift cards that are purchased through this transaction
    reOrderIndicator New property Boolean Indicates whether the cardholder is reordering previously purchased item(s)
  • true = the consumer is re-ordering at least one of the items again
  • false = this is the first time the consumer is ordering these items
cardPaymentMethodSpecificInput Existing property Object Object containing data regarding card payments
  threeDSecure New property Object Object containing specific 3-D Secure data
    priorThreeDSecureData New property Object

Object containing data regarding the consumer authentication that occurred prior to the current transaction

      method New property

enum (string)

Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction
      utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the prior 3-D Secure authentication

      acsTransactionId New property AN36

The ACS Transaction ID for a prior 3-D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the consumer).

    challengeIndicator New property Enum (String)

Allows you to indicate if you want the consumer to be challenged for extra security on this transaction.

  • no-preference = You have no preference whether or not to challenge the consumer (default)
  • no-challenge-requested = you prefer the cardholder not to be challenged
  • challenge-requested = you prefer the consumer to be challenged
  • challenge-required = you require the consumer to be challenged
    skipAuthentication Moved property Boolean
  • true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
  • false = 3D Secure authentication will not be skipped for this transaction.

Note: This is only possible if your account in our system is setup for 3D Secure authentication and if your configuration in our system allows you to override it per transaction.

Note: Any configured Dynamic 3D rules will be ignored when you submit this property.

Moved from cardPaymentMethodSpecificInput

  isRecurring Existing property Boolean Indicates if this transaction is of a one-off or a recurring type
  • true - This is recurring
  • false - This is one-off

This is used with property recurringPaymentSequenceIndicator to determine if the transaction is a first of recurring

  recurring New property Object Object containing data related to recurring
    endDate New property AN8

Date (YYYYMMDD) in the future after which no further authorisations shall be performed.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    minFrequency New property AN3

This indicates the number of days between the recurring authorizations. Can be set to "1" to indicate that the frequency is variable.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    recurringPaymentSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of recurring transactions
  • recurring = This transaction is a subsequent transaction in a series of recurring transactions

Note: For any first of a recurring the system will automatically create a token as you will need to use a token for any subsequent recurring transactions. In case a token already exists this is indicated in the response with a value of False for the isNewToken property in the response.

Note: This property is required when isRecurring is set to true.

3-D Secure will not be used when this property is set to recurring

Moved from cardPaymentMethodSpecificInput.recurringPaymentSequenceIndicator

  unscheduledCardOnFileRequestor Existing property

Enum

(string)

Indicates which party initiated the unscheduled recurring transaction. Allowed values:

  • merchantInitiated - Merchant Initiated Transaction.
  • cardholderInitiated - Cardholder Initiated Transaction.

Note: this property is not allowed if isRecurring is true.

Required if unscheduledCardOnFileIndicator is 'subsequent'. Otherwise it must not be 'merchantInitiated'.

3-D Secure will not be used when this property is set to cardholderInitiated

  unscheduledCardOnFileSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of unscheduled recurring transactions
  • subsequent = This transaction is a subsequent transaction in a series of unscheduled recurring transactions


Note: this property is not allowed if isRecurring is true.

Renamed from unscheduledCardOnFileIndicator

Additional response properties related to 3-D Secure version 2

There are no additional response properties to the Create hostedCheckout call for 3-D Secure version 2.

API

To keep our API logical and easy to understand we decided to change some of the existing object definitions. Our system will accept both the old definition and the new definition as long as you don't mix old and new definitions in one API call. This means that your current implementation will keep working, but will most likely not support all the properties required to ensure the maximum number of consumers that will use the frictionless flow. Our new SDKs will only support the new object definitions and will require some development work on your side to adopt.

Create Payment API

Request properties for 3-D Secure version 2

The below overview shows all properties in the input that are used in the 3-D Secure version 2 authentication. In the description it is mentioned if the property is required and under which conditions. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
fraudFields Existing property Object Object containing additional data that will be used to assess the risk of fraud
  addressesAreIdentical Deprecated property Boolean
  • true - the billing and shipping addresses are identical
  • false - the billing and shipping addresses are different

Deprecated - please use order.shipping.addressIndicator to indicate that the billing and shipping address are identical.

merchant New property Object Object containing information on you, the merchant
  websiteUrl Moved property AN60

The website from which the purchase was made

Moved from fraudFields.website and renamed to make it more clear we expect an URL.

This property is not used for 3-D Secure version 2.

  contactWebsiteUrl New property AN2048 URL to find contact or support details to contact in case of questions
order Existing property Object Order object containing order related data
  additionalInput Existing property Object Object containing additional input on the order
    typeInformation Existing property Object Object containing specific classifications of the transaction
      transactionType New property Enum (string)

Required for merchants from Brazil in case order.amountOfMoney.amount is not 0

Identifies the type of transaction being authenticated.

  • purchase = The purpose of the transaction is to purchase goods or services
  • check-acceptance = The purpose of the transaction is to accept a 'check'/'cheque'
  • account-funding = The purpose of the transaction is to fund an account
  • quasi-cash = The purpose of the transaction is buy a quasi cash type product that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets or casino gaming chips.
  • prepaid-activation-or-load = The purpose of the transaction is to activate or load a prepaid card
  customer New property Object Object containing data related to the consumer
    account New property Object Object containing data related to the account the consumer has with you
      createDate New property AN8

The date (YYYYMMDD) on which the consumer created their account with you

We will calculate the CustomerAccountAgeIndicator using this property and the order.customer.accountType.

      changeDate New property AN8

The last date (YYYYMMDD) on which the consumer made changes to their account with you. These are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the changes are used.

      changedDuringCheckout New property Boolean
  • true = the consumer made changes to their account during this checkout
  • false = the consumer didn't change anything to their account during this checkout

The changes meant here are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changeDate to determine the 'age' of the changes. For 3-D Secure version 2 only the resulting 'age' of the changes is used.

      passwordChangeDate New property AN8

The last date (YYYYMMDD) on which the consumer changed their password for the account used in this transaction

We will use the data from this property and the order.customer.account.passwordChangedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the password change are used.

      passwordChangedDuringCheckout New property Boolean Property that indicates if the password of an account is changed during this checkout
  • true = the consumer made changes to their password of the account used during this checkout
  • false = the consumer didn't change anything to their password of the account used during this checkout

We will use the data from this property and the order.customer.account.passwordChangeDate to determine the 'age' of the password change. For 3-D Secure version 2 only the resulting 'age' of the password change is used.

      hasForgottenPassword Moved property Boolean

Specifies if the consumer (initially) had forgotten their password

  • true - The consumer has forgotten their password
  • false - The consumer has not forgotten their password

Moved (and renamed) existing property order.fraudFields.hasForgottenPwd to the order.customer.account object

This property is not used for 3-D Secure version 2.

      hadSuspiciousActivity New property Boolean

Specifies if you have experienced suspicious activity on the account of the consumer

  • true = you have experienced suspicious activity (including previous fraud) on the consumer account used for this transaction
  • false = you have experienced no suspicious activity (including previous fraud) on the consumer account used for this transaction
      authentication New property Object Object containing data on the authentication used by the consumer to access their account
        utcTimestamp New property AN12 Timestamp (YYYYMMDDHHmm) of the authentication of the consumer to their account with you
        method New property Enum (String)

Authentication used by the consumer on your website

  • guest = no login occurred, consumer is 'logged in' as guest
  • merchant-credentials = the consumer logged in using credentials that are specific to you
  • federated-id = the consumer logged in using a federated ID
  • issuer-credentials = the consumer logged in using credentials from the card issuer (of the card used in this transaction)
  • third-party-authentication = the consumer logged in using third-party authentication
  • fido-authentication = the consumer logged in using a FIDO authenticator
  • fido-authentication-signed-assurance = the consumer logged in using a FIDO authenticator and you have signed FIDO assurance data
  • src-assurance-data = SRC Assurance Data
      paymentActivity New property Object Object containing data on the purchase history of the consumer with you
        numberOfPurchasesLast6Months New property N4 Number of successful purchases made by this consumer with you in the last 6 months
        numberOfPaymentAttemptsLast24Hours New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 24 hours
        numberOfPaymentAttemptsLastYear New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 12 months
      paymentAccountOnFileType New property Enum (String)

Required for merchants in Brazil

Indicates the type of account. For example, for a multi-account card product.

  • not-applicable = the card used doesn't support multiple card products
  • credit = the card used is a credit card
  • debit = the card used is a debit card
      paymentAccountOnFile New property Object Object containing information on the payment account data on file (tokens)
        numberOfCardOnFileCreationAttemptsLast24Hours New property N3 Number of attempts made to add new card to the consumer account in the last 24 hours
        createDate New property AN8

The date (YYYYMMDD) when the payment account on file was first created.

In case a token is used for the transaction we will use the creation date of the token in our system in case you leave this property empty.

    accountType New property Enum (String) Type of the customer account that is used to place this order. Can have one of the following values:
  • none = None (guest)
  • created = Account was created during this transaction
  • existing = Existing account was used for this transaction

We will try to automatically determine the value for this field:

  • in case cardPaymentMethodSpecificInput.tokenize is set to true we will set the value of this property to created (even though there might be an existing token matching the card details)
  • in case a token is used for this transaction the value will be set to existing
  • in case cardPaymentMethodSpecificInput.tokenize is set to false and no token is used for this transaction we will default to none
    companyInformation Existing property Object Object containing information of the company in case the consumer is a company
      vatNumber Moved property AN17

Local VAT number of the 'consumer'

Moved from order.customer

This property is not used for 3-D Secure version 2.

    billingAddress Existing property Object Object containing the billing address details
      additionalInfo Existing property AN50 Additional address information
      city Existing property AN40 City
      countryCode Existing property AN2 ISI 3166-1 alpha-2 country code
      houseNumber Existing property AN15 House number
      stateCode Existing property AN9 State code
      street Existing property AN50 Streetname
      zip Existing property AN10 Zip code
    device New property Object Object containing information on the device and browser of the consumer
      acceptHeader New property AN2048

Required for 3-D Secure version 2 for the authenticationFlow "browser"

The accept-header of the consumer client from the HTTP Headers.

      ipAddress Moved property AN45

The IP address of the consumer client from the HTTP Headers.

Moved from fraudFields, increased in size (to also accommodate IPv6 addresses) and renamed (previously fraudFields.customerIpAddress)

      deviceFingerprintTransactionId Moved property AN50

One must use the deviceFingerprintTransactionId received by the response of the endpoint /{merchant}/products/{paymentProductId}/deviceFingerprint which was also used by the JavaScript code

Moved from fraudFields.deviceFingerprintTransactionId

This property is not used for 3-D Secure version 2, although in the future we might use this service to populate the device and browser related properties.

      defaultFormFill Moved property Enum (String)

Degree of default form fill, with the following possible values:

  • automatically - All form fields filled automatically
  • automatically-but-modified - All form fields filled automatically, but some form fields were modified manually
  • manually - All form fields were entered manually

Moved from fraudFields.defaultFormFill

This property is not used for 3-D Secure version 2.

      timezoneOffsetUtcMinutes New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Offset in minutes of timezone of the client vs the UTC. Value is returned by the JavaScript getTimezoneOffset() Method.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

      locale New property AN8

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Locale of the client device/browser. Returned in the browser from the navigator.language property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

      userAgent New property AN2048

Required for 3-D Secure version 2 for the authenticationFlow "browser"

User-Agent of the client device/browser from the HTTP Headers.

As a fall-back we will use the userAgent that might be included in the encryptedCustomerInput, but this is captured client side using JavaScript and might be different.

      browserData New property Object

Object containing information regarding the browser of the consumer

        javaEnabled New property Boolean

Required for 3-D Secure version 2 for the authenticationFlow "browser"

  • true = Java is enabled in the browser
  • false = Java is not enabled in the browser (default if left empty)

Value is returned from the navigator.javaEnabled property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        javaScriptEnabled New property Boolean

Required for 3-D Secure version 2 for the authenticationFlow "browser"

  • true = JavaScript is enabled in the browser
  • false = JavaScript is not enabled in the browser (default if left empty)

Note: Required in future 3-D Secure version 2.2

        colorDepth New property N2

Required for 3-D Secure version 2 for the authenticationFlow "browser"

ColorDepth in bits. Value is returned from the screen.colorDepth property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        screenHeight New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Height of the screen in pixels. Value is returned from the screen.height property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        screenWidth New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Width of the screen in pixels. Value is returned from the screen.width property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        innerHeight New property AN6

The innerHeight of the frame in case you are capturing your payments in a frame. We will use this to validate if the height provided in the cardPaymentMethodSpecifInput.threeDSecure.challengeCanvasSize will actually fit in the iFrame you use.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser.

        innerWidth New property AN6

The innerWidth of the frame in case you are capturing your payments in a frame. We will use this to validate if the width provided in the cardPaymentMethodSpecifInput.threeDSecure.challengeCanvasSize will actually fit in the iFrame you use.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser.

    contactDetails Existing property Object Object containing contact details of the consumer
      mobilePhoneNumber New property AN20

International version of the mobile phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      phoneNumber Existing property AN20

International version of the home phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      workPhoneNumber New property AN20

International version of the work phone number of the consumer including the leading + (i.e. +31235671500)

Official max length is N15 making it AN16 to include the leading + sign

  shipping New property Object Object containing information regarding shipping / delivery
    type New property Enum (String) Indicates the merchandise delivery timeframe
  • electronic = electronic delivery (services or digital goods)
  • same-day = same day delivery
  • overnight = overnight delivery
  • 2-day-or-more = two day or more deliveries
    firstUsageDate New property AN8

Date (YYYYMMDD) when the shipping details for this transaction where first used

We will use the data from this property and the order.shipping.isFirstUsage to determine the 'age' of the shipping details. For 3-D Secure version 2 this property and the 'age' of the shipping details change are used.

    isFirstUsage New property Boolean Indicator if this shipping address is used for the first time to ship an order
  • true = the shipping details are used for the first time with this transaction
  • false = the shipping details have been used for other transactions in the past

We will use the data from this property and the order.shipping.firstUsageDate to determine the 'age' of the shipping details. For 3-D Secure version 2 only the resulting 'age' of the shipping details is used.

    addressIndicator New property Enum (String) Indicates shipping method chosen for the transaction.
  • same-as-billing = the shipping address and the billing address are identical
  • another-verified-address-on-file-with-merchant = another verified address of the consumer that is on file with you
  • different-than-billing = shipping address is different from the billing address
  • ship-to-store = goods are shipped to a store (shipping address = store address)
  • digital-goods = electronic delivery of digital goods
  • travel-and-event-tickets-not-shipped = travel and/or event tickets that are not shipped
  • other = other means of delivery
    emailAddress New property AN70 Email address linked to the shipping
    address New property Object Object containing address information
      additionalInfo Moved property AN50

Additional address information

Moved from order.customer.shippingaddress

      city Moved property AN40

City

Moved from order.customer.shippingaddress

      countryCode Moved property AN2

ISO 3166-1 alpha-2 country code

Moved from order.customer.shippingaddress

      houseNumber Moved property AN15

House number

Moved from order.customer.shippingaddress

      name Moved property Object

Object containing the name elements

Moved from order.customer.shippingaddress.name

        firstName Moved property AN15

Given name(s) or first name(s) of the consumer

Moved from order.customer.shippingaddress.name.firstName

This property is not used for 3-D Secure version 2.

        surname Moved property AN70

Surname(s) or last name(s) of the consumer

Moved from order.customer.shippingaddress.name.surname

This property is not used for 3-D Secure version 2.

        surnamePrefix Moved property AN15

Middle name - In between first name and surname - of the consumer

Moved from order.customer.shippingaddress.name.surnamePrefix

This property is not used for 3-D Secure version 2.

        title Moved property AN35

Title of consumer

Moved from order.customer.shippingaddress.name.title

This property is not used for 3-D Secure version 2.

      state Moved property AN35

State of the consumer 

Moved from order.customer.shippingaddress.state

This property is not used for 3-D Secure version 2.

      stateCode Moved property AN9

State code

Moved from order.customer.shippingaddress.stateCode

      street Moved property AN50

Street name

Moved from order.customer.shippingaddress.street

      zip Moved property AN17

Zip code

Moved from order.customer.shippingaddress.zip

    trackingNumber Moved property AN19

Shipment tracking number

Moved from fraudFields and renamed (old name = shipmentTrackingNumber) to bundle all the shipping related properties together.

This property is not used for 3-D Secure version 2.

    comments Moved property AN160

Comments included during shipping

Moved from fraudFields and renamed (old name = shipComments) to bundle all the shipping related properties together.

This property is not used for 3-D Secure version 2.

  shoppingCart Existing property Object Object containing information on the item(s) in the shopping cart
    isPreOrder New property Boolean

The consumer is pre-ordering one or more items

    preOrderItemAvailabilityDate New property AN8 Date (YYYYMMDD) when the preordered item becomes available
    giftCardPurchase New property Object Object containing information on purchased gift card(s)
      amountOfMoney New property Object Object containing information on an amount of money
        amount New property N12 Amount in cents and always having 2 decimals
        currencyCode New property AN3 Three-letter ISO currency code representing the currency for the amount
      numberOfGiftCards New property N2 Number of gift cards that are purchased through this transaction
    reOrderIndicator New property Boolean Indicates whether the cardholder is reordering previously purchased item(s)
  • true = the consumer is re-ordering at least one of the items again
  • false = this is the first time the consumer is ordering these items
cardPaymentMethodSpecificInput Existing property Object Object containing data regarding card payments
  card Existing property Object Object containing card data
    cardNumber Existing property AN19

The complete credit/debit card number (also know as the PAN)

The card number is always obfuscated in any of our responses

Required, except when a token or encryptedCustomerInput that includes this data is provided.
    cardholderName Existing property AN51

Card holder's name on the card

Required for 3-D Secure version 2, except when a token or encryptedCustomerInput that includes this data is provided.

This property was optional for payments on the GlobalCollect platform, but will be required for transactions that utilize 3-D Secure version 2.

    expiryDate Existing property AN4

Expiry date of the card
Format: MMYY

Required, except when a token or encryptedCustomerInput that includes this data is provided.

  isRecurring Existing property Boolean Indicates if this transaction is of a one-off or a recurring type
  • true - This is recurring
  • false - This is one-off

This is used with property recurringPaymentSequenceIndicator to determine if the transaction is a first of recurring

  recurring New property Object Object containing data related to recurring
    endDate New property AN8

Date (YYYYMMDD) in the future after which no further authorisations shall be performed.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    minFrequency New property AN3

This indicates the number of days between the recurring authorizations. Can be set to "1" to indicate that the frequency is variable.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    recurringPaymentSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of recurring transactions
  • recurring = This transaction is a subsequent transaction in a series of recurring transactions

Note: For any first of a recurring the system will automatically create a token as you will need to use a token for any subsequent recurring transactions. In case a token already exists this is indicated in the response with a value of False for the isNewToken property in the response.

Note: This property is required when isRecurring is set to true.

3-D Secure will not be used when this property is set to recurring

Moved from cardPaymentMethodSpecificInput.recurringPaymentSequenceIndicator

  threeDSecure New property Object Object containing specific data regarding 3-D Secure
    authenticationFlow New property

Enum

(String)

Indicates whether a transaction is performed in-app using an EMVco certified mobile SDK or inside a browser.

  • browser = Consumer is using a browser to complete the checkout (default)
  • in-app = Consumer is using an app with a 3-D Secure SDK to complete the checkout

Note: We will add support for the in-app flow in a future release.

    challengeCanvasSize New property Enum (String)

Required for 3-D Secure version 2 for the browser flow.

Dimensions of the challenge window that potentially will be displayed to the consumer. The challenge content is formatted to appropriately render in this window to provide the best possible user experience.

Preconfigured sizes are width x height in pixels of the window displayed in the consumer browser window. Possible values are:

  • 250x400 (default)
  • 390x400
  • 500x600
  • 600x400
  • full-screen
    challengeIndicator New property Enum (String)

Allows you to indicate if you want the consumer to be challenged for extra security on this transaction.

  • no-preference = You have no preference whether or not to challenge the consumer (default)
  • no-challenge-requested = you prefer the cardholder not to be challenged
  • challenge-requested = you prefer the consumer to be challenged
  • challenge-required = you require the consumer to be challenged
    externalCardholderAuthenticationData Moved property Object

Object containing results of an external authentication (not performed by Ingenico)

Moved from cardPaymentMethodSpecificInput

      cavv Moved property AN50

The CAVV (cardholder authentication verification value) or AAV (accountholder authentication value) provides an authentication validation value.


This is mandatory for ECI 1, 2, 5 and 6.

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      cavvAlgoritm Moved property AN1

The algorithm, from your 3D Secure provider, used to generate the authentication CAVV.


Required when
  • The 3D Secure authentication for the transaction is managed by a non-Ingenico ePayments 3D Secure authentication provider
  • You process the transaction through Atos

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      eci Moved property N2 Electronic Commerce Indicator provides authentication validation results returned after AUTHENTICATIONVALIDATION
  • 0 = No authentication, Internet (no liability shift, not a 3D Secure transaction)
  • 1 = Authentication attempted (MasterCard)
  • 2 = Successful authentication (MasterCard)
  • 5 = Successful authentication (Visa, Diners Club, Amex)
  • 6 = Authentication attempted (Visa, Diners Club, Amex)
  • 7 = No authentication, Internet (no liability shift, not a 3D Secure transaction)
  • (empty) = Not checked or not enrolled

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      threeDSecureVersion New property enum (string) The 3-D Secure version used for the authentication. Possible values:
  • v1
  • v2
      directoryServerTransactionId New property AN50 The 3-D Secure Directory Server transaction ID that is used for the 3-D Secure version 2 Authentication
      threeDServerTransactionId New property AN50 The 3-D Secure Server transaction ID that is used for the 3-D Secure version 2 Authentication
      validationResult Moved property AN1

The 3D Secure authentication result from your 3D Secure provider.

Required when
  • The 3D Secure authentication for the transaction is managed by a non-Ingenico ePayments 3D Secure authentication provider
  • You process the transaction through Atos

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      xid Moved property AN50

The transaction ID that is used for the 3D Authentication version 1

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

    priorThreeDSecureData New property Object

Object containing data regarding the consumer authentication that occurred prior to the current transaction

      acsTransactionId New property AN36

The ACS Transaction ID for a prior 3-D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the consumer).

      method New property

enum (string)

Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction
      utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the prior 3-D Secure authentication

    redirectionData New property Object

Required for 3-D Secure version 2 for the browser flow.

Object containing browser specific redirection related data

Moved from cardPaymentMethodSpecificInput

      returnUrl Moved property AN512

Required for 3-D Secure version 2 for the browser flow.

The URL that the consumer is redirect to after the payment flow has finished. You can add any number of key value pairs in the query string that, for instance help you to identify the consumer when they return to your site. Please note that we will also append some additional key value pairs that will also help you with this identification process.
Note: The provided URL should be absolute and contain the protocol to use, e.g. http:// or https://. For use on mobile devices a custom protocol can be used in the form of protocol://. This protocol must be registered on the device first.
URLs without a protocol will be rejected.

Moved from cardPaymentMethodSpecificInput

      variant New property AN10

Using the Configuration Center it is possible to create multiple variations of your MyCheckout payment pages. The redirection flow for 3-D Secure uses the MyCheckout payment pages to display the following types of pages:

  • Redirection page - All redirection using a POST method will load a page in the browser of the consumer that performs the actual redirection. This page contains a message to the consume explaining what is happening.
  • MethodURL page - Certain Issuers will use a specific flow in case of 3-D Secure version 2 to directly collect information from the consumer browser. This page contains a spinner indicating that this process is going on in.
By specifying a specific variant you can force the use of another variant then the default. This allows you to test out the effect of certain changes to your MyCheckout payment pages in a controlled manner. Please note that you need to specify the ID instead of the name of the variant.

    sdkData New property Object Object containing 3-D Secure in-app SDK data
      sdkAppId New property Object

Required for 3-D Secure version 2 for the in-app flow.

Universally unique ID created upon all installations and updates of your app on a consumer Device. This will be newly generated and stored by the 3DS SDK for each installation or update.

      deviceInfo New property AN64000

Required for 3-D Secure version 2 for the in-app flow.

Device information gathered by the 3DS SDK on a consumer device. This is JSON name/value pairs that as a whole is Base64url encoded.

      deviceRenderOptions New property Object

Object containing rendering options of the device

        sdkInterface New property

Enum

(string)

Required for 3-D Secure version 2 for the in-app flow.

Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.

  • native = The app supports only a native user interface
  • html = The app supports only an HTML user interface
  • both = Both Native and HTML user interfaces are supported by the app
        sdkUiType New property

Enum

(string)

Required for 3-D Secure version 2 for the in-app flow.

Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.

  • text = Text interface
  • single-select = Select a single option
  • multi-select = Select multiple options
  • oob = Out of bounds
  • html-other = HTML Other (only valid when cardPaymentMethodSpecificInput.threeDSecure.sdkData.deviceRenderOptions.sdkInterface is set to html)

Note: Currently, all 3-D Secure SDKs need to support all UI Types. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined by this specification).

      sdkEncryptedData New property AN64000

Required for 3-D Secure version 2 for the in-app flow.

JWE Object containing data encrypted by the 3-D Secure SDK.

      sdkEphemeralPublicKey New property AN256

Required for 3-D Secure version 2 for the in-app flow.

Public key component of the ephemeral key pair generated by the 3-D Secure SDK and used to establish session keys between the 3-D Secure SDK and ACS.

      sdkMaxTimeout New property AN2

Required for 3-D Secure version 2 for the in-app flow, except when order.amountOfMoney.amount is zero.

Indicates maximum amount of time (in minutes) for all exchanges. Minimum amount of minutes is 5.

      sdkReferenceNumber New property AN32

Required for 3-D Secure version 2 for the in-app flow.

Identifies the vendor and version for the 3-D Secure SDK that is integrated in your app, assigned by EMVCo when the 3-D Secure SDK is approved.

      sdkTransactionId New property AN36

Required for 3-D Secure version 2 for the in-app flow.

Universally unique transaction identifier assigned by the 3-D Secure SDK to identify a single transaction.

    skipAuthentication Moved property Boolean
  • true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
  • false = 3D Secure authentication will not be skipped for this transaction.

Note: This is only possible if your account in our system is setup for 3D Secure authentication and if your configuration in our system allows you to override it per transaction.

Note: Any configured Dynamic 3D rules will be ignored when you submit this property.

Moved from cardPaymentMethodSpecificInput

  unscheduledCardOnFileRequestor Existing property

Enum

(string)

Indicates which party initiated the unscheduled recurring transaction. Allowed values:

  • merchantInitiated - Merchant Initiated Transaction.
  • cardholderInitiated - Cardholder Initiated Transaction.

Note: this property is not allowed if isRecurring is true.

Required if unscheduledCardOnFileIndicator is 'subsequent'. Otherwise it must not be 'merchantInitiated'.

3-D Secure will not be used when this property is set to cardholderInitiated

  unscheduledCardOnFileSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of unscheduled recurring transactions
  • subsequent = This transaction is a subsequent transaction in a series of unscheduled recurring transactions


Note: this property is not allowed if isRecurring is true.

Renamed from unscheduledCardOnFileIndicator

Additional response properties related to 3-D Secure version 2

It is possible that the Authentication fails and the reason why will be detailed in the errors. It is also possible that the issuer will require Strong Customer Authentication (SCA) to be provided before the issuer will authorize the transaction. This means that you should process the transaction in a way that will allow SCA through for instance a challenge to take place.

The below overview shows all properties in the output that are used in the 3-D Secure version 2 authentication. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
payment Existing property Object Object containing data regarding the payment
  paymentOutput Existing property Object Object containing output data regarding the payment
    cardPaymentMethodSpecificOutput Existing property Object Object containing card payment method specific output
      threeDSecureResults Existing property Object Object containing results of the 3D Secure authentication
        sdkData New property Object Object containing 3-D Secure in-app SDK data
          sdkTransactionId New property AN36

Universally unique transaction identifier assigned by the 3-D Secure SDK to identify this transaction.

        threeDSecureData New property Object Object containing data regarding the 3D Secure authentication
          acsTransactionId New property AN36

The ACS Transaction ID for this transaction.

You should store this data as you will need it for the next transaction with the same card

          method New property Enum (String) Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction

You should store this data as you will need it for the next transaction with the same card

          utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the 3-D Secure authentication of this transaction

You should store this data as you will need it for the next transaction with the same card

        directoryServerTransactionId New property AN36

The 3-D Secure Directory Server transaction ID that is used for the 3-D Secure version 2 Authentication

This property is used in the communication with the acquirer

        threeDServerTransactionId New property AN36

The 3-D Secure Server transaction ID that is used for the 3-D Secure version 2 Authentication

This property is used in the communication with the acquirer

        threeDSecureVersion New property AN10

The 3-D Secure version used for the authentication

This property is used in the communication with the acquirer

The above mentioned additional properties in the response to the Create Payment request have been added generically. This means that they are also returned on a Get Payment request and all other requests that return a paymentOutput object. please note that they are only returned in case of a 3-D Secure version 2 authentication.

Webhooks

The additional properties that have been added to the Create Payment response have also been added to the webhook payment events, in case a 3-D Secure version 2 authentication was completed.

3-D Secure version 2

3-D Secure version 2 is an evolution of the existing 3-D Secure version 1 programs: Verified by Visa, Mastercard SecureCode, AmericanExpress SafeKey, Diners/Discover ProtectBuy and JCB J/Secure. It is based on a specification that has been drafted by EMVco. EMVCo exists to facilitate worldwide interoperability and acceptance of secure payment transactions. It is overseen by EMVCo’s six member organizations—American Express, Discover, JCB, Mastercard, UnionPay, and Visa—and supported by dozens of banks, merchants, processors, vendors and other industry stakeholders who participate as EMVCo Associates.

To reflect current and future market requirements, EMVco recognized the need to create a new 3-D Secure specification that would support app-based authentication and integration with digital wallets, as well as traditional browser-based e-commerce transactions. This led to the development and publication of the EMV® 3-D Secure – Protocol and Core Functions Specification. The specification takes into account these new payment channels and supports the delivery of industry leading security, performance and user experience.

Besides the major global card brands we also see that some local card brands are also looking to adopt similar/identical means of authentication as defined in the 3-D Secure version 2 specifications.

Why a new version

Version 1 of 3-D Secure results in redirects for consumers, to pages that aren't always optimized for the device that the consumer is using. This increases the drop-off rate of the consumers during your checkout. Next to this, the way the consumer has to authenticate isn't always the best way from a usability point of view, again increasing the drop-off even further. Due to the drop-off impact not all merchants have adopted 3-D Secure, so consumers aren't always familiar with the flow and this again leads to increased drop-off. In short the user experience leaves a lot to desire and you are faced with a loss of revenue due to a reduction of conversion on your checkout. Below map shows the drop-off percentages for 3-D Secure version 1 we observed on Ingenico's Global Collect Payment Platform in the first half of 2018.

GlobalCollect 3-D Secure version 1 drop-off per region in 2018

The implementation of 3-D Secure version 1 historically has introduced more friction than necessary. As more and more transactions are app based and we see rapid development of new ways to make payments there was a need for an updated version of 3-D Secure that could deal with this, which is 3-D Secure version 2.

What will change

One of the core differences is that the issuer can use a lot of data-points from the transaction to determine the risk of the transaction (risk-based analysis). For low-risk transactions, issuers will not challenge the transaction (e.g. not sending an SMS to the cardholder) although authenticating the transaction (frictionless). Inversely, for high risk transaction, issuers will require the cardholder to authenticate with an SMS or biometric means (challenge). This can then result in a frictionless authentication, which doesn't involve the consumer to be redirected. In case the consumer is using an app this also applies. In case a challenge is required by the issuer this can be handled inside the app. This greatly improves the user experience and will increase conversion.

Separately the Strong Customer Authentication (SCA) required in Europe by September 14th, 2019 as specified in PSD2 will result in a substantial increase in the number of transactions requiring the use of 3-D Secure authentication. The use of 3-D Secure version 2 should limit the potential negative impact on conversion as much as possible.

In short 3-D Secure version 2 means:

  • You will need to implement 3-D Secure before September 14th, 2019 if your transactions fall within the EU PSD2 SCA guidelines (in case you don't already support 3-D Secure).
  • You are advised (and for some are required) to submit additional data points to support the risk assessment performed by the issuer in case of 3-D Secure version 2
  • You might need to update your privacy policy with regards to GDPR as you might be sharing additional data-points with 3rd parties
  • A much better user experience for your consumers

Benefits

The expectation in the market is that a substantial percentage of transactions using 3-D Secure version 2 will follow the frictionless flow, which doesn't require anything additional from the consumer compared to current non-3-D Secure checkout flows. This means that you benefit from the increased security and liability shift that is provided by the 3-D Secure programs, while the conversion in your checkout process shouldn't be negatively impacted.

According to card networks projections, with 3-D Secure version 2, merchants will be able to achieve the same performance levels as physical store merchants (using Chip & PIN):

  • Up to 10 percentage points higher approval rates
  • Up to 50% reduced fraud rates
  • Around 50% lower abandonment rates.

Timeline

3Dv2 Timeline

A couple of dates are important:

  1. April 2019: Mastercard issuers globally and Visa issuers from Europe can support 3-D Secure version 2 in their production environments, so you might be impacted as well as you can only benefit if you provide the right data points.
  2. August 2019: Visa issuers In North and South America can support 3-D Secure version 2.
  3. September 14th, 2019: PSD2 SCA goes into effect in the European markets requiring Strong Customer Authentication for each online transaction that match the criteria as set forth in the PSD2 SCA guidelines.
  4. April 2020: Issuers from the rest of the world can support 3-D Secure version 2.

For each of the above activations the following applies: If the issuer supports 3-D Secure version 2 for the card, you should use 3-D Secure version 2. If you do not support 3-D Secure version 2, falling back to 3-D Secure version 1 remains a possibility without any impact on the liability shift.

Technical implementation

We have done our best to limit the impact of 3-D Secure version 2 for you. This means that we have kept the existing 3-D Secure flow and statuses the same. The impact has been reduced to API changes that introduce the additional new properties that you can (and in some cases should) provide to increase the likelihood of your transactions being authenticated using the frictionless flow.

Flow

Below flow shows the high-level flow of both version 1 and version 2 of 3-D Secure. Please note that we show the browser flow specifically for 3-D Secure version 2 as version 1 doesn't support different flows besides the browser flow. The functional flow between the two versions is the same from your point of view. After the initial payment creation two flows are possible:

  • One flow requiring the redirection of the consumer
  • One flow not requiring the redirection of the consumer

3Dv2 flow v1.1

The flow with the redirection for 3-D Secure version 2 could potentially only involve a page that allows the issuer to collect data from the consumers device without any user interaction. This is called a MethodURL flow in the 3-D Secure version 2 documentation. We have chosen to handle this flow on our hosted payment pages to reduce the implementation impact on you. This means that redirection will not always result in a so called Challenge towards the consumer and could still be considered friction-less in the 3-D Secure version 2 terminology. The statuses for each of the flows are identical with REDIRECTED for the flow that involves redirection and all the other possible statuses, like REJECTED, PENDING_APPROVAL, CAPTURE_REQUESTED, etc. for the non-redirect flow. Please see below image showing the 3-D Secure specific status flow for the most common implementation (not using the 2-step 3-D setup that requires explicit approval from your side to continue with the authorization).

Payment Flow Credit Cards 3Dv2

Additional data elements

The key aspect of 3-D Secure version 2 is the ability of the issuing bank to better assess the risk involved of the transaction. The specification 3-D Secure version 2 contains a lot of data elements, some of them were already commonly used in fraud screening, but some are new and specific to 3-D Secure. In general the data elements can be categorized in the following categories:

  • Card details
  • 3-D Secure specific information
    • Previous 3-D Secure results
    • Specific 'settings' for this transaction
  • Transaction information
    • Billing address data
    • Shipping details
    • Meta information on what the transaction is for
  • Consumer
    • Device/browser data
    • Account of the consumer with you
      • Authentication used
      • Account on file
      • Payment history

Our existing APIs already capture a lot of the data elements, but we are adding a lot of new data elements. The reason is that we believe that everybody in the payments ecosystem benefits from increased security, with the least amount of negative impact to the experience of the consumer. Payments are based on trust and by providing more data it becomes easier for parties to trust one-another, without requiring additional challenges to authenticate the consumer. Almost all of the newly added data elements are optional, but we advise you to supply as much of them as possible. This increases the likelihood of your transactions following the frictionless flow, while you benefit from liability shift. In case you use the MyCheckout hosted payment pages we will capture the Device/browser related data automatically.

MyCheckout Hosted Payment Pages

When you use the MyCheckout hosted payment pages we will capture some of the required data-points regarding the device and browser used by the consumer on your behalf to reduce the implementation burden on your side. To keep our API logical and easy to understand we decided to change some of the existing object definitions. Our system will accept both the old definition and new definition, but you are advised not to mix old and new definitions in one API call, because our system will reject it if you try to submit multiple definitions of the same field.

It is important to note that even-tough we have added new properties and restructured the API your current implementation will keep working. In case you use the MyCheckout hosted payment pages all of the additional new properties are optional, but you are advised to supply as many of them to ensure the highest possible number of transactions follow the frictionless flow.

As the cardHolderName is a required property we will also automatically capture that property in case 3-D Secure version 2 has been enabled on your account.

Create Hosted Checkout API

The API that is used to initialize a hostedCheckout session has been updated. Please find below an overview of all the new properties that have been added as well as the changes to the object definitions. There are less new properties in this API vs the Create Payment API as we will capture all the device and browser related data ourselves. Next to this we also determine the size of the challenge area, based on the size of the window/iframe that the MyCheckout hosted payment pages are displayed in. In case you use an iframe to show the MyCheckout hosted payment pages note that the size of the iframe has a minimum width of 250 pixels and a minimum height of 400 pixels.

Minimal Frame size for Challenge

The below overview shows all properties in the input that are used in the 3-D Secure version 2 authentication. In the description it is mentioned if the property is required and under which conditions. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
fraudFields Existing property Object Object containing additional data that will be used to assess the risk of fraud
  addressesAreIdentical Deprecated property Boolean
  • true - the billing and shipping addresses are identical
  • false - the billing and shipping addresses are different

Deprecated - please use order.shipping.addressIndicator to indicate that the billing and shipping address are identical.

order Existing property Object Order object containing order related data
  additionalInput Existing property Object Object containing additional input on the order
    typeInformation Existing property Object Object containing specific classifications of the transaction
      transactionType New property Enum (string)

Required for merchants from Brazil if order.amountOfMoney.amount is not 0

Identifies the type of transaction being authenticated.

  • purchase = The purpose of the transaction is to purchase goods or services
  • check-acceptance = The purpose of the transaction is to accept a 'check'/'cheque'
  • account-funding = The purpose of the transaction is to fund an account
  • quasi-cash = The purpose of the transaction is to buy a quasi cash type product that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets or casino gaming chips.
  • prepaid-activation-or-load = The purpose of the transaction is to activate or load a prepaid card
  customer New property Object Object containing data related to the consumer
    account New property Object Object containing data related to the account the consumer has with you
      createDate New property AN8

The date (YYYYMMDD) on which the consumer created their account with you

We will calculate the CustomerAccountAgeIndicator using this property and the order.customer.accountType.

      changeDate New property AN8

The last date (YYYYMMDD) on which the consumer made changes to their account with you. These are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the changes are used.

      changedDuringCheckout New property Boolean
  • true = the consumer made changes to their account during this checkout
  • false = the consumer didn't change anything to their account during this checkout

The changes meant here are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changeDate to determine the 'age' of the changes. For 3-D Secure version 2 only the resulting 'age' of the changes is used.

      passwordChangeDate New property AN8

The last date (YYYYMMDD) on which the consumer changed their password for the account used in this transaction

We will use the data from this property and the order.customer.account.passwordChangedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the password change are used.

      passwordChangedDuringCheckout New property Boolean Property that indicates if the password of an account is changed during this checkout
  • true = the consumer made changes to their password of the account used during this checkout
  • false = the consumer didn't change anything to their password of the account used during this checkout

We will use the data from this property and the order.customer.account.passwordChangeDate to determine the 'age' of the password change. For 3-D Secure version 2 only the resulting 'age' of the password change is used.

      hasForgottenPassword Moved property Boolean

Specifies if the consumer (initially) had forgotten their password

  • true - The consumer has forgotten their password
  • false - The consumer has not forgotten their password

Moved (and renamed) existing property order.fraudFields.hasForgottenPwd to the order.customer.account object

This property is not used for 3-D Secure version 2.

      hadSuspiciousActivity New property Boolean

Specifies if you have experienced suspicious activity on the account of the consumer

  • true = you have experienced suspicious activity (including previous fraud) on the consumer account used for this transaction
  • false = you have experienced no suspicious activity (including previous fraud) on the consumer account used for this transaction
      authentication New property Object Object containing data on the authentication used by the consumer to access their account
        utcTimestamp New property AN12 Timestamp (YYYYMMDDHHmm) of the authentication of the consumer to their account with you
        method New property Enum (String)

Authentication used by the consumer on your website

  • guest = no login occurred, consumer is 'logged in' as guest
  • merchant-credentials = the consumer logged in using credentials that are specific to you
  • federated-id = the consumer logged in using a federated ID
  • issuer-credentials = the consumer logged in using credentials from the card issuer (of the card used in this transaction)
  • third-party-authentication = the consumer logged in using third-party authentication
  • fido-authentication = the consumer logged in using a FIDO authenticator
      paymentActivity New property Object Object containing data on the purchase history of the consumer with you
        numberOfPurchasesLast6Months New property N4 Number of successful purchases made by this consumer with you in the last 6 months
        numberOfPaymentAttemptsLast24Hours New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 24 hours
        numberOfPaymentAttemptsLastYear New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 12 months
      paymentAccountOnFileType New property Enum (String)

Required for merchants in Brazil

Indicates the type of account. For example, for a multi-account card product.

  • not-applicable = the card used doesn't support multiple card products
  • credit = the card used is a credit card
  • debit = the card used is a debit card
      paymentAccountOnFile New property Object Object containing information on the payment account data on file (tokens)
        numberOfCardOnFileCreationAttemptsLast24Hours New property N3 Number of attempts made to add new card to the consumer account in the last 24 hours
        createDate New property AN8

The date (YYYYMMDD) when the payment account on file was first created.

In case a token is used for the transaction we will use the creation date of the token in our system in case you leave this property empty.

    accountType New property Enum (String) Type of the customer account that is used to place this order. Can have one of the following values:
  • none = None (guest)
  • created = Account was created during this transaction
  • existing = Existing account was used for this transaction

We will try to automatically determine the value for this field:

  • in case cardPaymentMethodSpecificInput.tokenize is set to true or the consumer checks the Remember my details box, we will set the value of this property to created (even though there might be an existing token matching the card details)
  • in case a token is used for this transaction the value will be set to existing
  • in case cardPaymentMethodSpecificInput.tokenize is set to false and no token is used for this transaction we will default to none
    billingAddress Existing property Object Object containing the billing address details
      additionalInfo Existing property AN50 Additional address information
      city Existing property AN40 City
      countryCode Existing property AN2 ISI 3166-1 alpha-2 country code
      houseNumber Existing property AN15 House number
      stateCode Existing property AN9 State code
      street Existing property AN50 Streetname
      zip Existing property AN10 Zip code
    companyInformation Existing property Object Object containing information of the company in case the consumer is a company
      vatNumber Moved property AN17

Local VAT number of the 'consumer'

Moved from order.customer

This property is not used for 3-D Secure version 2.

    contactDetails   Object Object containing contact details of the consumer
      emailAddress Existing property AN70 Email address of the consumer
      mobilePhoneNumber New property AN20

International version of the mobile phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      phoneNumber Existing property AN20

International version of the home phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      workPhoneNumber New property AN20

International version of the work phone number of the consumer including the leading + (i.e. +31235671500)

Official max length is N15 making it AN16 to include the leading + sign

  shipping New property Object Object containing information regarding shipping / delivery
    type New property Enum (String) Indicates the merchandise delivery timeframe
  • electronic = electronic delivery (services or digital goods)
  • same-day = same day delivery
  • overnight = overnight delivery
  • 2-day-or-more = two day or more deliveries
    firstUsageDate New property AN8

Date (YYYYMMDD) when the shipping details for this transaction where first used

We will use the data from this property and the order.shipping.isFirstUsage to determine the 'age' of the shipping details. For 3-D Secure version 2 this property and the 'age' of the shipping details change are used.

    isFirstUsage New property Boolean Indicator if this shipping address is used for the first time to ship an order
  • true = the shipping details are used for the first time with this transaction
  • false = the shipping details have been used for other transactions in the past

We will use the data from this property and the order.shipping.firstUsageDate to determine the 'age' of the shipping details. For 3-D Secure version 2 only the resulting 'age' of the shipping details is used.

    addressIndicator New property Enum (String) Indicates shipping method chosen for the transaction.
  • same-as-billing = the shipping address and the billing address are identical
  • another-verified-address-on-file-with-merchant = another verified address of the consumer that is on file with you
  • different-than-billing = shipping address is different from the billing address
  • ship-to-store = goods are shipped to a store (shipping address = store address)
  • digital-goods = electronic delivery of digital goods
  • travel-and-event-tickets-not-shipped = travel and/or event tickets that are not shipped
  • other = other means of delivery
    emailAddress New property AN70 Email address linked to the shipping
    address New property Object Object containing address information
      additionalInfo Moved property AN50

Additional address information

Moved from order.customer.shippingaddress

      city Moved property AN40

City

Moved from order.customer.shippingaddress

      countryCode Moved property AN2

ISO 3166-1 alpha-2 country code

Moved from order.customer.shippingaddress

      houseNumber Moved property AN15

House number

Moved from order.customer.shippingaddress

      name Moved property Object

Object containing the name elements

Moved from order.customer.shippingaddress.name

        firstName Moved property AN15

Given name(s) or first name(s) of the consumer

Moved from order.customer.shippingaddress.name.firstName

This property is not used for 3-D Secure version 2.

        surname Moved property AN70

Surname(s) or last name(s) of the consumer

Moved from order.customer.shippingaddress.name.surname

This property is not used for 3-D Secure version 2.

        surnamePrefix Moved property AN15

Middle name - In between first name and surname - of the consumer

Moved from order.customer.shippingaddress.name.surnamePrefix

This property is not used for 3-D Secure version 2.

        title Moved property AN35

Title of consumer

Moved from order.customer.shippingaddress.name.title

This property is not used for 3-D Secure version 2.

      state Moved property AN35

State to which the shipment is being send

 

Moved from order.customer.shippingaddress.state

This property is not used for 3-D Secure version 2.

      stateCode Moved property AN9

State code

Moved from order.customer.shippingaddress.stateCode

      street Moved property AN50

Street name

Moved from order.customer.shippingaddress.street

      zip Moved property AN17

Zip code

Moved from order.customer.shippingaddress.zip

    trackingNumber Moved property AN19

Shipment tracking number

Moved from fraudFields and renamed (old name = shipmentTrackingNumber)

This property is not used for 3-D Secure version 2.

    comments Moved property AN160

Comments included during shipping

Moved from fraudFields and renamed (old name = shipComments)

This property is not used for 3-D Secure version 2.

  shoppingCart Existing property Object Object containing information on the item(s) in the shopping cart
    isPreOrder New property Boolean

The consumer is pre-ordering one or more items

    preOrderItemAvailabilityDate New property AN8 Date (YYYYMMDD) when the preordered item becomes available
    giftCardPurchase New property Object Object containing information on purchased gift card(s)
      amountOfMoney New property Object Object containing information on an amount of money
        amount New property N12 Amount in cents and always having 2 decimals
        currencyCode New property AN3 Three-letter ISO currency code representing the currency for the amount
      numberOfGiftCards New property N2 Number of gift cards that are purchased through this transaction
    reOrderIndicator New property Boolean Indicates whether the cardholder is reordering previously purchased item(s)
  • true = the consumer is re-ordering at least one of the items again
  • false = this is the first time the consumer is ordering these items
cardPaymentMethodSpecificInput Existing property Object Object containing data regarding card payments
  threeDSecure New property Object Object containing specific 3-D Secure data
    priorThreeDSecureData New property Object

Object containing data regarding the consumer authentication that occurred prior to the current transaction

      method New property

enum (string)

Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction
      utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the prior 3-D Secure authentication

      acsTransactionId New property AN36

The ACS Transaction ID for a prior 3-D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the consumer).

    challengeIndicator New property Enum (String)

Allows you to indicate if you want the consumer to be challenged for extra security on this transaction.

  • no-preference = You have no preference whether or not to challenge the consumer (default)
  • no-challenge-requested = you prefer the cardholder not to be challenged
  • challenge-requested = you prefer the consumer to be challenged
  • challenge-required = you require the consumer to be challenged
    skipAuthentication Moved property Boolean
  • true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
  • false = 3D Secure authentication will not be skipped for this transaction.

Note: This is only possible if your account in our system is setup for 3D Secure authentication and if your configuration in our system allows you to override it per transaction.

Note: Any configured Dynamic 3D rules will be ignored when you submit this property.

Moved from cardPaymentMethodSpecificInput

  isRecurring Existing property Boolean Indicates if this transaction is of a one-off or a recurring type
  • true - This is recurring
  • false - This is one-off

This is used with property recurringPaymentSequenceIndicator to determine if the transaction is a first of recurring

  recurring New property Object Object containing data related to recurring
    endDate New property AN8

Date (YYYYMMDD) in the future after which no further authorisations shall be performed.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    minFrequency New property AN3

This indicates the number of days between the recurring authorizations. Can be set to "1" to indicate that the frequency is variable.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    recurringPaymentSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of recurring transactions
  • recurring = This transaction is a subsequent transaction in a series of recurring transactions

Note: For any first of a recurring the system will automatically create a token as you will need to use a token for any subsequent recurring transactions. In case a token already exists this is indicated in the response with a value of False for the isNewToken property in the response.

Note: This property is required when isRecurring is set to true.

3-D Secure will not be used when this property is set to recurring

Moved from cardPaymentMethodSpecificInput.recurringPaymentSequenceIndicator

  unscheduledCardOnFileRequestor Existing property

Enum

(string)

Indicates which party initiated the unscheduled recurring transaction. Allowed values:

  • merchantInitiated - Merchant Initiated Transaction.
  • cardholderInitiated - Cardholder Initiated Transaction.

Note: this property is not allowed if isRecurring is true.

Required if unscheduledCardOnFileIndicator is 'subsequent'. Otherwise it must not be 'merchantInitiated'.

3-D Secure will not be used when this property is set to cardholderInitiated

  unscheduledCardOnFileSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of unscheduled recurring transactions
  • subsequent = This transaction is a subsequent transaction in a series of unscheduled recurring transactions


Note: this property is not allowed if isRecurring is true.

Renamed from unscheduledCardOnFileIndicator

Additional response properties related to 3-D Secure version 2

There are no additional response properties to the Create hostedCheckout call for 3-D Secure version 2.

API

To keep our API logical and easy to understand we decided to change some of the existing object definitions. Our system will accept both the old definition and the new definition as long as you don't mix old and new definitions in one API call. This means that your current implementation will keep working, but will most likely not support all the properties required to ensure the maximum number of consumers that will use the frictionless flow. Our new SDKs will only support the new object definitions and will require some development work on your side to adopt.

Create Payment API

Request properties for 3-D Secure version 2

The below overview shows all properties in the input that are used in the 3-D Secure version 2 authentication. In the description it is mentioned if the property is required and under which conditions. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
fraudFields Existing property Object Object containing additional data that will be used to assess the risk of fraud
  addressesAreIdentical Deprecated property Boolean
  • true - the billing and shipping addresses are identical
  • false - the billing and shipping addresses are different

Deprecated - please use order.shipping.addressIndicator to indicate that the billing and shipping address are identical.

merchant New property Object Object containing information on you, the merchant
  websiteUrl Moved property AN60

The website from which the purchase was made

Moved from fraudFields.website and renamed to make it more clear we expect an URL.

This property is not used for 3-D Secure version 2.

  contactWebsiteUrl New property AN2048 URL to find contact or support details to contact in case of questions
order Existing property Object Order object containing order related data
  additionalInput Existing property Object Object containing additional input on the order
    typeInformation Existing property Object Object containing specific classifications of the transaction
      transactionType New property Enum (string)

Required for merchants from Brazil in case order.amountOfMoney.amount is not 0

Identifies the type of transaction being authenticated.

  • purchase = The purpose of the transaction is to purchase goods or services
  • check-acceptance = The purpose of the transaction is to accept a 'check'/'cheque'
  • account-funding = The purpose of the transaction is to fund an account
  • quasi-cash = The purpose of the transaction is buy a quasi cash type product that is representative of actual cash such as money orders, traveler's checks, foreign currency, lottery tickets or casino gaming chips.
  • prepaid-activation-or-load = The purpose of the transaction is to activate or load a prepaid card
  customer New property Object Object containing data related to the consumer
    account New property Object Object containing data related to the account the consumer has with you
      createDate New property AN8

The date (YYYYMMDD) on which the consumer created their account with you

We will calculate the CustomerAccountAgeIndicator using this property and the order.customer.accountType.

      changeDate New property AN8

The last date (YYYYMMDD) on which the consumer made changes to their account with you. These are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the changes are used.

      changedDuringCheckout New property Boolean
  • true = the consumer made changes to their account during this checkout
  • false = the consumer didn't change anything to their account during this checkout

The changes meant here are changes to billing & shipping address details, new payment account (tokens), or new users(s) added.

We will use the data from this property and the order.customer.account.changeDate to determine the 'age' of the changes. For 3-D Secure version 2 only the resulting 'age' of the changes is used.

      passwordChangeDate New property AN8

The last date (YYYYMMDD) on which the consumer changed their password for the account used in this transaction

We will use the data from this property and the order.customer.account.passwordChangedDuringCheckout to determine the 'age' of the changes. For 3-D Secure version 2 this property and the 'age' of the password change are used.

      passwordChangedDuringCheckout New property Boolean Property that indicates if the password of an account is changed during this checkout
  • true = the consumer made changes to their password of the account used during this checkout
  • false = the consumer didn't change anything to their password of the account used during this checkout

We will use the data from this property and the order.customer.account.passwordChangeDate to determine the 'age' of the password change. For 3-D Secure version 2 only the resulting 'age' of the password change is used.

      hasForgottenPassword Moved property Boolean

Specifies if the consumer (initially) had forgotten their password

  • true - The consumer has forgotten their password
  • false - The consumer has not forgotten their password

Moved (and renamed) existing property order.fraudFields.hasForgottenPwd to the order.customer.account object

This property is not used for 3-D Secure version 2.

      hadSuspiciousActivity New property Boolean

Specifies if you have experienced suspicious activity on the account of the consumer

  • true = you have experienced suspicious activity (including previous fraud) on the consumer account used for this transaction
  • false = you have experienced no suspicious activity (including previous fraud) on the consumer account used for this transaction
      authentication New property Object Object containing data on the authentication used by the consumer to access their account
        utcTimestamp New property AN12 Timestamp (YYYYMMDDHHmm) of the authentication of the consumer to their account with you
        method New property Enum (String)

Authentication used by the consumer on your website

  • guest = no login occurred, consumer is 'logged in' as guest
  • merchant-credentials = the consumer logged in using credentials that are specific to you
  • federated-id = the consumer logged in using a federated ID
  • issuer-credentials = the consumer logged in using credentials from the card issuer (of the card used in this transaction)
  • third-party-authentication = the consumer logged in using third-party authentication
  • fido-authentication = the consumer logged in using a FIDO authenticator
  • fido-authentication-signed-assurance = the consumer logged in using a FIDO authenticator and you have signed FIDO assurance data
  • src-assurance-data = SRC Assurance Data
      paymentActivity New property Object Object containing data on the purchase history of the consumer with you
        numberOfPurchasesLast6Months New property N4 Number of successful purchases made by this consumer with you in the last 6 months
        numberOfPaymentAttemptsLast24Hours New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 24 hours
        numberOfPaymentAttemptsLastYear New property N3 Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 12 months
      paymentAccountOnFileType New property Enum (String)

Required for merchants in Brazil

Indicates the type of account. For example, for a multi-account card product.

  • not-applicable = the card used doesn't support multiple card products
  • credit = the card used is a credit card
  • debit = the card used is a debit card
      paymentAccountOnFile New property Object Object containing information on the payment account data on file (tokens)
        numberOfCardOnFileCreationAttemptsLast24Hours New property N3 Number of attempts made to add new card to the consumer account in the last 24 hours
        createDate New property AN8

The date (YYYYMMDD) when the payment account on file was first created.

In case a token is used for the transaction we will use the creation date of the token in our system in case you leave this property empty.

    accountType New property Enum (String) Type of the customer account that is used to place this order. Can have one of the following values:
  • none = None (guest)
  • created = Account was created during this transaction
  • existing = Existing account was used for this transaction

We will try to automatically determine the value for this field:

  • in case cardPaymentMethodSpecificInput.tokenize is set to true we will set the value of this property to created (even though there might be an existing token matching the card details)
  • in case a token is used for this transaction the value will be set to existing
  • in case cardPaymentMethodSpecificInput.tokenize is set to false and no token is used for this transaction we will default to none
    companyInformation Existing property Object Object containing information of the company in case the consumer is a company
      vatNumber Moved property AN17

Local VAT number of the 'consumer'

Moved from order.customer

This property is not used for 3-D Secure version 2.

    billingAddress Existing property Object Object containing the billing address details
      additionalInfo Existing property AN50 Additional address information
      city Existing property AN40 City
      countryCode Existing property AN2 ISI 3166-1 alpha-2 country code
      houseNumber Existing property AN15 House number
      stateCode Existing property AN9 State code
      street Existing property AN50 Streetname
      zip Existing property AN10 Zip code
    device New property Object Object containing information on the device and browser of the consumer
      acceptHeader New property AN2048

Required for 3-D Secure version 2 for the authenticationFlow "browser"

The accept-header of the consumer client from the HTTP Headers.

      ipAddress Moved property AN45

The IP address of the consumer client from the HTTP Headers.

Moved from fraudFields, increased in size (to also accommodate IPv6 addresses) and renamed (previously fraudFields.customerIpAddress)

      deviceFingerprintTransactionId Moved property AN50

One must use the deviceFingerprintTransactionId received by the response of the endpoint /{merchant}/products/{paymentProductId}/deviceFingerprint which was also used by the JavaScript code

Moved from fraudFields.deviceFingerprintTransactionId

This property is not used for 3-D Secure version 2, although in the future we might use this service to populate the device and browser related properties.

      defaultFormFill Moved property Enum (String)

Degree of default form fill, with the following possible values:

  • automatically - All form fields filled automatically
  • automatically-but-modified - All form fields filled automatically, but some form fields were modified manually
  • manually - All form fields were entered manually

Moved from fraudFields.defaultFormFill

This property is not used for 3-D Secure version 2.

      timezoneOffsetUtcMinutes New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Offset in minutes of timezone of the client vs the UTC. Value is returned by the JavaScript getTimezoneOffset() Method.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

      locale New property AN8

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Locale of the client device/browser. Returned in the browser from the navigator.language property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

      userAgent New property AN2048

Required for 3-D Secure version 2 for the authenticationFlow "browser"

User-Agent of the client device/browser from the HTTP Headers.

As a fall-back we will use the userAgent that might be included in the encryptedCustomerInput, but this is captured client side using JavaScript and might be different.

      browserData New property Object

Object containing information regarding the browser of the consumer

        javaEnabled New property Boolean

Required for 3-D Secure version 2 for the authenticationFlow "browser"

  • true = Java is enabled in the browser
  • false = Java is not enabled in the browser (default if left empty)

Value is returned from the navigator.javaEnabled property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        javaScriptEnabled New property Boolean

Required for 3-D Secure version 2 for the authenticationFlow "browser"

  • true = JavaScript is enabled in the browser
  • false = JavaScript is not enabled in the browser (default if left empty)

Note: Required in future 3-D Secure version 2.2

        colorDepth New property N2

Required for 3-D Secure version 2 for the authenticationFlow "browser"

ColorDepth in bits. Value is returned from the screen.colorDepth property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        screenHeight New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Height of the screen in pixels. Value is returned from the screen.height property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        screenWidth New property AN6

Required for 3-D Secure version 2 for the authenticationFlow "browser"

Width of the screen in pixels. Value is returned from the screen.width property.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser. This means that 3-D Secure version 2.1 requires the use of JavaScript to be enabled. In the upcoming version 2.2 of the specification this is no longer a requirement. As we currently support version 2.1 it means that this property is required when cardPaymentMethodSpecifInput.threeDSecure.authenticationFlow is set to "browser".

        innerHeight New property AN6

The innerHeight of the frame in case you are capturing your payments in a frame. We will use this to validate if the height provided in the cardPaymentMethodSpecifInput.threeDSecure.challengeCanvasSize will actually fit in the iFrame you use.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser.

        innerWidth New property AN6

The innerWidth of the frame in case you are capturing your payments in a frame. We will use this to validate if the width provided in the cardPaymentMethodSpecifInput.threeDSecure.challengeCanvasSize will actually fit in the iFrame you use.

If you use the latest version of our JavaScript Client SDK, we will collect this data and include it in the encryptedCustomerInput property. We will then automatically populate this data if available.

Note: This data can only be collected if JavaScript is enabled in the browser.

    contactDetails Existing property Object Object containing contact details of the consumer
      mobilePhoneNumber New property AN20

International version of the mobile phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      phoneNumber Existing property AN20

International version of the home phone number of the consumer including the leading + (i.e. +16127779311)

Official max length is N15 making it AN16 to include the leading + sign

      workPhoneNumber New property AN20

International version of the work phone number of the consumer including the leading + (i.e. +31235671500)

Official max length is N15 making it AN16 to include the leading + sign

  shipping New property Object Object containing information regarding shipping / delivery
    type New property Enum (String) Indicates the merchandise delivery timeframe
  • electronic = electronic delivery (services or digital goods)
  • same-day = same day delivery
  • overnight = overnight delivery
  • 2-day-or-more = two day or more deliveries
    firstUsageDate New property AN8

Date (YYYYMMDD) when the shipping details for this transaction where first used

We will use the data from this property and the order.shipping.isFirstUsage to determine the 'age' of the shipping details. For 3-D Secure version 2 this property and the 'age' of the shipping details change are used.

    isFirstUsage New property Boolean Indicator if this shipping address is used for the first time to ship an order
  • true = the shipping details are used for the first time with this transaction
  • false = the shipping details have been used for other transactions in the past

We will use the data from this property and the order.shipping.firstUsageDate to determine the 'age' of the shipping details. For 3-D Secure version 2 only the resulting 'age' of the shipping details is used.

    addressIndicator New property Enum (String) Indicates shipping method chosen for the transaction.
  • same-as-billing = the shipping address and the billing address are identical
  • another-verified-address-on-file-with-merchant = another verified address of the consumer that is on file with you
  • different-than-billing = shipping address is different from the billing address
  • ship-to-store = goods are shipped to a store (shipping address = store address)
  • digital-goods = electronic delivery of digital goods
  • travel-and-event-tickets-not-shipped = travel and/or event tickets that are not shipped
  • other = other means of delivery
    emailAddress New property AN70 Email address linked to the shipping
    address New property Object Object containing address information
      additionalInfo Moved property AN50

Additional address information

Moved from order.customer.shippingaddress

      city Moved property AN40

City

Moved from order.customer.shippingaddress

      countryCode Moved property AN2

ISO 3166-1 alpha-2 country code

Moved from order.customer.shippingaddress

      houseNumber Moved property AN15

House number

Moved from order.customer.shippingaddress

      name Moved property Object

Object containing the name elements

Moved from order.customer.shippingaddress.name

        firstName Moved property AN15

Given name(s) or first name(s) of the consumer

Moved from order.customer.shippingaddress.name.firstName

This property is not used for 3-D Secure version 2.

        surname Moved property AN70

Surname(s) or last name(s) of the consumer

Moved from order.customer.shippingaddress.name.surname

This property is not used for 3-D Secure version 2.

        surnamePrefix Moved property AN15

Middle name - In between first name and surname - of the consumer

Moved from order.customer.shippingaddress.name.surnamePrefix

This property is not used for 3-D Secure version 2.

        title Moved property AN35

Title of consumer

Moved from order.customer.shippingaddress.name.title

This property is not used for 3-D Secure version 2.

      state Moved property AN35

State of the consumer 

Moved from order.customer.shippingaddress.state

This property is not used for 3-D Secure version 2.

      stateCode Moved property AN9

State code

Moved from order.customer.shippingaddress.stateCode

      street Moved property AN50

Street name

Moved from order.customer.shippingaddress.street

      zip Moved property AN17

Zip code

Moved from order.customer.shippingaddress.zip

    trackingNumber Moved property AN19

Shipment tracking number

Moved from fraudFields and renamed (old name = shipmentTrackingNumber) to bundle all the shipping related properties together.

This property is not used for 3-D Secure version 2.

    comments Moved property AN160

Comments included during shipping

Moved from fraudFields and renamed (old name = shipComments) to bundle all the shipping related properties together.

This property is not used for 3-D Secure version 2.

  shoppingCart Existing property Object Object containing information on the item(s) in the shopping cart
    isPreOrder New property Boolean

The consumer is pre-ordering one or more items

    preOrderItemAvailabilityDate New property AN8 Date (YYYYMMDD) when the preordered item becomes available
    giftCardPurchase New property Object Object containing information on purchased gift card(s)
      amountOfMoney New property Object Object containing information on an amount of money
        amount New property N12 Amount in cents and always having 2 decimals
        currencyCode New property AN3 Three-letter ISO currency code representing the currency for the amount
      numberOfGiftCards New property N2 Number of gift cards that are purchased through this transaction
    reOrderIndicator New property Boolean Indicates whether the cardholder is reordering previously purchased item(s)
  • true = the consumer is re-ordering at least one of the items again
  • false = this is the first time the consumer is ordering these items
cardPaymentMethodSpecificInput Existing property Object Object containing data regarding card payments
  card Existing property Object Object containing card data
    cardNumber Existing property AN19

The complete credit/debit card number (also know as the PAN)

The card number is always obfuscated in any of our responses

Required, except when a token or encryptedCustomerInput that includes this data is provided.
    cardholderName Existing property AN51

Card holder's name on the card

Required for 3-D Secure version 2, except when a token or encryptedCustomerInput that includes this data is provided.

This property was optional for payments on the GlobalCollect platform, but will be required for transactions that utilize 3-D Secure version 2.

    expiryDate Existing property AN4

Expiry date of the card
Format: MMYY

Required, except when a token or encryptedCustomerInput that includes this data is provided.

  isRecurring Existing property Boolean Indicates if this transaction is of a one-off or a recurring type
  • true - This is recurring
  • false - This is one-off

This is used with property recurringPaymentSequenceIndicator to determine if the transaction is a first of recurring

  recurring New property Object Object containing data related to recurring
    endDate New property AN8

Date (YYYYMMDD) in the future after which no further authorisations shall be performed.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    minFrequency New property AN3

This indicates the number of days between the recurring authorizations. Can be set to "1" to indicate that the frequency is variable.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicator is set to first and 3-D Secure version 2 is enabled for the merchant.

    recurringPaymentSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of recurring transactions
  • recurring = This transaction is a subsequent transaction in a series of recurring transactions

Note: For any first of a recurring the system will automatically create a token as you will need to use a token for any subsequent recurring transactions. In case a token already exists this is indicated in the response with a value of False for the isNewToken property in the response.

Note: This property is required when isRecurring is set to true.

3-D Secure will not be used when this property is set to recurring

Moved from cardPaymentMethodSpecificInput.recurringPaymentSequenceIndicator

  threeDSecure New property Object Object containing specific data regarding 3-D Secure
    authenticationFlow New property

Enum

(String)

Indicates whether a transaction is performed in-app using an EMVco certified mobile SDK or inside a browser.

  • browser = Consumer is using a browser to complete the checkout (default)
  • in-app = Consumer is using an app with a 3-D Secure SDK to complete the checkout

Note: We will add support for the in-app flow in a future release.

    challengeCanvasSize New property Enum (String)

Required for 3-D Secure version 2 for the browser flow.

Dimensions of the challenge window that potentially will be displayed to the consumer. The challenge content is formatted to appropriately render in this window to provide the best possible user experience.

Preconfigured sizes are width x height in pixels of the window displayed in the consumer browser window. Possible values are:

  • 250x400 (default)
  • 390x400
  • 500x600
  • 600x400
  • full-screen
    challengeIndicator New property Enum (String)

Allows you to indicate if you want the consumer to be challenged for extra security on this transaction.

  • no-preference = You have no preference whether or not to challenge the consumer (default)
  • no-challenge-requested = you prefer the cardholder not to be challenged
  • challenge-requested = you prefer the consumer to be challenged
  • challenge-required = you require the consumer to be challenged
    externalCardholderAuthenticationData Moved property Object

Object containing results of an external authentication (not performed by Ingenico)

Moved from cardPaymentMethodSpecificInput

      cavv Moved property AN50

The CAVV (cardholder authentication verification value) or AAV (accountholder authentication value) provides an authentication validation value.


This is mandatory for ECI 1, 2, 5 and 6.

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      cavvAlgoritm Moved property AN1

The algorithm, from your 3D Secure provider, used to generate the authentication CAVV.


Required when
  • The 3D Secure authentication for the transaction is managed by a non-Ingenico ePayments 3D Secure authentication provider
  • You process the transaction through Atos

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      eci Moved property N2 Electronic Commerce Indicator provides authentication validation results returned after AUTHENTICATIONVALIDATION
  • 0 = No authentication, Internet (no liability shift, not a 3D Secure transaction)
  • 1 = Authentication attempted (MasterCard)
  • 2 = Successful authentication (MasterCard)
  • 5 = Successful authentication (Visa, Diners Club, Amex)
  • 6 = Authentication attempted (Visa, Diners Club, Amex)
  • 7 = No authentication, Internet (no liability shift, not a 3D Secure transaction)
  • (empty) = Not checked or not enrolled

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      threeDSecureVersion New property enum (string) The 3-D Secure version used for the authentication. Possible values:
  • v1
  • v2
      directoryServerTransactionId New property AN50 The 3-D Secure Directory Server transaction ID that is used for the 3-D Secure version 2 Authentication
      threeDServerTransactionId New property AN50 The 3-D Secure Server transaction ID that is used for the 3-D Secure version 2 Authentication
      validationResult Moved property AN1

The 3D Secure authentication result from your 3D Secure provider.

Required when
  • The 3D Secure authentication for the transaction is managed by a non-Ingenico ePayments 3D Secure authentication provider
  • You process the transaction through Atos

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

      xid Moved property AN50

The transaction ID that is used for the 3D Authentication version 1

Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData

    priorThreeDSecureData New property Object

Object containing data regarding the consumer authentication that occurred prior to the current transaction

      acsTransactionId New property AN36

The ACS Transaction ID for a prior 3-D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the consumer).

      method New property

enum (string)

Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction
      utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the prior 3-D Secure authentication

    redirectionData New property Object

Required for 3-D Secure version 2 for the browser flow.

Object containing browser specific redirection related data

Moved from cardPaymentMethodSpecificInput

      returnUrl Moved property AN512

Required for 3-D Secure version 2 for the browser flow.

The URL that the consumer is redirect to after the payment flow has finished. You can add any number of key value pairs in the query string that, for instance help you to identify the consumer when they return to your site. Please note that we will also append some additional key value pairs that will also help you with this identification process.
Note: The provided URL should be absolute and contain the protocol to use, e.g. http:// or https://. For use on mobile devices a custom protocol can be used in the form of protocol://. This protocol must be registered on the device first.
URLs without a protocol will be rejected.

Moved from cardPaymentMethodSpecificInput

      variant New property AN10

Using the Configuration Center it is possible to create multiple variations of your MyCheckout payment pages. The redirection flow for 3-D Secure uses the MyCheckout payment pages to display the following types of pages:

  • Redirection page - All redirection using a POST method will load a page in the browser of the consumer that performs the actual redirection. This page contains a message to the consume explaining what is happening.
  • MethodURL page - Certain Issuers will use a specific flow in case of 3-D Secure version 2 to directly collect information from the consumer browser. This page contains a spinner indicating that this process is going on in.
By specifying a specific variant you can force the use of another variant then the default. This allows you to test out the effect of certain changes to your MyCheckout payment pages in a controlled manner. Please note that you need to specify the ID instead of the name of the variant.

    sdkData New property Object Object containing 3-D Secure in-app SDK data
      sdkAppId New property Object

Required for 3-D Secure version 2 for the in-app flow.

Universally unique ID created upon all installations and updates of your app on a consumer Device. This will be newly generated and stored by the 3DS SDK for each installation or update.

      deviceInfo New property AN64000

Required for 3-D Secure version 2 for the in-app flow.

Device information gathered by the 3DS SDK on a consumer device. This is JSON name/value pairs that as a whole is Base64url encoded.

      deviceRenderOptions New property Object

Object containing rendering options of the device

        sdkInterface New property

Enum

(string)

Required for 3-D Secure version 2 for the in-app flow.

Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.

  • native = The app supports only a native user interface
  • html = The app supports only an HTML user interface
  • both = Both Native and HTML user interfaces are supported by the app
        sdkUiType New property

Enum

(string)

Required for 3-D Secure version 2 for the in-app flow.

Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.

  • text = Text interface
  • single-select = Select a single option
  • multi-select = Select multiple options
  • oob = Out of bounds
  • html-other = HTML Other (only valid when cardPaymentMethodSpecificInput.threeDSecure.sdkData.deviceRenderOptions.sdkInterface is set to html)

Note: Currently, all 3-D Secure SDKs need to support all UI Types. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined by this specification).

      sdkEncryptedData New property AN64000

Required for 3-D Secure version 2 for the in-app flow.

JWE Object containing data encrypted by the 3-D Secure SDK.

      sdkEphemeralPublicKey New property AN256

Required for 3-D Secure version 2 for the in-app flow.

Public key component of the ephemeral key pair generated by the 3-D Secure SDK and used to establish session keys between the 3-D Secure SDK and ACS.

      sdkMaxTimeout New property AN2

Required for 3-D Secure version 2 for the in-app flow, except when order.amountOfMoney.amount is zero.

Indicates maximum amount of time (in minutes) for all exchanges. Minimum amount of minutes is 5.

      sdkReferenceNumber New property AN32

Required for 3-D Secure version 2 for the in-app flow.

Identifies the vendor and version for the 3-D Secure SDK that is integrated in your app, assigned by EMVCo when the 3-D Secure SDK is approved.

      sdkTransactionId New property AN36

Required for 3-D Secure version 2 for the in-app flow.

Universally unique transaction identifier assigned by the 3-D Secure SDK to identify a single transaction.

    skipAuthentication Moved property Boolean
  • true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
  • false = 3D Secure authentication will not be skipped for this transaction.

Note: This is only possible if your account in our system is setup for 3D Secure authentication and if your configuration in our system allows you to override it per transaction.

Note: Any configured Dynamic 3D rules will be ignored when you submit this property.

Moved from cardPaymentMethodSpecificInput

  unscheduledCardOnFileRequestor Existing property

Enum

(string)

Indicates which party initiated the unscheduled recurring transaction. Allowed values:

  • merchantInitiated - Merchant Initiated Transaction.
  • cardholderInitiated - Cardholder Initiated Transaction.

Note: this property is not allowed if isRecurring is true.

Required if unscheduledCardOnFileIndicator is 'subsequent'. Otherwise it must not be 'merchantInitiated'.

3-D Secure will not be used when this property is set to cardholderInitiated

  unscheduledCardOnFileSequenceIndicator Moved property Enum (string)
  • first = This transaction is the first of a series of unscheduled recurring transactions
  • subsequent = This transaction is a subsequent transaction in a series of unscheduled recurring transactions


Note: this property is not allowed if isRecurring is true.

Renamed from unscheduledCardOnFileIndicator

Additional response properties related to 3-D Secure version 2

It is possible that the Authentication fails and the reason why will be detailed in the errors. It is also possible that the issuer will require Strong Customer Authentication (SCA) to be provided before the issuer will authorize the transaction. This means that you should process the transaction in a way that will allow SCA through for instance a challenge to take place.

The below overview shows all properties in the output that are used in the 3-D Secure version 2 authentication. For each of the properties we have marked them as follows:

  • New property New - The property did not previously exist in our API.
  • Moved property Moved - We have decided to move or rename an existing property to a more logical location.
  • Existing property Existing - This is an existing property that is used in the authentication process.
  • Deprecated property Deprecated - One property needed for 3-D Secure version 2 has an overlap with an existing property and in this case we have decided to deprecate the existing property as the new property needed to provide more detail.

Property nameChange / TypeDescription
payment Existing property Object Object containing data regarding the payment
  paymentOutput Existing property Object Object containing output data regarding the payment
    cardPaymentMethodSpecificOutput Existing property Object Object containing card payment method specific output
      threeDSecureResults Existing property Object Object containing results of the 3D Secure authentication
        sdkData New property Object Object containing 3-D Secure in-app SDK data
          sdkTransactionId New property AN36

Universally unique transaction identifier assigned by the 3-D Secure SDK to identify this transaction.

        threeDSecureData New property Object Object containing data regarding the 3D Secure authentication
          acsTransactionId New property AN36

The ACS Transaction ID for this transaction.

You should store this data as you will need it for the next transaction with the same card

          method New property Enum (String) Method of authentication used for this transaction. Possible values:
  • frictionless = frictionless authentication
  • challenged = cardholder was challenged
  • avs-verified = AVS verified
  • other = another issuer method was used to authenticate this transaction

You should store this data as you will need it for the next transaction with the same card

          utcTimestamp New property AN12

Timestamp in UTC (YYYYMMDDHHmm) of the 3-D Secure authentication of this transaction

You should store this data as you will need it for the next transaction with the same card

        directoryServerTransactionId New property AN36

The 3-D Secure Directory Server transaction ID that is used for the 3-D Secure version 2 Authentication

This property is used in the communication with the acquirer

        threeDServerTransactionId New property AN36

The 3-D Secure Server transaction ID that is used for the 3-D Secure version 2 Authentication

This property is used in the communication with the acquirer

        threeDSecureVersion New property AN10

The 3-D Secure version used for the authentication

This property is used in the communication with the acquirer

The above mentioned additional properties in the response to the Create Payment request have been added generically. This means that they are also returned on a Get Payment request and all other requests that return a paymentOutput object. please note that they are only returned in case of a 3-D Secure version 2 authentication.

Webhooks

The additional properties that have been added to the Create Payment response have also been added to the webhook payment events, in case a 3-D Secure version 2 authentication was completed.