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.

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"
      },
  }
}

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.

How can we improve?

Let’s collaborate to create a better experience.

Give feedback