Enable 3D Secure (3DS) authentication on the Priority Vault widget to verify a cardholder's identity at the time of vaulting — ensuring that only authenticated cards are stored against a customer profile.

📘

When 3DS is enabled for card vaulting, authentication occurs before the card is tokenized and stored. This protects your vault from unauthorized card additions and reduces the risk of fraudulent use of stored payment methods.

Prerequisites

Before enabling 3DS on Priority Vault, ensure the following are in place:

How 3DS Works in Priority Vault

3DS authentication during vaulting follows a distinct flow from payment-time authentication. The goal is to verify the cardholder's identity before the card is stored — not at the point of payment.

1. When a customer submits their card details in the Vault widget, the widget collects browser and device signals and initiates a 3DS authentication session.
2. If the issuer grants frictionless authentication, the card is tokenized and stored immediately — no customer action is required.
3. If the issuer requires a challenge, the widget renders the challenge modal inline within the vault interface. The customer completes the challenge before the card is stored.
4. Upon successful authentication, the card is tokenized and the token is associated with the customer profile in Priority Vault.
5. You receive the vault result via the onSuccess callback, along with the 3DS authentication outcome.
6. The stored token can then be used for future payments without re-authenticating the cardholder via 3DS.

Enable 3DS on Priority Vault

Pass the threeDSecure configuration object when initializing the Vault widget via WidgetSDK.create(). When enabled is set to true, 3DS authentication is triggered automatically before the card is vaulted.

const widget = WidgetSDK.create('VAULT', {
  clientSecret: clientSecret,
  containerId: '#vault-container',
  businessId: 'biz_123',
  customer: {
    id: 'cust_abc123'             // Required — card is vaulted against this customer profile
  },
  threeDSecure: {
    enabled: true                 // Enables 3DS authentication before card is tokenized
  },
  onSuccess: (result) => {
    console.log('Card vaulted successfully:', result.card.token);
    console.log('3DS status:', result.threeDSecure.authenticationStatus);
  },
  onError: (error) => {
    console.error('Vaulting error:', error.message);
  }
});

3DS Configuration Reference

onSuccess Response — Card Vaulted with 3DS

When 3DS is enabled, the onSuccess payload includes the vaulted card token alongside the 3DS authentication result.

{
  "widgetType": "VAULT",
  "status": "SUCCESS",
  "timestamp": 1774522622702,
  "actions": [
    "CARD.VAULT"
  ],
  "data": {
    "card": {
      "id": "10000000598951",
      "token": "TYT13KSQEBUA8FA3J6CW2ATUADV6KEIH",
      "brand": "VISA",
      "last4": "1111",
      "type": "CREDIT",
      "name": "Jane Smith",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "isDefault": false
    },
    "threeDSecure": {
      "eci": "05",
      "authenticationStatus": "Y",
      "liabilityShift": true
    },
    "customer": {
      "id": "cust_abc123"
    }
  }
}

3DS Response Fields

Using the Vaulted Token for Future Payments

Once a card is vaulted with successful 3DS authentication, use the returned token to submit future payments via the MX Checkout API. You do not need to re-run 3DS for recurring or credential-on-file transactions using this token, provided you pass the correct posData context.

{
  "amount": "75.00",
  "tenderType": "CARD",
  "merchantId": "4007497",
  "cardAccount": {
    "token": "TYT13KSQEBUA8FA3J6CW2ATUADV6KEIH"
  },
  "posData": {
    "cardholderPresence": "NotPresent",
    "panCaptureMethod": "Manual",
    "deviceAttendance": "VoiceAru",
    "deviceInputCapability": "VoiceAru",
    "deviceLocation": "VoiceAru",
    "partialApprovalSupport": "NotSupported",
    "transactionStatus": "Normal"
  },
  "cardPresent": false,
  "authorizationIndicator": "Final"
}

📘

For recurring or subscription payments using a vaulted token, always set posData.cardholderPresence to NotPresent and posData.transactionStatus to Normal. See Transaction Context (CNP) for the full POS data configuration.

Authentication Outcomes During Vaulting

⚠️

Cards where authentication status is N or R are not stored in the vault. The onError callback fires and the customer must retry with a different card or payment method.

Testing 3DS on Priority Vault

Use the sandbox environment to test 3DS vaulting flows before going live.

• In the sandbox, the challenge modal renders a simulated challenge screen. Enter any 6-digit OTP to complete the challenge and proceed with vaulting.
• Confirm the card.token is returned in the onSuccess payload for all successful authentication outcomes.
• Confirm onError fires for N (failed) and R (rejected) outcomes — no token should be returned.
• Use the 3DS test cards to simulate each authentication outcome.

📘

For the full 3DS test card reference, see 3D Secure Authentication — Sandbox Testing.

See Also

• 3D Secure (3DS) Authentication
• Enabling 3DS for Payments
• Priority Vault (Tokenization)
• Card Vaulting
• Transaction Context (CNP)
• ECI Codes
• Card Test Data