Search

Are you looking for test card numbers?

Would you like to contact support?

Automate submitting referrals

Our Referrals API lets you automate the uploading lists of referral details for Adyen risk rules. Upload referrals at a Company Account level.

You can upload lists of details such as:

  • Email
  • IP address
  • Mailing Address
  • Payment (PSP) Reference

For each list of referral details, you can set the action to:

  • block - Block payments associated with this referral detail.
  • trust - Allow payments associated with this referral detail.
  • delete - Remove these referral details from your account.

Any invalid entries from the submitted referral list will be skipped. Wildcards are not allowed when uploading using the Referrals API, but can be submitted through your Customer Area.

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>