{"title":"Automate submitting referrals","category":"default","creationDate":1779620071,"content":"<p>You can use our <a href=\"\/risk-management\/automate-submitting-referrals\/referrals-api-reference\">Referrals API<\/a> to automate uploading lists of referrals and referral details to <a href=\"\/risk-management\/configure-standard-risk-rules\/referral-rules\">block and trust lists<\/a>.<\/p>\n<p>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 <code>accountCode<\/code>, but the referral will be applied on the company account.<\/p>\n<p>Using the Referrals API, you can upload referral details such as:<\/p>\n<ul>\n<li>Email addresses<\/li>\n<li>IP addresses<\/li>\n<li>Billing addresses<\/li>\n<li>Details connected to a payment (PSP) reference<\/li>\n<\/ul>\n<p>You cannot upload <a href=\"\/risk-management\/configure-manual-risk\/configure-custom-risk-rules#create-custom-list-comparison\">custom lists<\/a> using the Referrals API.<\/p>\n<p>For each request with referral details, you can set the <code>action<\/code> to:<\/p>\n<ul>\n<li><strong>block<\/strong> - Block payments associated with this referral detail.<\/li>\n<li><strong>trust<\/strong> - Allow payments associated with this referral detail.<\/li>\n<li><strong>delete<\/strong> - Remove these referral details from your account.<\/li>\n<\/ul>\n<div class=\"notices blue\">\n<p>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 <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/p>\n<\/div>\n<h2>Requirements<\/h2>\n<h3>Required roles<\/h3>\n<p>To make requests using the Referrals API, your <a href=\"\/development-resources\/api-credentials\">API credential<\/a> needs the following roles:<\/p>\n<ul>\n<li>API referral lists management<\/li>\n<\/ul>\n<p>To check if you have this role:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API Credentials<\/strong>.<\/li>\n<li>Select the webservice that you want to use to make the request.<\/li>\n<li>Under <strong>Permissions<\/strong> &gt; <strong>Roles<\/strong>, search for <strong>API referral lists management<\/strong>.<\/li>\n<\/ol>\n<p>If you do not have this role, contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a>.<\/p>\n<h3>Enable block and trust lists and configure risk scores<\/h3>\n<p>To make sure that the referrals trigger:<\/p>\n<ul>\n<li>Enable the block and trust lists that you want to use in your risk profile configuration.<\/li>\n<li>Configure a risk score for <strong>block<\/strong>, and (if applicable) <strong>trust<\/strong> in case a payment contains a property that matches an item in the list.<\/li>\n<\/ul>\n<h2 id=\"block-referral-emails\">Add email address referrals<\/h2>\n<p>The following example demonstrates how to add items to the email address block list: <strong>johnsmith@example.com<\/strong> and <strong>jsmith_example.com<\/strong>.<\/p>\n<p>In this case,\u00a0<strong>johnsmith@example.com<\/strong> is added and\u00a0<strong>jsmith_example.com<\/strong> is skipped because the input is not valid.<\/p>\n<p>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 <code>skippedReferrals<\/code> section of the response.<\/p>\n<p>Submit this request to the <a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured<\/a> endpoint. For more details, see <a href=\"\/risk-management\/automate-submitting-referrals\/referrals-api-reference\">Referrals API reference<\/a>.<\/p>\n<h3 id=\"request\">Example request to block email addresses<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'352382451'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"accountCode\\\":\\\"YOUR_COMPANY_ACCOUNT\\\",\\n   \\\"referralType\\\":\\\"shopperemail\\\",\\n   \\\"action\\\":\\\"block\\\",\\n   \\\"referrals\\\":[\\n      {\\n         \\\"referralContainer\\\":{\\n            \\\"referral\\\":\\\"johnsmith@example.com\\\"\\n         }\\n      },\\n      {\\n         \\\"referralContainer\\\":{\\n            \\\"referral\\\":\\\"jsmith_example.com\\\"\\n         }\\n      }\\n   ],\\n   \\\"reason\\\":\\\"Test behavior\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3 id=\"response\">Response<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'738381688'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"referralServiceResult\\\":{\\n      \\\"success\\\":true\\n   },\\n   \\\"skippedReferrals\\\":[\\n      \\\"jsmith_example.com\\\"\\n   ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2 id=\"block-referral-ip-addresses\">Add IP address referrals<\/h2>\n<p>The following example demonstrates how to how to add items to the IP address block list:\u00a0<strong>10.0.0.1\/24<\/strong> and <strong>8.8.8.1\/30<\/strong>.<\/p>\n<p>In this case, <strong>10.0.0.1\/24<\/strong>\u00a0is added and <strong>8.8.8.1\/30<\/strong>\u00a0is skipped.<\/p>\n<p>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 <code>skippedReferrals<\/code> section of the response.<\/p>\n<p>Submit this request to the <a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured<\/a> endpoint. For more details, see <a href=\"\/risk-management\/automate-submitting-referrals\/referrals-api-reference\">Referrals API reference<\/a>.<\/p>\n<h3 id=\"request-1\">Example request to block IP addresses<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'442627636'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"accountCode\\\":\\\"YOUR_COMPANY_ACCOUNT\\\",\\n   \\\"referralType\\\":\\\"shopperip\\\",\\n   \\\"action\\\":\\\"block\\\",\\n   \\\"referrals\\\":[\\n      {\\n         \\\"referralContainer\\\":{\\n            \\\"referral\\\":\\\"10.0.0.1\\\\\\\/24\\\"\\n         }\\n      },\\n      {\\n         \\\"referralContainer\\\":{\\n            \\\"referral\\\":\\\"8.8.8.1\\\\\\\/30\\\"\\n         }\\n      }\\n   ],\\n   \\\"reason\\\":\\\"Test behavior\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3 id=\"response-1\">Response<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'343446206'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"referralServiceResult\\\":{\\n      \\\"success\\\":true\\n   },\\n   \\\"skippedReferrals\\\":[\\n      \\\"8.8.8.1\\\\\\\/30\\\"\\n   ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2 id=\"block-referral-addresses\">Add shopper address referrals<\/h2>\n<p>The following example demonstrates how to add items to the shopper address block list.<\/p>\n<p>In this case, the first address is added to the block list, and the second address is skipped\u00a0because the <code>countryCode<\/code> input is not valid.<\/p>\n<p>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 <code>skippedReferrals<\/code> section of the response.<\/p>\n<p>Submit this request to the <a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured<\/a> endpoint. For more details, see <a href=\"\/risk-management\/automate-submitting-referrals\/referrals-api-reference\">Referrals API reference<\/a>.<\/p>\n<h3 id=\"request-2\">Example request to block shopper addresses<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'602011152'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"accountCode\\\":\\\"YOUR_COMPANY_ACCOUNT\\\",\\n   \\\"referralType\\\":\\\"shopperaddress\\\",\\n   \\\"action\\\":\\\"block\\\",\\n   \\\"addressReferrals\\\":[\\n      {\\n         \\\"shopperAddress\\\":{\\n            \\\"street\\\":\\\"Main St\\\",\\n            \\\"houseNumberOrName\\\":\\\"2\\\",\\n            \\\"city\\\":\\\"Amsterdam\\\",\\n            \\\"postalCode\\\":\\\"1000AA\\\",\\n            \\\"stateOrProvince\\\":\\\"Noord-Holland\\\",\\n            \\\"countryCode\\\":\\\"NL\\\"\\n         }\\n      },\\n      {\\n         \\\"shopperAddress\\\":{\\n            \\\"street\\\":\\\"West lane\\\",\\n            \\\"houseNumberOrName\\\":\\\"2\\\",\\n            \\\"city\\\":\\\"London\\\",\\n            \\\"postalCode\\\":\\\"1100AB\\\",\\n            \\\"stateOrProvince\\\":\\\"England\\\",\\n            \\\"countryCode\\\":\\\"UK\\\"\\n         }\\n      }\\n   ],\\n   \\\"reason\\\":\\\"Test behavior\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3 id=\"response-2\">Response<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'832481686'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"referralServiceResult\\\":{\\n      \\\"success\\\":true\\n   },\\n   \\\"skippedReferrals\\\":[\\n      \\\"West lane,2,London,1100AB,England,UK\\\"\\n   ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2 id=\"block-referrals-by-the-payment-reference\">Add referrals based on the payment reference<\/h2>\n<p>The following example demonstrates how to add some of the payment details to the respective block lists based on the payment's <code>pspReference<\/code>. In the example below, the card number and shopper email should be blocked for the payment with <code>pspReference<\/code> equal to <strong>9900000000000001<\/strong>, and the shopper IP should be blocked for the <code>pspReference<\/code> equal to <strong>9900000000000002<\/strong>.<\/p>\n<p>You can see which referrals are skipped in the <code>skippedReferrals<\/code> section of the response. In this case, the first <code>pspReference<\/code> is skipped. (<strong>9900000000000001,[cardnumber,shopperemail]<\/strong>).<\/p>\n<p>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 <code>pspReference<\/code>.<\/p>\n<p>Submit this request to the <a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured<\/a> endpoint. For more details, see <a href=\"\/risk-management\/automate-submitting-referrals\/referrals-api-reference\">Referrals API reference<\/a>.<\/p>\n<h3 id=\"request-3\">Example request to block payment details<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'1151446606'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"accountCode\\\":\\\"YOUR_COMPANY_ACCOUNT\\\",\\n   \\\"referralType\\\":\\\"paymentreference\\\",\\n   \\\"action\\\":\\\"block\\\",\\n   \\\"paymentReferenceReferrals\\\":[\\n      {\\n         \\\"paymentReferenceReferral\\\":{\\n            \\\"pspReference\\\":\\\"9900000000000001\\\",\\n            \\\"referralTypes\\\":[\\n               \\\"cardnumber\\\",\\n               \\\"shopperemail\\\"\\n            ]\\n         }\\n      },\\n      {\\n         \\\"paymentReferenceReferral\\\":{\\n            \\\"pspReference\\\":\\\"9900000000000002\\\",\\n            \\\"referralTypes\\\":[\\n               \\\"shopperip\\\"\\n            ]\\n         }\\n      }\\n   ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3 id=\"response-3\">Response<\/h3>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"''\" :id=\"'519562439'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n   \\\"referralServiceResult\\\":{\\n      \\\"success\\\":true\\n   },\\n   \\\"skippedReferrals\\\":[\\n      \\\"9900000000000001,[cardnumber,shopperemail]\\\"\\n   ]\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>","url":"https:\/\/docs.adyen.com\/risk-management\/automate-submitting-referrals","articleFields":{"id":"25148478","type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"08-09-2020 22:03"},"algolia":{"url":"https:\/\/docs.adyen.com\/risk-management\/automate-submitting-referrals","title":"Automate submitting referrals","content":"You can use our Referrals API to automate uploading lists of referrals and referral details to block and trust lists.\nBy 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.\nUsing the Referrals API, you can upload referral details such as:\n\nEmail addresses\nIP addresses\nBilling addresses\nDetails connected to a payment (PSP) reference\n\nYou cannot upload custom lists using the Referrals API.\nFor each request with referral details, you can set the action to:\n\nblock - Block payments associated with this referral detail.\ntrust - Allow payments associated with this referral detail.\ndelete - Remove these referral details from your account.\n\n\nIf 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.\n\nRequirements\nRequired roles\nTo make requests using the Referrals API, your API credential needs the following roles:\n\nAPI referral lists management\n\nTo check if you have this role:\n\nLog in to your Customer Area.\nGo to Developers &gt; API Credentials.\nSelect the webservice that you want to use to make the request.\nUnder Permissions &gt; Roles, search for API referral lists management.\n\nIf you do not have this role, contact our Support Team.\nEnable block and trust lists and configure risk scores\nTo make sure that the referrals trigger:\n\nEnable the block and trust lists that you want to use in your risk profile configuration.\nConfigure a risk score for block, and (if applicable) trust in case a payment contains a property that matches an item in the list.\n\nAdd email address referrals\nThe following example demonstrates how to add items to the email address block list: johnsmith@example.com and jsmith_example.com.\nIn this case,\u00a0johnsmith@example.com is added and\u00a0jsmith_example.com is skipped because the input is not valid.\nA 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.\nSubmit this request to the https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured endpoint. For more details, see Referrals API reference.\nExample request to block email addresses\n\n    \n\nResponse\n\n    \n\nAdd IP address referrals\nThe following example demonstrates how to how to add items to the IP address block list:\u00a010.0.0.1\/24 and 8.8.8.1\/30.\nIn this case, 10.0.0.1\/24\u00a0is added and 8.8.8.1\/30\u00a0is skipped.\nA 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.\nSubmit this request to the https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured endpoint. For more details, see Referrals API reference.\nExample request to block IP addresses\n\n    \n\nResponse\n\n    \n\nAdd shopper address referrals\nThe following example demonstrates how to add items to the shopper address block list.\nIn this case, the first address is added to the block list, and the second address is skipped\u00a0because the countryCode input is not valid.\nA 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.\nSubmit this request to the https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured endpoint. For more details, see Referrals API reference.\nExample request to block shopper addresses\n\n    \n\nResponse\n\n    \n\nAdd referrals based on the payment reference\nThe 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.\nYou can see which referrals are skipped in the skippedReferrals section of the response. In this case, the first pspReference is skipped. (9900000000000001,[cardnumber,shopperemail]).\nA 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.\nSubmit this request to the https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured endpoint. For more details, see Referrals API reference.\nExample request to block payment details\n\n    \n\nResponse\n\n    \n","type":"page","locale":"en","boost":18,"hierarchy":{"lvl0":"Home","lvl1":"Risk management","lvl2":"Automate submitting referrals"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/risk-management","lvl2":"\/risk-management\/automate-submitting-referrals"},"levels":3,"category":"Risk Management","category_color":"green","tags":["Automate","submitting","referrals"]},"articleFiles":{"343446206.json":"<p alt=\"\">343446206.json<\/p>","352382451.json":"<p alt=\"\">352382451.json<\/p>","442627636.json":"<p alt=\"\">442627636.json<\/p>","519562439.json":"<p alt=\"\">519562439.json<\/p>","602011152.json":"<p alt=\"\">602011152.json<\/p>","738381688.json":"<p alt=\"\">738381688.json<\/p>","832481686.json":"<p alt=\"\">832481686.json<\/p>","1151446606.json":"<p alt=\"\">1151446606.json<\/p>"}}