@gr4vy/sdk

中文文档
2.4.47发布于 2026/11/11TypeScriptCommonJS构建来源已验证近 30 天下载 5.2万

开发者方便且类型安全 类型SDK 格鲁维 API (英语).

中文使用文档
文档目录63 节
  1. 内容提要
  2. 目录
  3. SDK 安装
  4. 国家预防机制
  5. 菲律宾
  6. 阿宝
  7. 雅伦
  8. 所需资源
  9. SDK 示例使用法
  10. 示例
  11. 持有者代号生成
  12. 嵌入式符号生成
  13. 自动附加一个退出会话
  14. 商务账户 ID 选择
  15. Webhooks 验证
  16. 参数
  17. 现有资源和业务
  18. 会计更新者。 工作
  19. ApiKey 平板电脑
  20. 审计日志
  21. 买家
  22. 卡片计划定义
  23. 离职会议
  24. 数字钱包
  25. 礼品卡
  26. 商业账户
  27. 付款链接
  28. 支付方法
  29. 备选付款办法
  30. 支付服务定义
  31. 支付服务
  32. 付款
  33. 退款
  34. 报告执行
  35. 报告
  36. 作用
  37. 三维情景
  38. 交易
  39. 处理错误
  40. 示例
  41. 错误分类
  42. 服务器选择
  43. 按名称选择服务器
  44. 覆盖服务器 URL / 客户端
  45. 自定义 HTTP 客户端
  46. 认证
  47. 常客安全计划
  48. SDK 安装
  49. 国家预防机制
  50. 菲律宾
  51. 阿宝
  52. 雅伦
  53. SDK 示例使用法
  54. 示例
  55. 倾斜
  56. 检索
  57. 内容提要
  58. 目录
  59. 独立职能
  60. 调试
  61. 测试
  62. 捐款
  63. SDK 创建者 说话方便

Gr4vy 类型脚本 SDK

开发者方便且类型安全 类型SDK 格鲁维 API (英语).

NPM Version

内容提要

TypeScript 的官方 Gr4vy SDK 提供了从您的服务器端应用程序中与 Gr4vy API 交互的方便方式. 这个SDK可以使您无缝地整合了Gr4vy强大的支付管弦能力,包括:

  • 创建交易:以各种支付方法和服务启动和处理支付.
  • 管理买方:安全地储存和管理买方信息.
  • 储存支付方法:安全地储存并象征性地说明今后使用的支付方法.
  • 处理Webhooks:轻松处理并回应Gr4vy的Webhook事件.
  • 更多:访问Gr4vy API支付功能的完整套件.

这个SDK是为了简化开发,减少锅炉板代码,帮助您快速高效地与Gr4vy一起起起跑. 它处理认证,请求签名,并为大多数API端点提供易用的方法.

目录

SDK 安装

SDK可以安装其中之一 无, (中文(简体) ), 小时, (中文(简体) ), 包头 或者说 线条 软件包管理器.

国家预防机制

npm add @gr4vy/sdk

菲律宾

pnpm add @gr4vy/sdk

阿宝

bun add @gr4vy/sdk

雅伦

yarn add @gr4vy/sdk

所需资源

对于支持的 JavaScript 运行时间, 请参考 运行时间.md。 。 。 .

SDK 示例使用法

示例

import fs from "fs";
import { Gr4vy, withToken } from "@gr4vy/sdk";

async function run() {
    const gr4vy = new Gr4vy({
        server: "sandbox",
        id: "example",
        bearerAuth: withToken({
          privateKey: fs.readFileSync("private_key.pem", "utf8"),
        }),
    });

    const result = await gr4vy.transactions.list({});

    // Handle the result
    console.log(result);
}

run();

持有者代号生成

或者,您可以用 SDK 或自己的客户端库创建一个符号.

import { getToken } from "@gr4vy/sdk";

async function run() {
    const token = await getToken({
          privateKey: fs.readFileSync("private_key.pem", "utf8"),
    });
    console.log(token);
}

run();

说明: 这只会创造一个符号一次。 使用 withToken 以动态生成一个符号 每个请求.

嵌入式符号生成

