You can use our Referrals API to automate uploading lists of referrals and referral details to block and trust lists.
By default, block and trust lists are maintained per company account. This means you can provide a setting once and apply it to all merchant accounts under the company account. You can upload referrals using a merchant or a company accountCode, but the referral will be applied on the company account.
Using the Referrals API, you can upload referral details such as:
- Email addresses
- IP addresses
- Billing addresses
- Details connected to a payment (PSP) reference
You cannot upload custom lists using the Referrals API.
For each request with 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.
If the request contains referral values that are not valid, the referral will be skipped. Wildcards are not allowed when uploading using the Referrals API, but can be submitted through your Customer Area.
Requirements
Required roles
To make requests using the Referrals API, your API credential needs the following roles:
- API referral lists management
To check if you have this role:
- Log in to your Customer Area.
- Go to Developers > API Credentials.
- Select the webservice that you want to use to make the request.
- Under Permissions > Roles, search for API referral lists management.
If you do not have this role, contact our Support Team.
Enable block and trust lists and configure risk scores
To make sure that the referrals trigger:
- Enable the block and trust lists that you want to use in your risk profile configuration.
- Configure a risk score for block, and (if applicable) trust in case a payment contains a property that matches an item in the list.
Add email address referrals
The following example demonstrates how to add items to the email address block list: johnsmith@example.com and jsmith_example.com.
In this case, johnsmith@example.com is added and jsmith_example.com is skipped because the input is not valid.
A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the skippedReferrals section of the response.
Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint. For more details, see Referrals API reference.
Example request to block email addresses
Response
Add IP address referrals
The following example demonstrates how to how to add items to the IP address block list: 10.0.0.1/24 and 8.8.8.1/30.
In this case, 10.0.0.1/24 is added and 8.8.8.1/30 is skipped.
A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the skippedReferrals section of the response.
Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint. For more details, see Referrals API reference.
Example request to block IP addresses
Response
Add shopper address referrals
The following example demonstrates how to add items to the shopper address block list.
In this case, the first address is added to the block list, and the second address is skipped because the countryCode input is not valid.
A referral can be skipped if it is already present in the list, or if the input is not valid. You can see which referrals are skipped in the skippedReferrals section of the response.
Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint. For more details, see Referrals API reference.
Example request to block shopper addresses
Response
Add referrals based on the payment reference
The following example demonstrates how to add some of the payment details to the respective block lists based on the payment's pspReference. In the example 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.
You can see which referrals are skipped in the skippedReferrals section of the response. In this case, the first pspReference is skipped. (9900000000000001,[cardnumber,shopperemail]).
A referral can be skipped if it is already present in the list. The API request fails if the payment detail is not present in the payment with the provided pspReference.
Submit this request to the https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured endpoint. For more details, see Referrals API reference.