Risk data documentation
Find all the specification for fraud-related fields.
Additional Risk Data information
To optimize our fraud prevention efforts, we strongly encourage merchants to fully utilize the additional_risk_data
field when making Payment API calls. This comprehensive data allows us to conduct in-depth analyses, significantly enhancing our ability to identify and prevent fraudulent transactions.
Merchants may provide the information that applies to their particular case.
Property | Type | Description | Type |
---|---|---|---|
device | Device object | Additional information on the device used for purchase. | Required |
payer | Payer object | Additional information on the payer. | Recommended and optional fields. |
basket | List of Item objects | Information on the items purchased. | Recommended and optional fields. |
shipping | Shipping object | Information on the shipping/alternative address. | Required for Retail, Marketplace, and Delivery industries. |
beneficiary | Beneficiary object | Information on the beneficiary. | Required for Account funding flows (wallets, live streaming, etc). |
subscription | Subscription object | Additional information on the subscription. | Recommended for recurring payments. |
submerchant | Submerchant object | Information on the submerchant account. | Required for merchants with more merchants that involve submerchants. |
purchase | Purchase object | The purchase object is used to provide additional general information about the purchase. | Optional fields |
Example Payment with Additional Risk Data object
{
"amount": 399.8,
"currency": "USD",
"country": "BR",
"payment_method_id": "CARD",
"payment_method_flow": "DIRECT",
"payer": {
"name": "Thiago Gabriel",
"email": "[email protected]",
"document": "53033315550",
"user_reference": "12345",
"address": {
"state": "Rio de Janeiro",
"city": "Volta Redonda",
"zip_code": "27275-595",
"street": "Servidao B-1",
"number": "1106"
}
},
"card": {
"holder_name": "Thiago Gabriel",
"number": "4111111111111111",
"cvv": "123",
"expiration_month": 10,
"expiration_year": 2040
},
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications",
"additional_risk_data": {
"device": {
"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",
"geolocation": "-34.8798853,-56.1867859",
"locale": "en-US",
"advertising_id": "EA7583CD-A667-48BC-B806-42ECB2B48606",
"vendor_id": "uapff_93e9a58cc03a0e7f45c2cf50ca567a99",
"android_id": "cdda802e-fb9c-47ad-9866-0794d394c913",
"media_drm_id": "0102030405060708090a0b0c0d0e0f10"
},
"payer": {
"account_creation_date": "20201110",
"is_positive": false,
"email_is_valid": true,
"phone_is_valid": false,
"first_purchase_date": "20201110",
"last_order_id": "1525634152634",
"total_order_count": 12,
"total_order_amount": 152.03,
"last_updated_date": "20201020",
"reputation": 5
},
"basket": [
{
"unit_price": 199.9,
"category": "Electronic",
"item_reference": "SP-562138",
"product_name": "Pexel 25",
"quantity": 2,
"url": "https://www.merchant.com/products/SP-562138",
"brand": "Smoogle",
"subcategory": "Droid smartphones",
"published_date": "20201113",
"rating": 4.5,
"count_reviews": 13,
"subscription": {
"id": "adgte1256",
"period": "P1M",
"current_period": 3,
"end_date": "20240801"
}
}
]
},
"shipping": {
"address": {
"state": "Montevideo",
"city": "Montevideo",
"zip_code": "11300",
"street": "Avda. Brasil",
"number": "1234 Ap. 501"
},
"cost": 12.34,
"delivery_company": "FadEx",
"method": "FREE",
"delivery_date": "20211020",
"is_forwarding_address": false,
"geolocation": "-34.8798853,-56.1867859"
},
"beneficiary": {
"email": "[email protected]",
"phone": "55119846785",
"accountID": "384059hji",
"name": "gabriel thiago",
"document": "54678903",
"created_date": "20220704"
},
"submerchant": {
"merchant_reference": "12534",
"name": "Submerchant name",
"website": "https://www.submerchant.com",
"industry": 17,
"document": "15236713521",
"nationality": "BR",
"email": "[email protected]",
"username": "submerchant_username",
"phone": "123456712345",
"created_date": "20210311",
"total_order_count": 35,
"total_order_amount": 45020,
"last_updated_date": "20210312",
"onboarding_ip_address": "123.21.31.124",
"onboarding_email": "[email protected]",
"reputation": 4,
"ship_from_address": {
"state": "Montevideo",
"city": "Montevideo",
"zip_code": "11300",
"street": "Avda. Brasil",
"number": "1234 Ap. 401"
},
"last_login": "20210312",
"device_id": "2fg3d4gf234",
"kyc_review": true,
"fraud_review": true,
"fraud_review_type": "MULTIPLE_ACCOUNTS",
"fraud_review_description": "Passed to fraud review because of blacklist NEW_ACCOUNT_MULTIPLE_ACCOUNTS",
"submerchant_description": "Business description",
"checkout_type": "WEBSITE_REDIRECT",
"checkout_subtype": "TOKEN",
"registered_company": true,
"bank_account": {
"beneficiary_name": "Account's onwer's nam",
"beneficiary_document": "15236713521",
"account": "487445839",
"branch": "name/number",
"beneficiary_email": "[email protected]",
"beneficiary_phone": "5512345678901"
}
}
}
Detail Information
Device
The Device object is used to store information on the device (e.g., laptop, smartphone) used to make the purchase.
To provide information about the Device ID, there are two possible options:
- If you calculate your Device ID, you can send this information in the Payer object, under the
deviceid
field. - If you use the dLocal integration, you must send the information in
additional_risk_data.device_id.event_uuid
. Also, the following fields could be sent:
Property | Type | Description | Type |
---|---|---|---|
event_uuid | String | dLocal Device ID. | Required |
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). | Optional |
vendor_id | String | For Apple, an alphanumeric string that uniquely identifies a device to the vendor (identifierForVendor ). | Optional |
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. | Optional |
media_drm_id | String | For Android, the MediaDrm device unique ID. | Optional |
Example Device object
"additional_risk_data":{
"device": {
"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",
"geolocation" : "-34.8798853,-56.1867859",
"locale": "en-US",
"advertising_id": "EA7583CD-A667-48BC-B806-42ECB2B48606",
"vendor_id": "uapff_93e9a58cc03a0e7f45c2cf50ca567a99",
"android_id": "cdda802e-fb9c-47ad-9866-0794d394c913",
"media_drm_id": "0102030405060708090a0b0c0d0e0f10"
}
}
Payer
The basic information of the payer, meaning the entity that initiates the payment, must be sent in the Payer object. This object is intended to collect additional information.
Property | Type | Description | Type |
---|---|---|---|
account_creation_date | String | Date of creation of the account. YYYYMMDD format. This information is used to generate different risk segments based on the age of the account. | Recommended |
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.This field can be used to define a healthy segment to which fewer rules can be applied. | Recommended |
phone_is_valid | Boolean | Set to TRUE if the payer's phone number has been validated. | Optional |
email_is_valid | Boolean | Set to TRUE if the payer's email has been validated. | Optional |
first_purchase_date | String | Date of first successful purchase. YYYYMMDD format. | Optional |
last_order_id | String | Last order id placed by this account, not including the current order. | Optional |
total_order_count | Number | The total count of orders purchased by this account. | Optional |
total_order_amount | Number | The total amount purchased by this account. | Optional |
last_updated_date | Date | The last time a change was made to this account, e.g. changed address. YYYYMMDD format. | Optional |
reputation | Number | The reputation of the payer, from 0 (negative) to 5 (positive). | Optional |
Example Payer object
"additional_risk_data":{
"payer": {
"account_creation_date": "20201110",
"is_positive": false,
"email_is_valid": true,
"phone_is_valid": false,
"first_purchase_date": "20201110",
"last_order_id": "1525634152634",
"total_order_count": 12,
"total_order_amount": 152.03,
"last_updated_date": "20201020",
"reputation": 5
}
}
Basket
This object is a list of items and should be used to specify the different items purchased and their characteristics. This applies to both physical and digital products.
Our fields are flexible and can be adapted to the information you have. Our team is available to assist you in this process if necessary.
Property | Type | Description | Type |
---|---|---|---|
unit_price | Number | Unit price. | Recommended |
category | String | Product category. | Recommended |
item_reference | String | Item ID/Reference. | Recommended |
product_name | String | Product or service name. | Recommended |
quantity | Number | Quantity of items purchased. | Recommended |
url | String | The item URL. | Recommended |
brand | String | Product brand. | Optional |
subcategory | String | The item subcategory. | Optional |
published_date | String | Date when the product was added/published in the store. YYYYMMDD format. | Optional |
rating | Number | The product rating, as a score from 1 to 5. | Optional |
count_reviews | Number | Number of customer reviews the product has received. | Optional |
Example Basket & Item object
"additional_risk_data":{
"basket": [
{
"unit_price": 199.90,
"category": "Electronic",
"item_reference": "SP-562138",
"product_name": "Pexel 25",
"quantity": 2,
"url": "https://www.merchant.com/products/SP-562138",
"brand": "Smoogle",
"subcategory": "Droid smartphones",
"published_date": "20201113",
"rating": 4.5,
"count_reviews": 13
}
]
}
Shipping
For merchants in Delivery, Retail, Marketplace, or whenever the delivery of a physical product is involved, the billing address must be included in the Payer object, and the shipping address must be included in the shipping object. Additionally, the rest of the parameters in the shipping object are optional.
Property | Type | Description | Type |
---|---|---|---|
address | Address object | Represents the address, documented in this table. | Required |
address.state | String | State. | Required |
address.city | String | City. | Required |
address.zip_code | String | ZIP Code. | Required |
address.street | String | Street. | Required |
address.number | String | Street number. | Required |
cost | Number | Cost of the delivery (in USD). | Optional |
delivery_company | String | Name of the delivery company. | Optional |
method | String | The type of shipment selected during checkout. See the list. | Optional |
delivery_date | String | Shipping delivery date. YYYYMMDD format. | Optional |
is_fowarding_address | Boolean | If the shipping address is a forwarding address. | Optional |
geolocation | String | Shipping geolocation. | Optional |
Example Shipping object
"additional_risk_data":{
"shipping": {
"address": {
"state": "Montevideo",
"city": "Montevideo",
"zip_code": "11300",
"street": "Avda. Brasil",
"number": "1234 Ap. 501"
},
"cost": 12.34,
"delivery_company": "FadEx",
"method": "FREE",
"delivery_date": "20211020",
"is_forwarding_address": false,
"geolocation": "-34.8798853,-56.1867859"
}
}
Beneficiary
For merchants that include an account funding flow, beneficiary information is mandatory. If you have any questions, our fraud team can provide assistance and guidance as needed.
This information is crucial for detecting and preventing buyer and seller fraud. It applies to both cards and alternative payment methods.
Property | Type | Description | Type |
---|---|---|---|
email | String | The email address associated with the beneficiary's account. | Required |
name | String | The full name of the beneficiary. | Required |
phone | String | The phone number associated with the beneficiary's account. | Required |
document | String | An identification document (e.g., passport, ID card) of the beneficiary. | Required |
account_id | String | A unique identifier for the beneficiary's account where the funds will be deposited. | Required |
created_date | String | The date when the beneficiary account was created. YYYYMMDD format. | Required |
Example Beneficiary object
"additional_risk_data":{
"beneficiary": {
"email":"[email protected]",
"phone":"55119846785",
"accountID":"384059hji",
"name":"gabriel thiago",
"document":"54678903",
"created_date":"20220704"
}
}
Subscription
For merchants with recurring payments and subscriptions, we recommend providing detailed information about the subscription periods.
This data will enhance the accuracy of the fraud strategy and help detect friendly chargebacks.
Property | Type | Description | Type |
---|---|---|---|
subscription | Subscription Object | Represents the subscription period, documented in this table. | Recommended |
subscription.id | String | Subscription ID/reference. | Recommended |
subscription.period | String | Renewal period in ISO 8601 format (P1M, P3M, P1Y etc). | Recommended |
subscription.current_period | String | The current subscription period that the recurring order belongs to. | Recommended |
subscription.end_date | String | Subscription end date. YYYYMMDD format. | Recommended |
Example Subscription object
"additional_risk_data":{
"basket":[
{
"subscription":{
"id":"adgte1256",
"period":"P1M",
"current_period":3,
"end_date":"20240801"
}
]
}
Submerchant
This section covers all merchants that involve submerchants or those processing through different URLs.
For these cases, it is necessary to identify each submerchant and their website. Additionally, various recommended and optional features are presented.
Property | Type | Description | Type |
---|---|---|---|
merchant_reference | String | The ID/reference of the submerchant account. | Required |
website | String | Submerchant website. | Required |
document | String | Submerchant's document. | Required |
email | String | Submerchant's email address. | Required |
name | String | Submerchant name. | Required |
phone | String | Phone number. | Required |
onboarding_email | String | The email used when this seller account was created. | Required |
industry | Number | Submerchant industry, see industry codes list. | Optional |
nationality | String | Submerchant's nationality (ISO 3166 country code). | Optional |
username | String | The unique username associated with the seller's online account. | Optional |
created_date | String | Date of account creation. YYYYMMDD format. | Optional |
total_order_count | Number | The total count of orders sold by this seller. | Optional |
total_order_amount | Number | The total amount sold by this seller (in USD). | Optional |
ship_from_address | Object | The address from where the submerchant ships the orders. | Recommended |
ship_from_address.street | String | Street. | Recommended |
ship_from_address.number | String | Street number. | Recommended |
ship_from_address.city | String | City. | Recommended |
ship_from_address.zip_code | String | ZIP Code. | Recommended |
ship_from_address.state | String | State. | Recommended |
device_id | String | Submerchant's unique device identifier (onboarding). | Recommended |
last_updated_date | String | The last time a change was made to this submerchant (e.g. changed address). YYYYMMDD format. | Optional |
onboarding_ip_address | String | The IP address of the device used when this seller account was created. | Optional |
reputation | Number | The reputation of the submerchant, from 0 (negative) to 5 (positive). | Optional |
last_login | Date | The last time this submerchant logged in. YYYYMMDD format. | Optional |
KYC_review | Boolean | Informs if KYC was reviewed. | Optional |
Fraud_review | Boolean | Informs if there was a fraud review. | Optional |
Fraud_review_type | List | If there was a fraud review, what type was it. | Optional |
Fraud_review_description | String | Description of the fraud review performed. | Optional |
submerchant_description | String | Information and description about the business provided by the merchant. | Optional |
Checkout_type | String | Type of integration the merchant is using for the checkout. | Optional |
Checkout_subtype | String | Additional information regarding the integration subtype. | Optional |
industry_name | String | Merchant Industry. | Optional |
Registered_Company | Boolean | If the merchant is an individual or a company. | Optional |
bank_account | Object | Bank account information. | Optional |
bank_account.beneficiary_name | String | Bank account's owner's full name. | Optional |
bank_account.beneficiary_document | String | Bank account's owner's document ID. | Optional |
bank_account.account | Number | Bank account's number. | Optional |
bank_account.branch | String | Where was the bank account opened. | Optional |
bank_account.beneficiary_email | String | Bank account's owner's email address. | Optional |
bank_account.beneficiary_phone | Number | Bank account's owner's phone number. | Optional |
Example Submerchant object
"additional_risk_data":{
"submerchant": {
"merchant_reference": "12534",
"name": "Submerchant name",
"website": "https://www.submerchant.com",
"industry": 17,
"document": "15236713521",
"nationality": "BR",
"email": "[email protected]",
"username": "submerchant_username",
"phone": "123456712345",
"created_date": "20210311",
"total_order_count": 35,
"total_order_amount": 45020,
"last_updated_date": "20210312",
"onboarding_ip_address": "123.21.31.124",
"onboarding_email": "[email protected]",
"reputation": 4,
"ship_from_address": {
"state": "Montevideo",
"city": "Montevideo",
"zip_code": "11300",
"street": "Avda. Brasil",
"number": "1234 Ap. 401"
},
"last_login":"20210312",
"device_id":"2fg3d4gf234",
"kyc_review":true,
"fraud_review":true,
"fraud_review_type":"MULTIPLE_ACCOUNTS",
"fraud_review_description":"Passed to fraud review because of blacklist NEW_ACCOUNT_MULTIPLE_ACCOUNTS",
"submerchant_description":"Business description",
"checkout_type":"WEBSITE_REDIRECT",
"checkout_subtype":"TOKEN",
"registered_company":true,
"bank_account": {
"beneficiary_name": "Account's onwer's nam",
"beneficiary_document": "15236713521",
"account": "487445839",
"branch": "name/number",
"beneficiary_email": "[email protected]",
"beneficiary_phone": "5512345678901"
},
}
}
Purchase
The Purchase object is used to provide additional general information about the purchase.
Property | Type | Description | Type |
---|---|---|---|
is_retry | Boolean | Indicates if the payment is a retry by the user of the same previously rejected purchase attempt. | Recommended |
channel | String | The channel or source where the order was placed. See the list . | Recommended |
time_in_session | Number | The time in seconds that a user spent within the session in the website or app before making the purchase. | Recommended |
Example Purchase object
"additional_risk_data":{
"purchase": {
"is_retry": false,
"channel": "WEB",
"time_in_session": 55,
}
}
Appendix - Codes
Industry codes list
Code | Industry |
---|---|
1 | Advertising |
2 | Antivirus |
3 | Delivery |
4 | Donations |
5 | Education |
6 | Gaming |
7 | Healthcare |
8 | Hosting |
9 | Investing / Financial services |
10 | IT Services |
11 | Marketplace |
12 | Money remittance |
13 | Payroll |
14 | Prepaid cards |
15 | PSP |
16 | Retail - Offline |
17 | Retail - Online |
18 | Ridesharing |
19 | SaaS |
20 | Social |
21 | Software / Apps |
22 | Streaming |
23 | Transport |
24 | Travel |
25 | Wallet |
26 | Dating |
27 | Crypto |
999 | Others |
Shipping methods list
Code | Description |
---|---|
FREE | Free Shipping |
PICKUP | Pickup in store |
INTERNATIONAL | International |
EXPRESS | Express |
STANDARD | Standard |
Purchase channel list
Code | Description |
---|---|
WEB | Users buy through the website. |
PHONE | Orders made by phone calls. |
MOBILE_APP | Users buy through a mobile application. |
SOCIAL | Users buy through a social network platform (Facebook, Instagram). |
MARKETPLACE | Users buy in an e-commerce store where products are sold by multiple sellers (Amazon). |
IN_STORE | Orders purchased in a physical store. |
Let’s collaborate to create a better experience.
Give feedbackUpdated about 15 hours ago