或者,您可以创建一个用于嵌入的符号如下 .

import { Gr4vy, getEmbedToken } from "@gr4vy/sdk";

async function run() {
    const privateKey = fs.readFileSync("private_key.pem", "utf8")

    const gr4vy = new Gr4vy({
        server: "sandbox",
        id: "example",
        bearerAuth: withToken({ privateKey }),
    });

    const checkoutSession = await gr4vy.checkoutSessions.create()

    const token = await getEmbedToken({ 
      privateKey,
      checkoutSessionId: checkoutSession.id,
      embedParams: {
        amount: 1299,
        currency: 'USD',
        buyerExternalIdentifier: 'user-1234',
      }
    });

    console.log(token);
}

run();

说明: 这只会创造一个符号一次。 使用 withToken 以动态生成一个符号 每个请求.

自动附加一个退出会话

对于 Embed ,建议在每次交易中都附加一个检出会话. 这个 getEmbedTokenWithCheckoutSession 帮助者使用您的 SDK 客户端创建退出会话 返回带有结果的嵌入符 checkout_session_id 已经钉住,在一个呼叫.

import fs from "node:fs";
import { Gr4vy, getEmbedTokenWithCheckoutSession, withToken } from "@gr4vy/sdk";

async function run() {
    const privateKey = fs.readFileSync("private_key.pem", "utf8")

    const gr4vy = new Gr4vy({
        server: "sandbox",
        id: "example",
        bearerAuth: withToken({ privateKey }),
    });

    const token = await getEmbedTokenWithCheckoutSession({
      client: gr4vy,
      privateKey,
      embedParams: {
        amount: 1299,
        currency: 'USD',
        buyerExternalIdentifier: 'user-1234',
      }
    });

    console.log(token);
}

run();

你可以选择通过一个 checkoutSession 种子会话的正体(例如用推车项) 或元数据)和a merchantAccountId 以覆盖客户端配置的商号.

商务账户 ID 选择

根据使用的密钥,您可能需要明确定义要使用的商号账户ID. 在我们的API, 此使用 X-GR4VY-MERCHANT-ACCOUNT-ID 头曰. 使用SDK时,可以设置 merchantAccountId 每一个请求.

const result = await gr4vy.transactions.list({
    merchantAccountId: 'merchant-12345'
})

或者,在初始化SDK时也可以设置商号账户ID.

const gr4vy = new Gr4vy({
    server: "sandbox",
    id: "example",
    merchantAccountId: 'merchant-12345',
    bearerAuth: withToken({ privateKey }),
});

Webhooks 验证

SDK提供了一个 verifyWebhook 用于验证Gr4vy收到的webhook请求的方法。 这确保了网钩有效载荷是真实的,没有被篡改.

import { verifyWebhook } from "@gr4vy/sdk";

const payload = 'your-webhook-payload'
const secret = 'your-webhook-secret'
const signatureHeader = 'signatures-from-header'
const timestampHeader = 'timestamp-from-header'
const timestampTolerance = 300 // optional, in seconds (default: 0)

try {
  verifyWebhook(
    payload,
    secret,
    signatureHeader,
    timestampHeader,
    timestampTolerance
  )
  console.log('Webhook verified successfully!')
} catch (error) {
  console.error('Webhook verification failed:', error.message)
}

参数

  • payload:在webhook请求中收到的原始有效载荷字符串.
  • secret:用来签下"网钩"的秘密. 这在你的Gr4vy仪表板上提供.
  • signatureHeader编号: X-Gr4vy-Signature 由 webhook 请求发出的头条 .
  • timestampHeader编号: X-Gr4vy-Timestamp 由 webhook 请求发出的头条 .
  • timestampTolerance数字 : (备选) 允许的最大值( 以秒计) 在webhook中当前时间和时间戳之间的相差 。 默认为 0 (没有宽容).

现有资源和业务

可用方法

会计更新者。 工作

  • 创建 - 创建账户更新工作

ApiKey 平板电脑

  • 列表 - 列出所有 API 密钥对
  • 创建 - 创建 API 密钥对
  • 起来 - 拿一对API钥匙
  • 更新 - 更新 API 密钥对
  • 删除 - 删除 API 密钥对

