This site requires javascript to be enabled.

3D Secure - Payments API Implementation

Results for

Results for Searching

Create payment request

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 use the frictionless flow. Our new SDKs will 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 name Change / Type Description
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 ISO 3166-1 alpha-2 country code
      houseNumber Existing property AN15 House number
      stateCode Existing property AN3 ISO 3166-2 alpha-3 state code
Please note that the max length used for 3-D Secure version 2 is AN3.
      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

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

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

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

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 AN3

ISO 3166-2 alpha-3 state code
Please note that the max length used for 3-D Secure version 2 is AN3.

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
  transactionChannel Existing property Enum (String) Indicates the channel via which the payment is created. Allowed values:
  • ECOMMERCE - The transaction is a regular E-Commerce transaction (default)
  • MAIL - The transaction is a Mail Order
  • MOTO - The transaction is a Mail Order/Telephone Order
  • TELEPHONE - The transaction is a Telephone Order

This is used to determine if the transaction is eligible for 3-D Secure. All transactions flagged as MAIL, MOTO or TELEPHONE are out of scope for PSD2 Strong Customer Authentication.

  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

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

The card holder's name on the card.

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 (default if left empty)

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
    exemptionRequest New property Enum (String)

Allows you to indicate if you want us to request a certain type of exemption.

  • none = No exemption flagging is to be used of this transaction (Default)
  • automatic = Our systems will determine the best possible exemption based on the transaction parameters and the risk scores
  • transaction-risk-analysis = You have determined that this transaction is of low risk and are willing to take the liability. Please note that your fraud rate needs to stay below thresholds to allow your use of this exemption.
  • low-value = The value of the transaction is below 30 EUR. Please note that the issuer will still require every 5th low-value transaction in 24 hours to be strongly authenticated. The issuer will also keep track of the cumulative amount authorized on the card. When this exceeds 150 EUR strong customer authentication is also required.
  • whitelist = You have been whitelisted by the customer at the issuer
    externalCardholderAuthenticationData Moved property Object

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

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-Worldline 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

      directoryServerTransactionId New property AN50 The 3-D Secure Directory 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-Worldline 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

  initialSchemeTransactionId New property AN100

The unique scheme transactionId of the initial transaction that was performed with SCA. In case this is unknown a scheme transactionId of an earlier transaction part of the same sequence can be used as a fall-back.
Strongly advised to be submitted for any MerchantInitiated or recurring transaction (a subsequent one).

Additional response properties related to 3-D Secure version 2

It's 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. Put simply, you should process the transaction in a way that allows 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 name Change / Type Description
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
      initialSchemeTransactionId New property AN100 The unique scheme transactionId of the initial transaction that was performed with SCA.
Should be stored by the merchant to allow it to be submitted in future transactions.
      schemeTransactionId New property AN100 The unique scheme transactionId of this transaction.
Should be stored by the merchant to allow it to be submitted in future transactions. Use this value in case the initialSchemeTransactionId property is empty.
      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

        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, with the exception of the initialSchemeTransactionId and the schemeTransactionId. One or both of these will be returned based on acquirer capabilities.

Examples

