@globalpayments/js

中文文档
5.4.0发布于 2026/11/05GPL-2.0TypeScript近 30 天下载 1.1万

PCI 友好调试

中文使用文档
文档目录12 节
  1. 目录
  2. 使用量
  3. 配置
  4. 处理全局错误
  5. 付款请求 API
  6. 支付方法
  7. 从源头建楼
  8. 发展
  9. 开发期间监视文件
  10. 测试
  11. 捐款
  12. 自由主义

全球支付 JavaScript 库

PCI 友好调试

此插件允许您使用各种全球支付品牌的在线支付(eCommerce)功能—— Heartland, Global Affairs eCommerce, Cayan/Genius, TSYS, Global Affairs Institution (fka OpenEdge) —— 将信用卡,礼品卡,或 ACH/ eCheck 账户转换为安全标志值,可以以PCI友好方式收取.

目录

使用量

<script src="https://js.globalpay.com/5.4.0/globalpayments.js"></script>

注:通过国家防范机制安装只能提供类型脚本类型进行类型检查.

配置

选项

publicApiKey - 说吧 string (备选)

注:仅适用于心脏地带在线支付.

与商户相关的公用API密钥. 此API密钥被绑定在Ceartland的特定商家/腾讯账户组合上,需要匹配的秘密API密钥来消耗这一值.

binCheck - 说吧 object (备选)

注:仅适用于心脏地带在线支付.

启用 BIN 检查各种能力 .

密钥类型默认说明
hsaFsabooleanfalse确定所提供的卡片是否用于卫生保健(HSA/FSA).
surchargebooleanfalse如果供应的卡可以附加收费,则会阻塞.
merchantId - 说吧 string (备选)

注:仅适用于全球支付电子商务和GP API.

就全球支付电子商务一体化而言,为账户提供的商号标识值.

对于使用多商支持的GP API集成,由合伙人支持的特定商户账户的商户ID值.

account - 说吧 string (备选)

注:仅适用于全球支付电子商务.

全球支付电子商务提供的账户ID值.

env - 说吧 string (备选)

支持的数值 :

  • production
  • sandbox (默认)

注:对于 Heartland eCommerce ,此值是从配置的 publicApiKey。 。 。 .

hash - 说吧 (object) => Promise<object> (备选)

注:仅适用于全球支付电子商务.

  • 输入:JS反对请求
  • 产出:一个承诺值,用正确的SHA1散列物解决进入JS对象的问题

这个 hash 属性取决于对您的后端的同步调用, 以便使用您的账户共享密钥在 JSON 请求中添加 SHA1 散列 。 下面的 Global Pays eCommerce 配置示例使用 Fellow API 和 PHP 脚本,但这可以使用任何其他选项,只要您能实现同样的结果. 这是为了防止你的秘密 暴露在未经授权的派对上.

customerExists - 说吧 boolean (备选)

注:仅适用于全球支付电子商务.

如果消费者已经有全球支付电子商务的客户记录,该数值应设定为: true。 。 。 .

customerReference - 说吧 string (备选)

注:仅适用于全球支付电子商务.

若为 customerExists 实值 true,这应当设定为客户的参考值/ID(PAYER_REF) (中文(简体) ).

webApiKey - 说吧 string (备选)

注:只应用到"天才"的取出.

API 密钥与给定的商号相关 .

deviceId - 说吧 string (备选)

注:仅适用于TransIT /TEP.

与给定账户相关的设备ID .

manifest - 说吧 string (备选)

注:仅适用于TransIT /TEP.

由集成伙伴使用商号ID,设备ID,交易金额和交易密钥生成的加密值.

X-GP-Api-Key - 说吧 string (备选)

注:适用于OpenEdge/全球支付 仅集成.

与账户相关的 API 密钥 .

X-GP-Environment - 说吧 string (备选)

注:适用于OpenEdge/全球支付 仅集成.

OpenEdge/全球支付综合环境.

merchantName - 说吧 string (备选)

注:只适用于心脏地带的账单付款.

与给定账户相关的商名 .

accessToken - 说吧 string (备选)

注:仅适用于GP API.

为应用程序创建的访问符 。 要求 PMT_POST_Create_Single 允许.

accountName - 说吧 string (备选)

注:仅适用于GP API.

给定的商号的代号账户名称 。 只有在与商号账户相关的一个以上标识账户时才需要