审计日志

  • 列表 - 清单审计记录条目

买家

买取者. 礼品卡

  • 列表 - 列出买家的礼品卡

买取者. 支付方法

  • 列表 - 列出买方付款方法

买取者. 航运 细节

  • 创建 - 增加买方运输详情
  • 列表 - 列出买方的货运详情
  • 起来 - 获得买方的运输细节
  • 更新 - 更新买方的运输细节
  • 删除 - 删除买方的货运细节

卡片计划定义

  • 列表 - 列表卡方案定义

离职会议

数字钱包

数字钱包. 域数

  • 创建 - 注册数字钱包域名
  • 删除 - 删除数字钱包域

数字钱包. 会议

礼品卡

礼物卡 活动

礼物卡 余额

  • 列表 - 礼品卡余额清单

礼物卡 发放

商业账户

商业账户。 三维配置

  • 创建 - 为商家创建 3DS 配置
  • 列表 - 列出商家的3DS配置
  • 更新 - 编辑 3DS 配置
  • 删除 - 删除商家的3DS配置

支付方法

支付方法。 网络插件

支付方法。 腾讯网. 密码
  • 创建 - 提供网络代号密码图

支付方法。 付费服务套件

  • 列表 - 列出付款服务标志
  • 创建 - 创建支付服务标志
  • 删除 - 删除付款服务代号

备选付款办法

支付服务定义

支付服务

付款

退款

报告执行

  • 列表 - 列出已执行报告

报告

报告。 处决

作用

三维情景

交易

交易 行动

交易 捕获

交易 活动

交易 退款

  • 起来 - 获得交易退款结算
  • 列表 - 清单交易退款结算

交易 退款

交易 退还. 全体
  • 创建 - 创建批次交易退款

交易 定居点

处理错误

Gr4vyError 是所有 HTTP 错误响应的基础类。 其属性如下:

财产类型说明
error.messagestring错误消息
error.statusCodenumberHTTP 响应状态代码 eg 404
error.headersHeadersHTTP 响应头
error.bodystringHTTP 躯体. 如果没有尸体返回, 则可以是空字符串 .
error.rawResponseResponse原始 HTTP 响应
error.data$可选的 一些错误可能包含结构化数据. 参见错误类。 。 。 .

示例

import { Gr4vy, withToken } from "@gr4vy/sdk";
import * as errors from "@gr4vy/sdk/models/errors";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  try {
    const result = await gr4vy.accountUpdater.jobs.create({
      paymentMethodIds: [
        "ef9496d8-53a5-4aad-8ca2-00eb68334389",
        "f29e886e-93cc-4714-b4a3-12b7a718e595",
      ],
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.Gr4vyError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.Error400) {
        console.log(error.data$.type); // string
        console.log(error.data$.code); // string
        console.log(error.data$.status); // number
        console.log(error.data$.message); // string
        console.log(error.data$.details); // ErrorDetail[]
      }
    }
  }
}

run();

错误分类

主错误 :

  • Gr4vyError: HTTP 错误响应的基础类.
    • Error400: 请求无效. 状态代码 400。 。 。 .
    • Error401: 请求未经批准. 状态代码 401。 。 。 .
    • Error403: 证书无效或呼叫者没有权限对资源采取行动. 状态代码 403。 。 。 .
    • Error404: 未找到资源 。 状态代码 404。 。 。 .
    • Error405: 不允许请求方法. 状态代码 405。 。 。 .
    • Error409: 找到重复的记录。 状态代码 409。 。 。 .
    • Error425:请求太早. 状态代码 425。 。 。 .
    • Error429: 提出了太多的请求。 状态代码 429。 。 。 .
    • Error500: 服务器遇到错误 。 状态代码 500。 。 。 .
    • Error502: 服务器遇到错误 。 状态代码 502。 。 。 .
    • Error504: 服务器遇到错误 。 状态代码 504。 。 。 .
    • HTTPValidationError: 校验出错. 状态代码 422。 。 。 *
少常见错误(6)

网络错误 :

