dLocal China
Search…
⌃K

安全付款

签名方法

签名方法需使用 SHA256 进行 HMAC 运算,签名Header需要包含版本前缀:包括签名版本和使用的hash算法,目前,我们使用:V2-HMAC-SHA256。

请求头

Header
类型
描述
X-Date
String
ISO8601 日期时间包含时区。 如: 2018-07-12T13:46:28.629Z
X-Login
String
dLocal分配给商家的 xLogin
X-Trans-Key
String
dLocal分配给商家的 xTransKey
Content-Type
String
application/json
X-Version
String
API Version
User-Agent
String
用于标识请求软件用户代理的应用程序类型、操作系统、软件供应商或软件版本。
Authorization
String
<auth version>, Signature: <hmac(secretKey, "X-Login+X-Date+RequestBody")>

以下是几种语言的Hmac签名生成示例:

Java
其它语言
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public final class SignatureCalculator {
private static final String HMAC_ALGORITHM = "HmacSHA256";
private static final String CHARSET = "UTF-8";
public static String calculateSignature(String x_Login, String x_Date, String secretKey, String body)
throws IOException, InvalidKeyException, NoSuchAlgorithmException {
// Create byte array with the required data for the signature.
ByteArrayOutputStream bout = new ByteArrayOutputStream();
bout.write(x_Login.getBytes(CHARSET));
bout.write(x_Date.getBytes(CHARSET));
bout.write(body.getBytes(CHARSET));
// Calculate the signature.
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), HMAC_ALGORITHM);
Mac mac = Mac.getInstance(HMAC_ALGORITHM);
mac.init(signingKey);
byte[] signature = mac.doFinal(bout.toByteArray());
// Create a String with the signature value.
Formatter formatter = new Formatter();
for (byte b : signature) {
formatter.format("%02x", b);
}
return formatter.toString();
}
}
语言
代码示例
PHP
$signature = hash_hmac("sha256", "$X-Login$X-Date$RequestBody", $secretKey);
Python
signature = hmac.new(secretKey, X-Login+X-Date+RequestBody, hashlib.sha256).hexdigest()
Ruby
signature = OpenSSL::HMAC.hexdigest('sha256', secretKey, $X-Login + $X-Date + RequestBody)
强烈建议您通过 查询付款方式 方法来测试您生成的签名值,确保在接下来的对接中您计算的签名值是有效的。

敏感信息加密

信用卡信息, 如卡号 number 和安全码 cvv, 可以使用 JWE 在JSON 请求Body中将其加密。该 标准在市场中被广泛使用,绝大多数编程语言都具有支持JWE的库
以下的参数可以被加密并且添加到encrypted_data 字段:
加密参数
信用卡加密Body示例
参数名称
类型
描述
cvv
String
信用卡安全码
number
String
信用卡编号
"card": {
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"encrypted_data": "[encrypted JSON goes here]"
}
加密流程如下
  1. 1.
    dLocal 创建一对RSA密钥同时通过第三方信任机构颁发一个证书。
  2. 2.
    dLocal 通过加密方法将公钥分享给商家。请咨询您的 技术客户经理 询问更多信息
  3. 3.
    商家使用此公钥和JWE来加密JSON请求中的 卡号number 和 安全码 cvv并且在API请求中通过encrypted_data字段来存储加密信息。其余的信息可以直接发送无需加密。
  4. 4.
    dLocal 使用私钥对信息进行加密。

幂等请求

如需通过幂等请求。在Header中添加 'X-Idempotency-Key' 来发起请求即可:
Header
类型
描述
X-Idempotency-Key
String
Key used for perform an idempotent request. Optional.

请求示例

curl -X POST \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'Content-Type: application/json' \
-H 'X-Version: 2.1' \
-H 'User-Agent: MerchantTest / 1.0 ' \
-H 'X-Idempotency-Key: a8a85bce-5733-4a6c-91b5-553ed4b3de16' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
-d '{body}'
https://api.dlocal.com/payments