This site requires javascript to be enabled.

3D Secure - Payments API Implementation

Results for

Results for Searching
  1. Home
  2. Best practices
  3. Services
  4. 3dsv2
  5. payments-api
  6. 3D Secure - Payments API Implementation

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 3D Secure version 2

The below overview shows all properties in the input that are used in the 3D Secure version 2 authentication. In the description it is mentioned if the property is required and under which conditions. 

Property Type Details
fraudFields object Object containing additional data that will be used to assess the risk of fraud.
merchant object Object containing information on you, the merchant.
websiteUrl string (60) The website from which the purchase was made. The '+' character is not allowed in this property for transactions that are processed by TechProcess Payment Platform.
contactWebsiteUrl string (2048) URL to find contact or support details to contact in case of questions.
order object Order object containing order related data.
shipping object Object containing information regarding shipping / delivery.
addressIndicator string Indicates shipping method chosen for the transaction. Possible values:
  • same-as-billing = the shipping address is the same as the billing address
  • another-verified-address-on-file-with-merchant = the address used for shipping is another verified address of the customer 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
additionalInput object Object containing additional input on the order.
typeInformation object Object that holds the purchase and usage type indicators.
transactionType string Required for merchants from Brazil in case order.amountOfMoney.amount is not 0.
Identifies the type of transaction being authenticated. Possible values are:
  • purchase = The purpose of the transaction is to purchase goods or services (Default)
  • 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 object Object containing the details of the customer.
account object Object containing data related to the account the customer has with you.
createDate string (8) The date (YYYYMMDD) on which the customer created their account with you.

We will calculate the CustomerAccountAgeIndicator using this property and the order.customer.accountType
changeDate string (8) The last date (YYYYMMDD) on which the customer 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 3D Secure version 2 this property and the 'age' of the changes are used.
changedDuringCheckout boolean
  • true = the consumer made changes to their account during this checkout
  • false = the customer didn't change anything to their account during this checkout
The changes ment 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.chang . eDate to determine the 'age' of the changes. For 3D Secure version 2 only the resulting 'age' of the changes is used.
passwordChangeDate string (8) The last date (YYYYMMDD) on which the customer changed their password for the account used in this transaction.

We will use the data from this property and the order.customer.account.passwordChangedDuring kout to determine the 'age' of the changes. For 3D Secure version 2 this property and the 'age' of the password change are used.
passwordChangedDuringCheckout boolean Indicates if the password of an account is changed during this checkout.
  • true = the customer made changes to their password of the account used during this checkout
  • false = the customer 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 3D Secure version 2 only the resulting 'age' of the password change is used.