Create Payment request
{
  "cardPaymentMethodSpecificInput": {
    "card": {
      "cvv": "352",
      "cardNumber": "4012000033330026",
      "expiryDate": "1220",
      "cardholderName": "Wile E. Coyote"
    },
    "isRecurring": false,
    "paymentProductId": 1,
    "transactionChannel": "ECOMMERCE",
    "threeDSecure": {
      "challengeIndicator": "no-preference",
      "challengeCanvasSize": "600x400",
      "authenticationFlow": "browser",
      "redirectionData": {
        "returnUrl": "https://hostname.myownwebsite.url"
      }
    }
  },
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 100
    },
    "customer": {
      "accountType": "none",
      "billingAddress": {
        "countryCode": "NL"
      },
      "device": {
        "acceptHeader": "texthtml,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "browserData": {
          "colorDepth": 24,
          "javaEnabled": false,
          "screenHeight": "1200",
          "screenWidth": "1920"
        },
        "ipAddress": "123.123.123.123",
        "locale": "en-US",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.1 Safari/605.1.15",
        "timezoneOffsetUtcMinutes": "420"
      },
      "locale": "en_US",
      "merchantCustomerId": "1234"
    },
    "references": {
      "merchantOrderId": 123456,
      "merchantReference": "vlSjO1XpvQgF3EYNvpA6rUDymoY6yD"
    }
  }
}    						
Create Payment response - Successful frictionless authentication using 3-D Secure version 2
HTTP/1.1 201 
Location: http://10.63.66.100:20104/v1/70417/payments/000007041700000008370000100001
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 22:35:47 GMT
Connection: close

{
   "creationOutput" : {
      "additionalReference" : "gUnulVY5fw3gjcuVpUgG",
      "externalReference" : "gUnulVY5fw3gjcuVpUgG3hMOPHU3Ry"
   },
   "payment" : {
      "id" : "000007041700000008370000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "merchantOrderId" : 123456,
            "merchantReference" : "gUnulVY5fw3gjcuVpUgG3hMOPHU3Ry",
            "paymentReference" : "0"
         },
         "paymentMethod" : "card",
         "cardPaymentMethodSpecificOutput" : {
            "paymentProductId" : 1,
            "fraudResults" : {
               "fraudServiceResult" : "no-advice",
               "avsResult" : "0",
               "cvvResult" : "0"
            },
            "threeDSecureResults" : {
               "cavv" : "AAABBEg0VhI0VniQEjRWAAAAAAA=",
               "directoryServerTransactionId" : "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
               "eci" : "05",
               "threeDSecureData" : {
                  "acsTransactionId" : "A9885E27-797D-4726-BDE6-18C502D62C04",
                  "method" : "frictionless",
                  "utcTimestamp" : "201907082235"
               },
               "threeDSecureVersion" : "2.1.0",
               "threeDServerTransactionId" : "1aaeac7f-3736-425f-b23b-f93051d1cc64"
            },
            "card" : {
               "cardNumber" : "************0026",
               "expiryDate" : "1220"
            }
         }
      },
      "status" : "PENDING_APPROVAL",
      "statusOutput" : {
         "isCancellable" : true,
         "statusCategory" : "PENDING_MERCHANT",
         "statusCode" : 600,
         "statusCodeChangeDateTime" : "20190708223547",
         "isAuthorized" : true,
         "isRefundable" : false
      }
   }
}    						
Create Payment response - MethodURL redirect required for 3-D Secure version 2
HTTP/1.1 201 
Location: http://10.63.66.100:20104/v1/70417/payments/000007041700000008380000100001
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 22:50:51 GMT
Connection: close

{
   "creationOutput" : {
      "additionalReference" : "Jb0dIphrG82esg5YA83K",
      "externalReference" : "Jb0dIphrG82esg5YA83KcjY0Rh8il5"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "d317d15e-0fb5-48ef-b177-cbebb282ff0d",
         "redirectURL" : "http://payment.globalcollect-cc100.com:20105/3dsecure/0be7decc-5fb8-4e29-a71a-5b0f1bc93926?returnMAC=d317d15e-0fb5-48ef-b177-cbebb282ff0d"
      }
   },
   "payment" : {
      "id" : "000007041700000008380000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "merchantOrderId" : 123456,
            "merchantReference" : "Jb0dIphrG82esg5YA83KcjY0Rh8il5",
            "paymentReference" : "0"
         },
         "paymentMethod" : "card",
         "cardPaymentMethodSpecificOutput" : {
            "paymentProductId" : 1,
            "threeDSecureResults" : {
               "threeDSecureData" : {
                  "utcTimestamp" : "201907082250"
               },
               "threeDSecureVersion" : "2.1.0",
               "threeDServerTransactionId" : "054379bc-3745-49ae-8756-5ee36641a5f9"
            },
            "card" : {
               "cardNumber" : "************7977",
               "expiryDate" : "1220"
            }
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20190708225051",
         "isAuthorized" : false,
         "isRefundable" : false,
         "threeDSecureStatus" : "ENROLLED"
      }
   }
}    						
The content of the threeDSecureResults object will contain less data. the stub we use to test against is a bit too enhousiastic in returning response data. Your code should not expect this object to be always returned and its content should be evaluated based upon the status of the transaction.