apiVersion - 说吧 string (备选)

注:仅适用于GP API.

目标API版本. 默认是 2021-03-22。 。 。 .

reference - 说吧 string (备选)

注:仅适用于GP API.

代码化请求的交易引用 。 如果没有提供,则在请求中创建并发送一个 GUID .

enableAutocomplete - 说吧 boolean (备选)

启用自动完成/ 自动填充功能 。 默认是 false。 。 。 .

language - 说吧 string (备选)

数值 html 元素的 lang 属性。 默认是 en。 。 。 .

requireCardHolderName - 说吧 boolean (备选)

注:仅适用于GP API.

启用对持卡人名字段的强制限制

enableCardFingerPrinting - 说吧 boolean (备选)

注:仅适用于GP API.

允许使用带有“ALWAYS”值的指纹模式

fieldValidation - 说吧 object (备选)

注:仅适用于GP API.

允许使用高频内置验证。 对象结构为:

  fieldValidation?: {
    enabled?: boolean, // (Optional)
    characterValidation?: string // Supported values: [`englishOnly`, `none`] (Optional)
  }

可选 characterValidation 字符串配置可以设置为 englishOnly 或者说 none ,这将显示卡片持有者名称是否包含英文字符.

qrCodePayments - 说吧 object (备选 - 在 apms 配置图)

注:仅适用于GP API.

允许使用QR码付款。 对象结构为:

  apms.qrCodePayments?: {
    enabled?: boolean, // (Optional)
    allowedPaymentMethods?: [ // Array of allowed Payment Methods (Optional)
      {
        provider: string,
        image: string,
      },
    ]
  }

可选 allowedPaymentMethods 对象配置可以设定手动添加首选的支付方法.

实例

心脏地带电子商务
GlobalPayments.configure({
  publicApiKey: "pkapi_cert_dNpEYIISXCGDDyKJiV"
});
全球支付电子商务
GlobalPayments.configure({
  merchantId: "merchant_id",
  account: "hpp",
  hash: (request) => {
    return fetch("/hash.php", {
      body: JSON.stringify(request),
      credentials: "omit",
      headers: new Headers({
        "Content-Type": "application/json",
      }),
      method: "POST",
    })
    .then((resp) => resp.json());
  },
  env: "sandbox"
});

天才检出

GlobalPayments.configure({
  webApiKey: "YU8PX7668FGMSH5L",
  env: "sandbox",
});

跨IT/TSEP

GlobalPayments.configure({
  deviceId: "88700000322602",
  manifest: "3c26272b6769cfa8b0c3c5a14dda4fc5365ed75c7330233a221a6e82aec667f35513c70862dc34f4ca31de7b4c824e129d23f8bce035fbbaa55aeb9da07b5d90bfe5d53c",
  env: "sandbox",
});

OpenEdge/ 全球支付一体化

GlobalPayments.configure({
  "X-GP-Api-Key": "oljHkRy0mAK9wqbQuUGZ9AUoe3ZtDrH7",
  "X-GP-Environment": "dev",
});

心脏地带付款

GlobalPayments.configure({
  merchantName: "IntegrationTesting",
  env: "sandbox",
});

处理全局错误

这个 GlobalPayments 全球变量显示 on 函数用于为内部事件发射器附加事件听众。 全球和/或母窗口运行时错误通过此程序被曝光,以及 error 事件处理器应当遵循窗体 :

type ErrorEventHandler = (error: IErrorEvent) => void;

地点 IErrorEvent 如下表单所示:

{
  error: true,
  reasons: [{
    code,
    message,
  }],
}

示例

GlobalPayments.on("error", (error) => {
  console.error(error);
});

付款请求 API

这个 付款请求 API 定义整个支付方法、支付系统、平台和商家的一致用户经验。 这不是一种新的支付方法,而是从用户偏好支付方法到商人的一种管道。 该功能由用户浏览器驱动,并允许访问与用户浏览器会话相关的存储支付信息.

以下是使用按钮和简单的10美元支付额的最小例子:

<div>
  <button type="button" id="paymentRequestPlainButton" style="display: none">Pay</button>
</div>
var paymentRequestForm = GlobalPayments.paymentRequest.setup("#paymentRequestPlainButton", {
  total: {
    label: "Total",
    amount: { value: 10, currency: "USD" }
  }
});

