dLocal China
Search…
dLocal.js 参考资料

引用 dlocal.js

如果您要使用dlocal.js,则首先要引用库并设置API密钥。 开始使用前,请在您的页面上包含此脚本 - 它应始终直接从 https://js.dlocal.com 加载。如需进行测试,您可以使用 https://js-sandbox.dlocal.com
1
<script src="https://js.dlocal.com/"></script>
Copied!

dLocal 对象

dlocal.fields([options])

使用 Smart Fields (在API中简称为fields) 创建预先构建的UI组件来收集付款信息。
1
var fields = dlocal.fields({
2
locale: 'en',
3
country: 'BR'
4
});
Copied!
这个方法创建一个fields实例,用于管理一组Smart Fields。它可以接收一个Options对象。可用的Options列表如下:
Option
类型
描述
locale
String
所在国家的二字简码IETF language tag ,用于显示占位符和错误提示。默认为西班牙语(es)。 支持的值为:es,en,pt,zh,cv,tr。
country
String
用户的国家二字简码:参考ISO 3166-1
fonts
Array (Optional)
一组自定义字体,使用fields对象创建Smart Fields时使用。可以通过传递具有 cssSrc 参数的对象来通过CSS文件加载字体,也可以通过直接传递 Font对象加载字体.
参数
类型
描述
cssSrc
String
指向具有 @font-face 定义的CSS文件的相对或绝对URL,例如: "https://fonts.googleapis.com/css?family=Open+Sans"

Font 对象

参数
类型
描述
family
String
font对象的名称。
src
String
指向自定义字体文件的有效 src 值。通常(并非总是)指向.woff.otf.svg后缀的文件的链接。
display
String (Optional)
有效的 font-display 值。
style
String
可选值:'normal', 'italic', 'oblique'。默认值: 'normal'.
unicodeRange
String (Optional)
有效的 unicode-range 值。
weight
String (Optional)
有效的 font-weight 。注意此值为String类型,不是数字类型。

dlocal.createToken(field, tokenData)

使用 dlocal.createToken()将Smart Fields收集的信息转换为Token,从而可以安全地通过您的服务器向dLocal API发起付款请求。 此Token在创建10分钟后或使用一次之后过期(如进行银行卡保存或者发起一次付款),因此请确保在时间范围内完成付款创建。
使用Smart Fields token 来存储银行卡并创建付款
如果你想先使用Smart Fields来 保存银行卡,然后用它来 发起付款,那么你需要使用Smart Fields 对银行卡进行两次Token申请。首先,你需要使用Smart fields token 来新建银行卡,然后再次获取Token并使用新的Token来发起付款。
1
dlocal.createToken(card,tokenData)
2
.then(function(result) {
3
// Handle result.token
4
}
5
.catch(function(result) {
6
// Handle result.error
7
}););
Copied!
此方法有两个参数:
  • field, 需要进行Token化的Smart Field。如果应用用此字段,Smart Field会从使用fields实例化的其他Smart Fields中提取数据以进行Token转化。
  • tokenData, 包含您已收集的其它付款信息的对象。 对于银行卡,它可以包含以下任何参数:
参数
类型
描述
name
String (Required)
持卡人姓名。
address_line1
address_line2
address_city address_state
address_zip address_country
String (Optional)
账单地址信息字段。 address_country字段是国家/地区的二字简码(例如,'BR' 表示巴西)。
currency
String (Optional)
交易货币种类。
dlocal.createToken 返回由result 对象解析的响应。此对象包含以下两个参数之一:
  • result.token: Token 创建成功。
  • result.error: 存在错误,包括用户端的验证错误。

dlocal.createInstallmentsPlan(field, amount, currency)

