@basis-theory/web-要素

安全、符合PCI的iframe元素,用于在网络应用程序中收集敏感数据。 卡片数据从不触及您的服务器.

安装

无

npm install @basis-theory/web-elements@beta

线条

yarn add @basis-theory/web-elements@beta

光盘N

<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>

快速启动

import BasisTheory from '@basis-theory/web-elements';

// Initialize (synchronous -- returns immediately)
const bt = BasisTheory('pk_test_...');

// Create elements
const cardNumberEl = bt.createElement('cardNumber', {
  placeholder: '4242 4242 4242 4242',
});
const expiryEl = bt.createElement('expiry', {
  placeholder: 'MM/YY',
});
const cvvEl = bt.createElement('cvv', {
  placeholder: '123',
});

// Mount to DOM (async -- creates secure iframes)
await Promise.all([
  cardNumberEl.mount('#card-number'),
  expiryEl.mount('#expiry'),
  cvvEl.mount('#cvv'),
]);

// Listen for validation changes
cardNumberEl.on('change', (event) => {
  console.log('Valid:', event.detail.isValid);
  console.log('Brand:', event.detail.cardBrand);
});

// Tokenize on form submission
const token = await bt.tokens.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

console.log('Token ID:', token.id);

CDN 使用量

<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', async () => {
    const bt = BasisTheory('pk_test_...');

    const cardNumberEl = bt.createElement('cardNumber');
    const expiryEl = bt.createElement('expiry');
    const cvvEl = bt.createElement('cvv');

    await Promise.all([
      cardNumberEl.mount('#card-number'),
      expiryEl.mount('#expiry'),
      cvvEl.mount('#cvv'),
    ]);
  });
</script>

元素类型

共享选项

所有元素类型在 createElement() 财务报告和审定财务报表 element.update()数字 :

文本元素选项

CVV 元素选项

方法

每个元素都暴露出相同的界面:

属性 : id (弦声), type (ElementType), (英语), mounted (boolean) (布尔语).

活动

更改事件有效载荷

所有要素都包括下列领域: event.detail数字 :

这个 cardNumber 元素添加: cardBrand, (中文(简体) ), last4, (中文(简体) ), bin, (中文(简体) ), cvvLengths, (中文(简体) ), potentialBrands,以及 matchStrength。 。 。 .

cardNumberEl.on('change', (event) => {
  const { isValid, cardBrand, last4 } = event.detail;
  console.log(`${cardBrand} ...${last4}`, isValid);
});

错误事件代码

SDK 选项

const bt = BasisTheory('pk_test_...', {
  debug: false,            // Enable verbose debug logging
  themeMode: 'auto',       // 'light' | 'dark' | 'auto'
  theme: { /* ThemeTokens */ },
  darkTheme: { /* ThemeTokens */ },
  timeoutMs: 30000,        // PostMessage timeout (ms)
});

服务

符号

// Create a token
const token = await bt.tokens.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

// Retrieve a token
const retrieved = await bt.tokens.retrieve(token.id, {
  apiKey: sessionApiKey, // from an authorized session
});

// Update a token
await bt.tokens.update(token.id, {
  metadata: { source: 'updated' },
});

// Encrypt with client-side JWE
const encrypted = await bt.tokens.encrypt(
  { type: 'card', data: { number: cardNumberEl, cvc: cvvEl } },
  publicKeyPEM,
  'key-id-123'
);

符号化

const result = await bt.tokenize({
  number: cardNumberEl,
  cvv: cvvEl,
  expiry: expiryEl,
});

符号意向

const intent = await bt.tokenIntents.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

const retrieved = await bt.tokenIntents.get(intent.id);

会议

const session = await bt.sessions.create();
// Send session.nonce to your backend to authorize
// Backend returns an apiKey for elevated access

const token = await bt.tokens.retrieve(tokenId, {
  apiKey: sessionApiKey,
});

他们

初始化时通过设计符和运行时切换模式 :

const bt = BasisTheory('pk_test_...', {
  themeMode: 'auto',
  theme: {
    colors: {
      primary: '#007bff',
      error: '#dc3545',
      success: '#28a745',
      text: { primary: '#1a1a1a', placeholder: '#6c757d' },
      background: { default: '#ffffff' },
      border: { default: '#dee2e6', focus: '#007bff' },
    },
    typography: {
      fontFamily: 'Inter, sans-serif',
      fontSize: { base: '16px' },
      fontWeight: { normal: '400' },
    },
    spacing: { sm: '8px', md: '12px', lg: '16px' },
    borders: {
      radius: { base: '6px' },
      width: { base: '1px' },
    },
  },
});

// Switch theme mode at runtime
await bt.updateThemeMode('dark');

类型脚本

货包船的完整类型定义. 主要出口:

import type {
  BasisTheorySDK,
  Element,
  ElementType,
  ElementOptions,
  SDKOptions,
  ChangeEventDetail,
  CardNumberChangeEventDetail,
  ReadyEventDetail,
  ErrorEventDetail,
  ErrorCode,
  ValidationError,
  TokenizeResult,
  Session,
} from '@basis-theory/web-elements';

文档

完整文档: https://developers.basistheory.com/docs/sdks/web/web-elements/ 页面存档备份,存于互联网档案馆

• 开始
• 元素类型
• 活动
• 服务
• 他们
• 迁移指南(v2到v3)

许可证

阿帕奇 - 2.0