dLocal China
Search…
Smart Fields 配置指导

引言

本指南将引导您使用dLocal的一体化card Smart Field(也称为“cardField”)来创建付款。card Field通过插入一个灵活的输入字段,以安全地收集所有必要的银行卡详细信息,从而简化表单,并最大限度地减少所需的字段数量。
您可以利用Smart Field(我们预先构建的UI组件)来创建支付表单,以安全地收集您客户的卡片信息,而无需处理敏感的持卡人数据。之后,银行卡详细信息会转换成一个替代的令牌,您可以安全地将该令牌发送到您的服务器。
以下是cardSmart Field的在线演示。请尝试调整浏览器宽度,来查看Field的适应方式。您可以对CodePen的代码进行更改
调整银行卡 Smart Field 代码来匹配商家网页风格
使用Smart Fields 创建自定义支付表单需要以下五个步骤:

创建之前:HTTPS 要求

所有通过Smart Field提交的付款信息,都是通过安全的HTTPS连接来完成的。为了保护您的网站免于某些形式的中间人攻击,并防止您的客户在新版浏览器中看到 混合内容 警告,您还必须使用HTTPS来为包含支付表单的页面提供支持。

第一步: 设置dLocal Smart Field

Smart Fields作为dLocal.js的一部分来提供。首先,将该脚本列入您的页面中,且该脚本应始终从 https://js.dlocal.com 直接加载。为方便进行测试,您可以访问 https://js-sandbox.dlocal.com
<script src="https://js.dlocal.com/"></script>
如需了解更多dLocal.js信息,请访问 dLocal.js参考 页面。
接下来,创建一个Smart Fields 的示例 (简称 fields()):
1
var dlocal = dlocal('your_API_key');
2
var fields = dlocal.fields({
3
locale: 'en',
4
country: 'BR'
5
});
Copied!

第二步:创建支付表单

为了安全地从您的客户那里收集银行卡详细信息,Smart Fields 会为您创建由dLocal托管的UI组件,然后这些组件会被放入您的支付表单中,而非由您直接创建。
为了确定在何处插入这些组件,请在您的支付表单中创建具有唯一ID的空 DOM 元素(容器)。我们建议将您的容器放在一个<label>内或在其旁边,并包含一个与Smart Field容器的唯一id相匹配的for属性。如此一来,当客户点击相应的标签时,Field 会自动聚焦。
例如:
1
<form action="/charge" method="post" id="payment-form">
2
<div class="form-row">
3
<label for="card-field">
4
Credit or Debit card
5
</label>
6
<div id="card-field">
7
<!-- A dLocal Smart Field will be inserted here. -->
8
</div>
9
10
<!-- Used to display Smart Field errors. -->
11
<div id="card-errors" role="alert"></div>
12
</div>
13
<div class="form-rowd">
14
<label>Cardholder name</label>
15
<input id="card-holder" type="text" name="card-holder" placeholder="John Doe" />
16
</div>
17
<button>Pay</button>
18
</form>
Copied!
当以上表单加载后,创建一个Field实例,并将其安装到以上创建的Field容器中
1
// Custom styling can be passed to options when creating a Smart Field.
2
var style = {
3
base: {
4
// Add your base input styles here. For example:
5
fontSize: '16px',
6
color: "#32325d",
7
}
8
};
9
10
// Create an instance of the card Field.
11
var card = fields.create('card', {style: style});
12
13
// Add an instance of the card Field into the `card-field` <div>.
14
card.mount(document.getElementById('card-field'));
Copied!
用户输入信息时,Smart Fields 会对这些信息进行验证。为了帮助您的客户发现错误,您应当监听 card 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!

第三步:创建分期付款计划(可选)

您可以指定一个分期付款计划,以保证每笔分期付款都会正确收取分期手续费。
1
<!-- Add to your form -->
2
<div class="form-row">
3
<label>Fees to pay</label>
4
<div class="select-wrapper">
5
<span></span>
6
<select id="installments" disabled>
7
<option value="">Enter the card number first</option>
8
</select>
9
</div>
10
</div>
Copied!
强烈建议您将CreateInstallmentsPlan包含在brand事件中,因为分期付款计划仅仅取决于交易金额和卡种。
1
let actualBrand = null;
2
card.on('brand', function (event) {
3
document.getElementById('card-errors').innerHTML = "";
4
if (event.brand) {
5
//when card brand changes
6
actualBrand = cardStatus.brand;
7
//totalAmount & currency of the purchase
8
dlocal.createInstallmentsPlan(card, totalAmount, currency)
9
.then((result) => {
10
var installmentsSelect = document.getElementById('installments');
11
buildInstallments(installmentsSelect, result.installments);
12
}).catch((result) => {
13
console.error(result);
14
});
15
}
16
});
17
18
function buildInstallments(installmentsInput, installmentsPlan) {
19
const installmentsOptions = installmentsPlan.installments.reduce(function (options, plan) {
20
options += "<option value=" + plan.id + ">" + plan.installments + " of " + currency + " " + plan.installment_amount + " (Total : " + currency + " " + plan.total_amount + ")</option>";
21
return options;
22
}, "");
23
installmentsInput.disabled = false;
24
installmentsInput.innerHTML = installmentsOptions;
25
}
Copied!

第四步:创建Token来安全传输信用卡信息

之后,使用 Smart Fields 所收集的支付详细信息可用来转换为一个Token。针对处理表单上的提交事件创建一个事件处理程序,该处理程序会将敏感信息发送到dLocal, 以申请Token,并阻止表单的提交(表单由JavaScript程序在下一步提交)。
1
// Create a token or display an error when the form is submitted.
2
var form = document.getElementById('payment-form');
3
form.addEventListener('submit', function(event) {
4
event.preventDefault();
5
var cardHolderName = document.getElementById('card-holder').value;
6
dlocal.createToken(card, {
7
name: cardHolderName
8
}).then(function(result) {
9
// Send the token to your server.
10
dlocalTokenHandler(result.token);
11
}).catch((result) => {
12
if (result.error) {
13
// Inform the customer that there was an error.
14
var errorField = document.getElementById('card-errors');
15
errorField.textContent = result.error.message;
16
}
17
});
18
});
Copied!
dlocal.CreateToken会返回一个使用result对象来进行解析的Promise,该对象具有已成功创建的令牌result.token

第五步: 将Token和其余信息提交给服务器

最后一步是将Token以及收集到的任何其他信息提交给服务器。
1
function dlocalTokenHandler(token) {
2
// Insert the token ID into the form so it gets submitted to the server
3
var form = document.getElementById('payment-form');
4
var tokenInput = document.createElement('input');
5
tokenInput.setAttribute('type', 'hidden');
6
tokenInput.setAttribute('name', 'dlocalToken');
7
tokenInput.setAttribute('value', token.id);
8
form.appendChild(tokenInput);
9
10
// Submit the form
11
form.submit();
12
}
Copied!
用该方法创建的令牌在10分钟后或使用一次后过期(例如:使用Token进行一次付款或者保存银行卡)。如果您想保存该卡片,以便后续再进行付款,您需要保存银行卡。有关保存卡片的更多信息,请点击本链接
使用Smart Fields token 来存储银行卡并创建付款
如果你想先使用Smart Fields来 保存银行卡,然后用它来 发起付款,那么你需要使用Smart Fields 对银行卡进行两次Token申请。首先,你需要使用Smart fields token 来新建银行卡,然后再次获取Token并使用新的Token来发起付款。

接下来:创建付款

使用您刚刚收集的信用卡Token来创建付款。点击此处了解如何创建支付。
Last modified 1yr ago