# @gr4vy/embed-react 中文文档

规范地址：https://npmcn.com/package/%40gr4vy/embed-react/

版本：2\.44\.0
npm 元数据更新时间：2026-09-22T15:12:50.415Z
中文译文更新时间：2026-11-16T21:31:12.421Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gr4vy/embed-react
原文对照：https://npmcn.com/package/%40gr4vy/embed-react/?lang=original
项目主页：https://gr4vy.com/
源码仓库：https://github.com/gr4vy/gr4vy-embed

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：88.8 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18\.3\.1，react-dom \>=18\.3\.1
- 首次发布：2020-12-31T00:38:40.645Z
- 最新版本发布：2026-09-22T15:12:50.052Z
- 近 30 天下载量：23478（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：138（近 12 个月 11 个）

## 中文简介

在您的 React app 中嵌入信用卡表格并存储卡片细节,授权卡片,并抓取交易.

## 安装

```sh
npm install @gr4vy/embed-react
```

也可以使用：`pnpm add @gr4vy/embed-react`、`yarn add @gr4vy/embed-react`、`bun add @gr4vy/embed-react`

## README

# Gr4vy 嵌入反应

![NPM Version](https://img.shields.io/npm/v/@gr4vy/embed-react?color=green&style=for-the-badge) ![License](https://img.shields.io/npm/l/@gr4vy/embed-react?style=for-the-badge)

快速将Gr4vy嵌入您的 React app 存储卡片细节, 授权支付,并获取交易.

使用 [`@gr4vy/embed`](https://npmcn.com/package/%40gr4vy/embed) 在非反应应用程序中.

## 使用量

通过命令行,将这个软件包安装如下.

```bash
npm install @gr4vy/embed-react --save-prod
# pnpm add @gr4vy/embed-react --save
```

## 开始吧

要使用 Gr4vy Embed,请导入 `Gr4vyEmbed` 组件.

```js
const Gr4vyEmbed = require("@gr4vy/embed-react")
// import Gr4vyEmbed from "@gr4vy/embed-react"

<Gr4vyEmbed
  gr4vyId='[GR4VY_ID]'
  token='[TOKEN]'
  amount={1299}
  currency='USD'
  country='US'
  form='#payment-form'
/>
```

> **说明**替换 `[GR4VY_ID]` 财务报告和审定财务报表 `[TOKEN]` 以您本人的身份 和JWT访问标志。 看到我们的任何 [服务器侧 SDKs 软件](https://github.com/gr4vy?q=sdk) 更多细节.

### 表单

Gr4vy Embed 期待 HTML 窗体的查询会附加自己. 这个 此元素的值是一个可解析的查询字符串 `document.querySelector`。例如 `<form id="cardform">` 这将是 代表 `#cardform`。 。 。 .

| HTML 元素 | 示例 | 说明 |
| --- | --- | --- |
| `form` | `#order` | 指定 HTML `<form>` 元素或查询元素以附加附加输入。 Gr4vy 将自动在此表格中插入隐藏的输入字段,其中包含交易ID. |

### 选项

这一一体化的备选方案如下.

| 外地 | 默认 | 说明 |
| --- | --- | --- |
| `amount` | `null` | 授权或扣押的金额 `currency`仅此而已. |
| `apiHost` | `null` | **有时需要** - Gr4vy API 服务器的主机(主机名和端口) 使用时可省略 `gr4vyId` 选项. |
| `buyerExternalIdentifier` | `null` | 一个Gr4vy买家的可选外部ID. 交易将自动与持有该外部身份证的买方挂钩。 如果不存在持有这种外部身份证的买方,则将不予理睬。 如果 `buyerId` 提供. |
| `buyerId` | `null` | Gr4vy买家的可选身份证. 交易将自动与持有该身份证的买方相关联。 如果不存在持有这种身份证明的买方,则将不予理睬. |
| `buyer` | `null` | 代表买方的可选标物(个人细节、账单细节和货运信息). |
| `country` | `null` | **需求** 一个有效的 `ISO 3166` 国家代码. |
| `currency` | `null` | **需求** 有效、活跃、3个特征 `ISO 4217` 用于授权或捕捉 `amount` 为. |
| `environment` | `production` | 请求的环境。 可能会 `sandbox` 或者说 `production`。 。 。 . |
| `externalIdentifier` | `null` | 可提供的可选外部标识符 。 这将自动与 Gr4vy 创建的任何资源相链接, 并随后可用于通过该 ID 查找资源 |
| `gr4vyId` | `null` | **经常需要** Gr4vy ID 自动设置 `apiHost` 改为 `api.<gr4vyId>.gr4vy.app` 财务报告和审定财务报表 `iframeHost` 改为 `embed.<gr4vyId>.gr4vy.app`。 。 。 . |
| `iframeHost` | `null` | **有时需要** - 服务器主机(主机名和端口),主机为Gr4vy支付表. 使用时可省略 `gr4vyId` 选项. |
| `intent` | `authorize` | `authorize`, (中文(简体) ), `preferAuthorize`, (中文(简体) ), `capture` - 定义API呼叫的意图。 这决定了想要的交易初始状态. 当使用时, `preferAuthorize` 自动切换到 `capture` 如果选中的支付方法不支持延迟捕获. |
| `locale` | `en` | 一个可选的地块,它由 `ISO 639 Language Code` 之后是可选 `ISO 3166 Country Code`,比如说. `en`, (中文(简体) ), `en-gb` 或者说 `pt-br`。 。 。 . |
| `onEvent` | `null` | 一个可选的事件处理器来绑定窗体. 需要开展各种活动,下文将进一步阐述. |
| `store` | `ask` | `'ask'`, (中文(简体) ), `'preselect'`, (中文(简体) ), `true`, (中文(简体) ), `false` - 明确储存付款方法,询问买方,或默认预先选择。 要求数 `buyerId` 或者说 `buyerExternalIdentifier`。 。 。 . |
| `theme` | `null` | 主题自定义选项( 见 Theming) |
| `token` | `null` | **需求** - 服务器端生成了 JWT 令牌,用于认证任何API 呼叫. |
| `onComplete` | `null` | 用交易对象召回。 (表格提交必须手工处理) |
| `display` | `all` | `all`, (中文(简体) ), `addOnly`, (中文(简体) ), `storedOnly`, (中文(简体) ), `supportsTokenization` - 过滤支付方法,仅显示存储方法,仅显示新的支付方法或支持符号化的方法. |
| `customOptions` | `null` | 自定义选项列表 。 譬如说. `[{ label: 'Giftcard', method: 'giftcard', description: 'You will be asked for a giftcard code.', iconUrl: 'data:image/svg+xml,...'}]` |
| `onCustomSubmit` | `null` | 选择自定义支付选项并提交表格时召回 . |
| `metadata` | `Object` | 交易元数据密钥/值的可选对象 。 所有值都应该是一个字符串. |
| `paymentSource` | `null` | `installment`, (中文(简体) ), `moto`, (中文(简体) ), `recurring` - 可用于表示Embed用于获取订阅或分期付款的第一个交易。 当使用时, `store` 被暗示为 `true` 财务报告和审定财务报表 `display` 被暗示为 `supportsTokenization`。这意味着不支持符号化的支付选项是自动隐藏的. |
| `cartItems` | `Array` | 每个对象必须定义一个 `name`, (中文(简体) ), `quantity`,以及 `unitAmount`。 。 。 . |
| `statementDescriptor` | `Object` | 买方在银行对账单中会看到含有购买信息以构建报表信息的可选对象。 请注意,对这些领域的支持因支付服务提供商和基本银行而异,因此Gr4vy只能确保每个受支持的平台采取最佳努力方式.  
举例来说,大多数平台只会支持对 `name` 财务报告和审定财务报表 `description` 字段,缩短为22个字符.  
对象可以包含 `name`, (中文(简体) ), `description`, (中文(简体) ), `phoneNumber`, (中文(简体) ), `city` 财务报告和审定财务报表 `url` 键,带有字符串值. `phoneNumber` 应采用E164格式。 Gr4vy 建议避免在字母数字范围外的字符和点(`.`确保广泛的兼容性. |
| `secure` | `true` | 强制 iframeHost 和 apiHost 使用的可选布尔 `https` 默认协议。 这对地方发展有用,使用 `http` 协议. |
| `requireSecurityCode` | `false` | 一个可选的布林,它迫使安全代码用于存储的卡片付款. |
| `popupTimeout` | `number` | 在毫秒内自动取消弹出互动的可选超时. |
| `shippingDetailsId` | `null` | 为买方储存的一组货运细节的可选独特标识. |
| `connectionOptions` | `null` | 处理交易时可选择的一组选项传递给连接(见https://docs.gr4vy.com/reference#operation/authorize-new-Transaction) |
| `fullPageReturnUrl` | `string` | 当 Embed 在应用程序浏览器中被使用时, 或者当在商页被关闭的弹出( 移动) 中完成付款时, 用户会被重定向到可选的返回 URL |
| `redirectMode` | `fallback` | `fallback`, (中文(简体) ), `fullPage` - 一个可选的配置,以改变如何向支付提供者进行重定向. `fallback` 在重新定向之前尝试弹出, `fullPage` 将始终执行整页重定向,而不是使用弹出。 这可用于测试无法使用弹出时的倒置行为. |
| `onBeforeTransaction` | `null` | 一个可选的回调钩子在交易创建前被叫做正. 它允许你改变 `metadata`, (中文(简体) ), `externalIdentifier` 财务报告和审定财务报表 `shippingDetailsId` 在交易请求之前 这回话应该能还清承诺. |
| `showDeleteButton` | `false` | 一个可选的布尔来控制存储支付方法上删除按钮的显示,以便购买者可以删除它们 . |
| `merchantAccountId` | `default` | 可选的商人账户ID. |
| `billingAddressFields` | `Object` | 带有计费细节要求的可选对象.  
所有属性都是可选的. 示例 `{ address: { houseNumberOrName: true, line1: true, city: true, postalCode: true, state: true, country: true }, emailAddress: true, firstName: true, lastName: true, taxId: true }` |
| `antiFraudFingerprint` | `string` | 用作设备指纹的可选字符串。 保留未设定选择入选Gr4vy的自动反欺诈功能. |
| `enableAnimations` | `false` | 打开动画的可选布尔 . |
| `separatePaymentOptions` | `false` | 可选择的布尔以区分支付选项 . |
| `compactPaymentOptions` | `false` | 可选布尔, 当设置为 `true`,在紧凑的布局中显示支付选项. |
| `excludedMethods` | `null` | 可选排除方法列表. |
| `optionLabels` | `Object` | 支付选项标签的可选对象映射 |
| `autoSelectOption` | `null` | `first`, (中文(简体) ), `firstStored`, (中文(简体) ), `firstNonStored`, (中文(简体) ), `none` - 可用于告诉 Embed 自动选择第一个可用的支付方法、第一个存储方法、第一个非存储方法或根本不选择任何方法。 默认情况下,如果没有存储的方法活动,Embed会自动选择卡法. |
| `installmentCount` | `number` | 要求买方分期付款的可选价值. |
| `approvalExpiresAt` | `null` | 一个可选的ISO 8601日期时间字符串,用于设定交易批准的期限. 设定为 `null` 或省略,不适用核准期满。 客户端验证只检查该值是否为字符串;API验证了实际格式. |
| `topLevelDomain` | `null` | 例如,顶级页面的可选域 `shop.example.com`。当托管 Embed 的页面本身在 iframe 中时设置此功能: 钱包根据顶级文档域进行验证, 而嵌入的页面无法可靠地读取。 域名还必须为商户账户上的钱包注册. 当嵌入没有被设定时被忽略 . |

### 活动

这个 `onEvent` 选项可以用来收听窗体释放出的某些事件.

```js
<Gr4vyEmbed
  amount={1299}
  currency='USD'
  onEvent={(name, data) => {...}}
  ...
/>
})
```

目前,我们Gr4vy Embed发布以下事件.

#### `agumentError`

初始输入时返回( E)`element`, (中文(简体) ), `options`) 格式不正确或缺失.

```json
{
  "code": "argumentError",
  "option": "currency",
  "message": "must be a valid number"
}
```

#### `optionsLoaded`

当选项被装入时返回 。 存储的选项包括: `id`。 。 。 .

```json
[
  {
    "id": "...",
    "method": "card",
    "mode": "card"
  },
  {
    "method": "card",
    "mode": "card"
  }
]
```

#### `formUpdate`

表格更新时返回 。 目前只通知开发者, 如果窗体 无效.

```json
{
  "valid": false
}
```

#### `transactionCreated`

Gr4vy 接受交易时返回完整的交易对象, 不论地位如何 要知道,这可能是一个待决或拒绝 交易。 跟踪 API 失败请使用 `transactionFailed` 活动.

```json
{
  "type": "transaction",
  "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
  "status": "pending",
  ...
}
```

#### `transactionCancelled`

当买方明确取消一项交易,例如结束一次弹出或驳回Apple Pay时返回。 目前不支持三维安全交易 并且不应与交易被拒绝或发生错误相混淆.

```json
{
  "type": "transactionCancelled"
}
```

#### `transactionFailed`

API 呼叫无法创建客户端交易时返回或 服务器出错。 换句话说,这个事件是在不正确数据(如: 无效的 JWT) 传递给 Gr4vy API 和 HTTP 状态代码 `4XX` 或者说 `5XX` 区域返回.

由于交易失败或减少 支付服务的下游问题,请订阅 `transactionCreated` 活动.

```json
{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found"
}
```

#### `apiError`

当窗体遇到 API 错误时返回 .

```json
{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found",
  "details": []
}
```

#### `cardDetailsChanged`

当卡BIN在形式上有所改变时返回. 它包含输入卡的信息,如BIN,卡类型和计划等.

```json
{
  "bin": "42424242",
  "scheme": "visa",
  "cardType": "debit"
}
```

### 自定义表格提交

嵌入会自动提交带有隐藏输入的支付表, 使用 `onComplete` 调用.

```tsx
<Gr4vyEmbed
  amount={1299}
  currency='USD'
  onEvent={(name, data) => {...}}
  onComplete={(transaction) => {
    // Handle custom form submission
  }}
/>
```

### 无表格的提交

嵌入不需要有表格,才能进入 `EmbedInstance` 你可以直接通过一个裁判。 你应该执行 `onComplete` 如果您选择了这个选项.

```tsx
import Gr4vyEmbed, { EmbedInstance } from '@gr4vy/embed-react';
import { useRef } from 'react';

const MyComponent = () => {
  const embed = useRef<EmbedInstance>();

  return <div>
    <Gr4vyEmbed ref={embed} {...}/>
    <button onClick={() => embed.current.submit()}>
  </div>

}

```

请注意,如果你们俩拥有 `form` 道具设置和使用 `embed.current.submit()` 您可能注意到 Embed 连续提交两次, 你会看到一个调试模式的警告日志 。 这一般不是一个问题,除了钱包,在钱包中,会话两次被创建,有可能导致Apple Pay的"Page已经有一个活跃的支付会话"等错误. 如果你是在没有表格的情况下提交的,你不应该通过 `form` 避免这些问题.

## 自定义选项

嵌入会提供自定义的支付选项, 如果您需要整合到已有的退出中 。 这不会触发任何处理 嵌入后,您需要处理表格提交。 你应该执行 `onComplete` 如果您选择了这个选项.

```tsx
<Gr4vyEmbed
  // Provide a list of custom options
  customOptions={[
    {
      label: 'Giftcard',
      method: 'giftcard', // This should be a unique identifier for your custom option
      description: 'You will be asked to enter a giftcard',
      iconUrl: `data:image/svg+xml,...`, // This should be a data:image/svg+xml url
    }
  ]}
  // Handle the submit for a custom option
  onCustomSubmit={({ method: 'giftcard' }) => {
    console.log(`Paid by ${method}`);
  }}
/>
```

## 更新交易元数据和外部标识符

默认情况下, Embed 在初始化 Embed 时会使用您通过的选项, 用于每次交易请求 。 使用 `onBeforeTransaction` 调用。 这是有用的,如果你想 创建一个即时唯一的ID,并将此指定给交易,作为元数据或外部标识符.

```ts
setup({
  onBeforeTransaction: async () => {
    const { orderId } = await merchantBackend.getOrderId()
    return {
      externalIdentifier: orderId,
    }
  },
})
```

如果您指定了已被设定为默认选项的密钥, 您就需要将已有的值与您的更改合并 .

```ts
setup({
  onBeforeTransaction: async ({ metadata }) => {
    const { token, orderId } = await merchantBackend.getOrderId()

    return {
      token, // new token with pinned metadata
      metadata: {
        ...metadata, // merge existing metadata
        orderId,
      },
    }
  },
})
```

## 许可证

这个项目是在以下项下提供的: [麻省理工学院许可证](https://npmcn.com/package/%40gr4vy/embed-react/LICENSE)。 。 。 .

## 常见问题

### @gr4vy/embed-react 是什么？

在您的 React app 中嵌入信用卡表格并存储卡片细节,授权卡片,并抓取交易\.

### 如何安装 @gr4vy/embed-react？

在项目目录运行 npm install @gr4vy/embed-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.3\.1）、react-dom（\>=18\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gr4vy/embed-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gr4vy/embed-react 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gr4vy/embed-react 可以商用吗？

@gr4vy/embed-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gr4vy/embed-react 的下载量有多少？

根据 npm 官方下载统计，@gr4vy/embed-react 在 2026/10/17 – 2026/11/15 这 30 天内被下载 23,478 次，日均约 783 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gr4vy/embed-react 还在维护吗？

最新版本 2\.44\.0 发布于 2026/09/22（1 个月前）；至今共发布 138 个版本，其中过去 12 个月发布了 11 个；首次发布于 2020/12/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