The additional threeDSecureStatus returns ENROLLED as the card is available for authentication via either 3-D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3-D Secure as smooth as possible. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3-D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3-D Secure version of flow. We did remove some steps in the process resulting in the following statusCodes no longer being returned: 20, 25 and 30.

Create Payment response - Challenge required for 3-D Secure version 2
HTTP/1.1 201 
Location: http://10.63.66.100:20104/v1/70417/payments/000007041700000008390000100001
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 22:56:26 GMT
Connection: close

{
   "creationOutput" : {
      "additionalReference" : "YQPU7omuq4m4L8DJPmGh",
      "externalReference" : "YQPU7omuq4m4L8DJPmGhK5ybC0DxFn"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "a59255a0-2d1e-4b65-ad8e-7666d9eaa51a",
         "redirectURL" : "http://payment.globalcollect-cc100.com:20105/redirector/70ad24f4-4c0a-442c-99b2-e4bdfd1aa0ec?locale=en_US"
      },
      "showData" : [ ]
   },
   "payment" : {
      "id" : "000007041700000008390000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "merchantOrderId" : 123456,
            "merchantReference" : "YQPU7omuq4m4L8DJPmGhK5ybC0DxFn",
            "paymentReference" : "0"
         },
         "paymentMethod" : "card",
         "cardPaymentMethodSpecificOutput" : {
            "paymentProductId" : 1,
            "threeDSecureResults" : {
               "directoryServerTransactionId" : "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
               "threeDSecureData" : {
                  "acsTransactionId" : "A9885E27-797D-4726-BDE6-18C502D62C18",
                  "method" : "frictionless",
                  "utcTimestamp" : "201907082256"
               },
               "threeDSecureVersion" : "2.1.0",
               "threeDServerTransactionId" : "7e583802-8f45-4c67-81a9-07f975e2413d"
            },
            "card" : {
               "cardNumber" : "************2672",
               "expiryDate" : "1220"
            }
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20190708225626",
         "isAuthorized" : false,
         "isRefundable" : false,
         "threeDSecureStatus" : "ENROLLED"
      }
   }
}    						
The content of the threeDSecureResults object will contain less data. the stub we use to test against is a bit too enhousiastic in returning response data. Your code should not expect this object to be always returned and its content should be evaluated based upon the status of the transaction.

The additional threeDSecureStatus returns ENROLLED as the card ia available for authentication via either 3-D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3-D Secure as smooth as possble. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3-D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3-D Secure version of flow. We did remove some steps in the process resulting in the following statusCodes no longer being returned: 20, 25 and 30.

Create Payment response - Challenge required for 3-D Secure version 1 (fall-back scenario)
HTTP/1.1 201 
Location: http://10.63.66.100:20104/v1/70417/payments/000007041700000008410000100001
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 23:07:24 GMT
Connection: close

