Risk data documentation

Find all the specification for fraud-related fields.

Additional Risk Data Information

For a more in-depth analysis of transactions for fraud patterns, we recommend that our merchants consider using the additional_risk_data object in their Payment API calls, which can be used to better identify fraudulent transactions.

Merchants may provide the information that applies for their particular case.

PropertyTypeDescription
submerchantSubmerchant objectInformation on the submerchant account.
Required for PSPs / Marketplaces.
shippingShipping object​Information on the shipping/alternative address.
Required for Retail.
beneficiaryBeneficiary object​ Information on the beneficiary, if different from the payer.
basketList of Item objectsInformation on the items purchased.
Required.
payerPayer objectAdditional information on the payer's user account.
deviceDevice object​Additional information on the device used for purchase.
purchasePurchase object​The purchase object is used to provide additional general information about the purchase.
travelTravel object​The travel object is used to provide additional information details about the travel operations.

Example Payment with Additional Risk Data object

{
  "amount": 399.80,
  "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": {
      "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"
          }
      },
      "shipping": {
          "address": {
              "state": "Montevideo",
              "city": "Montevideo",
              "zip_code": "11300",
              "street": "Avda. Brasil",
              "number": "1234 Ap. 501"
          },
          "is_physical": true,
          "cost": 12.34,
          "delivery_company": "FadEx",
          "method": "FREE",
          "delivery_date": "20211020",
          "is_forwarding_address": false,
          "geolocation": "-34.8798853,-56.1867859"
      },
      "beneficiary": {
          "email": "[email protected]",
          "name": "John Doe",
          "phone": "09671268364",
          "document": "513672561"
      },
      "basket": [
          {
              "unit_price": 199.90,
              "brand": "Smoogle",
              "category": "Smartphone",
              "item_reference": "SP-562138",
              "upc": "1758929364928",
              "manufacturer": "Smoogle",
              "product_name": "Pexel 25",
              "quantity": 2,
              "size": "regular",
              "subcategory": "Droid smartphones",
              "url": "https://www.merchant.com/products/SP-562138",
              "published_date": "20201113",
              "rating": 4.5,
              "count_reviews": 13,
              "image": "https://www.merchant.com/products/SP-562138/photos/1.jpg",
              "stock": 32,
              "weight": 0.34,
              "subscription": {
                  "id": "A15-D267125367",
                  "period": "P1M",
                  "current_period": 3,
                  "end_date": "20220101" 
              }
          }
      ],
      "payer" : {
          "email_is_valid": true,
          "phone_is_valid": false,
          "account_creation_date": "20201110",
          "first_purchase_date": "20201110",
          "is_positive": false,
          "last_order_id": "1525634152634",
          "total_order_count": 12,
          "total_order_amount": 152.03,
          "last_updated_date": "20201020",
          "wish_list": [
              {
                  "item_reference": "125312435",
                  "unit_price": 1300,
                  "product_name": "Pexel 25 for dummies"
              }
          ],
          "reputation": 5
      },
      "purchase": {
          "is_retry": false,
          "channel": "WEB",
          "time_in_session": 55,
          "search_history": [
              {
                  "item_reference": "125312435",
                  "unit_price": 1300,
                  "product_name": "Pexel 25 for dummies"
              }
          ]
      },
      "discount_codes": [
          {
              "amount": 10,
              "percentage": 20,
              "code": "PROMO20OFF",
              "valid_until": "20211130",
              "description": "20% off Smoogle products"
          }
      ],
      "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",
          "event_uuid": "ab825a72-62c3-4df5-9886-25c75856fac7"

      },
      "travel": {
          "car_rental": [
              {
                  "insurance_charges": 160.00,
                  "pickup_city": "Montevideo",
                  "pickup_country": "UY",
                  "pickup_date": "2021032",
                  "rental_charges": 15.03,
                  "return_city": "Buenos Aires",
                  "return_country": "AR",
                  "return_date": "20210320"
              }
          ],
          "flight": {
              "itinerary": {
                  "flight_code": "AR138",
                  "reservation_code": "6AL3J2",
                  "legs": [
                      {
                          "amount": 800.00,
                          "arrival": "MVD",
                          "arrival_time": "2021-04-29 07:16:24",
                          "carrier_code": "AR",
                          "class_of_travel": "F",
                          "departure": "EZE",
                          "departure_time": "2021-04-29 04:30:15",
                          "destination": "Montevideo"
                      }
                  ]
              },
              "passengers": [
                  {
                      "date_of_birth": "19890703",
                      "ffp_ID": "ABC3454",
                      "first_name": "John",
                      "last_name": "Doe",
                      "nationality": "BR"
                  }
              ]
          },
          "lodging": [
              {
                  "amount": 123,
                  "check_in_date": "20210314",
                  "check_out_date": "20210318",
                  "city": "Montevideo",
                  "country": "UY",
                  "guests": 2,
                  "prepaid_expenses": 0,
                  "rooms": 1
              }
          ]
      }
   }
}

