- Home
- All APIs
- WPG guide
- Authentication
- 3DS Flex (Hosted)
3DS Flex (Hosted)
Prerequisite: You need to be setup for 3DS2, before using it with Worldpay. For more information, contact your Relationship Manager.
Worldpay will handle 3DS on your behalf. Submit your
Note: We recommend providing an orderCode
of less than 50 characters for 3DS Flex requests. Where the orderCode
is longer than 50 characters, we will truncate it for downstream processing. This adjusted orderCode
is only be used in Cardinal's systems.
This doesn't impact the orderCode
that is stored internally, the orderCode
that is returned to you, or the orderCode
that is visible in the Merchant Admin Interface (MAI).
You should consider providingriskData
Adding Risk Data
Provide additional information in the <riskData>
element to increase the chances that the shopper won't be challenged. <riskData>
contains three child elements:
Information about the shopper and how they are authenticating with Worldpay.
The <authenticationRiskData>
element contains:
Element | Description | Type |
---|---|---|
authenticationTimestamp | Date and time that you're submitting the authorisation. | WPG XML date/time format: specify sub-attributes second , minute , hour , dayOfMonth , month , year |
Attribute | Description | Type |
---|---|---|
authenticationMethod | The method used to authenticate the shopper. | Possible values:
|
Information about the shopper's account with you.
The <shopperAccountRiskData>
element contains:
Element | Description | Type |
---|---|---|
<shopperAccountCreationDate> | Date that the shopper opened the account with the merchant. | WPG XML date format: specify sub-attributes dayOfMonth , month , year |
<shopperAccountModificationDate> | Date that the shopper's account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added. | WPG XML date format: specify sub-attributes dayOfMonth , month , year |
<shopperAccountPasswordChangeDate> | Date that shopper's account with the merchant had a password change or account reset. | WPG XML date format: specify sub-attributes dayOfMonth , month , year . |
<shopperAccountShippingAddressFirstUseDate> | Indicates when the shipping address used for the transaction was first used. | WPG XML date format: specify sub-attributes dayOfMonth , month , year . |
<shopperAccountPaymentAccountFirstUseDate> | Date the payment account was added to the shopper account. | WPG XML date format: specify sub-attributes dayOfMonth , month , year . |
Attribute | Description | Type |
---|---|---|
transactionsAttemptedLastDay | Number of transactions (successful and abandoned) for this shopper account with the merchant across all payment accounts in the previous 24 hours. | Integer 0-999 |
transactionsAttemptedLastYear | Number of transactions (successful and abandoned) for this shopper account with the merchant across all payment accounts in the previous year. | Integer 0-999 |
purchasesCompletedLastSixMonths | Number of purchases with this shopper account during the previous six months. | Integer 0-999 |
addCardAttemptsLastDay | Number of Add Card attempts in the last 24 hours. | Integer 0-999 |
previousSuspiciousActivity | Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the shopper account. | Boolean (true or false ) |
shippingNameMatchesAccountName | Indicates if the cardholder name on the account is identical to the shipping name used for this transaction. | Boolean (true or false ) |
shopperAccountAgeIndicator | Indicates how long the shopper had the account with the merchant. | Possible Values: noAccount , createdDuringTransaction , lessThanThirtyDays , thirtyToSixtyDays , moreThanSixtyDays |
shopperAccountChangeIndicator | Length of time since the last change to the shopper's account. This includes billing or shipping address, new payment methods or new users added. | Possible values: changedDuringTransaction , lessThanThirtyDays , thirtyToSixtyDays , moreThanSixtyDays |
shopperAccountPasswordChangeIndicator | Indicates when the shopper's account password was last changed or reset. | Possible Values: noChange , changedDuringTransaction , lessThanThirtyDays , thirtyToSixtyDays , moreThanSixtyDays |
shopperAccountShippingAddressUsageIndicator | Indicates when the shipping address was first used. | Possible Values: thisTransaction , lessThanThirtyDays , thirtyToSixtyDays , moreThanSixtyDays |
shopperAccountPaymentAccountIndicator | Indicates when the payment account was first used. | Possibe Values: noAccount , duringTransaction , lessThanThirtyDays , thirtyToSixtyDays , moreThanSixtyDays |
Information about the order.
The <transactionRiskData>
element contains:
Element | Description | Type |
---|---|---|
<transactionRiskDataGiftCardAmount> | For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123 | Amount (value , currencyCode , exponent , <debitCreditIndicator> ) |
<transactionRiskDataPreOrderDate> | For a pre-ordered purchase, the expected date that the merchandise will be available. | Date |
Attribute | Description | Type |
---|---|---|
shippingMethod | Indicates shipping method chosen for the transaction. | Possible Values:
|
deliveryTimeframe | Indicates the delivery timeframe. | Possible values:
|
deliveryEmailAddress | For electronically delivered goods only. Email address to which the merchandise was delivered. | email address |
reorderingPreviousPurchases | Indicates whether the shopper is reordering previously purchased merchandise. | Boolean (true or false ) |
preOrderPurchase | Indicates whether shopper is placing an order with a future availability or release date. | Boolean (true or false ) |
giftCardCount | Total count of individual prepaid gift cards purchased. | Integer >=0 |
We also we recommend submitting the following additional data fields with HPP payment requests:
Note: Do not include a [<state>
] data field unless the billing or shipping address is domiciled within the United States or China. In this case the value is two-characters long as defined in the country subdivision code within the ISO-3611-2 specification. Only provide the two characters after US- or "CN-", for example FL for Florida and BJ for Beijing, etc.
Testing 3DS with HPP
Test card numbers
Use the below values in Card number:
Card type | Test card number |
---|---|
American Express | 343434343434343 |
Diners | 36700102000000 and 36148900647913 |
JCB | 3528000700000000 |
MasterCard | 5555555555554444, 5454545454545454 and 2221000000000009 |
MasterCard Debit | 5163613613613613 |
Visa | 4444333322221111, 4911830000000 and 4917610000000000 |
Visa Debit | 4462030000000000 and 4917610000000000003 |
Visa Electron (UK only) | 4917300800000000 |
Visa Purchasing | 4484070000000000 |
Magic values
Use the below values in Cardholder's name to simulate the different payment outcomes:
Magic value | Scenario simulated | Authentication Outcome | Payment Outcome |
---|---|---|---|
3DS_V1_CHALLENGE_IDENTIFIED | Successful challenge | Cardholder authenticated | AUTHORISED |
3DS_V1_CHALLENGE_NOT_IDENTIFIED | Successful challenge | Authentication offered but not used | AUTHORISED |
3DS_V1_CHALLENGE_VALID_ERROR | Challenge valid error | Authentication attempted but error | AUTHORISED |
3DS_V1_NOT_ENROLLED | Card not enrolled in 3DS1 | Authentication offered but not used (Non-Amex) None (Amex) | AUTHORISED |
3DS_V1_UNKNOWN_ENROLMENT | 3DS1 enrolment status unavailable (external/internal error) | Authentication Unavailable | AUTHORISED |
3DS_V1_CHALLENGE_UNKNOWN_IDENTITY | Challenge failed | Authentication attempted but failed | REFUSED |
3DS_V2_FRICTIONLESS_IDENTIFIED | Frictionless authentication | Cardholder authenticated | AUTHORISED |
3DS_V2_FRICTIONLESS_NOT_IDENTIFIED | Frictionless attempted (offered but not used) | Authentication offered but not used | AUTHORISED |
3DS_V2_FRICTIONLESS_REJECTED | Frictionless rejected | Authentication rejected | REFUSED |
3DS_V2_FRICTIONLESS_VALID_ERROR | 3DS2 frictionless authentication unavailable (external/internal error) | Authentication Unavailable | AUTHORISED |
3DS_V2_CHALLENGE_IDENTIFIED | Successful challenge | Cardholder authenticated | AUTHORISED |
3DS_V2_CHALLENGE_VALID_ERROR | Challenge valid error | Authentication attempted but error | AUTHORISED |
3DS_V2_CHALLENGE_UNKNOWN_IDENTITY | Challenge failed | Authentication attempted but failed | REFUSED |
3DS_BYPASSED | 3DS bypassed | none | AUTHORISED |
3DS_BYPASSED_AFTER_CHALLENGE | 3DS bypassed after challenge | none | AUTHORISED |