hasForgottenPassword 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 3D Secure version 2.
hadSuspiciousActivity 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 object Object containing data on the authentication used by the consumer to access their account.
utcTimestamp string (12) Timestamp (YYYYMMDDHHmm) of the authentication of the consumer to their account with you.
method 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 object Object containing data on the purchase history of the consumer with you.
numberOfPurchasesLast6Months integer (4) Number of successful purchases made by this consumer with you in the last 6 months.
numberOfPaymentAttemptsLast24Hours integer (3) Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 24 hours.
numberOfPaymentAttemptsLastYear integer (3) Number of payment attempts (so including unsuccessful ones) made by this consumer with you in the last 12 months.
paymentAccountOnFileType 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 object Object containing information on the payment account data on file (tokens).
numberOfCardOnFileCreationAttemptsLast24Hours integer (3) Number of attempts made to add new card to the consumer account in the last 24 hours.
createDate string (8) 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 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 object Object containing information of the company in case the consumer is a company.
vatNumber   Local VAT number of the 'consumer' Moved from order.customer This property is not used for 3D Secure version 2.
billingAddress object Object containing the billing address details.
additionalInfo string (50) Additional address information.
city string (40) City.
countryCode string (2) ISO 3166-1 alpha-2 country code.
houseNumber string (15) House number.
stateCode string  
street string (50) Street name.
zip string (10) Zip code.
device object Object containing information on the device and browser of the consumer.
acceptHeader string (2408) Required for 3D Secure version 2 for the authenticationFlow "browser"
The accept-header of the consumer client from the HTTP Headers.
ipAddress string (45) Required for 3D 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 string (50) 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 3D Secure version 2, although in the future we might use this service to populate the device and browser related properties.
defaultFormFill 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 3D Secure version 2
timezoneOffsetUtcMinutes string (6) Required for 3D 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 3D 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 is set to "browser".
locale string (8) Required for 3D 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 3D 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 is set to "browser".
userAgent string (2048) Required for 3D 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 object Object containing information regarding the browser of the consumer.
javaEnabled boolean Required for 3D 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 3D 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 is set to "browser".
javaScriptEnabled boolean Required for 3D 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 3D Secure version 2.2
colorDepth integer (2) Required for 3D 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 3D 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 is set to "browser".
screenHeight string (6) Required for 3D 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 3D 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 is set to "browser".
screenWidth string (6) Required for 3D 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 3D 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 is set to "browser".
innerHeight string (6) 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 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 string (6) 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 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 object Object containing contact details of the consumer.
mobilePhoneNumber string (20) International version of the mobile phone number of the customer including the leading + (i.e. +16127779311).
Official max length is string (15) making it string (16) to include the leading + sign
phoneNumber string (20) International version of the home phone number of the consumer including the leading + (i.e. +16127779311).
Official max length is string (15) making it string (16) to include the leading + sign
workPhoneNumber string (20) International version of the work phone number of the consumer including the leading + (i.e. +31235671500).
Official max length is string (15) making it string (16) to include the leading + sign
shipping object Object containing information regarding shipping / delivery.
type 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 boolean 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 3D Secure version 2 this property and the 'age' of the shipping details change are used.
isFirstUsage 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 3D Secure version 2 only the resulting 'age' of the shipping details is used.
addressIndicator 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 string (70) Email address linked to the shipping.
address object Object containing address information.
additionalInfo string (50) Additional address information. Moved from order.customer.shippingaddress
city string (40) City Moved from order.customer.shippingaddress
countryCode string (2) ISO 3166-1 alpha-2 country code. Moved from order.customer.shippingaddress
houseNumber string (15)  
name object Object containing the name elements.
Moved from order.customer.shippingaddress.name
firstName string (15) Given name(s) or first name(s) of the consumer.
Moved from order.customer.shippingaddress.name.firstName

This property is not used for 3D Secure version 2.
surname string (70) Surname(s) or last name(s) of the consumer.
Moved from order.customer.shippingaddress.name.surname

This property is not used for 3D Secure version 2.
surnamePrefix string (15) Middle name - In between first name and surname - of the consumer.
Moved from order.customer.shippingaddress.name.surnamePrefix

This property is not used for 3D Secure version 2.
title   Title of consumer.
Moved from order.customer.shippingaddress.name.title
This property is not used for 3D Secure version 2.
state string (35) State of the consumer.
Moved from order.customer.shippingaddress.state
This property is not used for 3D Secure version 2.
stateCode string (3) ISO 3166-2 alpha-3 state code.
Please note that the max length used for 3D Secure version 2 is string (3).

Moved from order.customer.shippingaddress.stateCode
street string (50) Street name.
oved from order.customer.shippingaddress.street
zip string Zip code.
Moved from order.customer.shippingaddress.zip
trackingNumber string (19) 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 3D Secure version 2.
comments string (160) 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 3D Secure version 2.
shoppingCart object Object containing information on the item(s) in the shopping cart.
isPreOrder boolean The consumer is pre-ordering one or more items.
preOrderItemAvailabilityDate string (8) Date (YYYYMMDD) when the preordered item becomes available.
giftCardPurchase object Object containing information on purchased gift card(s).
amountOfMoney object Object containing information on an amount of money.
amount integer (12) Amount in cents and always having 2 decimals.
currencyCode string (3) Three-letter ISO currency code representing the currency for the amount.
numberOfGiftCards integer (2) Number of gift cards that are purchased through this transaction.
reOrderIndicator 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 object Object containing data regarding card payments.
transactionChannel 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 3D Secure.

All transactions flagged as MAIL, MOTO or TELEPHONE are out of scope for PSD2 Strong Customer Authentication.
card object Object containing card data.
cardNumber string (19) 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 string (51) Required for 3D 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 3D Secure version 2.
expiryDate string (4) Expiry date of the cardFormat: MMYY

Required, except when a token or encryptedCustomerInput that includes this data is provided.
isRecurring 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 object Object containing data related to recurring.
endDate string (8) Date (YYYYMMDD) in the future after which no further authorizations shall be performed.