使用dlocal.createInstallmentsPlan()创建分期付款计划,确保分期付款的手续费正常收取。
1
dlocal.createInstallmentsPlan(card, amount, currency)
2
.then(function(result) {
3
// Handle result.installments
4
}
5
.catch(function(result) {
6
// Handle result.error
7
}););
Copied!
强烈建议 您在 brand 事件中包含 createInstallmentsPlan。因为分期付款计划仅取决于交易金额和银行卡卡种。
分期付款参数
分期付款计划对象
分期付款对象
分期付款计划对象示例
参数
类型
描述
field
SmartField
您希望创建分期付款计划的Smart Field,如果您不使用card字段,我们建议使用number字段创建分期付款,但任何字段都是有效的。
amount
Positive Float
分期付款计划的金额。
currency
String
分期付款计划的货币种类。
参数
类型
描述
id
String
分期付款计划 id。
country
String
分期付款计划国家(和您创建 Field 时使用的国家相同)。
currency
String
分期付款计划的货币种类。
bin
String
信用卡BIN码。(前6位数字)
amount
Positive Float
分期付款计划的金额。
installments
分期付款计划信息。
参数
类型
描述
id
String
分期付款 id。
installment_amount
Positive Float
分期付款金额。
total_amount
Positive Float
分期付款总金额。
installments
Integer
分期付款期数。
1
{
2
"id" : "INS54434",
3
"country" : "BR",
4
"currency" : "BRL",
5
"bin" : "435921",
6
"amount": 1500,
7
"installments" : [
8
{
9
"id" : "INS54434-3",
10
"installment_amount" : 550,
11
"installments" : 3,
12
"total_amount" : 1650
13
},
14
{
15
"id" : "INS54434-6",
16
"installment_amount" : 350,
17
"installments" : 6,
18
"total_amount" : 2100
19
},
20
{
21
"id" : "INS54434-8",
22
"installment_amount" : 250,
23
"installments" : 12,
24
"total_amount" : 3000
25
}
26
]
27
}
Copied!

dlocal.getBinInformation(field)

使用 dlocal.getBinInformation(field)方法来查询此信用卡号的信息。
响应示例
1
"bin": {
2
"bin": "430307",
3
"brand": "VI",
4
"type": "DEBIT",
5
"category": "CLASSIC",
6
"issuer": "RIAS REDBANC, S.A.",
7
"country": "UY"
8
}
Copied!

Fields 对象

fields.create(type, options)

1
var card = fields.create('card');
Copied!
此方法用于创建Smart Field实例。 需要使用Smart Field的Typeoptions来进行创建。

Smart Field Types

Type
描述
card
灵活的输入框,可以用于收集cardNumber(卡号),cardExpiry(有效期)和cardCvc(安全码)。
pan
卡号,可以与 expirationcvv 类型的Smart Fields一起使用。
expiration
银行卡过期日期。可以与 pancvv 类型的Smart Fields一起使用。
cvv
银行卡安全码CVC 。可以与 panexpiration 类型的Smart Fields一起使用。
cvv-only
如果您只需要Token化CVV,可使用此Smart Field。
`card`类型 Smart Field结算页面示例
`pan`, `expiration`, 和 `cvv` Smart Fields组成的结算页面示例

Field Options

所有的Smart Fields都接受一组通用的Option,以及一些特定的Option。

通用 options:

Option
类型
描述
placeholder
String or Object
为Field设置自定义占位符。 对于numberexpirationcvv这三种SmartField此选项是包含相关占位符值的字符串。如果是cardField,则此选项是包含所有输入值所对应的占位符值的对象,如下所示:
{
cvv: "cvv placeholder",
number: "number placeholder",
expiration: "expiration placeholder"
}
classes
Object (Optional)
当dLocal Field处于某种特定状态时,在DOM容器元素上设置自定义类名。
base - 应用到容器上的基类。
默认为 DlocalField
complete- 当Field完成时应用的类名。
默认为 DlocalField--complete
empty - 当Field为空时应用应用的类名。
默认为 DlocalField--empty
focus - 当Field被聚焦时应用的类名。
默认为 DlocalField--focus
invalid - 当Field不可用时应用的类名。
默认为 DlocalField--invalid
webkitAutofill - 当Field的值被浏览器(仅限于Chrome和Safari浏览器)自动填充时使用的类名。
默认为DlocalField--autofilled
style
Object (Optional)
使用CSS熟悉自定义外观,通过下面的变体可以将样式定义为一个对象
  • base, 基础样式—所有的其它变体都从此样式派生
  • complete, 当用户在Field中填入有效输入值时生效
  • empty, 当Field中没有任何用户输入时生效
  • invalid, 当Field中的输入无效值时生效
  • autofilled, 当Filed被浏览器自动填充时生效
