web-threeds

概览

网络三德软件包是一个JavaScript/TypeScript库,旨在简化网络应用程序中3DS(3D Security)认证程序的实施. 它为处理3DS进程的会话创建和质疑步骤提供了简化的界面.

网络三德软件包揭露出两种主要方法: createSession 财务报告和审定财务报表 startChallenge这些方法有助于启动和处理3DS会议和挑战.

方法

createSession

createSession({ pan }: Create3dsSessionRequest): Promise<Create3dsSessionResponse>

这种方法启动一个3DS会话,用提供的 PAN(Prime Account Number)向服务器提出请求. 它返回一个解析 Creat3dsSessionResponse 对象的保证,其中包含会话细节 .

startChallenge

startChallenge(options: ThreeDSChallengeRequest): Promise<void>

这种方法通过向ACS(Access Control Server)提出附带必要参数的请求开始3DS挑战. 它处理挑战过程并回报一个承诺.

用法实例

创建 3DS 会话

import { BasisTheory3ds } from '3ds-web';

const apiKey = 'your_api_key';
const { createSession } = BasisTheory3ds(apiKey);

const session = await createSession({
  pan: '<BASIS_THEORY_TOKEN_ID>',
});

开始挑战

import { BasisTheory3ds } from '3ds-web';

const apiKey = 'your_api_key';
const { startChallenge } = BasisTheory3ds(apiKey);

await startChallenge({
  sessionId: 'session_id',
  acsTransactionId: 'acs_transaction_id',
  acsChallengeUrl: 'acs_challenge_url',
  threeDSVersion: '2.2.0',
  windowSize: '05', // Optional, defaults to 'THREE'
});

处理错误

两者 createSession 财务报告和审定财务报表 startChallenge 可能会出错,包括出错的细节.

• API 错误 (从) createSession)作为有包含3DS服务的全部错误细节的额外属性的出错对象返回
• 挑战错误 (从) startChallenge)作为标准错误对象和描述性信件返回

错误结构

try {
  const session = await createSession({ tokenId: 'token_id' });
} catch (error) {
  // Error object properties:
  console.log(error.message); // Human-readable error message
  console.log(error.title); // Error title (e.g., "3DS Service Error")
  console.log(error.status); // HTTP status code (e.g., 424)
  console.log(error.detail); // Detailed description

  // Nested error object with additional context (normalized to camelCase):
  if (error.error) {
    console.log(error.error.serviceStatus); // HTTP status from 3DS service (e.g., "403")
    console.log(error.error.sessionId); // Session ID for debugging
    console.log(error.error.errorSource); // Which service failed (e.g., "3DS Server", "ACS")
    console.log(error.error.message); // Detailed error message
    console.log(error.error.detail); // Additional error context
  }
}

常见错误设想

1. 3DS服务出错(现状424)

当3DS服务或发卡器返回出错时,这些出错发生:

try {
  const session = await createSession({ tokenId: 'token_id' });
} catch (error) {
  if (error.status === 424) {
    // Handle 3DS service errors
    switch (error.error?.serviceStatus) {
      case '403':
        // Access denied by issuer
        console.log('Merchant configuration issue:', error.error.detail);
        break;
      case '401':
        // Authentication failed
        console.log('Authentication failed:', error.error.message);
        break;
      default:
        console.log('3DS service error:', error.message);
    }
  }
}

2. 验证错误(现状400)

这些错误发生在请求参数无效时 :

try {
  const session = await createSession({ tokenId: 'invalid_token' });
} catch (error) {
  if (error.status === 400) {
    console.log('Validation error:', error.message);
  }
}

示例:综合错误处理

import { BasisTheory3ds } from '@basis-theory/web-threeds';

const bt3ds = BasisTheory3ds('your_api_key');

try {
  const session = await bt3ds.createSession({ tokenId: 'token_id' });

  // Continue with challenge if needed
  try {
    await bt3ds.startChallenge({
      sessionId: session.id,
      acsTransactionId: 'acs_transaction_id',
      acsChallengeUrl: 'acs_challenge_url',
      threeDSVersion: '2.2.0',
    });
  } catch (challengeError) {
    // Handle challenge-specific errors
    console.error('Challenge error:', challengeError.message);
    if (challengeError.message.includes('Timed out')) {
      showErrorToUser('Challenge timed out. Please try again.');
    } else if (challengeError.message.includes('Invalid challenge request')) {
      showErrorToUser('Invalid challenge configuration.');
    } else {
      showErrorToUser('Challenge failed. Please try again.');
    }
    throw challengeError; // Re-throw to outer catch
  }
} catch (error) {
  // Log full error details for debugging
  console.error('3DS Error:', {
    message: error.message,
    title: error.title,
    status: error.status,
    detail: error.detail,
    error: error.error,
  });

  // Determine action based on error type
  if (error.status === 424 && error.error?.errorSource === '3DS Server') {
    // Merchant configuration issue - contact support
    showErrorToUser(
      'Payment authentication unavailable. Please try a different card.'
    );
  } else if (error.status === 424 && error.error?.errorSource === 'ACS') {
    // Issuer authentication issue
    showErrorToUser('Card authentication failed. Please contact your bank.');
  } else if (error.status === 400) {
    // Validation error
    showErrorToUser('Invalid card information. Please check and try again.');
  } else {
    // Generic error (could be challenge error or session error)
    showErrorToUser('An error occurred. Please try again later.');
  }
}

配置选项

挑战请求

challengeContainerOptions 允许您自定义 id 3DS 挑战容器的属性,这样您就可以使用 CSS 设定目标并应用样式。 它可以使3DS挑战界面在您的应用的布局中精确定位.

const { startChallenge } = BasisTheory3ds(apiKey, {
  challengeConfigurationOptions: {
    id: 'customId',
  },
});