Submerchant

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.

PropertyTypeDescription
merchant_referenceStringThe ID/reference of the sub-merchant account. Optional.
nameStringSub-merchant name.
Required for PSPs/marketplaces.
websiteStringSub-merchant website. Optional.
industryNumberSub-merchant industry, see industry codes list. Optional.
documentStringSubmerchant's document.
nationalityStringSubmerchant's nationality (ISO 3166 country code).
emailStringSubmerchant's email address.
usernameStringThe unique username associated with the seller's online account.
phoneStringPhone number.
created_dateStringDate of account creation in YYYYMMDD format.
total_order_countNumberThe total count of orders sold by this seller.
total_order_amountNumberThe total amount sold by this seller (in USD).
last_updated_dateStringThe last time a change was made to this submerchant (e.g. changed address).
YYYYMMDD format.
onboarding_ip_addressStringThe IP address of the device used when this seller account was created.
onboarding_emailStringThe email used when this seller account was created.
reputationNumberThe reputation of the submerchant, from 0 (negative) to 5 (positive).
ship_from_addressObjectThe address from where the submerchant ships the orders.
ship_from_address.streetStringStreet.
ship_from_address.numberStringStreet number.
ship_from_address.cityStringCity.
ship_from_address.zip_codeStringZip Code.
ship_from_address.stateStringState.

Example Submerchant object

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

Shipping

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).

PropertyTypeDescription
addressAddress objectRepresents the address, documented in this table. Optional.
address.stateStringState. Optional.
address.cityStringCity. Optional.
address.zip_codeStringZip code. Optional.
address.streetStringStreet. Optional.
address.numberStringStreet number. Optional.
is_physicalBooleanTrue if a physical delivery to this address is involved (i.e. for retail goods). Optional.
costNumberCost of the delivery (in USD).
delivery_companyStringName of the delivery company.
methodStringThe type of shipment selected during checkout. See the list.
delivery_dateStringShipping delivery date. in YYYYMMDD format.
is_fowarding_addressBooleanIf the shipping address is a forwarding address.
geolocationStringShipping geolocation.

Example Shipping object

"shipping": {
            "address": {
                "state": "Montevideo",
                "city": "Montevideo",
                "zip_code": "11300",
                "street": "Avda. Brasil",
                "number": "1234 Ap. 501"
            },
            "is_physical": true,
            "cost": 12.34,
            "delivery_company": "FadEx",
            "method": "FREE",
            "delivery_date": "20211020",
            "is_forwarding_address": false,
            "geolocation": "-34.8798853,-56.1867859"
        }

Beneficiary

PropertyTypeDescription
emailStringEmail address. Optional.
nameStringName & surname. Optional.
phoneStringPhone number. Optional.
documentStringDocument. Optional.

Example Beneficiary object

"beneficiary": {
            "email": "[email protected]",
            "name": "John Doe",
            "phone": "09671268364",
            "document": "513672561"
        }

Item

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.

PropertyTypeDescription
unit_priceNumberUnit price.
Recommended.
brandStringProduct brand. Optional.
categoryStringProduct category.
Recommended.
item_referenceStringItem ID/Reference.
Recommended.
upcStringUniversal Product Code. Optional.
manufacturerStringProduct manufacturer. Optional.
product_nameStringProduct or service name.
Recommended.
quantityNumberQuantity of items purchased.
Recommended
sizeStringProduct size (e.g. S, M, L, XL). Optional.
subcategoryStringThe item subcategory.
urlStringThe item URL.
published_dateStringDate when the product was added/published in the store. In YYYYMMDD format.
ratingNumberThe product rating, as a score from 1 to 5.
count_reviewsNumberNumber of customer reviews the product has received.
imageStringThe URL with the product image.
stockNumberThe quantity of products available for sale.
weightNumberThe product weight in kg.
subscriptionObjectA subscription object can be used to specify additional data for subscription business models.
subscription.idStringSubscription ID/reference.
subscription.periodStringRenewal period in ISO 8601 format (P1M, P3M, P1Y etc).
subscription.current_periodNumberThe current subscription period that the recurring order belongs.
subscription.end_dateStringSubscription end date. YYYYMMDD format.