对于上述所有变体,都可以自定义下列的属性:
  • color
  • fontFamily
  • fontSize
  • fontSmoothing
  • fontStyle
  • fontVariant
  • iconColor
  • lineHeight,为避免游标在浏览器中呈现效果不一致,请考虑在Field的容器上使用填充。
  • letterSpacing
  • textDecoration
  • textShadow
  • textTransform
以下虚类和虚元素也可以使用上述属性设置样式,作为变体内的嵌套对象。
  • :hover
  • :focus
  • ::placeholder
  • ::selection
  • :disabled

card 和 number Field 专用的Options

Option
类型
描述
iconStyle
String (Optional)
Field中图标的外观,有效值为 'solid' 'default'。
hideIcon
Boolean (Optional)
是否隐藏图标。默认为 false.

Field 对象

field.mount(domElement)

您需要创建一个容器DOM元素来安装Smart Field。 如果容器DOM元素具有标签,则在单击其标签时,Field将自动聚焦。有两种方法可以做到这一点:
  1. 1.
    <label>中安装示例。
    1
    <label>Card
    2
    <div id="card-field"></div>
    3
    </label>
    Copied!
  2. 2.
    for 关键词来创建一个<label>, 此标签引用容器的ID。
    1
    <label for="card-field">Card</label>
    2
    <div id="card-field"></div>
    Copied!
field.mount()方法会将Field附加到DOM, field.mount() 可以接收CSS Selector (例如, '#card-field') 或 DOM 元素.
1
cardField.mount('#card-field');
Copied!

field.on(event, handler)

与Smart Field通信的唯一方法是通过监听一个事件。Fields可能会发出以下任何事件。所有事件都有一个有效负载对象,该对象具有fieldType属性,该属性具有发出事件的 Field 的 type
事件
描述
blur
当任何Fields元素失去焦点时触发。 事件有效载荷始终包含某些特定的键::
  • empty - Boolean - true 代表值为空。
  • complete - Boolean -true 代表值的格式正确且填写完整。
    • complete 可用于逐步展示表单的下一部分或启用表单提交。
    • complete 不是客户是否完成输入的指示 - 它仅表示该字段已包含完整,格式正确的值。
  • error - 当前数据存在验证错误, 包含由错误消息,错误代码和错误类型组成alidation_error。
  • brand - String - 通过Card BIN检测到的银行卡品牌。
  • element - String - 触发此事件的Field 名称: 'number', 'expiration', 'cvv'。
  • hasFocus - Boolean - true 表示任意Field元素具有焦点 (在下列Fields中此值总为False: pan, expirationcvv)。
  • autofilled - Boolean - true 表示任意Fields 由浏览器自动填充。
focus
当任何Fields元素获得焦点时触发。事件有效载荷始终包含某些特定的键:
  • empty - Boolean - true 代表值为空。
  • complete - Boolean -true 代表值的格式正确且填写完整。
    • complete 可用于逐步展示表单的下一部分或启用表单提交。
    • complete 不是客户是否完成输入的指示 - 它仅表示该字段已包含完整,格式正确的值。
  • error - 当前数据存在验证错误, 包含由错误消息,错误代码和错误类型组成alidation_error。
  • brand - String - 通过Card BIN检测到的银行卡品牌。
  • element - String - 触发此事件的Field 名称: 'number', 'expiration', 'cvv'。
  • autofilled - Boolean - true 表示任意Fields 由浏览器自动填充。
error
validation_error由以下内容组成:错误消息,代码和类型。
检测到客户端验证错误时触发。 事件有效载荷包含具有当前验证错误信息的error 。
complete
当Field完整状态变化时触发。事件有效载荷总是包含complete - Boolean - key,当字段完整且格式正确时为true,否则为false。
empty
当Filed是否为空值的状态变化时触发,事件有效载荷总是包含 empty - Boolean - key,当Field为空时该值为 true, 否则为 false。
ready
当Field安装并加载到DOM中时触发。
change
• 当字段上的任何以下值发生更改时触发。 除了一些特定于字段的键之外,事件有效负载始终还包含某些特定的键。
  • empty - Boolean - true 代表值为空。
  • complete - Boolean -true 代表值的格式正确且填写完整。
    • complete 可用于逐步展示表单的下一部分或启用表单提交。
    • complete 不是客户是否完成输入的指示 - 它仅表示该字段已包含完整,格式正确的值。
  • error - 当前数据存在验证错误, 包含由错误消息,错误代码和错误类型组成alidation_error。
  • brand - String - 通过Card BIN检测到的银行卡品牌。
  • autofilled - Boolean - true 表示任意Fields 由浏览器自动填充。
