Provide data for risk checks

Adyen's API for payment requests contains several optional fields that can be provided by the merchants. Some of these fields are quite important when the merchant uses several risk checks in the Risk System. We recommend the use of the following fields in order to use to its fullest the capabilities of Adyen's Risk System.

Standard Fields

The standard risk fields comprise the minimum data points required to use our risk system:

Field Required Description
reference (tick)

A unique identifier associated to a specific transaction. It is used in all communication with you regarding the status of the payment.

We recommend using a unique value per payment, but this is not a requirement.

shopperReference (error)

A shopper's reference, which is the unique identifier for a shopper.

Used in the following risk checks:

dateOfBirth (error)

The shopper's date of birth.

Format: ISO-8601; example: YYYY-MM-DD

Used in the following risk checks:

shopperName (error)

A shopper's personal information including the firstName, infix, lastName, and gender.

Used in the following risk checks:

shopperEmail (error)

shopperIP

(error)
deliveryAddress (error)

The address where a shopper is going to receive goods/services. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

billingAddress (error)

The address where a shopper is going to receive the bill. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

deviceFingerprint (error)

Information from a shopper's device and uses the combined value to identify the device of the shopper.

Used in the following risk checks:

telephoneNumber

(error) A shopper's phone number (only in countries where it is legal to collect).

socialSecurityNumber

(error) A shopper's social security number (only in countries where it is legal to collect).
deliveryDate (error)

The expected date of delivery or fulfillment of the goods/services to the shopper.

Used in the following risk checks:

fraudOffset (error) An integer that is added to the final fraud score of all risk checks. The value can be either positive or negative.
merchantOrderReference (error) A reference that merchants can use to link multiple transactions to each other.
browserInfo (error) With the browser info data, we can determine if the device is mobile or not, which is used for device fingerprinting and other device logic.

Enriched Data - Risk Check additional information

Adyen provides the following additional data points to make our risk system even more powerful.

These fields should be used within the additionalData field. For more information on submitting additionalData see the PaymentRequest.additionalData topic.

{  
   "amount":{  
      "value":1700,
      "currency":"EUR"
   },
   "card":{  
      "number":"4111111111111111",
      "expiryMonth":"8",
      "expiryYear":"2018",
      "cvc":"737",
      "holderName":"Simon Hopper"
   },
   "reference":"LASPDAVIDDK2",
   "merchantAccount":"TestMerchant",
   "shopperReference":"Simon Hopper",
   "dateOfBirth":"1982-07-17",
   "shopperName":{
      "firstName":"Simon",
      "infix":"R.",
      "lastName":"Hopper",
      "gender": "MALE"
   },
   "shopperEmail":"s.hopper@test.com",
   "shopperIP":"61.294.12.12",
   "deliveryAddress":"123 Delivery street, San Francisco",
   "billingAddress":"123 Delivery street, San Francisco",
   "telephoneNumber":"4154761000",
   "deliveryDate":"30062017",
   "additionalData":{  
   		"riskdata.deliveryMethod":"express"
   		"riskdata.basket.item.productTitle":"Blue T Shirt"
   		"riskdata.promotions.promotion.promotionName":"Big Sale promotion"
   }
}
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
   <soap:Body>
      <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
         <ns1:paymentRequest>
            <amount xmlns="http://payment.services.adyen.com">
               <value xmlns="http://common.services.adyen.com">1700</value>
               <currency xmlns="http://common.services.adyen.com">EUR</currency>
            </amount>
            <card xmlns="http://payment.services.adyen.com">
               <number>4111111111111111</number>
               <expiryMonth>08</expiryMonth>
               <expiryYear>2018</expiryYear>
               <cvc>737</cvc>
               <holderName>Simon Hopper</holderName>
            </card>
            <reference xmlns="http://payment.services.adyen.com">LASPDAVIDDK2</reference>
            <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
            <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
            <dateOfBirth xmlns="http://payment.services.adyen.com">1982-07-17</dateOfBirth>
            <shopperName xmlns="http://payment.services.adyen.com">
               <firstName xmlns="http://common.services.adyen.com">Simon</firstName>
               <infix xmlns="http://common.services.adyen.com">R.</infix>
               <lastName xmlns="http://common.services.adyen.com">Hopper</lastName>
               <gender xmlns="http://common.services.adyen.com">MALE</gender>
            </shopperName>
            <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
            <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
			<deliveryAddress xmlns="http://payment.services.adyen.com">123 Delivery street San Francisco</deliveryAddress>
			<billingAddress xmlns="http://payment.services.adyen.com">123 Delivery street San Francisco</billingAddress>
			<telephoneNumber xmlns="http://payment.services.adyen.com">4154761000</telephoneNumber>
			<deliveryDate xmlns="http://payment.services.adyen.com">30062017</deliveryDate>
            <additionalData xmlns="http://payment.services.adyen.com">
               <riskdata.deliveryMethod>express</riskdata.deliveryMethod>
			   <riskdata.basket.item.productTitle>Blue T Shirt</riskdata.basket.item.productTitle>
			   <riskdata.promotions.promotion.promotionName>Big Sale promotion</riskdata.promotions.promotion.promotionName>
 
            </additionalData>
         </ns1:paymentRequest>
      </ns1:authorise>
   </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=10000&amount.currency=EUR&card.expiryYear=2018&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12&deliveryAddress=123+Delivery+street+San+Francisco&billingAddress=123+Delivery+street+San+Francisco&telephoneNumber=4154761000&deliveryDate=30062017&additionalData.riskdata.deliveryMethod=EXPRESS&additionalData.riskdata.basket.item.productTitle=Blue+T+Shirt&additionalData.riskdatapromotions.promotion.promotionName=Big+Sale+promotion