继承从 Gr4vyError数字 :

  • ResponseValidationError:从服务器返回的数据和SDK期望的结构之间的类型不匹配. 见 error.rawValue 原值和 error.pretty() 用于格式化良好的多行字符串.

* 检查 方法文档 以查看该错误是否适用.

服务器选择

按名称选择服务器

您可以通过将服务器名称传递到 server: keyof typeof ServerList 初始化 SDK 客户端实例时的可选参数 。 然后,选定服务器将作为使用它的操作的默认值. 本表列出与可用服务器相关的名称:

名称服务器变量说明
sandboxhttps://api.sandbox.{id}.gr4vy.appid
productionhttps://api.{id}.gr4vy.appid

如果选中的服务器有变量, 您可以通过 SDK 构建器中提供的额外参数来覆盖其默认值 :

变量参数默认说明
idid: string"example"您的 Gr4vy 实例的子域 .

示例

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create({
    paymentMethodIds: [
      "ef9496d8-53a5-4aad-8ca2-00eb68334389",
      "f29e886e-93cc-4714-b4a3-12b7a718e595",
    ],
  });

  console.log(result);
}

run();

覆盖服务器 URL / 客户端

默认服务器也可以通过将 URL 传递到 serverURL: string 初始化 SDK 客户端实例时的可选参数 。 例如:

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create({
    paymentMethodIds: [
      "ef9496d8-53a5-4aad-8ca2-00eb68334389",
      "f29e886e-93cc-4714-b4a3-12b7a718e595",
    ],
  });

  console.log(result);
}

run();

自定义 HTTP 客户端

TypeScript SDK 使用一个 HTTPClient 将本地人包裹起来 获取 API这个 客户端是薄薄的包装 fetch 并且提供连接钩子的能力 围绕可用于修改请求或处理的请求生命周期 错误和反应.

这个 HTTPClient 构造器使用可选 fetcher 参数可以是 用于整合第三方 HTTP 客户端或用于编写测试以嘲弄 hTTP 客户端并输入固定设备.

以下例子说明如何:

  • 通过使用 未编辑代理代理代理服务器
  • 使用该 "beforeRequest" 向请求添加自定义头和超时
  • 使用该 "requestError" 记录错误的钩头
import { Gr4vy } from "@gr4vy/sdk";
import { ProxyAgent } from "undici";
import { HTTPClient } from "@gr4vy/sdk/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({
  // 'fetcher' takes a function that has the same signature as native 'fetch'.
  fetcher: (input, init) =>
    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
    fetch(input, { ...init, dispatcher } as RequestInit),
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Gr4vy({ httpClient: httpClient });

认证

常客安全计划

这个SDK在全球支持以下安全计划:

名称类型计划环境变量
bearerAuth网页HTTP 缓冲器GR4VY_BEARER_AUTH

用 API 认证 bearerAuth 初始化 SDK 客户端实例时必须设置参数 。 例如:

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create({
    paymentMethodIds: [
      "ef9496d8-53a5-4aad-8ca2-00eb68334389",
      "f29e886e-93cc-4714-b4a3-12b7a718e595",
    ],
  });

  console.log(result);
}

run();

SDK 安装

SDK可以安装其中之一 无, (中文(简体) ), 小时, (中文(简体) ), 包头 或者说 线条 软件包管理器.

国家预防机制

npm add @gr4vy/sdk

菲律宾

pnpm add @gr4vy/sdk

阿宝

bun add @gr4vy/sdk

雅伦

yarn add @gr4vy/sdk

SDK 示例使用法

示例

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create({
    paymentMethodIds: [
      "ef9496d8-53a5-4aad-8ca2-00eb68334389",
      "f29e886e-93cc-4714-b4a3-12b7a718e595",
    ],
  });

  console.log(result);
}

run();

倾斜

此 SDK 中的一些端点支持 pagination. 要用帕吉恩语,你 使您的 SDK 调用如常, 但返回的响应对象也将是 可使用下列设备消耗的同步可执行性: for await...of 语法.

举个例子说

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.apiKeyPairs.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

检索