Note: This property is required when isRecurring is set to true, property recurringPaymentSequenceIndicato is set to first and 3D Secure version 2 is enabled for the merchant.
minFrequency integer (4) 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 3D Secure version 2 is enabled for the merchant.
recurringPaymentSequenceIndicator 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. 3D Secure will not be used when this property is set to recurring Moved from cardPaymentMethodSpecificInput. recurringPaymentSequenceIndicator
threeDSecure object Object containing specific data regarding 3D Secure.
authenticationFlow 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 3D Secure SDK to complete the checkout
Note: We will add support for the in-app flow in a future release.
challengeCanvasSize string Required for 3D 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 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 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 object Object containing results of an external authentication (not performed by Worldline). Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData
cavv string (50) 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 string (1) 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 cardPayment
eci integer (2) 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 string The 3D Secure Directory Server transaction ID that is used for the 3D Secure version 2 Authentication.
validationResult   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 string Transaction ID for the Authentication. Moved from cardPaymentMethodSpecificInput.externalCardHolderAuthenticationData
priorThreeDSecureData object Object containing data regarding the consumer authentication that occurred prior to the current transaction.
acsTransactionId string (36) The ACS Transaction ID for a prior 3D Secure authenticated transaction (for example, the first recurring transaction that was authenticated with the consumer).
method 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 string (12) Timestamp in UTC (YYYYMMDDHHmm) of the prior 3D Secure authentication.
sdkData object Object containing 3D Secure in-app SDK data.
sdkAppId string (36) Required for 3D 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.
deviceRenderOptions object Required for 3D 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.
sdkInterface string Required for 3D 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
sdkEncryptedData string (64000) Required for 3D Secure version 2 for the in-app flow. JWE Object containing data encrypted by the 3D Secure SDK.
sdkEphemeralPublicKey string (256) Required for 3D Secure version 2 for the in-app flow. Public key component of the ephemeral key pair generated by the 3D Secure SDK and used to establish session keys between the 3D Secure SDK and ACS.
sdkMaxTimeout string (2) Required for 3D 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 string (32) Required for 3D Secure version 2 for the in-app flow. Identifies the vendor and version for the 3D Secure SDK that is integrated in your app, assigned by EMVCo when the 3D Secure SDK is approved.
sdkTransactionId string (36) Required for 3D Secure version 2 for the in-app flow. Universally unique transaction identifier assigned by the 3D Secure SDK to identify a single transaction.
skipAuthentication boolean
  • true = 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is is set to true and recurringPaymentSequenceIndicator is 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 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 is true. Required if unscheduledCardOnFileIndicator is 'subsequent'. Otherwise it must not be 'merchantInitiated'. 3D Secure will not be used when this property is set to cardholderInitiated
unscheduledCardOnFileSequenceIndicator 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   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 (subsequent one).

Additional response properties related to 3D 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 3D Secure version 2 authentication.

Property name Type Description
payment Object Object containing data regarding the payment
  paymentOutput Object Object containing output data regarding the payment
    cardPaymentMethodSpecificOutput Object Object containing card payment method specific output
      initialSchemeTransactionId 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 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 Object Object containing results of the 3D Secure authentication
        sdkData Object Object containing 3D Secure in-app SDK data
          sdkTransactionId AN36 Universally unique transaction identifier assigned by the 3D Secure SDK to identify this transaction.
        threeDSecureData Object Object containing data regarding the 3D Secure authentication
          acsTransactionId 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 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 AN12 Timestamp in UTC (YYYYMMDDHHmm) of the 3D Secure authentication of this transaction. You should store this data as you will need it for the next transaction with the same card
        directoryServerTransactionId AN36 The 3D Secure Directory Server transaction ID that is used for the 3D Secure version 2 Authentication. This property is used in the communication with the acquirer.
        threeDServerTransactionId AN36 The 3D Secure Server transaction ID that is used for the 3D Secure version 2 Authentication.
        threeDSecureVersion AN10 The 3D 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 3D 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 3D Secure version 2
{
   "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 3D Secure version 2
{
   "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 3D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3D Secure as smooth as possible. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3D 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 3D Secure version 2
{
   "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 3D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3D Secure as smooth as possble. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3D 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 3D Secure version 1 (fallback scenario)
{
   "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 3D Secure version. We continue to use the same terminology and statusses as before to make your transition to support 3D Secure as smooth as possble. We take care of the optional additional methodURL step on our side, to reduce the impact of implementing 3D Secure version 2 to only the submission of the new properties.

Redirection is always handled in the exact same way regardless of the 3D 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 3D Secure v2 authentication with optional cardholderInfo
{
  "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 3D 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 3D Secure
{
   "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