Click API updates for 3DS 2.1

API Endpoint

3D Secure 2.1 is now available in Click for merchants/integrators using our Hosted Payment Page and Direct Post integrations.

Integration

You should send the additional data as part of the initial request to Click. This ensures that any personally identifiable information is sent separately to card details, enhancing the cardholder’s security. We remove all 3DS 2 data from our systems at the end of each transaction. Click collects as much of the mandatory information from our own systems as possible to reduce the integration work required by merchants. Paymark are happy to help you decide which information is most relevant and useful for your specific use cases.

We have split the fields into logical groups based on the the recommendation of EMVco.

Field groups Reason No of fields
Browser information Minimum fields to function 8
Merchant Risk Info, Cardholder Account Info Strongly Recommended by EMVco. 26
Transaction & Checkout Page Info Lowest effort for merchants to source data 27
Login & Authentication Info More effort for merchants to source data 7

Browser information

Overview

These are the minimum new fields required for a functioning 3DS 2.1 flow. Click gathers this information for Hosted Payment Pages.

Field definitions

browser.acceptHeader required

String | Max length 2048

The cardholder’s browser accept header.


browser.ipAddress required

String | Max length 250

The cardholder’s IP address. Must follow IPV4 or IPV6 pattern: /^([0-9A-Fa-f]{0,4}:​){1,7}[0-9A-Fa-f]{1,4}|(\d{1,3}.){3}\d{1,3}$/

example: 2001:0db8:0000:0042:0000:8a2e:0370:7334


browser.javaEnabled required

Boolean

Whether the cardholder’s browser is Java enabled. If JavaScript is not enabled in the cardholder’s browser, this value should be FALSE.


browser.language required

String | Max length 8

The cardholder’s browser language as defined in IETF BCP47.

Example: en-NZ


browser.colorDepth required

String | enum

The cardholder’s browser colour depth (note US spelling in field name). Options are:

  • 1bit

  • 4bits

  • 8bits

  • 15bits

  • 16bits

  • 24bits

  • 32bits

  • 48bits

If JavaScript is not enabled in the cardholder’s browser, this value should be 1bit.


browser.screenHeight required

Integer | int32 | Max length 6 | Range 0 - 999999

The cardholder’s browser screen height. If JavaScript is not enabled in the cardholder’s browser, this value should be 0.


browser.screenWidth required

Integer | int32 | Max length 6 | Range 0 - 999999

The cardholder’s browser screen width. If JavaScript is not enabled in the cardholder’s browser, this value should be 0.


browser.timeZone required

Integer | int32 | Max length 4

The cardholder’s browser time zone offset from UTC in minutes. We recommend using JavaScript new Date().getTimezoneOffset(). If JavaScript is not enabled in the cardholder’s browser, this value should be 0.


browser.userAgent required

String | Max length 2048

The cardholder’s browser user agent string

Merchant Risk Info, Cardholder Account Info

Overview

These are the set of optional fields which are strongly recommended to be implemented by EMVco. These should have the highest impact in reducing the number of challenges cardholders receive.

Field definitions

threeDSRequestorInformation.challengeIndicator Optional

String | enum

Allows a merchant to indicate if they’d like a challenge to happen. Options are:

  • NoPreference (ACS will decide)

  • NoChallengeRequested (cardholder should not be challenged)

  • ChallengeRequested3DSRequestorPreference (merchant would like the cardholder to be challenged)

  • ChallengeRequestedMandate (merchant is legally required to challenge the cardholder for this transaction)


accountInformation.cardholderInformation.accountAgeIndicator Optional

String | enum

Length of time that the cardholder has had an account with the merchant

  • NoAccount

  • CreatedDuringTransaction

  • LessThan30Days

  • Between30And60Days

  • MoreThan60Days


accountInformation.cardholderInformation.accountDate Optional

String | Max length 10

Date that the cardholder created their account with the merchant

Example: 2015-04-14


accountInformation.cardholderInformation.accountChangeIndicator Optional

String | enum

Length of time since the cardholder’s account information with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Options are:

  • ChangedDuringThisTransaction

  • LessThan30Days

  • Between30And60Days

  • MoreThan60Days


accountInformation.cardholderInformation.accountChange Optional

String | Max length 10

Date that the cardholder’s account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

Example: 2015-04-14


accountInformation.cardholderInformation.accountPasswordChangeIndicator Optional

String | enum

Length of time since the cardholder’s account with the merchant had a password change. Options are:

  • ChangedDuringThisTransaction

  • LessThan30Days

  • Between30And60Days

  • MoreThan60Days


accountInformation.cardholderInformation.accountPasswordChange Optional

String | Max length 10

Date that the cardholder’s account password was last changed.

Example: 2015-04-14


accountInformation.shippingAddressWasFirstUsed Optional

String | enum

Indicates when the shipping address used for this transaction was first used by this cardholder.

  • ThisTransaction

  • LessThan30Days

  • Between30And60Days

  • MoreThan60Days


