Integrated authentication

Overview

Integrated authentication follows the same steps as standalone authentication but with some differences in terms of data collection and evaluation.

Key differences from standalone:

• Single integration point: No need to integrate with separate payment processors.
• Reduced complexity: Fewer API calls and data handling steps.
• Built-in transaction processing: You can initiate transaction by just sending authentication id. We will get the authentication data automatically and use it in authorisation.
• Consolidated reporting: View both authentication and transaction data in one place.

Process

Integrated authentication follows these steps:

Step 1: Pre-initiation

You send a request to POST /v1/threedsecure/integrated/authentications with the transaction and card data. If you don't send a providerId, PXP evaluates which is the best provider for your transaction.

Step 2: Evaluation

You receive the authenticationId, threeDSecureSupported status, and scaMandated indicator.

Step 3: Authentication decision

Check the applicableExemptions and recommendedChallengeIndicator, then decide whether to proceed with authentication. Note that exemptions are applicable only if "scaMandated": true and PXP only evaluates whether low-value exemption (LVP) and/or transaction risk analysis (TRA) is applicable for the transaction (both exemptions can be applicable). You decide which exemption to apply and when (i.e., for authentication or authorisation) and whether to apply it all. If you apply the exemption directly for authorisation, then you have to accept the risk of a soft decline. If an exemption has been granted during authentication, the same exemption is going to be used for authorisation (managed by PXP).

Step 4: Fingerprinting

Fingerprinting isn't a required step, but by performing it you increase the chance for frictionless authentication.

Use threeDSecureFingerprintUrl and threeDSecureFingerprintData for device fingerprinting. If you receive empty fields, it means that the issuer doesn't support fingerprinting for the card and you should proceed to step 5.

1. Render a hidden HTML iframe in the cardholder's browser, with a form containing a field named threeDSMethodData with the extracted value from threeDSecureFingerprintData.
2. Submit the form via HTTP POST to the threeDSecureFingerprintUrl:

<form name="frm" method="POST" action="fingerprintCallbackUrl">
  <input type="hidden" name="threeDSMethodData"value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0" />
</form>

3. The issuer's ACS should respond with an HTTP POST with a threeDSMethodData field submitted to your fingerprintCallbackUrl. If the response isn't received within 10 seconds of the POST, you should consider the fingerprinting as unsuccessful and proceed to step 5.

<form name="frm" method="POST" action="RedirectUrl">
  <input type="hidden" name="threeDSMethodData"value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0" />
</form>

Step 5: Authentication

You send a request to PUT /authentications/{id}/browser-authentication with the requested challenge indicator and detailed transaction data. This request triggers the frictionless flow of the authentication with the issuer.

Check the state for the outcome. The possible values are:

• AuthenticationSuccessful: Authentication was successful. You can proceed with authorising the transaction by sending the authenticationId in the initiate transaction request.
• AuthenticationFailed: The authentication wasn't successful. It's not advisable to proceed with authorisation because there's no liability shift to the issuer. Check the state code and reason.
• AuthenticationError: An error occurredduring authentication. It's not advisable to proceed with authorisation because there's no liability shift to the issuer. Check the state code and reason.
• AuthenticationRejected: The authentication was rejected by the issuer. You can't proceed with authorisation.
• PendingCustomerChallenge: The authentication is stepped up to challenge, proceed with step 6.

Step 6: Challenge handling

Use the acsUrl and challengeData to re-direct the cardholder to the page of the issuer for authentication.

1. Create an HTML iframe in the cardholder's browser with a form containing a field named creq with the extracted value from challengeData. Note: this iframe/window is sized according to the value of challengeWindowSize sent in the authentication request.
2. Submit the form via HTTP POST to the ACS URL returned in the acsUrl field in order to display the challenge window.
3. Wait for the issuer's challenge response to the challengeCallbackUrl that was sent in the authentication request. This will contain a cres field which should be extracted and decoded from Base64 to string. If a response isn't received within 10 minutes, then the challenge process is considered unsuccessful.

{
  "threeDSServerTransID": "f7a91d6d-d00f-4452-bc3f-7fe993f2f1dd",
  "transStatus": "Y",
  "acsTransID": "1a70e471-1352-4e08-8f50-b6e3790aeac0",
  "messageType": "CRes",
  "messageVersion": "2.2.0"
}

Use the value in transStatus to re-direct the cardholder to the respective page for successful/unsuccessful authentication.

• If the authentication was successful, the transStatus is Y or A.
• If the authentication wasn't successful, the transStatus is any other value.

Webhook notifications

Configure callback URLs to receive real-time updates. Please note that the cardholderAuthenticationVerificationValue isn't sent in webhook notifications due to security reasons. Check the state for the outcome. Possible values:

• AuthenticationSuccessful: Authentication was successful. You can proceed with step 7: authorising the transaction.
• AuthenticationFailed: The authentication wasn't successful. It's not advisable to proceed with authorisation because there's no liability shift to the issuer. Check the state code and reason.
• AuthenticationError: An error occurredduring authentication. It's not advisable to proceed with authorisation because there's no liability shift to the issuer. Check the state code and reason.
• AuthenticationRejected: The authentication was rejected by the issuer. You can't proceed with authorisation.

Step 7: Authorisation

You can proceed with authorising the transaction by sending just the authenticationId in the initiate transaction request. We strongly recommend only authorising authenticated transactions. For more information about initiating transactions, see Card transaction and 3D Secure and PSD2.

Authentication flows

Authentication can take place through either:

• A frictionless flow, which is a cardholder-less, "invisible" flow.
• A challenge flow, which requires cardholder interaction for identification purposes.

A chargeback liability shift applies to transactions that are subsequently classified as fully 3DS2-authenticated.

Frictionless flow

The smoothest experience where authentication happens invisibly without customer interaction. This occurs when risk assessment determines no additional verification is needed.

Key benefits:

• Instant completion (< 1 second).
• No interruption to checkout.
• Higher conversion rates.
• Full liability shift protection.

How frictionless authentication works

1. Data collection: You send transaction data via the pre-initiate API.
2. Risk assessment: The Directory Server analyses over 100 data points including:
   • Device fingerprinting data.
   • Transaction history and patterns.
   • Your merchant risk profile.
   • The cardholder's behaviour patterns.
3. Decision: If the fraud risk is deemed low, then the authentication completes automatically.
4. Response: The CAVV and ECI values are provided immediately for payment authorisation.

When frictionless flow applies

• Low-risk transactions: Based on comprehensive risk analysis.
• Trusted devices: Previously authenticated devices with good history.
• Regular patterns: Transactions matching established cardholder behaviour.
• Low amounts: Transactions below risk thresholds. This varies by issuer.

Example frictionless response

{
  "uniqueId": "bc7a8a2b-ec7e-437d-a9e5-4cb62dd10bee",
  "state": "AuthenticationSuccessful",
  "transactionStatus": "Y",
  "electronicCommerceIndicator": "02",
  "exemptionGranted": false,
  "exemptionGrantedByIssuer": null,
  "acsUrl": null,
  "challengeData": null,
  "stateData": null,
  "cardholderInfo": null
}

Optimising for frictionless

To increase frictionless authentication rates:

• Collect comprehensive browser data, as more data points improve risk assessment.
• Use device fingerprinting.
• Maintain consistent merchant data.
• Implement a proper 3DS method.

Challenge flow

When additional verification is required, customers are redirected to their bank's authentication page to complete verification using methods like SMS, push notifications, or biometrics.

The flow is triggered by:

• High-risk transactions.
• Merchant preferences.
• Regulatory requirements (SCA).
• Issuer- or scheme-specific policies.
• New devices or unusual patterns.

Your integration automatically handles both flows, with PXP determining which is appropriate based on risk assessment and regulatory requirements.

How challenge authentication works

1. Challenge required: The ACS determines that frictionless authentication is insufficient.
2. Challenge setup: You receive an acsUrl and challengeData from the authentication response.
3. Customer redirect: The cardholder is redirected to the issuer's authentication page.
4. Verification methods: The cardholder completes verification using:
   • An SMS OTP (One-Time Password).
   • Push notifications to their banking app.
   • Biometric authentication.
   • Hardware tokens.
5. Result communication: The authentication result is sent back to you.
6. Completion: The final authentication data is provided for payment processing.

Example challenge response

{
  "uniqueId": "24621597-87d5-4e55-917a-f2086e1cf536",
  "state": "PendingCustomerChallenge",
  "transactionStatus": "C",
  "electronicCommerceIndicator": null,
  "exemptionGranted": false,
  "exemptionGrantedByIssuer": null,
  "acsUrl": "https://acs.revolut.com/challenges/browser",
  "challengeData": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyN2ZhN2U2Yy1iY2NkLTQwM2YtOGRiYS1hNTU2NzA1N2JlNTkiLCJhY3NUcmFuc0lEIjoiYzkyYTM3ZmUtNTg2Mi00NWEyLWEzNWMtNjM5Y2RkNmMwY2FkIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0",
  "stateData": null,
  "cardholderInfo": null
}

Challenge window sizes

When you initiate an authentication, you can configure the challenge display size based on your integration using the challengeWindowSize parameter.

It accepts the following values:

Scheme requirements

Since 12 August 2024, Visa requires the following fields:

• In the pre-initiation request: cardData.card.holderName.
• In the initiation request:
  • One of the following: shopper.email, shopper.workPhoneNumber, shopper.homePhoneNumber, or shopper.mobilePhoneNumber
  • browserData.screenHeight
  • browserData.screenWidth
  • browserData.ipAddress

In addition to this, providing all cardholder billing address information in the billingAddress object is highly recommended.