{
   "creationOutput" : {
      "additionalReference" : "fU3pYUGRWRippBwdyliJ",
      "externalReference" : "fU3pYUGRWRippBwdyliJV2tsKubTrN"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "f6708f89-68fe-4e65-9e55-bfe8f638da34",
         "redirectURL" : "http://payment.globalcollect-cc100.com:20105/redirector/319ea199-4094-44ba-b28d-c17a10089b0c?locale=en_US"
      },
      "showData" : [ ]
   },
   "payment" : {
      "id" : "000007041700000008410000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "merchantOrderId" : 123456,
            "merchantReference" : "fU3pYUGRWRippBwdyliJV2tsKubTrN",
            "paymentReference" : "0"
         },
         "paymentMethod" : "card",
         "cardPaymentMethodSpecificOutput" : {
            "paymentProductId" : 1,
            "card" : {
               "cardNumber" : "************0002",
               "expiryDate" : "1220"
            }
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20190708230724",
         "isAuthorized" : false,
         "isRefundable" : false,
         "threeDSecureStatus" : "ENROLLED"
      }
   }
}    						

The additional threeDSecureStatus returns ENROLLED as the card ia available for authentication via either 3-D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3-D Secure as smooth as possble. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3-D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3-D Secure version of flow. We did remove some steps in the process resulting in the following statusCodes no longer being returned: 20, 25 and 30.

Create Payment response - Rejected 3-D Secure version 2 authentication with optional cardholderInfo
HTTP/1.1 402 
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 23:09:28 GMT
Connection: close

{
  "errorId": "5d23642a18a1c3fe481964da5a96df5f",
  "errors": [
    {
      "code": "401025",
      "message": "MEDIUM_CONFIDENCE",
      "httpStatusCode": 402
    }
  ],
  "paymentResult": {
    "creationOutput": {
      "additionalReference": "EEeYqOtEOFMnmf1oLPmr",
      "externalReference": "EEeYqOtEOFMnmf1oLPmrliDjr568mC"
    },
    "merchantAction": {
      "actionType": "SHOW_TRANSACTION_RESULTS",
      "renderingData": "eyJ0eXBlIjoicnBwSG9zdGVkQ2hlY2tvdXQiLCJob3N0ZWRTZXNzaW9uU3BlY2lmaWNJbnB1dCI6eyJ0eXBlIjoicnBwU3BlY2lmaWNJbnB1dCIsImNhcnQiOnsiY3VycmVuY3lTeW1ib2wiOiLigqwiLCJ0b3RhbFByaWNlIjoxMDB9LCJyZXR1cm5DYW5jZWxTdGF0ZSI6ZmFsc2V9LCJjcmVhdGVkUGF5bWVudE91dHB1dCI6eyJwYXltZW50Ijp7ImlkIjoiMDAwMDA3MDQxNzAwMDAwMDA4NDUwMDAwMTAwMDAxIiwic3RhdHVzIjoiUEVORElOR19BUFBST1ZBTCJ9LCJtZXJjaGFudEFjdGlvbiI6eyJhY3Rpb25UeXBlIjoiU0hPV19UUkFOU0FDVElPTl9SRVNVTFRTIiwic2hvd0RhdGEiOlt7ImtleSI6IkNBUkRIT0xERVJJTkZPIiwidmFsdWUiOiJjYXJkaG9sZGVyIn1dfX0sInBhcnRpYWxQYXltZW50SW5wdXQiOnsiYW1vdW50IjoxMDAsImNvdW50cnlDb2RlIjoiTkwiLCJjdXJyZW5jeUNvZGUiOiJFVVIiLCJpc1JlY3VycmluZyI6ZmFsc2UsIm1lcmNoYW50SWQiOiI3MDQxNyIsInBheW1lbnRQcm9kdWN0SWQiOjF9LCJycHBTcGVjaWZpY0lucHV0Ijp7ImNhcnQiOnsiY3VycmVuY3lTeW1ib2wiOiLigqwiLCJ0b3RhbFByaWNlIjoxMDB9LCJyZXR1cm5DYW5jZWxTdGF0ZSI6ZmFsc2V9fQ==",
      "showData": [
        {
          "key": "CARDHOLDERINFO",
          "value": "Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx."
        }
      ]
    },
    "payment": {
      "id": "000007041700000008440000100001",
      "paymentOutput": {
        "amountOfMoney": {
          "amount": 100,
          "currencyCode": "EUR"
        },
        "references": {
          "merchantOrderId": 123456,
          "merchantReference": "EEeYqOtEOFMnmf1oLPmrliDjr568mC",
          "paymentReference": "0"
        },
        "paymentMethod": "card",
        "cardPaymentMethodSpecificOutput": {
          "paymentProductId": 1,
          "threeDSecureResults": {
            "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
            "threeDSecureData": {
              "acsTransactionId": "A9885E27-797D-4726-BDE6-18C502D62C08",
              "method": "frictionless",
              "utcTimestamp": "201907082309"
            },
            "threeDSecureVersion": "2.1.0",
            "threeDServerTransactionId": "77737c0c-9a6b-432f-a2c6-c66a0438476b"
          },
          "card": {
            "cardNumber": "************5550",
            "expiryDate": "1220"
          }
        }
      },
      "status": "REJECTED",
      "statusOutput": {
        "errors": [
          {
            "code": "401025",
            "requestId": "7830",
            "message": "MEDIUM_CONFIDENCE",
            "httpStatusCode": 402
          }
        ],
        "isCancellable": false,
        "statusCategory": "UNSUCCESSFUL",
        "statusCode": 180,
        "statusCodeChangeDateTime": "20190708230928",
        "isAuthorized": false,
        "isRefundable": false,
        "threeDSecureStatus": "INVALID_PARES_OR_NOT_COMPLETED"
      }
    }
  }
}    						
The content of the threeDSecureResults object will contain less data. the stub we use to test against is a bit too enthusiastic in returning response data. Your code should not expect this object to be always returned and its content should be evaluated based upon the status of the transaction.

