--- title: "3D Secure - Payments API Implementation" canonical_url: https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/payments-api/ --- 1. [Home](https://docs.connect.worldline-solutions.com/) 2. Best practices 3. Services 4. 3dsv2 5. [payments-api](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/payments-api.md) 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 requestCopy code { "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 2Copy code { "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 2Copy code { "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 2Copy code { "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)Copy code { "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 cardholderInfoCopy code { "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 SecureCopy code { "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](https://docs.connect.worldline-solutions.com/services/3d-secure-version-2.md "Read more about 3-D Secure version 2") 2. [Highlevel implementation](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/implementation.md "Read more about 3-D Secure impact on the highlevel implementation & flows") 3. [Consumer user experience](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/consumer-ux.md "Read more about 3-D Secure impact on the user experience of the consumer") 4. [MyCheckout hosted payment pages implementation](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/mycheckout.md "Read more about 3-D Secure impact on the Create hostedCheckout API") 5. **Create Payment API implementation** 6. [Test cases](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/test-cases.md "Read more about 3-D Secure test cases") 7. [Special use cases](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/special-cases.md "Read more about 3-D Secure special use cases") 8. [Webhooks](https://docs.connect.worldline-solutions.com/best-practices/services/3dsv2/webhooks.md "Read more about 3-D Secure version 2 impact on webhooks")