paymentRequestForm.on("token-success", function (resp) {
  // Payment data was successfully tokenized
  console.log(response);

  // TODO: POST data to backend for processing

  // Mark the payment as `success`, `fail`, or `unknown`
  // after processing response is known
  GlobalPayments.paymentRequest.complete("success");
});
paymentRequestForm.on("token-error", function (resp) {
  // An error occurred during tokenization
  console.log(resp);
});
paymentRequestForm.on("error", function (resp) {
  // An error occurred during setup or tokenization
  console.log(resp);
});

不应用额外的样式 :

Example: Raw Payment Request API button

这将附加必要的事件处理器, 一旦点击按钮, 即可启动支付请求支付流程 :

Example: Payment Request API review screen

支付方法

此库目前支持 :

信用卡/贴卡

滴入式信用/减值卡表便于启动. 您的集成需要一个 HTML 表格,其中包含一个投放表单的目标 :

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Target for the credit card form -->
  <div id="credit-card"></div>
</form>

和一些设置窗体的 JavaScript :

const cardForm = GlobalPayments.creditCard.form("#credit-card");

// form-level event handlers. examples:
cardForm.ready(() => {
  console.log("Registration of all credit card fields occurred");
});
cardForm.on("token-success", (resp) => {
  // add payment token to form as a hidden input
  const token = document.createElement("input");
  token.type = "hidden";
  token.name = "payment-reference";
  token.value = resp.paymentReference;

  // submit data to the integration's backend for processing
  const form = document.getElementById("payment-form");
  form.appendChild(token);
  form.submit();
});
cardForm.on("token-error", (resp) => {
  // show error to the consumer
});

// field-level event handlers. example:
cardForm.on("card-number", "register", () => {
  console.log("Registration of Card Number occurred");
});

这将在页面负载中创建一个带有默认样式的窗体 :

Example: Drop-in credit card form

见演示 联合通讯社

如果默认样式与您想要的UI/UX相冲突,可以通过指定退出 blank 样式 :

const cardForm = GlobalPayments.creditCard.form("#credit-card", { style: "blank" });

Example: Drop-in credit card form (blank)

见演示 联合通讯社

样式可按您的整合要求被推入窗体的字段:

cardForm.addStylesheet({
  // You styles
});

需要更多的控制/灵活性吗? 您的整合可以对原始卡表构建器施加杠杆作用:

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Targets for the credit card form's fields -->
  <div id="credit-card-card-holder"></div>
  <div id="credit-card-card-number"></div>
  <div id="credit-card-card-cvv"></div>
  <div id="credit-card-card-expiration"></div>
  <div id="credit-card-submit"></div>
</form>
const cardForm = GlobalPayments.ui.form({
  fields: {
    "card-holder-name": {
      placeholder: "Jane Smith",
      target: "#credit-card-card-holder",
      validationMessages: {
        NotValidCardHolderName: 'Please enter a valid Card Holder Name',
        CharactersMoreThan100: 'Card Holder Name can be at most 100 characters'
      }
    },
    "card-number": {
      placeholder: "•••• •••• •••• ••••",
      target: "#credit-card-card-number",
      validationMessages: {
        Required: 'A Card Number is required',
        CharactersLessThan12: 'The Card Number must consist of at least 12 digits',
        NumberIsNotValid: 'The Card Number is not valid',
        NotAllowedCardType: 'Cannot process this card type, please use another Card'
      },
    },
    "card-expiration": {
      placeholder: "MM / YYYY",
      target: "#credit-card-card-expiration",
      validationMessages: {
        NotCompleted: 'Please enter a valid month/year',
        YearNotValid: 'The year is not valid',
        MonthNotValid: 'The month is not valid',
        ExpiryDateNotValid: 'The Expiry Date is not valid',
      }
    },
    "card-cvv": {
      placeholder: "•••",
      target: "#credit-card-card-cvv",
      validationMessages: {
        CodeIsNotValid: 'The Card CVV is not valid',
        CodeIsLessThan3Digits: 'Card CVV is too short',
        CodeMustBe3Digits: 'Card CVV must be 3 digits',
        AmexCodeMustBe4Digits: 'Card CVV for Amex must be 4 digits',
      }
    },
    "submit": {
      value: "Submit",
    }
  },
  styles: {
    // Your styles
  }
});

添加多自定义字体

要添加多个自定义字体,可以使用以下配置: 1