Enriched Data - Basket and promotional content fields 

Adyen provides merchants the possibility to include basket and promotion information of a payment transaction in their API request to Adyen. This extra information is particularly important when performing case management of transactions before they are captured.

These fields should be used within the additionalData field. For more information on submitting additionalData see the PaymentRequest.additionalData topic.

The following example demonstrates the use of this object:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest>
        <additionalData>
          <entry>
            <key xsi:type="xsd:string">riskdata.basket.item1.productName</key>
            <value xsi:type="xsd:string">fake product</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">riskdata.basket.item1.productCount</key>
            <value xsi:type="xsd:string">5</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">riskdata.basket.item2.productName</key>
            <value xsi:type="xsd:string">good product</value>
          </entry>
          <entry>
            <key xsi:type="xsd:string">riskdata.basket.item2.productCount</key>
            <value xsi:type="xsd:string">1000</value>
          </entry>
        </additionalData>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">1500</value>
        </amount>
        <card xmlns="http://payment.services.adyen.com">
            <expiryMonth>8</expiryMonth>
            <expiryYear>2018</expiryYear>
            <holderName>Joep M.</holderName>
            <number>4111111111111111</number>
            <cvc>737</cvc>
        </card>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">ref12345</reference>
  		  <shopperReference xmlns="http://payment.services.adyen.com">123</shopperReference>
  		  <shopperEmail xmlns="http://payment.services.adyen.com">12dfgs4334345346@adyen.com</shopperEmail>
  		  <shopperIP xmlns="http://payment.services.adyen.com">127.0.0.1</shopperIP>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope> 

Enriched Data - Custom Risk Fields

Adyen provides merchants the possibility to send data into custom fields that can, in turn, be used in Custom Risk Checks.

 In order to request a field,  contact Support Team and indicate:

  1. The name of the field (one word name)
  2. The data type of the field

The options for data type are:

  • String

  • StringList

  • Number

  • NumberList

  • Date

  • DateList

After the field has been created, it is activated and appears in the Custom Risk Rule interface. AND/OR rules are then created.

 You can then submit data to the additionaldata.riskdata.<customfieldname> field.



Questions

Can't find something you are looking for? Look at our FAQ for answers or contact Support.