Referral list API

With Referrals API you can automatically upload lists of referrals for Adyen risk checks. For each uploaded list, you must specify the action (block or trust) to either blacklist or whitelist the specified referrals. You can also set the action to delete to remove specific referrals from your account.

Limitations:

  • Wildcards are not allowed when uploading using the Referrals API. They can be submitted only through the Customer Area.
  • Any invalid entries from the submitted referral list will be skipped and marked as such in the response.
  • Uploading referrals must be always done at the company level, even when submitting a merchant's accountCode.

Block referral emails

The following example demonstrates how to block two emails: "johnsmith@example.com" and "jsmith_example.com". In this case, "johnsmith@example.com" is blocked and "jsmith_example.com" is skipped (which is specified in the skippedReferrals section of the response).

Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint.

Request

{
   "accountCode":"TestMerchant",
   "referralType":"shopperemail",
   "action":"block",
   "referrals":[
      {
         "referralContainer":{
            "referral":"johnsmith@example.com"
         }
      },
      {
         "referralContainer":{
            "referral":"jsmith_example.com"
         }
      }
   ],
   "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>shopperemail</referralType>
            <referrals>
               <referralContainer>
                  <referral>johnsmith@example.com</referral>
               </referralContainer>
               <referralContainer>
                  <referral>jsmith_example.com</referral>
               </referralContainer>
            </referrals>
         </request>
      </uploadReferralsStructured>
   </soap:Body>
</soap:Envelope>

Response

{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "jsmith_example.com"
   ]
}
<?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>jsmith_example.com</ns0:string>
            </ns0:skippedReferrals>
         </ns0:response>
      </ns0:uploadReferralsStructuredResponse>
   </soap:Body>
</soap:Envelope>

Block referral IP addresses

The following example demonstrates how to block two IP addresses: 10.0.0.1/24 and 8.8.8.1/30. In this case, 10.0.0.1/24 is blocked and 8.8.8.1/30 is skipped (which is specified in the skippedReferrals section of the response).

Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint.

Request

{
   "accountCode":"TestMerchant",
   "referralType":"shopperip",
   "action":"block",
   "referrals":[
      {
         "referralContainer":{
            "referral":"10.0.0.1\/24"
         }
      },
      {
         "referralContainer":{
            "referral":"8.8.8.1\/30"
         }
      }
   ],
   "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>
               <referralContainer>
                  <referral>10.0.0.1/24</referral>
               </referralContainer>
               <referralContainer>
                  <referral>8.8.8.1/30</referral>
               </referralContainer>
            </referrals>
         </request>
      </uploadReferralsStructured>
   </soap:Body>
</soap:Envelope>

Response

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

<?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.8.1/30</ns0:string>
            </ns0:skippedReferrals>
         </ns0:response>
      </ns0:uploadReferralsStructuredResponse>
   </soap:Body>
</soap:Envelope>

Block referral addresses

The following example demonstrates how to block two referrals based on their addresses. In this case, the first address is blocked and the second address is skipped (which is specified in the skippedReferrals section of the response).

Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint.

Request

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

Response

{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "West lane,2,London,1100AB,England,UK"
   ]
}

<?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>West lane,2,London,1100AB,England,UK</ns0:string>
            </ns0:skippedReferrals>
         </ns0:response>
      </ns0:uploadReferralsStructuredResponse>
   </soap:Body>
</soap:Envelope>

Block referrals by the payment reference

The following example demonstrates how to block some of the payment details based on the payment's pspReference. In the code below, the card number and shopper email should be blocked for the payment with pspReference equal to 9900000000000001, and the shopper IP should be blocked for the pspReference equal to 9900000000000002.

The response contains the skippedReferrals section, which informs that the first pspReference is skipped (9900000000000001,[cardnumber,shopperemail]).

Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint.

Request

{
   "accountCode":"TestMerchant",
   "referralType":"paymentreference",
   "action":"block",
   "paymentReferenceReferrals":[
      {
         "paymentReferenceReferral":{
            "pspReference":"9900000000000001",
            "referralTypes":[
               "cardnumber",
               "shopperemail"
            ]
         }
      },
      {
         "paymentReferenceReferral":{
            "pspReference":"9900000000000002",
            "referralTypes":[
               "shopperip"
            ]
         }
      }
   ]
}
<?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>
            <referralType>paymentreference</referralType>
            <paymentReferenceReferrals>
               <paymentReferenceReferral>
                  <pspReference>9900000000000001</pspReference>
                  <referralTypes>
                     <referralType>cardnumber</referralType>
                     <referralType>shopperemail</referralType>
                  </referralTypes>
               </paymentReferenceReferral>
               <paymentReferenceReferral>
                  <pspReference>9900000000000002</pspReference>
                  <referralTypes>
                     <referralType>shopperip</referralType>
                  </referralTypes>
               </paymentReferenceReferral>
            </paymentReferenceReferrals>
         </request>
      </uploadReferralsStructured>
   </soap:Body>
</soap:Envelope>

Response

{
   "referralServiceResult":{
      "success":true
   },
   "skippedReferrals":[
      "9900000000000001,[cardnumber,shopperemail]"
   ]
}
<?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>9900000000000001,[cardnumber,shopperemail]</ns0:string>
            </ns0:skippedReferrals>
         </ns0:response>
      </ns0:uploadReferralsStructuredResponse>
   </soap:Body>
</soap:Envelope>