此 SDK 中的一些端点支持重试. 如果在没有任何配置的情况下使用SDK,则会回落到API提供的默认重试策略. 然而,默认的重试策略可以在一次操作的基础上被推翻,或者在整个SDK中被推翻.

更改单个 API 调用默认重试策略, 只需为调用提供重试 Config 对象 :

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create(
    {
      paymentMethodIds: [
        "ef9496d8-53a5-4aad-8ca2-00eb68334389",
        "f29e886e-93cc-4714-b4a3-12b7a718e595",
      ],
    },
    undefined,
    {
      retries: {
        strategy: "backoff",
        backoff: {
          initialInterval: 1,
          maxInterval: 50,
          exponent: 1.1,
          maxElapsedTime: 100,
        },
        retryConnectionErrors: false,
      },
    },
  );

  console.log(result);
}

run();

如果您想要覆盖所有支持重试的操作的默认重试策略, 您可以在 SDK 初始化时提供重试Config :

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
  id: "example",
  server: "sandbox",
  merchantAccountId: "default",
  bearerAuth: withToken({
    privateKey: fs.readFileSync("private_key.pem", "utf8"),
  }),
});

async function run() {
  const result = await gr4vy.accountUpdater.jobs.create({
    paymentMethodIds: [
      "ef9496d8-53a5-4aad-8ca2-00eb68334389",
      "f29e886e-93cc-4714-b4a3-12b7a718e595",
    ],
  });

  console.log(result);
}

run();

内容提要

Gr4vy:Gr4vy API. (中文(简体) ).

目录

独立职能

上述所有方法都作为独立功能提供。 这些 函数是用于在浏览器中运行的应用程序的理想功能,没有服务器 运行时间或应用程序捆绑大小为主的其他环境 关心。 当使用捆绑器构建您的应用程序时, 全部未使用 功能将被从最后的捆绑中排除,或者被树切除.

要了解更多独立函数, 请检查 职能.md。 。 。 .

现有的独立职能

调试

您可以为 SDK 请求和响应设置 SDK 以发送调试日志 .

你可以通过一个匹配的日志 console'作为 SDK 选项的接口.

[尖叫声] 注意调试日志会揭示一些秘密, 如标题中的 API 令牌, 打印到控制台或文件中的日志信息 。 建议只在本地开发期间使用这一特征,而不能用于生产.

import { Gr4vy } from "@gr4vy/sdk";

const sdk = new Gr4vy({ debugLogger: console });

通过设置环境变量也可以启用默认调试日志 GR4VY_DEBUG 改为 true, (中文(简体) ), 1, (中文(简体) ), yes 或者说 on (大小写不敏感). 任何其它价值都使它失效.

发展

测试

SDK有一个端到端的测试套件,能与E2E相对抗. 地点 页:1 private_key.pem 用于repo 根(或导出)中的测试环境 PRIVATE_KEY),然后:

npm install
npx vitest run

见 试验. md 为全向导——套间布局,并列 和CI 硬化、基于财产的测试、覆盖/端点覆盖报告,以及 如何测试与释放管道的联系.

捐款

虽然我们重视对SDK的开源贡献,但这个库是程序生成的. 随便打开公关或Github问题作为概念的证明,我们会尽力将其纳入未来的发行中!

SDK 创建者 说话方便

版本与发布记录

@gr4vy/sdk 共发布 317 个版本,首次发布于 2025/04/23;过去 12 个月发布了 189 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.4.47latest2026/11/115 天前
2.4.462026/11/115 天前
2.4.452026/11/097 天前
2.4.442026/11/0511 天前
2.4.432026/11/0412 天前
2.4.422026/11/0412 天前

关于 @gr4vy/sdk 的常见问题

@gr4vy/sdk 是什么?

开发者方便且类型安全 类型SDK 格鲁维 API (英语).

如何安装 @gr4vy/sdk?

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

@gr4vy/sdk 支持 TypeScript 吗?

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

@gr4vy/sdk 支持 ESM 还是 CommonJS?

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

@gr4vy/sdk 可以商用吗?

@gr4vy/sdk 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@gr4vy/sdk 的下载量有多少?

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

@gr4vy/sdk 还在维护吗?

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