Example Basket & Item object

"basket": [
            {
                "unit_price": 199.90,
                "brand": "Smoogle",
                "category": "Smartphone",
                "item_reference": "SP-562138",
                "upc": "1758929364928",
                "manufacturer": "Smoogle",
                "product_name": "Pexel 25",
                "quantity": 2,
                "size": "regular",
                "subcategory": "Droid smartphones",
                "url": "https://www.merchant.com/products/SP-562138",
                "published_date": "20201113",
                "rating": 4.5,
                "count_reviews": 13,
                "image": "https://www.merchant.com/products/SP-562138/photos/1.jpg",
                "stock": 32,
                "weight": 0.34,
                "subscription": {
                    "id": "A15-D267125367",
                    "period": "P1M",
                    "current_period": 3,
                    "end_date": "20220101" 
                }
            }
        ]

Payer

PropertyTypeDescription
email_is_validBooleanSet to TRUE if the payer's email has been validated. Optional.
phone_is_validBooleanSet to TRUE if the payer's phone number has been validated. Optional.
account_creation_dateStringDate of account creation in YYYYMMDD format. Optional.
first_purchase_dateStringDate of first successful purchase in YYYYMMDD format. Optional.
is_positiveBooleanSet 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_idStringLast order id placed by this account, not including the current order.
total_order_countNumberThe total count of orders purchased by this account.
total_order_amountNumberThe total amount purchased by this account.
last_updated_dateThe last time a change was made to this account, e.g. changed address. YYYYMMDD format.
wish_listArrayA list of items that the user has in any or all of their favorites lists.
wish_list.item_referenceStringItem ID.
wish_list.unit_priceNumberItem unit price.
wish_list.product_nameStringItem name.
reputation NumberThe reputation of the payer, from 0 (negative) to 5 (positive).

Example Payer object

"payer": {
            "email_is_valid": true,
            "phone_is_valid": false,
            "account_creation_date": "20201110",
            "first_purchase_date": "20201110",
            "is_positive": false,
            "last_order_id": "1525634152634",
            "total_order_count": 12,
            "total_order_amount": 152.03,
            "last_updated_date": "20201020",
            "wish_list": [
                {
                    "item_reference": "125312435",
                    "unit_price": 1300,
                    "product_name": "Pexel 25 for dummies"
                }
            ],
            "reputation": 5
        }

Discount Code List

The discount_codes list is a list of entries that represent the discount codes or promotions that are applied to this purchase.

PropertyTypeDescription
amountNumberProduct discount amount at the moment of the purchase.
percentageNumberIf 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 StringThe ID of the discount/code used.
valid_untilStringPromotion end date. In YYYYMMDD format.
descriptionStringA description of the discount.

Device

The Device object is used to store information on the device (i.e. laptop, smartphone) used to make the purchase.

PropertyTypeDescription
user_agentStringBrowser's User Agent property. Optional.
geolocationStringUser's geolocation. Optional.
localeStringBrowser's locale. Optional.
advertising_idStringAn advertising ID is a unique user ID assigned to a mobile device, or operating environment(apple: advertisingIdentifier, android: GSF Id).
vendor_idStringFor Apple, an alphanumeric string that uniquely identifies a device to the vendor (identifierForVendor).
android_idStringFor Android, 64-bit number (as a hex String) that the OS randomly generates when the user first sets up the device.
media_drm_idStringFor Android, the MediaDrm device unique ID.
event_uuidStringdLocal Device ID - see dLocal Device ID integration below.

Example Device object

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

Purchase

The Purchase object is used to provide additional general information about the purchase.

