# @dintero/checkout-web-sdk 中文文档

规范地址：https://npmcn.com/package/%40dintero/checkout-web-sdk/

版本：0\.14\.2
npm 元数据更新时间：2026-10-13T08:18:14.837Z
中文译文更新时间：2026-11-12T10:20:08.324Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dintero/checkout-web-sdk
原文对照：https://npmcn.com/package/%40dintero/checkout-web-sdk/?lang=original
项目主页：https://github.com/Dintero/Dintero.Checkout.Web.SDK#readme
源码仓库：https://github.com/Dintero/Dintero.Checkout.Web.SDK

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

- 包体积（解压后）：293 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2020-02-03T16:26:20.850Z
- 最新版本发布：2026-10-13T08:18:14.063Z
- 近 30 天下载量：17872（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：117（近 12 个月 32 个）

## 中文简介

Dintero 查看网络前端的 SDK

## 安装

```sh
npm install @dintero/checkout-web-sdk
```

也可以使用：`pnpm add @dintero/checkout-web-sdk`、`yarn add @dintero/checkout-web-sdk`、`bun add @dintero/checkout-web-sdk`

## README

# Dintero 检查 JavaScript SDK 前端应用程序 [![Actions Status](https://github.com/Dintero/Dintero.Checkout.Web.SDK/workflows/CI/badge.svg?branch=master)](https://github.com/Dintero/Dintero.Checkout.Web.SDK/actions?query=branch%3Amaster+workflow%3ACI+) [![npm latest version](https://img.shields.io/npm/v/@dintero/checkout-web-sdk/latest.svg)](https://www.npmjs.com/package/@dintero/checkout-web-sdk)

在您的前端应用程序中使用此 SDK

-   在您网站上的 iframe 中嵌入已有的 Dintero 报到支付会话
-   将终端用户重定向到 Dintero 的完整页面版本, 用于现有的付款会话

_注意此 SDK 用于重定向或嵌入现有的支付会话 。 您不能使用 SDK 发送请求到检出 API 或建箱新的支付会话 ._