const cardForm = GlobalPayments.ui.form({
  fields: { ... },
  styles: {
    "@font-face": [
      {
        "font-family": "'Font 1'",
        "src": "url('url/font1.woff2') format('woff2')"
      },
      {
        "font-family": "'Font 2'",
        "src": "url('url/font2.woff2') format('woff2')"
      }]
      
    // Your styles
  }
});

或者说

cardForm.addStylesheet({
"@font-face": [
  {
    "font-family": "'Font 1'",
    "src": "url('url/font1.woff2') format('woff2')"
  },
  {
    "font-family": "'Font 2'",
    "src": "url('url/font2.woff2') format('woff2')"
  }]
});

校验信件

校验信件列表可在 /包装/全球支付-js/src/内部/lib/翻译/en.ts

Example: Raw credit card form

见演示 联合通讯社

礼品/信用卡

注:只适用于 Heartland eCommerce.

送入的礼物/忠诚卡表使得开始容易. 您的集成需要一个 HTML 表格,其中包含一个投放表单的目标 :

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Target for the gift/loyalty card form -->
  <div id="gift-card"></div>
</form>

和一些设置窗体的 JavaScript :

const cardForm = GlobalPayments.giftAndLoyalty.form("#gift-card");

// form-level event handlers. examples:
cardForm.ready(() => {
  console.log("Registration of all gift/loyalty card fields occurred");
});
cardForm.on("token-success", (resp) => {
  // add payment token to form as a hidden input
  const token = document.createElement("input");
  token.type = "hidden";
  token.name = "payment-reference";
  token.value = resp.paymentReference;

  // submit data to the integration's backend for processing
  const form = document.getElementById("payment-form");
  form.appendChild(token);
  form.submit();
});
cardForm.on("token-error", (resp) => {
  // show error to the consumer
});

// field-level event handlers. example:
cardForm.on("card-number", "register", () => {
  console.log("Registration of Card Number occurred");
});

这将在页面负载中创建一个带有默认样式的窗体 :

Example: Drop-in gift/loyalty form

见演示 联合通讯社

如果默认样式与您想要的UI/UX相冲突,可以通过指定退出 blank 样式 :

const cardForm = GlobalPayments.giftAndLoyalty.form("#gift-card", { style: "blank" });

Example: Drop-in gift/loyalty form (blank)

见演示 联合通讯社

样式可按您的整合要求被推入窗体的字段:

cardForm.addStylesheet({
  // You styles
});

需要更多的控制/灵活性吗? 您的整合可以对原始卡表构建器施加杠杆作用:

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Targets for the gift/loyalty card form's fields -->
  <div id="gift-card-card-number"></div>
  <div id="gift-card-submit"></div>
</form>
const cardForm = GlobalPayments.ui.form({
  fields: {
    "card-number": {
      placeholder: "•••• •••• •••• ••••",
      target: "#gift-card-card-number"
    },
    "submit": {
      value: "Submit",
      target: "#gift-card-submit"
    }
  },
  styles: {
    // Your styles
  }
});

Example: Raw gift/loyalty form

见演示 联合通讯社

ACH/电子检查账户

注:只适用于 Heartland eCommerce.

滴入式ACH/eCheck表格容易启动. 您的集成需要一个 HTML 表格,其中包含一个投放表单的目标 :

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Target for the ACH/eCheck form -->
  <div id="eCheck"></div>
</form>

和一些设置窗体的 JavaScript :

const eCheckForm = GlobalPayments.eCheck.form("#eCheck");

// form-level event handlers. examples:
eCheckForm.ready(() => {
  console.log("Registration of all ACH/eCheck fields occurred");
});
eCheckForm.on("token-success", (resp) => {
  // add payment token to form as a hidden input
  const token = document.createElement("input");
  token.type = "hidden";
  token.name = "payment-reference";
  token.value = resp.paymentReference;

  // submit data to the integration's backend for processing
  const form = document.getElementById("payment-form");
  form.appendChild(token);
  form.submit();
});
eCheckForm.on("token-error", (resp) => {
  // show error to the consumer
});

// field-level event handlers. example:
eCheckForm.on("account-number", "register", () => {
  console.log("Registration of Account Number occurred");
});

这将在页面负载中创建一个带有默认样式的窗体 :

Example: Drop-in ACH/eCheck form

见演示 联合通讯社

如果默认样式与您想要的UI/UX相冲突,可以通过指定退出 blank 样式 :

