安全字段
在您的节点应用中添加安全域 .
使用 @gr4vy/secure-fields-react 在反应应用程序中或 @gr4vy/secure-fields-cdn 在非节点网络应用程序中.
使用量
通过命令行,将这个软件包安装如下.
npm install @gr4vy/secure-fields --save-prod
# yarn add @gr4vy/secure-fields --save
开始吧
要使用安全字段, 您需要一些占位元素来附加安全字段 。 每一个要素都将被安全地段所取而代之。 这些要素可以是: <input> 但没必要这样.
<label for="cc-number">Card Number</label>
<input id="cc-number" />
<label for="cc-cvv">Security code</label>
<input id="cc-cvv" />
<label for="cc-expiry">Expiry date</label>
<input id="cc-expiry" />
<button id="cc-button">Submit</button>
要使用安全域,请拨打 new SecureFields() 方法,其中包含配置对象 environment (单位:千美元)sandbox 或者说 production),你的电话 gr4vyId (单位:千美元) sessionId 从电话中调用 检查会话 API选项 paymentMethod 对象为 id 财务报告和审定财务报表 scheme 也可以通过存储的支付方法来使用安全域.
然后,添加处理表单提交所需的字段和事件听众.
const { SecureFields } = require('@gr4vy/secure-fields')
// Alternatively
// import { SecureFields } from '@gr4vy/secure-fields'
const secureFields = new SecureFields({
gr4vyId: '[GR4VY_ID]',
environment: 'sandbox',
sessionId: '[SESSION_ID]',
// For stored payment methods (optional):
// paymentMethod: {
// id: '[PAYMENT_METHOD_ID]',
// scheme: 'visa' // Enables accurate CVV validation (3 digits for Visa/Mastercard, 4 for Amex)
// },
// Deprecated:
// paymentMethodId: '[PAYMENT_METHOD_ID]', // uuid of a stored payment method
})
secureFields.addFont('Lato')
const styles = {
color: 'black',
fontSize: '18px',
fontFamily: 'Lato',
':focus': {
color: 'blue',
},
}
const number = secureFields.addCardNumberField('#cc-number', { styles })
const expiry = secureFields.addExpiryDateField('#cc-expiry', { styles })
const cvv = secureFields.addSecurityCodeField('#cc-cvv', { styles })
secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () =>
console.log('Card tokenized successfully')
)
secureFields.addEventListener(
SecureFields.Events.CARD_VAULT_FAILURE,
(data) => console.log('Card tokenization failed', data) // data.status, data.code, data.message
)
number.addEventListener('input', (data) => {
console.warn('Input changed', data) // data.schema, data.codeLabel...
})
const button = document.querySelector('#cc-button')
button.addEventListener('click', () => {
secureFields.submit()
})
说明替换
[GR4VY_ID]用你的Gr4vy身份证和[SESSION_ID]带有有效的退出会话编号.
这将初始化安全字段,并用相应的安全元素来取代每个输入. 在提交时,它会安全地将卡片数据与Gr4vy保存在一起,之后您可以创建交易或将卡片保存到后期使用.
您也可随卡数据一同收集其他信息. 我们目前支持增加一个邮政编码字段,可在表格中添加该字段 addField 方法,通过特定 type 和其余的选择.
<!-- placeholder HTML code -->
<label for="postal-code">Postal code</label>
<input id="postal-code" />
// js code
const postalCode = secureFields.addField('#postal-code', {
type: 'postalCode',
pattern: '[A-Z][0-9]\\s[0-9][A-Z]{2}', // optional, defaults to 5 characters minimum
maxlength: 7 // optional, defaults to no maximum length
styles,
...
})
postalCode.addEventListener('input', (data) => {
console.warn('Input changed', data)
})
重设
每个实地实例都显示 clear() 用于程序重置值的方法.
const number = secureFields.addCardNumberField('#cc-number', { styles })
const clearButton = document.querySelector('#clear-button')
clearButton.addEventListener('click', () => number.clear())
验证
默认情况下,一个字段一旦用户离开就会被标记无效 。 打电话 validate() 以同时标记每个无效字段,包括用户从未触及过的空字段,例如用户点击"Pay"时。 使用 complete 财产的财产 FORM_CHANGE 如果表格未准备好, 则停止提交.
let complete = false
secureFields.addEventListener(SecureFields.Events.FORM_CHANGE, (data) => {
complete = data.complete
})
payButton.addEventListener('click', () => {
secureFields.validate()
if (secureFields.method === 'card' && !complete) return
secureFields.submit()
})
在不显示错误之前 validate() 叫做,设置 validateOn 改为 'submit' 在添加字段之前。 之后,错误更新为用户类型.
secureFields.setValidateOn('submit')
每一领域 FORM_CHANGE 事件及报告 touched (至少被打碎或鉴定一次)和 dirty (通过打入或浏览器自动填充,值至少改变一次).
自动聚焦
一旦一个字段的iframe被通过加载, 自动聚焦它 autoFocus: true。 。 。 .
const number = secureFields.addCardNumberField('#cc-number', {
autoFocus: true,
styles,
})
输入遮盖
隐藏卡号和安全码字段的值来隐藏敏感数据.
const number = secureFields.addCardNumberField('#cc-number', {
maskInput: {
character: '•', // masking character (default: •)
showLastFour: true, // keep last 4 digits visible when valid (card number only)
maskOnInput: true, // mask in real-time as the user types (default: on blur only)
},
styles,
})
也可以在程序上遮盖并解开一个字段:
number.redactValue() // mask the value
number.unredactValue() // unmask the value
自动提前
当当前字段完整且有效时,将焦点自动移动到下一个字段.
secureFields.setAutoAdvance({
enabled: true,
fieldOrder: ['number', 'expiryDate', 'securityCode'], // optional, defines the order of fields
})
说明:自动推进会给用户体验带来负面影响. 在投入生产前进行彻底测试.
方案图标
在卡号字段内显示卡片方案图标。 图标作为用户类型进行实时更新,并在API确认方案时被完善.
过 true 以显示检测到的方案图标以及任何附加方案(例如同名牌):
const number = secureFields.addCardNumberField('#cc-number', {
showSchemeIcons: true,
styles,
})
对于颗粒控件,通过一个对象来选择要显示的图标 :
const number = secureFields.addCardNumberField('#cc-number', {
showSchemeIcons: {
scheme: true, // show the detected card scheme icon (default: false)
additionalSchemes: true, // show additional scheme icons, e.g. co-branded (default: false)
placeholders: true, // show placeholder icons (Visa, Mastercard, Amex) before detection (default: false)
},
styles,
})
说明:最多3个图标随时可见. 在共同品牌的情景中,首先显示主方案图标,然后显示其他方案。 确保卡号输入的宽度足以容纳最多3个图标.
详情请查阅 提及 安全字段开始引导。 。 。 .
样式
每个安全场的外层造型完全由您控制,将自己的CSS应用到以下的类名上.
/* Applied to each field */
.secure-fields__input {
}
/* Applied to the card number field */
.secure-fields__input--number {
}
/* Applied to the expiry date field */
.secure-fields__input--expiry-date {
}
/* Applied to the security code field */
.secure-fields__input--security-code {
}
/* Applied to the postal code field */
.secure-fields__input--postal-code {
}
/* Applied to a focused field */
.secure-fields__input[data-secure-fields-focused] {
}
/* Applied to an invalid field */
.secure-fields__input[data-secure-fields-invalid] {
}
/* Applied to an autofilled field */
.secure-fields__input[data-secure-fields-autofilled] {
}
要设置一个字段内容的 CSS 对象, CSS 规则可以传递给 addCardNumberField, (中文(简体) ), addExpiryDateField, (中文(简体) ), addSecurityCodeField 财务报告和审定财务报表 addField 方法。 。 .
const styles = {
// Default styles applied to field
color: "#66666",
fontSize: "1.3em",
// ...etc
// Applied when field has a value autofilled by browser/extension
':autofill': { ... },
// Applied when field is hovered
':hover': { ... },
// Applied when field is focused
':focus': { ... },
// Applied when field is disabled
':disabled': { ... },
// Applied when field is valid
':valid': { ... },
// Applied when field is invalid
':invalid': { ... },
// Applied to field placeholder
'::placeholder': { ... },
}
并非所有 CSS 属性都可以设置 。 目前支持的列表如下.
backgroundColor
boxShadow
caretColor
color
colorScheme
cursor
font
fontFamily
fontFeatureSettings
fontKerning
fontSize
fontSizeAdjust
fontStretch
fontStyle
fontVariant
fontVariantAlternates
fontVariantCaps
fontVariantEastAsian
fontVariantLigatures
fontVariantNumeric
fontVariationSettings
fontWeight
letterSpacing
lineHeight
opacity
padding
textAlign
textShadow
textRendering
transition
MozOsxFontSmoothing
WebkitFontSmoothing
活动
全球活动
以下事件可通过下列方式监听: SecureFields 实例 addEventListener 方法.
| 名称 | 说明 | 示例 |
|---|---|---|
CARD_VAULT_SUCCESS | 卡片被成功金库时触发. | secureFields.addEventListener(SecureFields.Events.CARD_VAULT_SUCCESS, () => { console.log('Card has been tokenized successfully!') }) |
CARD_VAULT_FAILURE | 当卡片金库失败时触发 . | secureFields.addEventListener(SecureFields.Events.CARD_VAULT_FAILURE, ({ code, status, message }) => { console.log('Couldn\'t tokenize the card', { code, status, message }) }) |
FORM_CHANGE | 当一个窗体字段被更改时触发 。 这个 complete 属性显示表格是否准备好提交,即卡片号码和过期日期是否填充和有效. | secureFields.addEventListener(SecureFields.Events.FORM_CHANGE, ({ complete, fields }) => { console.log('Form state', { complete, fields }) }) |
READY | 安全域装入并准备使用时触发. | secureFields.addEventListener(SecureFields.READY, () => { console.log('Secure fields loaded') }) |
外地活动
以下事件可通过将事件处理器附加到一个字段(由 addCardNumberField, (中文(简体) ), addExpiryDateField, (中文(简体) ), addSecurityCodeField 财务报告和审定财务报表 addField 使用方法) addEventListener 方法.
其中一些提供了额外的有用数据,如卡BIN,验证状态,以及方案等. 例如,卡号字段中的输入事件可能包括: { schema: 'visa', codeLabel: 'CVV', valid: true, ... }。 。 。 .
| 名称 | 说明 | 示例 |
|---|---|---|
blur | 当场失去焦点时触发. | cardNumberField.addEventListener('blur', (data) => { console.log(data) /* { id: 'number' } */ }) |
focus | 当场获得焦点时触发. | cardNumberField.addEventListener('focus', (data) => { console.log(data) /* { id: 'number' } */ }) |
input | 当字段值被更改时触发 . | cardNumberField.addEventListener('input', (data) => { console.log(data) /* { id: 'number', schema: 'visa', codeLabel: 'CVV', valid: true, empty: true, autofilled: false, bin: '411111' } */ |
redacted | 当字段值被遮住( 或自动通过) 时触发 maskInput 或方案通过 redactValue()) (中文(简体) ). | cardNumberField.addEventListener('redacted', () => { console.log('Field redacted') }) |
unredacted | 当字段值被解析(自动或程序通过)时触发 unredactValue()) (中文(简体) ). | cardNumberField.addEventListener('unredacted', () => { console.log('Field unredacted') }) |
card-details-changed | 当API确认输入的BIN的卡片细节时触发. 包括已确认 scheme, (中文(简体) ), additionalSchemes (共同品牌网络),以及其他卡元数据. 只向牌号字段开火. | cardNumberField.addEventListener('card-details-changed', (data) => { console.log(data) /* { id: 'number', scheme: 'visa', additionalSchemes: ['mastercard'], ... } */ }) |
单击以支付
点击支付是在线支付更好的方式 — — 其特点是基于安全的远程商业行业标准的先进支付技术.
先决条件
遵循指示 点击以支付 Merchant 设置。 。 。 .
正在添加点击到 Pay
安全字段配置完毕后,您就可以开始在退出时添加 Click to Pay .
首先,在表格中添加一个占位符组件,以便“安全字段”知道在哪里使“点击支付”组件.
然后,添加一个简单的登录表单,让用户访问他们的Click to Pay存储的卡.
此外,添加一个复选框,允许尚未注册的客户确定是否想要与 Click To Pay 共享卡片数据 .
最后,确保将卡片输入用容器元件包裹(例如:. <form />),带有特定的标识.
<div id="click-to-pay"></div>
<div id="click-to-pay-sign-in" style="display: none;">
<label>Access your Click to Pay stored cards</label>
<input type="text" id="phoneOrEmail" />
<button id="signInButton">Continue</button>
</div>
<form id="card-form" style="display: none;">
<label htmlFor="cc-number">Card number</label>
<input type="text" id="cc-number" />
<label htmlFor="cc-expiry-date">Expiry date</label>
<input type="text" id="cc-expiry-date" />
<label htmlFor="cc-security-code">Security code</label>
<input type="text" id="cc-security-code" />
</form>
<input type="checkbox" id="click-to-pay-consent-checkbox" />
<label for="click-to-pay-consent-checkbox"
>Store my card with Click to Pay</label
>
<script>
var phoneOrEmail = document.querySelector('#phoneOrEmail')
var signInButton = document.querySelector('#signInButton')
signInButton.addEventListener('click', function () {
clickToPay.signIn({ email: phoneOrEmail.value })
})
</script>
接下来,将“单击以支付”的安全字段附加到此元素中。 这将需要您想要创建交易的用户的电子邮件和/或电话号码 。 它还需要 HTML 查询同意复选框,该复选框控制新卡的卡片数据是否与 Click To Pay 共享.
const clickToPay = secureFields.addClickToPay('#click-to-pay', {
dpaLocale: 'en_AU',
cardBrands: ['mastercard', 'visa', 'american-express'],
email: '[email protected]',
mobileNumber: {
countryCode: '61',
phoneNumber: '491570159',
},
consentCheckbox: '#click-to-pay-consent-checkbox',
signIn: '#click-to-pay-sign-in',
cardForm: '#card-form',
})
// clickToPay = { element: <div id="click-to-pay" />, signIn: ..., options: { dpaName: ... } }
可用点击支付选项如下:
| 选项名称 | 说明 |
|---|---|
srcDpaId | 政治部识别员。 这是您 Digital Pay 应用程序( DPA) 的独有标识符, 它是在登入时生成的 . |
dpaName | 登记的政治部的法定名称. |
cardBrands | 商家所接受的卡片计划列表. 我们目前支持 mastercard, (中文(简体) ), maestro, (中文(简体) ), visa, (中文(简体) ), amex, (中文(简体) ), discover |
cardForm | 参考出卡表包装. |
signIn | 指代登录元素包装. |
consentCheckbox | 引用“选入”的同意复选框元素. |
learnMoreLink | 参考学习更多联系要素. |
email | 用户电子邮件用于访问 Click to Pay . |
mobileNumber | 用于访问 Click to Pay 的用户电话号码 。 要求的格式是 { countryCode: string, phoneNumber: string } |
dynamicDataType | 用于卡片数据的密码图或令牌类型. 见 主卡文档 更多信息。 可能值为 NONE 财务报告和审定财务报表 CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM默认为 CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM。 。 。 . |
其他全球活动
以下点击到 Pay 事件可以通过将事件处理器附加到 SecureFields 实例 addEventListener 方法.
| 名称 | 说明 | 示例 |
|---|---|---|
CLICK_TO_PAY_INITIALIZED | 点击到 Pay 时已初始化 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_INITIALIZED, (clickToPay) => { console.log('Click to Pay initialized', clickToPay) }) |
CLICK_TO_PAY_READY | 点击到发薪准备时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_READY, ({ buyerExists }) => { console.log('Click to Pay ready', { buyerExists }) }) |
CLICK_TO_PAY_SIGN_OUT | 当用户从 Click to Pay 中签名时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_SIGN_OUT, ({ buyerExists }) => { console.log('User signed out') }) |
CLICK_TO_PAY_ERROR | 点击到 Pay 时触发出错 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_ERROR, (error) => { console.log('Click to Pay error', error) }) // "RETRIES_EXCEEDED" | "CODE_INVALID" | "INVALID_CARD" | "SIGN_OUT_FAILED" | "ACCT_INACCESSIBLE" | "UNKNOWN" | "USER_NOT_RECOGNIZED" | |
CLICK_TO_PAY_CANCEL | 当用户关闭 / 取消 点击到 Pay 时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_CANCEL, () => { console.log('User cancelled Click to Pay') }) |
CLICK_TO_PAY_CHECKOUT_WITH_NEW_CARD | 当一个用户用新卡(尚未注册到 Click to Pay)来完成取出时触发. | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_CHECKOUT_WITH_NEW_CARD, () => { console.log('User is using a new card') }) |
CLICK_TO_PAY_UNABLE_TO_LOAD_DPA | 当无法装入提供的 Click to Pay DA 时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_UNABLE_TO_LOAD_DPA, () => { console.log('Unable to load Click to Pay DPA') }) |
CLICK_TO_PAY_VISIBILITY_CHANGE | 当单击到付费元素显示或隐藏时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_VISIBILITY_CHANGE, (visible) => { console.log('Click to Pay element is ' + visible ? "visible" : "not visible") }) |
CLICK_TO_PAY_CARD_FORM_VISIBILITY_CHANGE | 当卡片格式的容器显示或隐藏时触发. | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_CARD_FORM_VISIBILITY_CHANGE, (visible) => { console.log('Card form is ' + visible ? "visible" : "not visible") }) |
CLICK_TO_PAY_SIGN_IN_VISIBILITY_CHANGE | 显示或隐藏容器中的标志时触发 . | secureFields.addEventListener(SecureFields.Events.CLICK_TO_PAY_SIGN_IN_VISIBILITY_CHANGE, (visible) => { console.log('Sign in is ' + visible ? "visible" : "not visible") }) |
METHOD_CHANGE | 当用户选择不同的方法时触发( 或 card 或者说 click-to-pay(中文(简体) ) | secureFields.addEventListener(SecureFields.Events.METHOD_CHANGE, (method) => { console.log('Selected method changed', method) }) |
更新退出选项
初始化后更新“ 点击支付” 退出选项。 当交易金额在用户提交前发生变化(例如手推车更新)时,此功能是有用的.
secureFields.clickToPay.updateCheckoutOptions({
transactionAmount: 9.99,
transactionCurrencyCode: 'AUD',
})
选项与先前设定的值合并,这样可以更新单个字段而不会丢失其余部分.
// Set initial options
secureFields.clickToPay.updateCheckoutOptions({
transactionAmount: 9.99,
transactionCurrencyCode: 'AUD',
})
// Later, update only the amount — currency is preserved
secureFields.clickToPay.updateCheckoutOptions({
transactionAmount: 12.99,
})
| 选项 | 类型 | 说明 |
|---|---|---|
transactionAmount | number | 交易金额. |
transactionCurrencyCode | string | 交易货币代码. |
API 参考
计数器
| 名称 | 说明 |
|---|---|
Events | 允许访问支持的活动. SecureFields.Events.READY |
version | 返回实例的当前版本. SecureFields.version |
方法
| 名称 | 说明 |
|---|---|
constructor | 配置对象的安全字段包括: environment, (中文(简体) ), gr4vyId 和会议编号。 可选 paymentMethod 对象为 id 财务报告和审定财务报表 scheme 也可以通过存储的支付方法来使用安全域. new SecureFields({...}) |
addCardNumberField | 注入安全类型字段 number。 。 。 . secureFields.addCardNumberField('#cc-number', { placeholder: 'Enter card number', ... }) |
addSecurityCodeField | 注入安全类型字段 securityCode。 。 。 . secureFields.addSecurityCodeField('#cc-security-code', { placeholder: 'Enter security code', ... }) |
addExpiryDateField | 注入安全类型字段 expiryDate。 。 。 . secureFields.addExpiryDateField('#cc-expiry-date', { placeholder: 'Enter expiry date', ... }) |
addField | 允许根据 type,例如邮政编码字段. secureFields.addField('#postal-code', { type: 'postalCode', placeholder: 'Enter postal code', ... }) |
addClickToPay | 注入一个初始化的字段. secureFields.addClickToPay('#click-to-pay', { dpaLocale: 'en_AU', cardBrands: ['mastercard', 'visa'], ... }) |
addEventListener | 将事件处理器附加到安全字段实例或安全字段,以便聆听特定事件。 需要支持的事件之一和回调 . secureFields.addEventListener(SecureFields.Events.READY, (data) => { ... }) cardNumberField.addEventListener('input', (data) => { ... }) |
removeEventListener | 删除先前所附的事件处理器. |
submit | 呼叫 Vault API 以对卡片数据进行标识并存储. secureFields.submit() |
setDebug | 启用/ 禁用调试模式 。 当调试模式启用后, SecureFields 将信息日志到控制台. secureFields.setDebug(true) |
addFont | 装入自定义字体 谷歌字体 用于内部输入。 您可以将字体家族以及样式或权重定义为字符串(例如"Lato:400,600"). 要使用已装入的字体,请添加正确的 fontFamily 属性到样式的对象. secureFields.addFont('Lato') |
validate | 标记每个无效字段,包括用户从未触及过的空字段,并标记所有字段为 touched。 。 。 . secureFields.validate() |
setValidateOn | 设置字段显示校验错误时 : 'blur' (默认),一旦用户离开一个字段,或 'submit',一次 validate() 名为. secureFields.setValidateOn('submit') |
setAutoAdvance | 当当前字段的值完整且有效时,允许自动提前将焦点自动移动到下一个字段. 接受 { enabled: boolean, fieldOrder?: Array<FieldType> }。 。 。 . secureFields.setAutoAdvance({ enabled: true }) |
实地方法
| 名称 | 说明 |
|---|---|
clear | 重置字段的值 . cardNumberField.clear() |
redactValue | 遮住现场在方案上的价值。 要应用遮盖行为, 配置 maskInput 为田地. cardNumberField.redactValue() |
unredactValue | 从方案角度解析实地价值。 要应用遮盖行为, 配置 maskInput 为田地. cardNumberField.unredactValue() |
外地选项
以下选项在添加字段(如:. addCardNumberField('#el', options)) (中文(简体) ).
| 名称 | 类型 | 说明 |
|---|---|---|
placeholder | string | 输入占位符文本 . |
styles | object | Iframe内部输入的 CSS 样式 . |
label | string | 输入的可访问标签 . |
autoFocus | boolean | 装入时自动聚焦字段 . |
maskInput | boolean | object | 启用输入掩码 。 使用 true 默认遮盖,或通过选项对象: character (装模作样的人物), showLastFour (只有卡号), maskOnInput (实时口罩). |
showSchemeIcons | boolean | object | 在卡号字段内显示卡片方案图标。 图标作为用户类型进行实时更新,并在API确认方案时被完善. 接受 true 以显示方案和额外方案图标,或用于接受颗粒控制的对象:二. 支助 scheme: (boolean) 显示检测到的方案二. 支助 additionalSchemes: (boolean) 显示同名图标二. 支助 placeholders: (boolean) 检测前显示 Visa/Mastercard/Amex最多显示3个图标——确保输入足够宽以容纳. 仅存于 addCardNumberField。 。 。 . |