The above scenario returns a new element in the 3-D Secure flow. For transactions that have not been authenticated successfully using a frictionless flow the issuer might return so called cardholderInfo. In case this is returned we will return this as part of a SHOW_TRANSACTION_RESULTS merchantAction. Presenting this data back to the consumer is optional. In our hostedCheckouts we will always show it to the consumer, but in the Create Payment flow this is left to you.

Create Payment response - Successful authorization without 3-D Secure
HTTP/1.1 201 
Location: http://10.63.66.100:20104/v1/70417/payments/000007041700000008420000100001
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 08 Jul 2019 23:09:03 GMT
Connection: close

{
   "creationOutput" : {
      "additionalReference" : "3PY2aFLDIusp0ESjdaon",
      "externalReference" : "3PY2aFLDIusp0ESjdaonVichbsybYn"
   },
   "payment" : {
      "id" : "000007041700000008420000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
         },
         "references" : {
            "merchantOrderId" : 123456,
            "merchantReference" : "3PY2aFLDIusp0ESjdaonVichbsybYn",
            "paymentReference" : "0"
         },
         "paymentMethod" : "card",
         "cardPaymentMethodSpecificOutput" : {
            "paymentProductId" : 1,
            "fraudResults" : {
               "fraudServiceResult" : "no-advice",
               "avsResult" : "0",
               "cvvResult" : "0"
            },
            "threeDSecureResults" : {
               "eci" : "7"
            },
            "card" : {
               "cardNumber" : "************9026",
               "expiryDate" : "1220"
            }
         }
      },
      "status" : "PENDING_APPROVAL",
      "statusOutput" : {
         "isCancellable" : true,
         "statusCategory" : "PENDING_MERCHANT",
         "statusCode" : 600,
         "statusCodeChangeDateTime" : "20190708230903",
         "isAuthorized" : true,
         "isRefundable" : false
      }
   }
}    						

Additional information

  1. Introduction
  2. Highlevel implementation
  3. Consumer user experience
  4. MyCheckout hosted payment pages implementation
  5. Create Payment API implementation
  6. Test cases
  7. Special use cases
  8. Webhooks