Fraud Prevention

dLocal Defense

dLocal Defense, our fraud prevention solution, is an integral part of our service. With dLocal Defense, all transactions processed by dLocal are run through our fraud prevention engine, which identifies market and industry-specific fraud patterns and prevents potentially fraudulent transactions from being processed.
In order to obtain the best results from dLocal Defense, it is required that as much information as possible is provided in the Payments API call (as documented here).
Required payment information used for fraud prevention includes the following:
    Payer's name and surname
    Email address
    Phone number
    Document
    Shipping address, otherwise billing address
    IP address
    User reference (user ID)
    Product details (see Item object definition below)
    Device ID (see below)
For PSPs / Marketplaces:
    Sub-merchant name

Additional information for fraud prevention

For a more in-depth analysis of transactions for fraud patterns, we recommend that our merchants also consider using the additional_risk_data object in their Payment API calls. This object includes a list of optional properties which can be used to better identify fraudulent transactions. All objects and properties within the Additional Risk Data object and all its contained objects are considered optional, so merchants may provide the information that applies for their particular case.

The Additional Risk Data object

Additional Risk Data object
Example Payment with Additional Risk Data object
Property
Type
Description
submerchant
Submerchant object
Information on the submerchant account. Required for PSPs / Marketplaces.
shipping
Shipping object
Information on the shipping / alternative address. Required for Retail.
beneficiary
Beneficiary object
Information on the beneficiary, if different from the payer. Optional.
basket
List of Item objects
Information on the items purchased. Required.
payer
Payer object
Additional information on the payer's user account. Optional.
device
Device object
Additional information on the device used for purchase. Optional.
purchase
Purchase object
The purchase object is used to provide additional general information about the purchase
1
{
2
"amount": 399.80,
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
"holder_name" : "Thiago Gabriel",
22
"number" : "4111111111111111",
23
"cvv" : "123",
24
"expiration_month" : 10,
25
"expiration_year" : 2040
26
},
27
"order_id": "657434343",
28
"notification_url": "http://merchant.com/notifications",
29
"additional_risk_data": {
30
"submerchant": {
31
"merchant_reference" : "12534",
32
"name" : "Submerchant name",
33
"website" : "https://www.submerchant.com",
34
"industry" : 17,
35
"document" : "15236713521",
36
"nationality" : "BR",
37
"email" : "[email protected]",
38
"username" : "submerchant_username",
39
"phone" : "123456712345",
40
"created_date" : "20210311",
41
"total_order_count" : 35,
42
"total_order_amount" : 45020,
43
"last_updated_date" : "20210312",
44
"onboarding_ip_address" : "123.21.31.124",
45
"onboarding_email" : "[email protected]",
46
"reputation" : 4,
47
"ship_from_address" : {
48
"state" : "Montevideo",
49
"city" : "Montevideo",
50
"zip_code": "11300",
51
"street" : "Avda. Brasil",
52
"number": "1234 Ap. 401"
53
}
54
},
55
"shipping" : {
56
"address" : {
57
"state" : "Montevideo",
58
"city" : "Montevideo",
59
"zip_code": "11300",
60
"street" : "Avda. Brasil",
61
"number": "1234 Ap. 501"
62
},
63
"is_physical" : true,
64
"cost" : 12.34,
65
"delivery_company" : "FadEx",
66
"method" : "FREE",
67
"delivery_date" : "20211020",
68
"is_forwarding_address" : false,
69
"geolocation": "-34.8798853,-56.1867859"
70
},
71
"beneficiary" : {
72
"email" : "[email protected]",
73
"name" : "John Doe",
74
"phone" : "09671268364",
75
"document" : "513672561"
76
},
77
"basket" : [
78
{
79
"unit_price" : 199.90,
80
"brand" : "Smoogle",
81
"category" : "Smartphone",
82
"item_reference" : "SP-562138",
83
"upc": "1758929364928",
84
"manufacturer" : "Smoogle",
85
"product_name" : "Pexel 25",
86
"quantity" : 2,
87
"size" : "regular",
88
"subcategory": "Droid smartphones",
89
"url": "https://www.merchant.com/products/SP-562138",
90
"published_date": "20201113",
91
"rating": 4.5,
92
"count_reviews": 13,
93
"image": "https://www.merchant.com/products/SP-562138/photos/1.jpg",
94
"stock": 32,
95
"weight": 0.34,
96
"subscription": {
97
"id": "A15-D267125367",
98
"period": "P1M",
99
"current_period": 3,
100
"end_date": "20220101"
101
}
102
}
103
],
104
"payer" : {
105
"email_is_valid" : true,
106
"phone_is_valid" : false,
107
"account_creation_date" : "20201110",
108
"first_purchase_date" : "20201110",
109
"is_positive" : false,
110
"last_order_id": "1525634152634",
111
"total_order_count": 12,
112
"total_order_amount": 152.03,
113
"last_updated_date": "20201020",
114
"wish_list": [
115
{
116
"item_reference": "125312435",
117
"unit_price": 1300,
118
"product_name": "Pexel 25 for dummies"
119
}
120
],
121
"reputation": 5
122
},
123
"purchase": {
124
"is_retry": false,
125
"channel": "WEB",
126
"time_in_session": 55,
127
"search_history": [
128
{
129
"item_reference": "125312435",
130
"unit_price": 1300,
131
"product_name": "Pexel 25 for dummies"
132
}
133
]
134
},
135
"discount_codes": [
136
{
137
"amount": 10,
138
"percentage": 20,
139
"code": "PROMO20OFF",
140
"valid_until" : "20211130",
141
"description" : "20% off Smoogle products"
142
}
143
],
144
"device" : {
145
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36",
146
"geolocation" : "-34.8798853,-56.1867859",
147
"locale": "en-US",
148
"advertising_id" : "EA7583CD-A667-48BC-B806-42ECB2B48606",
149
"vendor_id": "uapff_93e9a58cc03a0e7f45c2cf50ca567a99",
150
"android_id": "cdda802e-fb9c-47ad-9866-0794d394c913",
151
"media_drm_id": "0102030405060708090a0b0c0d0e0f10"
152
}
153
}
154
}
Copied!

