Referral list call

Using this call, you can add, update referral lists that are placed on several referral lists used for fraud checks with JSON or XML (via SOAP).

Limitations:

  • Wildcards are not allowed when uploading via API (for the risk checks that support them, they should be submitted through backoffice)
  • Any invalid entries from the submitted referral list will be skipped and marked as such in the response
  • Uploading referrals will always be done on company level, even when submitting a merchant accountCode (same behaviour as backoffice)

Endpoints:

Test

Live:


Example SOAP request (data to be replaced with payload examples):

Field Type Required Description
action String (tick) Type of action
accountCode String (tick) Merchant account code.
reason String (tick) Reason of the request.
referralType String (tick)

Type of referral included in the request.

Allowed values:

  • shopperemail
  • shopperip
  • pmowner -> this one corresponds to shopper name
  • shopperaddress
  • shopperreference
  • txvariantshopperreference
  • emaildomain
  • socialsecuritynumber
  • phonenumber
  • cardnumber
  • ibannumber
  • issuerreference
  • issuingcountry
  • persistentcookie
  • ipcountry

If you are including shopperAddress follow the specified structure for each referral replace the referralContainer with addressReferrals.

addressReferrals Class  (tick)

Container for address referral fields. This field should be used for uploading address referrals in place of referralContainer.

Contains the following fields:

  • city
  • country
  • houseNumberOrName
  • postalCode
  • stateOrProvince
  • street
city String (tick) The city name.
country String (tick) A valid value is an ISO 2-character country code.
houseNumberOrName String (tick) The house number or name.
postalCode String (tick) The postal code with a maximum of 5 characters for USA and maximum of 10 characters for any other country.
stateOrProvince String (tick)

For USA or Canada, a valid 2-character abbreviation for the state or province respectively. For other countries any abbreviation with maximum 3 characters for the state or province.

street String (tick) The street name.
referrals  Class (tick)

A container for the referralContainer.

Contains the following field:

  • referralContainer
referralContainer Class (tick)

A container for referrals.

Contains the following field:

  • referral
referral String  (tick)

Shopper referral.

Some examples of including referrals:

  • shopperIP - 8.8.8.8
  • shopperAddress - Fifth St.,5,Amsterdam,1000AA,Noord-Holland,NL
  • shopperemail - test@gmail.com

uploadReferrals:

Request:

{
   "accountCode":"TestMerchant",
   "referralType":"shopperip",
   "action":"block",
   "referrals":[
      {
         "referralContainer":{
            "referral":"johnsmith@example.com"
         }
      },
      {
         "referralContainer":{
            "referral":"jsmith@example.com"
         }
      }
   ],
   "reason":"test behaviour"
}

Response:

{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "10.0.0.1\/24",
      "8.8.8.1\/30"
   ]
}

Request:

<?xml version="1.0" encoding="UTF-8"?>
<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>
      <uploadReferralsStructured xmlns="http://referral.services.adyen.com">
         <request>
            <action>trust</action>
            <accountCode>TestMerchant</accountCode>
            <reason>test API</reason>
            <referralType>shopperip</referralType>
            <referrals>
               <referralContainer>
                  <referral>johnsmith@example.com</referral>
               </referralContainer>
               <referralContainer>
                  <referral>jsmith@example.com</referral>
               </referralContainer>
            </referrals>
         </request>
      </uploadReferralsStructured>
   </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0="http://referral.services.adyen.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <ns0:uploadReferralsStructuredResponse>
         <ns0:response>
            <ns0:referralServiceResult>
               <ns0:success>true</ns0:success>
            </ns0:referralServiceResult>
            <ns0:skippedReferrals>
               <ns0:string>8.8.4.4/32</ns0:string>
            </ns0:skippedReferrals>
         </ns0:response>
      </ns0:uploadReferralsStructuredResponse>
   </soap:Body>
</soap:Envelope>

Address referrals:

{
   "accountCode":"TestMerchant",
   "referralType":"shopperip",
   "action":"block",
   "referrals":[
      {
         "addressReferrals":[
            {
               "shopperAddress":{
                  "street":"Main St",
                  "houseNumberOrName":"2",
                  "city":"Amsterdam",
                  "postalCode":"1000AA",
                  "stateOrProvince":"Noord-Holland",
                  "countryCode":"NL"
               }
            },
            {
               "shopperAddress":{
                  "street":"West lane",
                  "houseNumberOrName":"2",
                  "city":"London",
                  "postalCode":"1100AB",
                  "stateOrProvince":"England",
                  "countryCode":"UK"
               }
            }
         ]
      }
   ],
   "reason":"test behaviour"
}
<?xml version="1.0" encoding="UTF-8"?>
<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>
      <uploadReferralsStructured xmlns="http://referral.services.adyen.com">
         <request>
            <action>trust</action>
            <accountCode>TestMerchant</accountCode>
            <reason>test API</reason>
            <referralType>shopperip</referralType>
            <referrals>
               <addressReferrals>
                  <shopperAddress>
                     <street>street</street>
                     <houseNumberOrName>1</houseNumberOrName>
                     <city>Testcity</city>
                     <postalCode>2000AA</postalCode>
                     <stateOrProvince />
                     <countryCode>NL</countryCode>
                  </shopperAddress>
                  <shopperAddress>
                     <street>StreetNm</street>
                     <houseNumberOrName>44</houseNumberOrName>
                     <city>SomeCity</city>
                     <postalCode>610000</postalCode>
                     <stateOrProvince>Moldova</stateOrProvince>
                     <countryCode>RO</countryCode>
                  </shopperAddress>
               </addressReferrals>
            </referrals>
         </request>
      </uploadReferralsStructured>
   </soap:Body>
</soap:Envelope>