PropertyTypeDescription
is_retryBooleanIndicates if the payment is a retry by the user of the same previously rejected purchase attempt.
channelStringThe channel or source where the order was placed. See the list.
time_in_sessionStringThe time in seconds that a user spent within the session in the website or app before making the purchase.
search_historyArrayThe search_history list contains the list of products that the user visited within the session before making the purchase.
search_history.item_referenceStringThe item ID.
search_history.unit_priceStringThe item's unit price.
search_history.product_nameStringThe item's product name.

Example Purchase object

        "purchase": {
            "is_retry": false,
            "channel": "WEB",
            "time_in_session": 55,
            "search_history": [
                {
                    "item_reference": "125312435",
                    "unit_price": 1300,
                    "product_name": "Pexel 25 for dummies"
                }
            ]
        }

Travel

PropertyTypeDescription
flight.itinerary.legs.carrier_codeStringIATA Carrier code (2 letters).
flight.itinerary.legs.class_of_travelStringOne letter travel class identificator (F/J/Y/W).
flight.itinerary.legs.departureStringIATA Airport code of departure (3 letters).
flight.itinerary.legs.departure_timeStringDate and time of departure (GMT-0) in YYYY-MM-DD HH:mm:ss
flight.itinerary.legs.destinationStringIATA Airport code of arrival (3 letters).
flight.passengersArrayUsed to store information of the passenger(s).
flight.passengers.date_of_birthStringDate of birth of passenger(s). In YYYYMMDD format.
flight.passengers.ffp_IDStringFrequent Flyer program ID.
flight.passengers.first_nameStringFirst name of passenger(s).
flight.passengers.last_nameStringLast name of passenger(s).
flight.passengers.nationalityStringNationality of passenger(s).
lodgingArrayLodging information.
lodging.amountNumberTotal fees charged per reservation.
lodging.check_in_dateStringDate of check in. In YYYYMMDD format.
lodging.check_out_dateStringDate of check out. In YYYYMMDD format.
lodging.cityStringName of city.
lodging.countryStringISO-3166 2-letter country code.
lodging.guestsNumberNumber of guests.
lodging.prepaid_expensesNumberPrepaid expenses for the booking.
lodging.roomsNumberNumber of rooms.

Example Travel object

"travel": {
    "car_rental": [
        {
            "insurance_charges": 160.00,
            "pickup_city": "Montevideo",
            "pickup_country": "UY",
            "pickup_date": "2021-03-12",
            "rental_charges": 15.03,
            "return_city": "Buenos Aires",
            "return_country": "AR",
            "return_date": "20210320"
        }
    ],
    "flight": {
        "itinerary": {
            "legs": [
                {
                    "amount": 800.00,
                    "arrival": "MVD",
                    "arrival_time": "2021-04-29 07:16:24",
                    "carrier_code": "AR",
                    "class_of_travel": "F",
                    "departure": "EZE",
                    "departure_time": "2021-04-29 04:30:15",
                    "destination": "Montevideo"
                }
            ]
        },
        "passengers": [
            {
                "date_of_birth": "19890703",
                "ffp_ID": "ABC3454",
                "first_name": "John",
                "last_name": "Doe",
                "nationality": "BR"
            }
        ]
    },
    "lodging": [
        {
            "amount": 123,
            "check_in_date": "",
            "check_out_date": "",
            "city": "Montevideo",
            "country": "UY",
            "guests": 2,
            "prepaid_expenses": 0,
            "rooms": 1
        }
    ]
}

Appendix - Codes

Industry codes list

CodeIndustry
1Advertising
2Antivirus
3Delivery
4Donations
5Education
6Gaming
7Healthcare
8Hosting
9Investing / Financial services
10IT Services
11Marketplace
12Money remittance
13Payroll
14Prepaid cards
15PSP
16Retail - Offline
17Retail - Online
18Ridesharing
19SaaS
20Social
21Software / Apps
22Streaming
23Transport
24Travel
25Wallet
26Dating
999Others

Shipping methods list

CodeDescription
FREEFree Shipping
PICKUPPickup in store
INTERNATIONALInternational
EXPRESSExpress
STANDARDStandard

Purchase channel list

CodeDescription
WEBUsers buy through the website.
PHONEOrders made by phone calls.
MOBILE_APPUsers buy through a mobile application.
SOCIALUsers buy through a social network platform (Facebook, Instagram).
MARKETPLACEUsers buy in an ecommerce store where products are sold by multiple sellers (Amazon).
IN_STOREOrders purchased in a physical store.

Did this page help you?