The Submerchant object

For PSPs / merchants with sub-merchant accounts, the submerchant object may be used to provide more information on the specific sub-merchant for which the payment was issued.
Submerchant object
Example Submerchant object
Property
Type
Description
merchant_reference
String
The ID / reference of the sub-merchant account. Optional.
name
String
Sub-merchant name. Required for PSPs / marketplaces.
website
String
Sub-merchant website. Optional.
industry
Number
Sub-merchant industry, see industry codes list. Optional.
document
String
Submerchant's document
nationality
String
Submerchant's nationality (ISO 3166 country code)
email
String
Submerchant's email address
username
String
The unique username associated with the seller's online account.
phone
String
Phone number
created_date
String
Date of account creation in YYYYMMDD format
total_order_count
Number
The total count of orders sold by this seller
total_order_amount
Number
The total amount sold by this seller (in USD)
last_updated_date
String
The last time a change was made to this submerchant (e.g. changed address).YYYYMMDD format.
onboarding_ip_address
String
The IP address of the device used when this seller account was created.
onboarding_email
String
The email used when this seller account was created.
reputation
Number
The reputation of the submerchant, from 0 (negative) to 5 (positive)
ship_from_address
Object
The address from where the submerchant ships the orders
ship_from_address.street
String
Street
ship_from_address.number
String
Street number
ship_from_address.city
String
City
ship_from_address.zip_code
String
Zip Code
ship_from_address.state
String
State
1
"submerchant": {
2
"merchant_reference" : "12534",
3
"name" : "Submerchant name",
4
"website" : "https://www.submerchant.com",
5
"industry" : 17,
6
"document" : "15236713521",
7
"nationality" : "BR",
8
"email" : "[email protected]",
9
"username" : "submerchant_username",
10
"phone" : "123456712345",
11
"created_date" : "20210311",
12
"total_order_count" : 35,
13
"total_order_amount" : 45020,
14
"last_updated_date" : "20210312",
15
"onboarding_ip_address" : "123.21.31.124",
16
"onboarding_email" : "[email protected]",
17
"reputation" : 4,
18
"ship_from_address" : {
19
"state" : "Montevideo",
20
"city" : "Montevideo",
21
"zip_code": "11300",
22
"street" : "Avda. Brasil",
23
"number": "1234 Ap. 401"
24
}
Copied!

The Shipping object

For merchants who handle separate Payment / Shipping addresses, the Shipping object may be used to specify the shipping address, and also to indicate whether the purchase has a physical delivery or not (i.e. retail vs digital goods).
Shipping object
Example Shipping object
Property
Type
Description
address
Address object
Represents the address, documented in this table. Optional.
address.state
String
State. Optional.
address.city
String
City. Optional.
address.zip_code
String
Zip code. Optional.
address.street
String
Street. Optional.
address.number
String
Street number. Optional.
is_physical
Boolean
True if a physical delivery to this address is involved (i.e. for retail goods). Optional.
cost
Number
Cost of the delivery (in USD)
delivery_company
String
Name of the delivery company
method
String
The type of shipment selected during checkout. See list below
delivery_date
String
Shipping delivery date. in YYYYMMDD format.
is_fowarding_address
Boolean
If the shipping address is a forwarding address
geolocation
String
Shipping geolocation
1
"shipping" : {
2
"address" : {
3
"state" : "Montevideo",
4
"city" : "Montevideo",
5
"zip_code": "11300",
6
"street" : "Avda. Brasil",
7
"number": "1234 Ap. 501"
8
},
9
"is_physical" : true,
10
"cost" : 12.34,
11
"delivery_company" : "FadEx",
12
"method" : "FREE",
13
"delivery_date" : "20211020",
14
"is_forwarding_address" : false,
15
"geolocation": "-34.8798853,-56.1867859"
16
}
Copied!

The Beneficiary object

For purchases where the beneficiary / recipient is not the payer (e.g. for gifts of physical / virtual goods), the Beneficiary object may be used to provide information on the product or service's recipient.
Beneficiary object
Example Beneficiary object
Property
Type
Description
email
String
Email address. Optional.
name
String
Name & surname. Optional.
phone
String
Phone number. Optional.
document
String
Document. Optional.
1
"beneficiary" : {
2
"email" : "[email protected]",
3
"name" : "John Doe",
4
"phone" : "09671268364",
5
"document" : "513672561"
6
}
Copied!

The Item object

The basket property contains a list of Item objects, used to provide information on the items purchased. Item objects are required for effective fraud prevention, within these the properties marked with "Recommended" are the most recommended ones to include.
Item object
Example Basket & Item object
Property
Type
Description
unit_price
Number
Unit price. Recommended.
brand
String
Product brand. Optional.
category
String
Product category. Recommended.
item_reference
String
Item ID / Reference. Recommended.
upc
String
Universal Product Code. Optional.
manufacturer
String
Product manufacturer. Optional.
product_name
String
Product or service name. Recommended.
quantity
Number
Quantity of items purchased. Recommended
size
String
Product size (e.g. S, M, L, XL). Optional.
subcategory
String
The item subcategory
url
String
The item url
published_date
String
Date when the product was added / published in the store. In YYYYMMDD format
rating
Number
The product rating, as a score from 1 to 5
count_reviews
Number
Number of customer reviews the product has received
image
String
The url with the product image
stock
Number
The quantity of products avaliable for sale
weight
Number
The product weight in kg
subscription
Object
A subscription object can be used to specify additional data for subscription business models
subscription.id
String
Subcription ID/reference
subscription.period
String
Renewal period in ISO 8601 format (P1M, P3M, P1Y etc)
subscription.current_period
Number
The current suscription period that the recurring order belongs
subscription.end_date
String
Suscription end date. YYYYMMDD format
1
"basket" : [
2
{
3
"unit_price" : 199.90,
4
"brand" : "Smoogle",
5
"category" : "Smartphone",
6
"item_reference" : "SP-562138",
7
"upc": "1758929364928",
8
"manufacturer" : "Smoogle",
9
"product_name" : "Pexel 25",
10
"quantity" : 2,
11
"size" : "regular",
12
"subcategory": "Droid smartphones",
13
"url": "https://www.merchant.com/products/SP-562138",
14
"published_date": "20201113",
15
"rating": 4.5,
16
"count_reviews": 13,
17
"image": "https://www.merchant.com/products/SP-562138/photos/1.jpg",
18
"stock": 32,
19
"weight": 0.34,
20
"subscription": {
21
"id": "A15-D267125367",
22
"period": "P1M",
23
"current_period": 3,
24
"end_date": "20220101"
25
}
26
}
27
]
Copied!

The Payer object

The Payer object within the Additional Risk Data object allows for providing additional information on the payer's user account.
Payer object
Example Payer object
Property
Type
Description
email_is_valid
Boolean
Set to True if the payer's email has been validated. Optional.
phone_is_valid
Boolean
Set to True if the payer's phone number has been validated. Optional.
account_creation_date
String
Date of account creation in YYYYMMDD format. Optional.
first_purchase_date
String
Date of first successful purchase in YYYYMMDD format. Optional.
is_positive
Boolean
Set to True if this payer is considered as a positive user by the merchant, e.g. for regular customers with a good purchase history. Optional.
last_order_id
String
Last order id placed by this account, not including the current order
total_order_count
Number
The total count of orders purchased by this account
total_order_amount
Number
The total amount purchased by this account
last_updated_date
String
The last time a change was made to this account (e.g. changed address).YYYYMMDD format.
wish_list
Array
A list of items that the user has in any or all of their favorites lists
wish_list.item_reference
String
Item ID
wish_list.unit_price
Number
Item unit price
wish_list.product_name
String
Item name
reputation
Number
The reputation of the payer, from 0 (negative) to 5 (positive)
1
"payer" : {
2
"email_is_valid" : true,
3
"phone_is_valid" : false,
4
"account_creation_date" : "20201110",
5
"first_purchase_date" : "20201110",
6
"is_positive" : false,
7
"last_order_id": "1525634152634",
8
"total_order_count": 12,
9
"total_order_amount": 152.03,
10
"last_updated_date": "20201020",
11
"wish_list": [
12
{
13
"item_reference": "125312435",
14
"unit_price": 1300,
15
"product_name": "Pexel 25 for dummies"
16
}
17
],
18
"reputation": 5
19
}
Copied!

The Discount codes list

The discount_codes list is a list of entries that represent the discount codes or promotions that are applied to this purchase
Discount code object
Property
Type
Description
amount
Number
Product discount amount at the moment of the purchase.
percentage
Number
If a percentage discount is applied the percentage of the total order amount the discount applies to. e.g. 20% off purchase. This field should be NULL if amount is provided.
code
String
The id of the discount / code used.
valid_until
String
Promotion end date. In YYYYMMDD format
description
String
A description of the discount

The Device object

The Device object is used to store information on the device (i.e. laptop, smartphone) used to make the purchase.
Device object
Example Device object
Property
Type
Description
user_agent
String
Browser's User Agent property. Optional.
geolocation
String
User's geolocation. Optional.
locale
String
Browser's locale. Optional.
advertising_id
String
An advertising ID is a unique user ID assigned to a mobile device, or operating environment(apple: advertisingIdentifier, android: GSF Id)
vendor_id
String
For Apple, an alphanumeric string that uniquely identifies a device to the vendor (identifierForVendor)
android_id
String
For Android, 64-bit number (as a hex String) that the OS randomly generates when the user first sets up the device
media_drm_id
String
For Android, the MediaDrm device unique ID
event_uuid
String
dLocal Device ID - see dLocal Device ID integration below
1
"device" : {
2
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36",
3
"geolocation" : "-34.8798853,-56.1867859",
4
"locale": "en-US",
5
"advertising_id" : "EA7583CD-A667-48BC-B806-42ECB2B48606",
6
"vendor_id": "uapff_93e9a58cc03a0e7f45c2cf50ca567a99",
7
"android_id": "cdda802e-fb9c-47ad-9866-0794d394c913",
8
"media_drm_id": "0102030405060708090a0b0c0d0e0f10"
9
}
Copied!

The Purchase object

The purchase object is used to provide additional general information about the purchase
Purchase object
Example Purchase object
Property
Type
Description
is_retry
Boolean
Indicates if the payment is a retry by the user of the same previously rejected purchase attempt.
channel
String
The channel or source where the order was placed, see list. See list below
time_in_session
String
The time in seconds that a user spent within the session in the website or app before making the purchase.
search_history
Array
The search_history list contains the list of products that the user visited within the session before making the purchase.
search_history.item_reference
String
The item ID
search_history.unit_price
String
The item's unit price
search_history.product_name
String
The item's product name
1
"purchase": {
2
"is_retry": false,
3
"channel": "WEB",
4
"time_in_session": 55,
5
"search_history": [
6
{
7
"item_reference": "125312435",
8
"unit_price": 1300,
9
"product_name": "Pexel 25 for dummies"
10
}
11
]
12
}
Copied!

dLocal Device ID integration

For merchants who are using DIRECT payment flows and are not using our Smart Fields solution, we strongly recommend the integration of the Fraud Prevention Javascript library within the payment flow of the client application. This script will allow the collection of detailed device information that will enhance the fraud prevention capabilities for each processed payment.
If you are using our Smart Fields solution, or any of our REDIRECT flows, the Device ID is being automatically collected so you may ignore this section.
Fraud Prevention JS library URLs:
For web applications, in order to integrate our JS library and perform the device data collection you should include the following code snippet right after the opening <body> tag:
1
<!-- Scripts -->
2
<script src=LIBRARY_URL></script>
3
4
<script text="text/javascript">
5
dlocalCollector.create({ apiKey: API_KEY })
6
.then((event_uuid) => console.log(event_uuid));
7
</script>
Copied!
Within this code, you should:
    1.
    Replace LIBRARY_URL with the URL for the sandbox or production environment, as detailed above.