Views:

Introduction

Use this article to quickly set up Payer Authentication (3‑D Secure) with CyberSource and troubleshoot common enrollment failures. Before starting integration, ensure you have completed all prerequisites with CyberSource and your acquirer. For full implementation details, refer to the Payer Authentication Developer Guide (PDF).

Prerequisites

Before configuring Payer Authentication with your web host, shopping cart, or integration:

  1. Contract and sign Payer Authentication (3DS) with CyberSource.
  2. Configure 3DS in the Enterprise Business Center (EBC).
  3. Confirm your acquirer supports 3DS for your merchant account.
  4. Contact Client Services to verify your setup.
    📄 How to Contact Client Services

Procedure

1. Understand the 3DS Enrollment Flow

The standard API integration for 3DS includes these steps:

  1. Setup Service – Run after card number entry to receive a JSON Web Token (JWT), reference ID, and device data collection URL.
  2. Device Data Collection – Use a hidden iframe to collect browser/device information. Complete before enrollment check.
  3. Check Enrollment – Determine if the card is enrolled and whether a challenge is needed.
  4. Step‑Up Authentication (if required) – Display the issuer’s challenge window within 30 seconds of the enrollment check.
  5. Validation Service (only if step‑up occurred) – Confirm authentication results.
  6. Authorization – Send 3DS authentication values with the authorization request for liability shift.

📄 For mobile SDK integrations, the Setup Service is not required. The SDK handles device data collection internally.

2. Common Causes of Enrollment Failure

  • Merchant account not configured for 3DS in EBC.
  • Acquirer not enabled for 3DS.
  • Unsupported card type or BIN range.
  • Unsupported currency.
  • Issuer not participating in 3DS.
  • 3DS version mismatch between merchant and issuer.
  • Card number formatting errors (Luhn check, invalid length).
  • Device data collection not completed before enrollment check.
  • Missing required API fields (returnURL, billing info, browser fields).
  • Step‑up iframe not initiated within 30 seconds of enrollment check.
  • Using test credentials in production or vice versa.
  • Network or API endpoint errors.

3. Troubleshoot by Reason Code

Use the table below to identify and resolve issues based on the reason code in the API response.

Reason CodeDescriptionAction
100Successful transactionProceed to authorization with 3DS fields for liability shift.
101Missing required field(s)Check missingField in the response, add data, and retry.
102Invalid field dataCheck invalidField in the response, correct format, and retry.
150General system failureRetry after a few minutes; contact support if persistent.
151Server timeoutRetry after short delay.
152Service timeoutRetry after short delay.
234Merchant configuration errorContact Client Services; do not retry until configuration is corrected.
475Enrolled – authentication requiredInitiate Step‑Up Iframe, complete challenge, validate, then authorize.
476Cannot be authenticatedDecline; request alternate payment method.

Related Information