We have released a new version. Documentation for our latest version can be found here.
Last Updated: 08 October 2024 | Change Log
Testing
Test your 3DS integration on the Try environment using the magic values provided below. Send requests and see simulated responses.
Card number
Use different card numbers to test issuer responses.
If you're creating tokens containing the test card numbers you must delete the token before creating another with the same PAN (e.g. to try different cardholder names to change the 3DS outcome). You will be prevented from creating another token using the same PAN. As an alternative you can also change the namespace used as part of the token creation.
| Card type | Test card number |
|---|---|
| American Express | 343434343434343 |
| 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 |
Cardholder name
Use different cardholder names to alter the 3DS authentication outcome.
If an invalid 3DS magic cardholder value is used e.g. Bob Smith the default scenario 3ds2-challenge-identified is used.
3DS1
| Magic value Legacy values (to be phased out) | Description | Authentication outcome | Verification outcome | Liability shift | Authentication values |
|---|---|---|---|---|---|
3ds1-challenge-identified3DS_V1_CHALLENGE_IDENTIFIED | Customer enters correct challenge details. | challenged | authenticated | Yes |
|
3ds1-invalid-signature3DS_V1_INVALID_SIGNATURE | Invalid signature returned, authentication details should not be trusted. | challenged | signatureFailed | No | Various value combinations Recommendation: Do not proceed with authorization |
3ds1-challenge-unknown-identity3DS_V1_CHALLENGE_UNKNOWN_IDENTITY | Customer enters incorrect challenge details. | challenged | authenticationFailed | No |
|
3ds1-challenge-not-identified3DS_V1_CHALLENGE_NOT_IDENTIFIED | Challenge attempted but the card issuer doesn't support 3DS, card scheme provides authentication details for this case. | challenged | authenticated | Yes |
|
3ds1-not-enrolled 3DS_V1_NOT_ENROLLED | Issuer not enrolled for 3DS. | notEnrolled | N/A | No |
|
3ds1-authentication-unavailable 3DS_V1_UNAVAILABLE | Authentication unavailable. | unavailable | N/A | No | various values (e.g. version, eci) |
3ds1-verification-unavailable 3DS_V1_CHALLENGE_AUTH_UNAVAILABLE | Verification unavailable. | challenged | unavailable | No |
|
3ds1-bypassed 3DS_BYPASSED | 3DS check is bypassed. Returned if 3DS premium is enabled or when there is a timeout connecting to the 3DS directory server. | bypassed | N/A | No |
|
3DS2
| Magic value Legacy values (to be phased out) | Description | Authentication outcome | Verification outcome | Liability shift | Authentication values |
|---|---|---|---|---|---|
3ds2-frictionless-identified 3DS_V2_FRICTIONLESS_IDENTIFIED | Successful frictionless authentication. | authenticated | N/A | Yes |
|
| 3ds2-frictionless-failed 3DS_V2_FRICTIONLESS_FAILED | Failed frictionless authentication. | authenticationFailed | N/A | No |
|
3ds2-frictionless-not-identified 3DS_V2_FRICTIONLESS_NOT_IDENTIFIED | Attempted frictionless authentication. | authenticated | N/A | Yes |
|
3ds2-frictionless-unavailable 3DS_V2_FRICTIONLESS_UNAVAILABLE | Unavailable frictionless authentication from the issuer. | unavailable | N/A | No |
|
3ds2-frictionless-rejected 3DS_V2_FRICTIONLESS_REJECTED | Rejected frictionless authentication from the issuer. | authenticationFailed | N/A | No |
|
3ds2-authentication-unavailable 3DS_V2_AUTH_UNAVAILABLE | Authentication unavailable. | unavailable | N/A | No |
|
3ds2-challenge-identified 3DS_V2_CHALLENGE_IDENTIFIED | Customer enters correct challenge details. | challenged | authenticated | Yes |
|
3ds2-challenge-unknown-identity 3DS_V2_CHALLENGE_UNKNOWN_IDENTITY | Customer enters incorrect challenge details. | challenged | authenticationFailed | No |
|
3ds2-verification-unavailable 3DS_V2_CHALLENGE_UNAVAILABLE | Verification unavailable. | challenged | unavailable | No |
|
3ds2-bypassed 3DS_V2_BYPASSED | 3DS check bypassed. | bypassed | N/A | No |
|
3ds2-bypassed-after-challenge 3DS_V2_BYPASSED_AFTER_CHALLENGE | 3DS check bypassed. | challenged | bypassed | No |
|
Device data initialization
Submit the device data initialize request.
Add token resource or card details to the request as required.
Device Data Collection (DDC)
Using the device data initialization response values, POST the deviceDataCollection.jwt and deviceDataCollection.bin to the deviceDataCollection.url as per the DDC form details.
Authentication
Add the SessionId from the DDC postMessage to deviceData.collectionReference in the authentication request
Challenge
If the authentication response has an outcome value of challenged, you must POST the challenge.jwt to the location of the challenge.url. For more information see Challenge Display details.
The simulator POSTs back a standard response to the iframe. You are then presented with an OK button. Click the OK button to be redirected to your returnURL.
Verification
Once the challenge form is complete, you can send a verification request containing the original challenge.reference from the authentication response.
Payment Authorization
Depending on your outcome, use the values returned in the authentication object from your authentication or verification request in your payment authorize 3DS request.
Liability Shift
Liability shift is confirmed on payment authorization. The cardholder magic value tables detail the different scenarios and the likely liability shift based on the authentication details provided (e.g. authenticationValue, eci, transactionId).
Outcomes
Successful (e.g. 3ds1-challenge-identified, 3ds2-frictionless-identified), the full set of authentication values returned: version, eci, transactionId and authenticationValue.
Failure (e.g. 3ds2-frictionless-failed, 3ds2-frictionless-rejected), authentication values are returned but you should not proceed to authorization.
Edge cases (e.g. 3ds1-not-enrolled, 3ds2-authentication-unavailable), authentication values may be returned (e.g. version and eci). An authorization can be attempted using the values provided but the success of this varies based on the issuer or scheme. There is likely to be a decline in acceptance as PSD2 comes into affect. In most cases liability shift is not applied.