accountInformation.shippingAddressUsage Optional

String | Max length 10

Date that the shipping address was first used by this cardholder.

Example: 2015-04-14


accountInformation.transactionActivityInTheLast24Hours Optional

Integer | Int32 | Max length 3 | Range 0-999

Total number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous 24 hours.


accountInformation.transactionActivityLastYear Optional

Integer | Int32 | Max length 3 | Range 0-999

Total number of times the cardholder has tried to add a card to their account with the merchant in the previous 24 hours.


accountInformation.provisionAttemptsInTheLast24Hours Optional

Integer | Int32 | Max length 3 | Range 0-999

Total number of times the cardholder has tried to add a card to their account with the merchant in the previous 24 hours.


accountInformation.numberOfPurchaseWithAccountInTheLastSixMonths Optional

Integer | int32 | max length 3 | Range 0-999

Total number of purchases by this cardholder account in the previous 6 months.


accountInformation.suspiciousAccountActivityDetected Optional

Boolean

Indicates whether the merchant has experienced suspicious activity (including previous fraud) on this cardholder account.


accountInformation.shippingNameAndCardholderNameAreIdentical Optional

Boolean

Indicates if the cardholder name on the account is identical to the shipping name used for this transaction


accountInformation.paymentAccountIndicator Optional

String | enum

Indicates the length of time since the payment method was added to the cardholder’s account with the merchant. Options are:

  • NoAccount

  • DuringThisTransaction

  • LessThan30Days

  • Between30And60Days

  • MoreThan60Days


accountInformation.paymentAccountAge Optional

String | Max length 10

Date that the payment method was added to the cardholder’s account with the merchant.

Example: 2015-04-14


merchantRiskIndicator.shippingIndicator Optional

String | enum

Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business.

If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. Options are:

  • ShipToCardholdersBillingAddress

  • ShipToAnotherVerifiedAddressOnFileWithMerchant

  • ShipToAddressThatIsDifferentThanTheCardholdersBillingAddress

  • PickUpAtLocalStore

  • DigitalGoods

  • TravelAndEventTicketsNotShipped


merchantRiskIndicator.deliveryTimeframe Optional

String | enum

Indicates the merchandise delivery timeframe. Options are:

  • ElectronicDelivery

  • SameDayShipping

  • OvernightShipping

  • TwoDayOrMoreShipping


merchantRiskIndicator.deliveryEmailAddress Optional

String | Max length 254

For electronic delivery, the email address the goods are sent to.

Pattern: ^.@.…*$


merchantRiskIndicator.reorderItemsIndicator Optional

String | enum

Indicates whether the cardholder is reordering previously purchased merchandise. Options are:

  • FirstTime

  • Reordered


merchantRiskIndicator.preOrderPurchaseIndicator Optional

String | enum

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. Options are:

  • MerchandiseAvailable

  • FutureAvailablility


merchantRiskIndicator.preOrderDate Optional

String | Max length 10

For a pre-ordered purchase, the expected date that the merchandise will be available.

Example: 2015-04-14


merchantRiskIndicator.giftCardInformation.amount.amount Conditional

Integer | int64 | Max length 15 | Range -99999999999999 to 999999999999999

For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units.

Example: $123.45 should be sent as 123

If you send merchantRiskIndicator.giftCardInformation.amount.amount you must also send merchantRiskIndicator.giftCardInformation.amount.currency.


merchantRiskIndicator.giftCardInformation.amount.currency Conditional

String | enum

ISO 4217 three-character currency code of prepaid or gift card value. Allowed values:

  • AUD

  • CAD

  • CHF

  • CNY

  • DKK

  • EUR

  • GBP

  • HKD

  • JPY

  • KRW

  • MYR

  • NOK

  • NZD

  • SEK

  • SGD

  • USD

  • ZAR

If you send merchantRiskIndicator.giftCardInformation.amount.amount you must also send merchantRiskIndicator.giftCardInformation.amount.currency.


merchantRiskIndicator.giftCardInformation.count Optional

Integer | int32 | Max length 2 | Range 1-99

Total number of gift cards purchased in this transaction.

Transaction & Checkout Page Info

Overview

These fields describe the transaction and information added during checkout

Field definitions

accountInformation.cardholderInformation.​name Optional

String | Max length 45

Cardholder’s name as it appears on the card.


threeDSRequestorInformation.purchaseInstalmentData Optional

Integer | int32 | Max length 3 | Range 2 - 999

Indicates the maximum number of authorisations permitted for instalment payments.


threeDSRequestorInformation.recurringExpiry Optional

String | Max length 10

If this transaction initiates a recurring payment, this field denotes the date of the final recurring payment.

Example: 2015-04-14


threeDSRequestorInformation.recurringFrequency Optional

Integer | int32 | Max length 4 | Maximum 9999

Indicates the minimum number of days between authorisations.


billingAddressSameAsShippingAddress Optional

Boolean

Is the cardholders’ billing address the same as their shipping address for this transaction?


billingAddress.addressLine1 Optional

