dLocal China
Search…
付款
通过此服务您可以创建,修改或者读取付款。如果你想查看特定付款方式的详细信息,您可以查看以下页面:
post
https://api.dlocal.com
/payments
创建付款

Payer对象

Payer 对象
Payer 对象示例
属性
类型
描述
name
String
买家全名,必填
email
String
买家邮箱地址.,必填
birth_date
String
买家生日,日-月-年 (DD-MM-YYYY), 选填。
phone
String
买家手机号,防止欺诈是必填的(请参阅欺诈预防)。
document
String
买家个人公民身份ID,点此了解更多,必填。
document2
String
其他个人身份证明,选填。
user_reference
String
买家在商家系统中的唯一编号,防止欺诈必填
address
买家地址,印度,南非以及预防欺诈必填。
ip
String
买家网络IP地址,防止欺诈必填
device_id
String
买家设备识别码,防止欺诈必填
1
{
2
"name" : "Thiago Gabriel",
3
"email" : "[email protected]",
4
"document" : "53033315550",
5
"user_reference": "12345",
6
"address": {
7
"state" : "Rio de Janeiro",
8
"city" : "Volta Redonda",
9
"zip_code" : "27275-595",
10
"street" : "Servidão B-1",
11
"number" : "1106"
12
}
13
"ip" : "179.27.83.210",
14
"device_id" : "2fg3d4gf234"
15
}
Copied!

Address 对象

Address 对象
Address 对象示例
Property
Type
Description
state
String
用户地址: 州/省,南非必填
city
String
用户地址: 城市,印度,南非必填。
zip_code
String
用户地址:邮编,南非必填
street
String
用户地址:街道,印度,南非必填。
number
String
用户地址:门牌号,印度,南非必填。
1
{
2
"state" : "Rio de Janeiro",
3
"city" : "Volta Redonda",
4
"zip_code" : "27275-595",
5
"street" : "Servidão B-1",
6
"number" : "1106"
7
}
Copied!

Card 对象

对于信用卡付款,除非您 完全PCI DSS合规 您才可以使用信用卡信息。否则您需要使用 Smart Fields 来收集信用卡信息。对于周期性付款(如按月支付会员费等),您可以先 保存银行卡 ,然后使用card_id来调用信用卡。
重要提示:
如果您直接使用信用卡信息来发起付款,你需要使用以下端口:https://api.dlocal.com/secure_payments
如果您使用card_id 或 token 来发起付款,你需要使用以下端口: https://api.dlocal.com/payments
Card 对象
Card 对象示例
属性
类型
描述
holder_name
String
持卡人全名, 没有提供tokencard_id 时必填。
expiration_month
Integer
两位数字,表示银行卡有效期月份。 没有提供tokencard_id 时必填
expiration_year
Integer
四位数字,表示银行卡有效期年份。 没有提供token card_id 时必填。
number
String
卡号,不能包含任何分隔符。 没有提供encrypted_datatokencard_id 时必填。
cvv
String
三位数字信用卡安全码, 选填,印度必填
encrypted_data
String
JWE 加密后的参数,选填。
token
String
使用Smart Fields生成的用于安全通信的信用卡Token, 选填。
cvv_token
String
使用CVV-only Smart Fields生成的用于安全通信的CVV Token. 选填。
card_id
String
通过 创建信用卡 方法响应中获得的信用卡ID, 选填。
installments
String
分期付款期数(1-12期),默认值1,选填。
installments_id
String
已创建好的分期付款计划ID,选填。
descriptor
String
动态付款描述,选填。
capture
Boolean
是否立即获取付款。 如果为false,则此付款会请求预授权(Authorization),并且需要后续捕获(Capture)付款。 默认值 TRUE. 选填。
save
Boolean
是否保存银行卡以便后续发起更多付款。如为“ture“,响应中将会返回card_id点此了解更多

原始信用卡的Card对象示例:

1
{
2
"holder_name": "Thiago Gabriel",
3
"expiration_month": 10,
4
"expiration_year": 2040,
5
"number": "4111111111111111",
6
"cvv": "123"
7
}
Copied!

使用 Smart Fields 获取 token的Card对象示例:

1
{
2
"token":"CV-124c18a5-874d-4982-89d7-b9c256e647b5"
3
}
Copied!

使用保存银行卡:创建银行卡方法获取 card_id 的Card对象示例:

1
{
2
"card_id":"CV-hgv23jh4g-n23n-kj3k-bkhb3-kj3hj3gjh3k3"
3
}
Copied!

