节点的 Gr4vy SDK
[大 这个SDK现在已经贬值了. 请参见我们的新 贝塔打字机 SDK 这个SDK的新方向.
Gr4vy通过一个统一的API提供任何您的支付整合. 详情请访问 gr4vy.com (英语)。 。 。 .
安装
要将 Gr4vy 添加到您的工程中, 请安装 @gr4vy/node 软件包如下.
npm install @gr4vy/node --save
# yarn add @gr4vy/node
开始
要打第一个API电话,你需要 请求 a 将设立Gr4vy实例。 请联系我们的销售团队 进行演示.
一旦你建立了Gr4vy账户,你需要去 一体化 面板并生成一个私钥。 我们建议把这个密钥存储在一个安全的地方 但是在这个代码样本中 我们只是从磁盘上读取文件.
const fs = require('fs')
const { Client, BuyerRequest } = require('@gr4vy/node')
// or: import { Client, BuyerRequest } from "@gr4vy/node";
const key = String(fs.readFileSync('./private.key'))
const client = new Client({
gr4vyId: 'YOUR_GR4VY_ID',
privateKey: key,
environment: 'production',
})
const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
const buyer = await client.newBuyer(buyerRequest)
console.log(buyer)
// {
// response: {...} the HTTP response object
// body {...} the parsed JSON
// }
环境
SDK 默认环境为 “ sandbox ” , 将交易发送到生产中, 设置环境 Client数字 :
const client = new Client({
gr4vyId: 'YOUR_GR4VY_ID',
privateKey: key,
environment: 'sandbox',
})
const client = new Client({
gr4vyId: 'YOUR_GR4VY_ID',
privateKey: key,
environment: 'production',
})
Gr4vy 嵌入器
要为 Gr4vy Embed 创建一个符号,请拨打 client.getEmbedToken() 函数
gr4vy Embed的金额、货币和可选购买信息.
// generate a session to tie any transactions to
const response = await this.newCheckoutSession()
// generate the token
const token = await client.getEmbedToken({
amount: 1299,
currency: 'USD',
buyerExternalIdentifier: 'user-1234',
checkoutSessionId: response.body.id,
// or: buyerId: ...
})
// or to combine both calls in one
const { token, checkoutSession } =
await client.getEmbedTokenWithCheckoutSession(embedParams)
你现在可以把这个标志 传递到你的前端 它可以用来 认证Gr4vy Embed.
刷新一个符号
获得带有新到期日的新令牌,或者在令牌上添加新数据,同时不丢失取出会话ID,
你可以打电话 updateEmbedToken 重新使用原始符号和新数据。 您的退出会
自动添加到同一种符号.
const token = await client.updateEmbedToken(oldToken, {
amount: 1299,
currency: 'USD',
buyerExternalIdentifier: 'user-1234',
})
其他数据
附加数据可以添加到一个符号上. 这个 buyerId 财务报告和审定财务报表 buyerExternalIdentifier
字段可以用于让符号为用户拉入先前存储的支付方法.
购买者需要先被创造,然后才能被这样使用.
const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
buyerRequest.externalIdentifier = 'user-1234'
const buyer = await client.newBuyer(buyerRequest)
const token = await client.getEmbedToken({
amount: 1299,
currency: 'USD',
buyerId: buyer.body.id,
})
初始化
客户端可以用 Gr4vy ID 初始化(gr4vyId和私人钥匙.
const client = new Client({
gr4vyId: 'acme',
privateKey: key,
})
或者,不要 gr4vyId 它可以初始化 与 baseUrl 用于直接使用的服务器.
const client = new Client({
baseUrl: 'https://api.acme.gr4vy.app',
privateKey: key,
})
您的 API 密钥可以在您的管理面板中创建 一体化 选项卡.
给API打电话
这个库方便地将每个API路径映射到一个分隔函数. 譬如说, GET /buyers?limit=100 将:
client.listBuyers(null, 100)
要创建或更新资源, API 需要为此请求对象
以修道院命名的资源 <Resource>Request 或者说
<Resource>UpdateRequest。 。 。 .
例如,要创建买方,您需要通过 BuyerRequest 对象
页:1 addBuyer 方法.
const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
const buyer = await client.newBuyer(buyerRequest)
同样,为了更新购买者,您需要通过 BuyerUpdateRequest。 。 。 .
const buyerUpdateRequest = new BuyerUpdateRequest()
buyerUpdateRequest.displayName = 'John D.'
const buyer = await client.updateBuyer(buyer.id, buyerUpdateRequest)
生成 API 无记名符号
SDK 可用于创建 API 访问令牌, 以便与其他请求一起使用 图书馆.
import { JWTScope } from '@gr4vy/node'
const bearerToken = client.getBearerToken(
[JWTScope.BuyersRead, JWTScope.BuyersWrite],
'1h'
)
第一个参数是Gr4vy API的公认范围列表. 第二个
参数是该符号定义的过期时间
vercel/ms 图书馆.
在 HTTP 的页眉中, 生成的符可以用作无记名符号 请求API.
Authorization: Bearer <bearerToken>
回应和承诺( O)
API 调用返回 a Promise 要么决定,要么拒绝.
每个解析的 API 调用返回包含 body
属性与已解析的 JSON 天体和 a response 表示对象
HTTP 响应对象,包括原始头和状态代码.
对于一个失败的 API 调用, 它返回一个与 API 一起返回的类似对象 body
错误.
client
.getBuyer(buyer.id)
.then((result) => {
console.dir(result.body) // the parsed JSON
console.dir(result.response.statusCode) // the status code of the response
})
.catch((error) => {
console.dir(error.response.body) // the parsed JSON of the error
console.dir(error.response.statusCode) // the status code of the error
})
正在校验 Webhooks
SDK提供了一个 verifyWebhook 用于验证Gr4vy收到的webhook请求的方法。 这确保了网钩有效载荷是真实的,没有被篡改.
使用量
const { Client } = require('@gr4vy/node')
// or: import { Client } from '@gr4vy/node';
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 {
Client.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(没有宽容).
错误
这个 verifyWebhook 方法在以下情况下丢出错误:
- 缺少信头值: 如果其中之一
signatureHeader或者说timestampHeader缺少. - 无效的页眉时间戳: 如果
timestampHeader不是一个有效的号码. - 未找到匹配的签名:如果签名与预期值不符.
- 时间戳太老了: 如果时间戳在允许的容忍度之外.
日志调试( D)
SDK使得对控制台的要求和回应变得容易.
const client = new Client({
gr4vyId: 'demo',
privateKey: key,
debug: true,
// merchantAccountId: 'my-merchant-id' # optional for multi merchant instances
})
这将输出请求参数和对控制台的响应如下.
Gr4vy - Request - .getBuyer: 41291df0-4a5d-42d9-a977-dbc8ef6463c4
Gr4vy - Response - .getBuyer - 200): Buyer {
type: 'buyer',
id: '41291df0-4a5d-42d9-a977-dbc8ef6463c4',
external_identifier: null,
display_name: 'Test',
created_at: 2021-02-23T16:23:22.794Z,
updated_at: 2021-02-23T16:23:22.794Z
}
发展
添加新的 API
要添加新的 API, 请运行以下命令以更新模型和基于 API 的 API 的 API 规格.
./openapi-generator-generate.sh
下一个, 更新 sdk/client.ts 绑定任何新的 API 或删除任何没有的 API
时间更长.
const poa = new PaymentOptionsApi(this.baseUrl)
this.listPaymentOptions = this.wrap(poa.listPaymentOptions.bind(poa))
this.apis.push(poa)
出版
此工程的出版将自动使用 yarn release
命令创建新版本,将其发布到标签上,然后触发一个
GitHub行动组织向国家预防机制发布新的一揽子计划.
许可证
此库在 MIT 许可证。 。 。 .
发布注释
- 1.0.0 - 更新到 OpenAPI SDK 生成器 v7. 6.0
- 0.65.0 - 更新依赖性