brand
当Field检测到银行卡品牌的变化时触发。 此事件只能在numberCard的SmartField中监听(在cvvexpiration Field中无效)。事件有效载荷始终包含brand - String - key,返回检测到的品牌名称,否则为null
如果使用分期付款,强烈建议您在Brand事件中包含 createInstallmentsPlan。 因为分期付款计划和手续费仅取决于交易金额和银行卡品牌。
autofilled
当Field检测到自动填充状态发生变化时触发。事件有效负载荷终包含autofilled - Boolean - key,如果字段是自动填充的,则为true

输入有效性验证

Smart Fields 在客户输入信息后可以进行有效性验证。为了帮助您的客户捕获错误,请在Field上监听change 事件并显示存在的任何错误:
1
card.addEventListener('change', function(event) {
2
var displayError = document.getElementById('card-errors');
3
if (event.error) {
4
displayError.textContent = event.error.message;
5
} else {
6
displayError.textContent = '';
7
}
8
});
Copied!

其它方法

方法
描述
blur()
模糊化Field
clear()
清除Field中的值
destroy()
从DOM中删除Field并销毁它。注意:无法重新激活或重新安装已销毁的Field到DOM。
focus()
聚焦Field,在card Field中会聚焦到number 字段。
unmount()
从DOM中卸载Field。调用 field.mount() 将其重新附加到DOM。
update(options)
更新用于初始化Field的Options。 更新将合并到现有配置中。接受与 fields.create() 相同的Options。
可以使用update()方法动态更改Smart Field的样式。此方法可实现在不同设备上查看时自动调整Fields尺寸的功能。
1
window.addEventListener('resize', function(event) {
2
if (window.innerWidth <= 320) {
3
card.update({style: {base: {fontSize: '13px'}}});
4
} else {
5
card.update({style: {base: {fontSize: '16px'}}});
6
}
7
});
8
9
var previousBrand;
10
card.on('change', function(event) {
11
if (event.brand !== previousBrand && event.brand === 'mastercard') {
12
card.update({style: {base: {color: 'orange'}}});
13
previousBrand = event.brand;
14
}
15
});
Copied!

Field 容器

为装载Smart Fields的容器设置样式,使其形似您自己的页面中的<input>。 例如,要控制Field上的填充和边框,请在容器上设置这些属性。 这通常通过复用您已应用于<input>DOM 元素的类来完成。 例如:
1
<style>
2
.my-input {
3
padding: 10px;
4
border: 1px solid #ccc;
5
}
6
</style>
7
8
<form>
9
<div>
10
<label>Name</label>
11
<input class="my-input">
12
</div>
13
<div>
14
<label>Card</label>
15
<!-- Using the same "my-input" class on the -->
16
<!-- regular input above and on this container. -->
17
<div class="my-input" id="card-field"></div>
18
</div>
19
</form>
Copied!
安装Field后,.DlocalField类会被添加到容器中。此外,当Field处于complete, empty, focused, invalid, autofilled(被浏览器自动填充)状态时,以下类将自动添加到容器中:
  • .DlocalField--complete
  • .DlocalField--empty
  • .DlocalField--focus
  • .DlocalField--invalid
  • .DlocalField--autofilled (仅支持Chrome 和 Safari)
这些类名可以在创建Smart Field时通过使用classes option 来自定义。

兼容的浏览器

dLocal.js致力于支持所有最新版本的主流浏览器。为了安全起见并为大多数客户提供最佳体验,我们不支持不再接收安全更新且仅有少量用户的浏览器。
  • 支持所有平台上的Chrome和Safari以及桌面端的Firefox。
  • 支持符合 Microsoft's lifecycle policy 的Internet Explorer和Edge浏览器。自2016年1月12日起,我们支持Internet Explorer 9及更高版本。
  • 支持Android 4.4及更高版本的Android原生浏览。
  • 浏览器需支持TLS 1.2。
如果您在特定浏览器上遇到关于dLocal.js的问题,请与我们联系,以便我们改善支持服务。
Last modified 2yr ago