[在docs.dintero](https://docs.dintero.com/docs/checkout/getting-started/)

## 在你开始之前

我们无法保证从嵌入式结账到SDK客户端运行时间的事件交付. 会话机器对机器 `callback_url` 将至少交付一次。 更多关于 [回调url 参数](https://docs.dintero.com/checkout-api.html#operation/checkout_session_profile_post) 我们的光谱.

对于安装了 Vipps 应用程序的设备的付款,在 Vipps 应用程序完成付款后,终端用户将返回浏览器 **页:1 `return_url` 在新浏览器标签中打开付款** 在设备上的背景浏览器标签中离开嵌入式取出的网站。 在此情况下,SDK不能保证操作者 `onPaymentAuthorized` 或者说 `onPaymentError` 将召入.

如果没有添加自定义处理器 `onPaymentError`, (中文(简体) ), `onPaymentAuthorized` 财务报告和审定财务报表 `onPaymentCanceled` sDK 将把用户重定向到 `return_url` 在支付会话中.

## 安装

**国家防范机制一揽子计划**

```
npm install @dintero/checkout-web-sdk
```

## 使用 SDK 进行嵌入式取出

Dintero 检查结果将添加到 `<div id="checkout-container"></div>` DOM节点.

### 最小示例

_当支付完成后,SDK将把终端用户重定向到 `return_url` 在支付会话中定义._

```html
<script type="text/javascript">
    const container = document.getElementById("checkout-container");

    dintero.embed({
        container,
        sid: "T11223344.<short-uuid>",
    });
</script>
```

### 完全内置 HTML JavaScript 示例

_取出 sdk 将会为承诺添加多填充, 如果浏览器不支持本地承诺 ._

```html
<script type="text/javascript">
    const container = document.getElementById("checkout-container");

    dintero
        .embed({
            container,
            sid: "T11223344.<short-uuid>",
            popOut: false, // optional parameter to enable pop out mode
            language: "no", // optional parameter, an ISO 639-1 two-letter language code
            debug: false, // optional parameter, log SDK activity to the console, do not use for production
            onSession: function (event, checkout) {
                console.log("session", event.session);
            },
            onPayment: function (event, checkout) {
                console.log("transaction_id", event.transaction_id);
                console.log("href", event.href);
                checkout.destroy();
            },
            onPaymentError: function (event, checkout) {
                console.log("href", event.href);
                checkout.destroy();
            },
            onSessionCancel: function (event, checkout) {
                console.log("href", event.href);
                checkout.destroy();
            },
            onSessionNotFound: function (event, checkout) {
                console.log("session not found (expired)", event.type);
                checkout.destroy();
            },
            onSessionLocked: function (event, checkout, callback) {
                console.log("pay_lock_id", event.pay_lock_id);
                callback(); // refresh session
            },
            onSessionLockFailed: function (event, checkout) {
                console.log("session lock failed");
            },
            onActivePaymentType: function (event, checkout) {
                console.log(
                    "payment product type selected",
                    event.payment_product_type,
                );
            },
            onAddressCallback: function (event, checkout, callback) {
                console.log("address callback to handle express session address updates", event.session);
                callback({
                    success: true,
                    error: undefined,
                });
            },
            onValidateSession: function (event, checkout, callback) {
                console.log("validating session", event.session);
                callback({
                    success: true,
                    clientValidationError: undefined,
                });
            },
            onAgeVerificationStarted: function (event, checkout) {
                console.log("age verification started");
            },
            onAgeVerificationFailed: function (event, checkout) {
                console.log("age verification failed", event.error);
            },
            onAgeVerificationEnded: function (event, checkout) {
                console.log("age verification ended", event.result);
            },
        })
        .then(function (checkout) {
            console.log("checkout", checkout);
        });
</script>
```

### 字体示例

```ts
import {
    embed,
    SessionLoaded,
    SessionUpdated,
    SessionPayment,
    SessionPaymentError,
    SessionCancel,
    SessionNotFound,
    AgeVerificationStarted,
    AgeVerificationFailed,
    AgeVerificationEnded,
} from "@dintero/checkout-web-sdk";

const container = document.getElementById("checkout-container");

const checkout = await embed({
    container,
    sid: "T11223344.<short-uuid>",
    popOut: false, // optional parameter to enable pop out mode
    language: "no", // optional parameter, an ISO 639-1 two-letter language code
    debug: false, // optional parameter, log SDK activity to the console, never in production
    onSession: (event: SessionLoaded | SessionUpdated) => {
        console.log("session", event.session);
    },
    onPayment: (
        event: SessionPaymentAuthorized | SessionPaymentOnHold,
        checkout,
    ) => {
        console.log("transaction_id", event.transaction_id);
        console.log("href", event.href);
        checkout.destroy();
    },
    onPaymentError: (event: SessionPaymentError, checkout) => {
        console.log("href", event.href);
        checkout.destroy();
    },
    onSessionCancel: (event: SessionCancel, checkout) => {
        console.log("href", event.href);
        checkout.destroy();
    },
    onSessionNotFound: (event: SessionNotFound, checkout) => {
        console.log("session not found (expired)", event.type);
        checkout.destroy();
    },
    onSessionLocked: (event: SessionLocked, checkout, callback) => {
        console.log("pay_lock_id", event.pay_lock_id);
        callback(); // refresh session
    },
    onSessionLockFailed: (event: SessionLockFailed, checkout) => {
        console.log("session lock failed");
    },
    onActivePaymentType: function (event: ActivePaymentProductType, checkout) {
        console.log(
            "payment product type selected",
            event.payment_product_type,
        );
    },
    onAddressCallback: function (event: AddressCallback, checkout, callback) {
        console.log("address callback to handle express session address updates", event.session);
        callback({
            success: true,
            error: undefined,
        });
    },
    onValidateSession: function (event: ValidateSession, checkout, callback) {
        console.log("validating session", event.session);
        callback({
            success: true,
            clientValidationError: undefined,
        });
    },
    onAgeVerificationStarted: (event: AgeVerificationStarted, checkout) => {
        console.log("age verification started");
    },
    onAgeVerificationFailed: (event: AgeVerificationFailed, checkout) => {
        console.log("age verification failed", event.error);
    },
    onAgeVerificationEnded: (event: AgeVerificationEnded, checkout) => {
        console.log("age verification ended", event.result);
    },
});
```

### 设置支付产品类型

付款产品类型可以随返回的设定 `setActivePaymentProductType()`函数在嵌入取出时.

选择“ vipps” 支付产品类型 :

```
checkout.setActivePaymentProductType("vipps");
```

重设置选择( 因此在退出时没有选择选项 ) :

```
checkout.setActivePaymentProductType();
```

### 使用 AddressCallback 处理取出快递地址更新

如果 `onAddressCallback` 提供报到 **将不会执行机器来更新地址调用** 付款会话中定义 对象在 `express.shipping_address_callback_url`。相反,SDK运行时间必须处理地址更新流程.

这个 `onAddressCallback` 当一个终端用户在嵌入式检查快递会话中提交地址细节(发送和计费地址)时,会引用函数。 调用函数被引用为更新的会话,该会话在 Dintero 后端尚未被坚持. 退出将被锁定, 付款将被暂停, 直到调用已提供的回调功能, 或 `checkout.submitAddressCallbackResult` 随结果调用.

何时 `onAddressCallback` 引用时您必须执行 [服务器对服务器会话更新](https://npmcn.com/package/%40dintero/checkout-web-sdk/#readme-perform-a-server-to-server-session-update) 包括运输选项或其他已改变的细节。 一旦 已更新会话, 您需要调用已提供的回调函数并得出结果 .

当会话成功更新时, 返回一个成功的结果 :

```js
{
    success: true;
}
```

如果会话更新失败, 以错误消息返回结果 :

```js
{
   success: false,
   error: "<reason for session update failure>"
}
```

实施实例:

```
onAddressCallback: function(event, checkout, callback) {
     // Perform a server-to-server session update
     getShippingOptionsForAddressAndUpdateSession(event.session).then(() => {
        callback({
            success: true,
        });
     }).catch((err) => {
        callback({
            success: false,
            error: toErrorMessage(err), 
        });
     });
},
```

> **说明:** 执行 `onAddressCallback`,无需手动锁定会话并刷新会话。 退出会自动锁定付款, 当 `callback` 函数用于返回结果.

### 更新一个快取会话

为了更新现有的通关快讯会话,遵循这些步骤:

1.  用 SDK 锁定会话
2.  执行服务器对服务器 [会话更新](https://docs.dintero.com/checkout-api.html#operation/checkout_session_put)
3.  用 SDK 刷新会话

#### 锁定会话

调用检查对象的锁会话 :

```js
checkout
    .lockSession()
    .then(function (sessionLockedEvent) {
        // initiate server side session update and then refresh the session
    })
    .catch(function (sessionLockFailedEvent) {
        // handle failure to lock
    });
```

`lockSession()` 返回在 `SessionLocked` 事件为 如果收到SessionLockFlied事件,则从退出中收到或拒绝.

当会话成功锁定时,您将会在 `onSessionLocked`。 。 。 . 如果锁定会话失败, 将会在 `onSessionLockFailed`。 。 。 .

当会话被锁定时, 退出中的所有编辑和支付都禁用 .

#### 执行服务器对服务器会话更新

见 [会话更新](https://docs.dintero.com/checkout-api.html#operation/checkout_session_put) 详细介绍会议哪些部分可以更新以及如何更新.

#### 刷新会话

在更新会话后,请在退出对象上拨打刷新会话:

```js
checkout.refreshSession();
```

或使用回调 `onSessionLocked`数字 :

```js
onSessionLocked: (event, checkout, callback) => {
    console.log("pay_lock_id", event.pay_lock_id);
    callback(); // refresh session
};
```

`refreshSession()` 返回在 `SessionUpdated` 从检出中收到事件.

当一个会话没有一个会话时,会再次启用编辑和支付 `pay_lock` 被取出时加载.

### 付款前的审定会议

在支付会议费用之前验证会议内容并采取行动,使用 `onSessionValidation`\- 汉德勒.

退出将被锁定, 付款将被暂停, 直到调用已提供的回调功能, 或 `checkout.submitValidationResult` 随结果调用.

验证成功时, 返回成功结果 :

```js
{
    success: true;
}
```

如果验证不成功, 以错误消息返回结果 :

```js
{
   success: false,
   clientValidationError: "session is not in sync with cart"
}
```

实施实例:

```
onValidateSession: function(event, checkout, callback) {
     // Call the ecommerce solution to make sure the session is sync with the cart
     callback({
         success: false,
         clientValidationError: "session is not in sync with cart",
     });
},
```

### 调试日志

设定 `debug: true` 选项中 `embed()` 或者说 `redirect()` 来制造SDK 记录它正在对浏览器控制台做什么。 每个条目都用 `console.log` 和前缀为 `[dintero-checkout-web-sdk]`。 。 。 .

> : 警告: **从不启用 `debug` 在生产中.** 日志条目包含完整的, sDK收到的未红化有效载荷,包括名称的支付会话, 最终用户的电子邮件、电话号码、地址和顺序.

SDK日志 :

-   选项 `embed()` 或者说 `redirect()` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}被叫来了 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}还被叫来了 验出url 他们决定
-   每个参数 `on<Event>` 处理器,在处理器出现前登录 引用
-   提交SDK的结果,通过 `callback` 授予 `onValidateSession`编号 :`onAddressCallback` 和通过 `checkout.submitValidationResult()`编号 :`checkout.submitAddressCallbackResult()`,哪个 输入所使用的函数名称
-   调试时需要的函数 : `lockSession()`, (中文(简体) ), `refreshSession()`, (中文(简体) ), `setActivePaymentProductType()`, (中文(简体) ), `submitValidationResult()`, (中文(简体) ), `submitAddressCallbackResult()` 财务报告和审定财务报表 `destroy()`,包括活动 `lockSession()` 财务报告和审定财务报表 `refreshSession()` 或拒绝的理由
-   处理器在主机应用程序中抛出的错误, SDK 除外 报告 `console.error`

装入、锁定并刷新会话的示例输出 :

```
[dintero-checkout-web-sdk] embed(options) {sid: "T11223344.<short-uuid>", debug: true, …}
[dintero-checkout-web-sdk] embed session url https://checkout.dintero.com/v1/view/…
[dintero-checkout-web-sdk] options.onSession() {type: "SessionLoaded", session: {…}} {…}
[dintero-checkout-web-sdk] checkout.lockSession()
[dintero-checkout-web-sdk] checkout.lockSession() resolved {type: "SessionLocked", …}
[dintero-checkout-web-sdk] options.onSessionLocked() {type: "SessionLocked", …} {…} f
[dintero-checkout-web-sdk] onSessionLocked callback()
[dintero-checkout-web-sdk] onSessionLocked callback() resolved {type: "SessionUpdated", …}
```

没有记录 `debug` 被忽略或设定为 `false`记录的措辞 条目是调试辅助工具,可能在发布之间更改.

### 年龄核查活动

如果支付会话已启用年龄验证,则取出会显示一个门,最终用户必须在剩余取出之前通过身份提供者(如BankID). 使用 `onAgeVerificationStarted`, (中文(简体) ), `onAgeVerificationFailed` 财务报告和审定财务报表 `onAgeVerificationEnded` 以响应嵌入页面中的此流.

-   `onAgeVerificationStarted` 当终端用户点击启动身份提供者流时,会调用.
-   `onAgeVerificationFailed` 当无法完成验证时, 也叫“ ” , 例如, 因为最终用户没有达到最低年龄要求, 或者身份提供者的授权失败 。 这个 `error` 字段有一个原因,例如:. `"age-requirement-not-met"`。请注意,从身份提供者中取消的终端用户不被视为失败 - 闸门被再次显示,以便它们可以重试 .
-   `onAgeVerificationEnded` 一旦核查通过并解除大门,就称为“核查”。 这个 `result` 字段当前总是 `"passed"`。 。 。 .

年龄核查正在进行中, `lockSession()`, (中文(简体) ), `refreshSession()`,以及 `setActivePaymentProductType()` 同步抛出 。 避免这些调用, 直到核查完成, 或处理错误 `try`编号 :`catch`承诺拒绝处理者不会抓住它.

```js
onAgeVerificationStarted: function (event, checkout) {
    console.log("age verification started");
},
onAgeVerificationFailed: function (event, checkout) {
    console.log("age verification failed", event.error);
},
onAgeVerificationEnded: function (event, checkout) {
    console.log("age verification ended", event.result);
},
```

## 使用 SDK 进行方向检出

用户被重定向到 Dintero 退出以完成支付.

```ts
import { redirect } from "dintero-checkout-web-sdk";

const checkout = redirect({
    sid: "T11223344.<short-uuid>",
});
```

## 错误

错误可以报告给 [https://github.com/Dintero/Dintero.checkout.Web.SDK/issues 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/Dintero/Dintero.Checkout.Web.SDK/issues)

## 警卫

联系我们 [安全性@dintero.com](mailto:security@dintero.com)

## 浏览器支持

版本以上所有主要浏览器 `N - 1`时 `N` 是最新版本.

SDK包括一个 [承诺的多填充](https://github.com/getify/native-promise-only) 如果浏览器不支持承诺,则将加入全球范围.

## 从源头建楼

```bash
make build
```

Dintero 检查 SDK 的构建方式 [s](https://tsdown.dev/)。 。 。 .

## 创建新版本

1.  执行所有对主分支的承诺,按照 [角提交信件格式](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format)
2.  当合并为主机时, 它会自动与 [语义释放](https://github.com/semantic-release/semantic-release)

## 常见问题

### @dintero/checkout-web-sdk 是什么？

Dintero 查看网络前端的 SDK

### 如何安装 @dintero/checkout-web-sdk？

在项目目录运行 npm install @dintero/checkout-web-sdk，或使用 pnpm add / yarn add / bun add。

### @dintero/checkout-web-sdk 支持 TypeScript 吗？

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

### @dintero/checkout-web-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dintero/checkout-web-sdk 可以商用吗？

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

### @dintero/checkout-web-sdk 的下载量有多少？

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

### @dintero/checkout-web-sdk 还在维护吗？

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