Direct Debit 对象

属性
类型
描述
holder_name
String
银行账户所有人姓名,必填
email
String
银行账户所有人邮箱,必填
document
String
银行账户所有人账户编号,必填
cbu
String
银行账户所有人CBU ,仅阿根廷必填。

请求示例

使用信用卡信息发起付款
使用信用卡Token发起付款
以下示例展示如何使用信用卡信息的信用卡付款(仅适用于完全 PCI DSS合规商家)。要使用加密的信用卡信息进行付款,只需将numbercvv参数替换为encrypted_data即可。

请求示例

1
curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'Content-Type: application/json' \
6
-H 'X-Version: 2.1' \
7
-H 'User-Agent: MerchantTest / 1.0 ' \
8
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
-d '{body}'
10
https://api.dlocal.com/secure_payments
Copied!

请求示例Body

1
{
2
"amount": 120.00,
3
"currency" : "USD",
4
"country": "BR",
5
"payment_method_id" : "CARD",
6
"payment_method_flow" : "DIRECT",
7
"payer":{
8
"name" : "Thiago Gabriel",
9
"email" : "[email protected]",
10
"document" : "53033315550",
11
"user_reference": "12345",
12
"address": {
13
"state" : "Rio de Janeiro",
14
"city" : "Volta Redonda",
15
"zip_code" : "27275-595",
16
"street" : "Servidao B-1",
17
"number" : "1106"
18
}
19
"ip" : "179.27.83.210",
20
"device_id" : "2fg3d4gf234"
21
},
22
"card":{
23
"holder_name" : "Thiago Gabriel",
24
"number" : "4111111111111111",
25
"cvv" : "123",
26
"expiration_month" : 10,
27
"expiration_year" : 2040
28
},
29
"order_id": "657434343",
30
"notification_url": "http://merchant.com/notifications"
31
}
Copied!
以下示例适用于使用Smart Fields 方法获取的Token的信用卡付款。 如果要使用 创建卡片 方法获得的card_id进行付款,只需将token参数替换为car_id即可。

请求示例

1
curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
5
-d '{body}'
6
https://api.dlocal.com/payments
Copied!

请求示例 Body

1
{
2
"amount": 120.00,
3
"currency" : "USD",
4
"country": "BR",
5
"payment_method_id" : "CARD",
6
"payment_method_flow" : "DIRECT",
7
"payer":{
8
"name" : "Thiago Gabriel",
9
"email" : "[email protected]",
10
"document" : "53033315550",
11
"user_reference": "12345",
12
"address": {
13
"state" : "Rio de Janeiro",
14
"city" : "Volta Redonda",
15
"zip_code" : "27275-595",
16
"street" : "Servidao B-1",
17
"number" : "1106"
18
}
19
},
20
"card":{
21
"token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5"
22
},
23
"order_id": "657434343",
24
"notification_url": "http://merchant.com/notifications"
25
}
Copied!
get
https://api.dlocal.com/payments/
{payment_id}
查询付款

请求示例

1
$ curl \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'User-Agent: MerchantTest / 1.0 ' \
7
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
8
https://api.dlocal.com/payments/PAY4334346343
Copied!
get
https://api.dlocal.com/payments/
{payment_id}/status
查询付款状态

示例请求

1
$ curl \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'User-Agent: MerchantTest / 1.0 ' \
7
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
8
https://api.dlocal.com/payments/PAY4334346343/status
Copied!

付款状态码

建议:通过在 description 字段中发送所需的状态代码,可以在沙盒环境中测试不同的状态代码,点此了解更多
状态
状态码
描述
PENDING
100
付款处理中。
PAID
200
付款已完成。
REJECTED
300
付款被拒绝。
CANCELLED
400
付款被取消。
EXPIRED
500
付款已过期。
AUTHORIZED
600
付款已授权。

拒绝状态码