const eCheckForm = GlobalPayments.eCheck.form("#eCheck", { style: "blank" });

Example: Drop-in ACH/eCheck form (blank)

见演示 联合通讯社

样式可按您的整合要求被推入窗体的字段:

eCheckForm.addStylesheet({
  // You styles
});

需要更多的控制/灵活性吗? 您的整合可以对原始形式构建器施加杠杆作用 :

<form id="payment-form" action="/charge" method="get">
  <!-- Other input fields to capture relevant data -->
  <label for="billing-zip">Billing Zip Code</label>
  <input id="billing-zip" name="billing-zip" type="tel" />

  <!-- Targets for the gift/loyalty card form's fields -->
  <div id="eCheck-account-number"></div>
  <div id="eCheck-routing-number"></div>
  <div>
    <select name="eCheck-check-type">
      <option> -- Check Type -- </option>
      <option>Checking</option>
      <option>Savings</option>
    </select>
  </div>
  <div>
    <select name="eCheck-account-type">
      <option> -- Account Type -- </option>
      <option>Personal</option>
      <option>Business</option>
    </select>
  </div>
  <div id="eCheck-submit"></div>
</form>
const eCheckForm = GlobalPayments.ui.form({
  fields: {
    "account-number": {
      placeholder: "Account Number",
      target: "#eCheck-account-number"
    },
    "routing-number": {
      placeholder: "•••••••••",
      target: "#eCheck-routing-number"
    },
    "submit": {
      value: "Submit",
      target: "#eCheck-submit"
    }
  },
  styles: {
    // Your styles
  }
});

Example: Raw ACH/eCheck form

见演示 联合通讯社

从源头建楼

yarn install
yarn run build

yarn run build 将执行下列任务:

  1. 清理干净 ./dist/ 目录.
  2. 根据 tslint.json。 。 。 .
  3. 将 Typescript 文件建入 ./dist/securesubmit.js 使用 tsconfig.json。 。 。 .
  4. 缩小 ./dist/securesubmit.js 输入 ./dist/securesubmit.min.js。 。 。 .
  5. 将所需资产文件复制到 ./dist/。 。 。 .

发展

符号化库以 Typescript 构建. Typescript 编译器作为Visual Studio的附加版本可供使用,但也可以独立安装. 这个图书馆的 package.json 文件还从下拉下一个使用 Typescript 编译器的副本 yarn install,允许它通过调用 ./node_modules/bin/tsc。 。 。 .

开发期间监视文件

yarn run build -w

测试

集成测试与Cypress一起运行,Cypress期望运行的网络服务器同时托管已建文件以及测试跑取器. 为此,利用适当的Bash脚本:

./test/run.sh

或 PowerShell 脚本 :

.\test\run.ps1

捐款

  1. 叉开它
  2. 创建您的特性分支( E)git checkout -b my-new-feature(中文(简体) )
  3. 提交更改( E)git commit -am 'Add some feature'(中文(简体) )
  4. 推向分行(git push origin my-new-feature(中文(简体) )
  5. 创建新的拉请求

自由主义

该项目根据GPLv2许可证获得许可证。 见 利比里亚 详细情况.

版本与发布记录

@globalpayments/js 共发布 73 个版本,首次发布于 2020/12/03;过去 12 个月发布了 20 个版本。

版本发布日期距今
5.4.0latest2026/11/0511 天前
5.3.02026/10/2918 天前
5.2.02026/10/151 个月前
5.1.32026/09/032 个月前
5.1.22026/08/133 个月前
5.1.12026/08/113 个月前

关于 @globalpayments/js 的常见问题

@globalpayments/js 是什么?

PCI 友好调试

如何安装 @globalpayments/js?

在项目目录运行 npm install @globalpayments/js,或使用 pnpm add / yarn add / bun add。

@globalpayments/js 支持 TypeScript 吗?

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

@globalpayments/js 可以商用吗?

@globalpayments/js 使用 GPL-2.0 许可。强 Copyleft:分发包含该代码的软件时,整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括,不构成法律意见,请以许可原文为准。

@globalpayments/js 的下载量有多少?

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

@globalpayments/js 还在维护吗?

最新版本 5.4.0 发布于 2026/11/05(11 天前);至今共发布 73 个版本,其中过去 12 个月发布了 20 个;首次发布于 2020/12/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。