String | Max length 50


billingAddress.addressLine2 Optional

String | Max length 50


billingAddress.addressLine3 Optional

String | Max length 50


billingAddress.postalCode Optional

String


billingAddress.city Optional

String | Max length 50


billingAddress.state Optional

String

ISO 3166-2 country subdivision code. NZ values: https://www.iso.org/obp/ui/#iso:code:3166:NZ

Example: NZ-AUK


billingAddress.country Optional

String | Max length 2

ISO 3166-1 alpha-2 country code

Example: NZ


email Optional

String | Max length 254

cardholder’s email address.

Pattern: /^.@.…*$/


shippingAddress.addressLine1 Optional

String | Max length 50


shippingAddress.addressLine2 Optional

String | Max length 50


shippingAddress.addressLine3 Optional

String | Max length 50


shippingAddress.postalCode Optional

String


shippingAddress.city Optional

String | Max length 50


shippingAddress.state Optional

String

ISO 3166-2 country subdivision code. NZ values: https://www.iso.org/obp/ui/#iso:code:3166:NZ

Example: NZ-AUK


shippingAddress.country Optional

String | Max length 2

ISO 3166-1 alpha-2 country code

Example: NZ


transactionType Optional

String | enum

Values derived from the 8583 ISO Standard. Options are:

  • GoodsOrServicePurchase

  • CheckAcceptance

  • AccountFunding

  • QuasiCashTransaction

  • PrepaidActivationAndLoad


accountType Optional

String | enum

Type of card account. Options are:

  • NotApplicable

  • Credit

  • Debit


homePhone.country Conditional

String | Max length 3

Country phone code (ITU-E.164 cc value)

Example: 64

If you provide homePhone.country you must also provide homePhone.subscriber.


homePhone.subscriber Conditional

String | Max length 15

rest of phone number

Example: 93568088

If you provide homePhone.country you must also provide homePhone.subscriber.


mobilePhone.country Conditional

String | Max length 3

Country phone code (ITU-E.164 cc value)

Example: 64

If you provide mobilePhone.country you must also provide mobilePhone.subscriber.


mobilePhone.subscriber Conditional

String | Max length 15

rest of phone number

Example: 93568088

If you provide mobilePhone.country you must also provide mobilePhone.subscriber.


workPhone.country Conditional

String | Max length 3

Country phone code (ITU-E.164 cc value)

Example: 64

If you provide workPhone.country you must also provide workPhone.subscriber.


workPhone.subscriber Conditional

String | Max length 15

rest of phone number

Example: 93568088

If you provide workPhone.country you must also provide workPhone.subscriber.

Authentication Info

Overview

These fields describe how the cardholder logged into the merchant website and their history of 3DS authentication.

Field definitions

threeDSRequestorInformation.authenticationInformation.data

String | Binary

The content of this field has not been specified by EMVco yet. DO NOT USE.


threeDSRequestorInformation.authenticationInformation.method

String | enum

Describes the way a cardholder logged into the merchant’s website. Options are:

  • No3DSRequestorAuthenticationOccurred

  • LoginToTheCardholderAccountAtThe3DSRequestorSystemUsingFederatedId

  • LoginToTheCardholderAccountAtThe3DSRequestorSystemUsingThirdPartyAuthentication

  • LoginToTheCardholderAccountAtThe3DSRequestorSystemUsingFidoAuthenticator


threeDSRequestorInformation.authenticationInformation.timestamp

String

Date and time in UTC of the cardholder authentication.

Example: 2015-04-14T11:55:04Z


threeDSRequestorInformation.priorAuthenticationInfo.data

String | Binary

The content of this field has not been specified by EMVco yet. DO NOT USE.


threeDSRequestorInformation.priorAuthenticationInfo.method

String | enum

Describes how the customer was authenticated through 3DS for a previous transaction. Options are:

  • FrictionlessAuthenticationOccurredByAcs

  • CardholderChallengeOccurredByAcs

  • AvsVerified

  • OtherIssuerMethods


threeDSRequestorInformation.priorAuthenticationInfo.reference

String | UUID | Max length

UUID representing previous authentication.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$


threeDSRequestorInformation.priorAuthenticationInfo.timestamp

String

Date and time in UTC of the cardholder authentication.

Example: 2015-04-14T11:55:04Z

Test cards

These test cards will allow you to test all scenarios. Any future expiry date will work.

Frictionless flow

Test case MasterCard Visa Expiry CVV Outcome
Cardholder successfully authenticated 5123450000000008 4508750015741019 Success
Cardholder failed authentication 5114395216041620 4589998437591445 Declined
3DS Status unavailable 5186158875610488 4927874264333790 Blocked
Cardholder authentication rejected 5162323223461467 4635691262664247 Blocked

Challenge flow

Test case MasterCard Visa Outcome
Cardholder successfully authenticated 2223000000000007 - Success
Cardholder failed authentication 5199768787888942 4253955490718757 Declined

Generated by aglio on 03 Apr 2024