@ basis-理论/反应要素

与 Basid Theory Elements v3 反应用于收集敏感数据的组件. 安全 PCI 兼容 iframes 包裹为 React 组件 有钩子, refs,以及打出的事件处理器.

安装

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

@basis-theory/web-elements 是一个依赖,将自动安装.

反应16.8+,17,18,19得到支持.

快速启动

import { useState, useRef } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  ExpiryElement,
  CVVElement,
  useBasisTheory,
} from '@basis-theory/react-elements';

function PaymentForm() {
  const { bt, error } = useBasisTheory();
  const cardNumberRef = useRef(null);
  const expiryRef = useRef(null);
  const cvvRef = useRef(null);

  const [cardNumberValid, setCardNumberValid] = useState(false);
  const [expiryValid, setExpiryValid] = useState(false);
  const [cvvValid, setCvvValid] = useState(false);

  const allValid = cardNumberValid && expiryValid && cvvValid;

  if (error) return <div>Failed to load payment form.</div>;

  const handleSubmit = async (e) => {
    e.preventDefault();

    const token = await bt.tokens.create({
      type: 'card',
      data: {
        number: cardNumberRef.current,
        expiration_month: expiryRef.current,
        expiration_year: expiryRef.current,
        cvc: cvvRef.current,
      },
    });

    // Send token.id to your backend
    console.log('Token created:', token.id);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement
        ref={cardNumberRef}
        placeholder="4242 4242 4242 4242"
        onChange={(event) => setCardNumberValid(event.detail.isValid)}
      />
      <ExpiryElement
        ref={expiryRef}
        placeholder="MM/YY"
        onChange={(event) => setExpiryValid(event.detail.isValid)}
      />
      <CVVElement
        ref={cvvRef}
        placeholder="123"
        onChange={(event) => setCvvValid(event.detail.isValid)}
      />
      <button type="submit" disabled={!allValid}>Pay</button>
    </form>
  );
}

export default function App() {
  return (
    <BasisTheoryProvider apiKey="pk_test_...">
      <PaymentForm />
    </BasisTheoryProvider>
  );
}

构成部分

基础理论

初始化SDK,并通过React Context提供给子组件. 所有组件和 useBasisTheory 钩子必须是这个提供者的后代.

<BasisTheoryProvider
  apiKey="pk_test_..."
  options={{
    debug: true,
    themeMode: 'auto',
    theme: { /* ThemeTokens */ },
  }}
  errorFallback={<div>Something went wrong.</div>}
>
  {children}
</BasisTheoryProvider>

卡片编号元素

有Luhn验证和品牌检测的安全卡号输入.

<CardNumberElement
  ref={cardNumberRef}
  placeholder="4242 4242 4242 4242"
  ariaLabel="Card number"
  disabled={false}
  readOnly={false}
  onChange={(event) => console.log(event.detail.isValid)}
  onReady={(event) => console.log('Ready')}
  onFocus={(event) => console.log('Focused')}
  onBlur={(event) => console.log('Blurred')}
  onError={(event) => console.error(event.detail.code)}
  className="my-card-input"
  containerStyle={{ border: '1px solid #ccc' }}
/>

过期

安全过期日输入(MM/YY格式).

<ExpiryElement
  ref={expiryRef}
  placeholder="MM/YY"
  onChange={(event) => console.log(event.detail.isValid)}
/>

简历

安全CVV/CVC输入. 当一个 CardNumberElement 在同一页(Visa/Mastercard3个数字,Amex4个数字).

<CVVElement
  ref={cvvRef}
  placeholder="123"
  onChange={(event) => console.log(event.detail.isValid)}
/>

文本元素

任何敏感值(SSN,账号等)的通用安全文本输入.

<TextElement
  ref={textRef}
  placeholder="###-##-####"
  mask={[/\d/, /\d/, /\d/, '-', /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
  transform={[/-/g, '']}
  validation={/^\d{9}$/}
  password={false}
  inputMode="numeric"
  required={true}
  maxLength={11}
  onChange={(event) => console.log(event.detail.isValid)}
/>

纸牌元素

将卡号,过期,CVV合并成一元的统一卡元.

<CardElement
  ref={cardRef}
  placeholder={{
    cardNumber: '4242 4242 4242 4242',
    expiryDate: 'MM/YY',
    cvc: '123',
  }}
  layout="auto"
  stackAt={400}
  iconPosition="right"
  onChange={(event) => console.log(event.detail.isValid)}
/>

共享元素道具

所有元素组件接受:

钩子

使用基准理论

从下方的任何组件访问 SDK 实例 BasisTheoryProvider。 。 。 .

import { useBasisTheory } from '@basis-theory/react-elements';

function MyComponent() {
  const { bt, error } = useBasisTheory();

  if (error) return <div>SDK failed to initialize.</div>;
  if (!bt) return <div>Loading...</div>;

  const handleTokenize = async () => {
    const token = await bt.tokens.create({
      type: 'card',
      data: { number: cardNumberRef.current },
    });
  };
}

回返 { bt: BasisTheorySDK | null, error: Error | null }。 。 。 .

查找方法

所有元素校正都暴露出这些方法和属性:

CardNumberElementRef 添加: cardBrand, (中文(简体) ), last4, (中文(简体) ), bin。 。 。 .

CardElementRef 添加: cardBrand, (中文(简体) ), last4, (中文(简体) ), bin, (中文(简体) ), errors, (中文(简体) ), number, (中文(简体) ), expiryDate, (中文(简体) ), cvc。 。 。 .

类型脚本

所有组件全部输入。 导入参考类型 useRef数字 :

import { useRef } from 'react';
import type {
  CardNumberElementRef,
  CVVElementRef,
  ExpiryElementRef,
  TextElementRef,
  CardElementRef,
} from '@basis-theory/react-elements';

const cardNumberRef = useRef<CardNumberElementRef | null>(null);
const cvvRef = useRef<CVVElementRef | null>(null);
const expiryRef = useRef<ExpiryElementRef | null>(null);

事件处理器类型也可用:

import type {
  ChangeEventDetail,
  CardNumberChangeEventDetail,
  CardElementChangeEventDetail,
  ReadyEventDetail,
  ErrorEventDetail,
  FocusEventDetail,
} from '@basis-theory/react-elements';

文档

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

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

许可证

阿帕奇 - 2.0