Gr4vy 嵌入反应
快速将Gr4vy嵌入您的 React app 存储卡片细节, 授权支付,并获取交易.
使用 @gr4vy/embed 在非反应应用程序中.
使用量
通过命令行,将这个软件包安装如下.
npm install @gr4vy/embed-react --save-prod
# pnpm add @gr4vy/embed-react --save
开始吧
要使用 Gr4vy Embed,请导入 Gr4vyEmbed 组件.
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 软件 更多细节.
表单
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 选项可以用来收听窗体释放出的某些事件.
<Gr4vyEmbed
amount={1299}
currency='USD'
onEvent={(name, data) => {...}}
...
/>
})
目前,我们Gr4vy Embed发布以下事件.
agumentError
初始输入时返回( E)element, (中文(简体) ), options) 格式不正确或缺失.
{
"code": "argumentError",
"option": "currency",
"message": "must be a valid number"
}
optionsLoaded
当选项被装入时返回 。 存储的选项包括: id。 。 。 .
[
{
"id": "...",
"method": "card",
"mode": "card"
},
{
"method": "card",
"mode": "card"
}
]
formUpdate
表格更新时返回 。 目前只通知开发者, 如果窗体 无效.
{
"valid": false
}
transactionCreated
Gr4vy 接受交易时返回完整的交易对象,
不论地位如何 要知道,这可能是一个待决或拒绝
交易。 跟踪 API 失败请使用 transactionFailed 活动.
{
"type": "transaction",
"id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"status": "pending",
...
}
transactionCancelled
当买方明确取消一项交易,例如结束一次弹出或驳回Apple Pay时返回。 目前不支持三维安全交易 并且不应与交易被拒绝或发生错误相混淆.
{
"type": "transactionCancelled"
}
transactionFailed
API 呼叫无法创建客户端交易时返回或
服务器出错。 换句话说,这个事件是在不正确数据(如:
无效的 JWT) 传递给 Gr4vy API 和 HTTP 状态代码 4XX 或者说
5XX 区域返回.
由于交易失败或减少
支付服务的下游问题,请订阅
transactionCreated 活动.
{
"type": "error",
"code": "unauthorized",
"status": 401,
"message": "No valid API authentication found"
}
apiError
当窗体遇到 API 错误时返回 .
{
"type": "error",
"code": "unauthorized",
"status": 401,
"message": "No valid API authentication found",
"details": []
}
cardDetailsChanged
当卡BIN在形式上有所改变时返回. 它包含输入卡的信息,如BIN,卡类型和计划等.
{
"bin": "42424242",
"scheme": "visa",
"cardType": "debit"
}
自定义表格提交
嵌入会自动提交带有隐藏输入的支付表, 使用 onComplete 调用.
<Gr4vyEmbed
amount={1299}
currency='USD'
onEvent={(name, data) => {...}}
onComplete={(transaction) => {
// Handle custom form submission
}}
/>
无表格的提交
嵌入不需要有表格,才能进入 EmbedInstance 你可以直接通过一个裁判。 你应该执行 onComplete 如果您选择了这个选项.
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 如果您选择了这个选项.
<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,并将此指定给交易,作为元数据或外部标识符.
setup({
onBeforeTransaction: async () => {
const { orderId } = await merchantBackend.getOrderId()
return {
externalIdentifier: orderId,
}
},
})
如果您指定了已被设定为默认选项的密钥, 您就需要将已有的值与您的更改合并 .
setup({
onBeforeTransaction: async ({ metadata }) => {
const { token, orderId } = await merchantBackend.getOrderId()
return {
token, // new token with pinned metadata
metadata: {
...metadata, // merge existing metadata
orderId,
},
}
},
})
许可证
这个项目是在以下项下提供的: 麻省理工学院许可证。 。 。 .