状态
状态码
描述
REJECTED
300
The payment was rejected.(付款拒绝)
REJECTED
301
Rejected by bank.(付款被银行拒绝)
REJECTED
302
Insufficient amount.(余额不足)
REJECTED
303
Card blacklisted.(银行卡被拉黑)
REJECTED
304
Score validation.(银行卡安全分数低)
REJECTED
305
Max attempts reached.(超过最大尝试数)
REJECTED
306
Call bank for authorize.(请致电银行授权此交易)
REJECTED
307
Duplicated payment.(付款重复)
REJECTED
308
Credit card disabled.(银行卡未激活)
REJECTED
309
Card expired.(信用卡已过期)
REJECTED
310
Card reported lost.(信用卡已挂失)
REJECTED
311
Card requested by the bank.(银行拒绝此卡请求)
REJECTED
312
Card restricted by the bank.(银行限制此卡交易)
REJECTED
313
Card reported stolen.(此卡被偷盗)
REJECTED
314
Invalid card number.(卡号不正确)
REJECTED
315
Invalid security code.(信用卡cvv错误)
REJECTED
316
Unsupported operation.(不支持此操作)
REJECTED
317
Rejected due to high risk.(此卡高风险)
REJECTED
318
Invalid transaction.(交易无效)
REJECTED
319
Amount exceeded.(超过最大交易额度)
REJECTED
320
3D-Secure is required. (需要3DS验证)
REJECTED
321
Error in acquirer.(收单方错误)

Pending 状态码

状态
状态码
描述
PENDING
100
付款在处理中。
PENDING
101
付款在进行3DS 安全验证中。

错误提示

下面你可以查看信用卡付款的例子,如需查看更多示例,请查看 此页面
如需查看现金(票据)支付的示例,请查看 此页面
如需查看银行转账支付的示例,请查看 此页面
所有的错误信息都已HTTP状态码:4XX, 5XX 进行展示,下面是错误提示的格式:
属性
类型
描述
code
Integer
错误码。
message
String
错误描述。
param
String
以免有一个参数错误。
示例错误
1
{
2
"code": 5005,
3
"message": "User unauthorized due to cadastral situation"
4
}
Copied!

Http 错误代码

HTTP 状态码
错误代码
错误描述
403 Forbidden
3001
无效的凭据。
3002
未注册的IP。
3003
商家没有权限使用此API。
404 Not Found
4000
未找到此付款。
400 Bad Request
5000
无效的请求。
5001
参数无效 : [parameter_name]
5002
无效的交易状态。
5003
不支持此国家。
5004
此国家不支持该货币种类。
5005
用户由于地籍原因未获授权。
5006
用户尝试次数超过限制。
5007
超过最大交易金额。
5008
Token未找到或未激活。
5009
订单ID重复。
5010
支付方式不可用。
5013
不支持此操作。
5014
黑名单用户。
5016
超过最小金额限制。
5017
API版本无效。
5018
交易已产生拒付。
429 Too many requests
6000
API请求尝试过多。
500 Internal Server Error
7000
输入正确,但dLocal未能处理此付款,不常见的情况。

通知消息

通知消息将在付款状态发生改变时发送到商家指定的通知URL。 如果该URL与dLocal商户面板中指定的URL不同,则优先取用来自付款请求中的notification_url字段。 请求的正文将始终是 Payment 对象。
商家在接收到dLocal发送通知消息后,需回复HTTP状态码: 200 来确认已收到此通知。否则此通知消息将它每10分钟重新发送一次到商家的通知接收链接,持续30天。

通知消息POST示例

POST: {payment.notification_url}
1
{
2
"id": "D-4-be8eda8c-5fe7-49dd-8058-4ddaac00611b",
3
"amount": 72.00,
4
"status": "PAID",
5
"status_detail": "The payment was paid.",
6
"status_code": "200",
7
"currency": "USD",
8
"country": "AR",
9
"payment_method_id": "RP",
10
"payment_method_type": "TICKET",
11
"payment_method_flow": "REDIRECT",
12
"payer": {
13
"name": "Nino Deicas",
14
"user_reference": "US-jmh3gb4kj5h34",
15
"email": "[email protected]",
16
},
17
"order_id": "4m1OdghPUQtg",
18
"notification_url": "http://www.merchant.com/notifications",
19
"created_date": "2019-06-26T15:17:31.000+0000"
20
}
Copied!

通知消息签名

HMAC签名将使用请求Key和密钥来计算,此密钥只有您和dLocal知晓。通过验证此签名,您可以确认通知信息在传输过程中未被篡改。
dLocal会使用和 安全付款 页面所描述的同样的方法来签名所有的POST(SHA256 HMAC 哈希算法)
只需要获取通知消息中HTTP Header中的Authorization参数,然后对比您使用X-LoginSecretKey以及通知消息中的X-Date和请求Body计算出的签名。如果签名匹配,您就可以安全地信任此通知消息是从dLocal发送的有效通知。
Last modified 11d ago