Click API updates for 3DS 2.1

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 ¶

Challenge flow ¶