{"title":"Referrals API reference","category":"default","creationDate":1779533780,"content":"<p>To communicate with our API, you submit HTTP requests to applicable endpoints.<\/p>\n<p>These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the\u00a0Adyen payments platform.<\/p>\n<p>This document lists all endpoints available for you to integrate with the test platform and\u00a0run QA checks.<\/p>\n<div class=\"notices yellow\">\n<p>Requests to the Referrals API are rate limited to 10 referrals per request, and 10 requests per minute.<\/p>\n<\/div>\n<h2 id=\"endpoints\">Endpoints<\/h2>\n<h3 id=\"soap\">SOAP<\/h3>\n<p>For the\u00a0SOAP\u00a0messaging protocol, all test payment requests must be posted to the following endpoint:<\/p>\n<ul>\n<li><a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService<\/a><\/li>\n<\/ul>\n<p>The data schema for corresponding SOAP objects is available at:<\/p>\n<ul>\n<li><a href=\"https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService?wsdl\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">https:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService?wsdl<\/a><\/li>\n<\/ul>\n<h3 id=\"json-and-form\">JSON and FORM<\/h3>\n<p>This is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an HTTP POST URL).<\/p>\n<table>\n<thead>\n<tr>\n<th><\/th>\n<th><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>POST<\/td>\n<td><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><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div class=\"sc-notice note\"><div>\n<p>After you are ready to go live, you should switch to either generic or custom\u00a0live endpoints. For more information, refer to <a href=\"\/development-resources\/live-endpoints\">Live endpoints<\/a>.<\/p>\n<\/div><\/div>\n<h2>Create upload referrals request<\/h2>\n<p>Upload one or more items to a block or trust list, or delete items from a list.<\/p>\n<p>For the request to be successful:<\/p>\n<ul>\n<li>Make sure that the referral values match the <code>referralType<\/code> in the request.<\/li>\n<li>You can upload one type of referral per request, and one type of action (<strong>block<\/strong>, <strong>trust<\/strong> or <strong>delete<\/strong>).<\/li>\n<li>Depending on the type of referral you upload, include the correct object to specify the referral details: <code>referralContainer<\/code>, <code>addressReferrals<\/code>, or <code>paymentReferenceReferrals<\/code>.<\/li>\n<\/ul>\n<p>For example requests, see <a href=\"\/risk-management\/automate-submitting-referrals\">Automate submitting referrals<\/a>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Type<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>accountCode<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The name of the company account for which you want to upload referrals.<\/td>\n<\/tr>\n<tr>\n<td><code>action<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The action type. Possible values:<\/p><ul><li markdown=\"1\">block<\/li><li markdown=\"1\">trust<\/li><li markdown=\"1\">delete<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td><code>addressReferrals<\/code><\/td>\n<td>Array of <a href=\"#shopperaddress\">shopperAddress<\/a><\/td>\n<td style=\"text-align: center;\"><\/td>\n<td>Required when you want to manage a shopper address referral list. <br>This field replaces <code>referralContainer<\/code>, and must be used in combination with the referral type <strong>shopperaddress<\/strong>.<br>Use this object to add addresses to the referral list.<\/td>\n<\/tr>\n<tr>\n<td><code>paymentReferenceReferrals<\/code><\/td>\n<td>Array of <a href=\"#paymentreferencereferral\">paymentReferenceReferral<\/a><\/td>\n<td style=\"text-align: center;\"><\/td>\n<td>Required when you want to upload referrals connected to a payment reference. <br>This field replaces <code>referralContainer<\/code>, and must be used in combination with the referral type <strong>paymentreference<\/strong>.<br>Use this object to extract a set of specified referral types from the payment based on the provided PSP reference.<\/td>\n<\/tr>\n<tr>\n<td><code>reason<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>Reason of the request. <br>For the referral type <code>paymentreference<\/code>, the <code>reason<\/code> field is automatically generated to include the PSP reference, and you cannot specify a free-text reason.<\/td>\n<\/tr>\n<tr>\n<td><code>referralType<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The type of a referral included in the request.<br>Possible values: <ul><li markdown=\"1\">cardnumber<\/li><li markdown=\"1\">emaildomain<\/li><li markdown=\"1\">ibannumber<\/li><li markdown=\"1\">ipcountry<\/li><li markdown=\"1\">issuerreference<\/li><li markdown=\"1\">issuingcountry<\/li><li markdown=\"1\">paymentreference<br>When you use this referral type, you must include <a href=\"#paymentreferencereferral\">paymentReferenceReferral<\/a> details in the request.<\/li><li markdown=\"1\">persistentcookie<\/li><li markdown=\"1\">phonenumber<\/li><li markdown=\"1\">pmowner <br>This is the shopper name referral list.<\/li><li markdown=\"1\">shopperaddress <br>When you use this referral type, you must include <a href=\"#shopperaddress\">shopperAddress<\/a> details in the request.<\/li><li markdown=\"1\">shopperemail<\/li><li markdown=\"1\">shopperip<\/li><li markdown=\"1\">shopperreference<\/li><li markdown=\"1\">txvariantshopperreference <br>This is the PayPal Payer ID referral list.<\/li><li markdown=\"1\">socialsecuritynumber<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td><code>referrals<\/code><\/td>\n<td>Array of <a href=\"#referralcontainer\">referralContainer<\/a><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A container object for the referral type you want to upload. Not applicable for <code>addressReferrals<\/code> or <code>paymentReferenceReferrals<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"referralcontainer\">referralContainer object<\/h2>\n<p>Use this object to specify which items to upload to a block or trust list, or remove items from a list.<\/p>\n<p>For the request to be successful:<\/p>\n<ul>\n<li>Use the <code>referralContainer<\/code> object.<\/li>\n<li>Make sure that the referral items that you submit match the <code>referralType<\/code> in the request.<\/li>\n<li>You can upload one type of referral per request, and one type of action (<strong>block<\/strong>, <strong>trust<\/strong> or <strong>delete<\/strong>).<\/li>\n<\/ul>\n<p>For example requests, see <a href=\"\/risk-management\/automate-submitting-referrals#block-referral-emails\">Add email address referrals<\/a> and <a href=\"\/risk-management\/automate-submitting-referrals#block-referral-ip-addresses\">Add IP address referrals<\/a>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Type<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>referral<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The value for the referral item that you want to upload. Must match the <code>referralType<\/code>. <br>Examples:<ul><li markdown=\"1\"><code>johnsmith@example.com<\/code><br>(for referrals of type <strong>shopperemail<\/strong>)<\/li><li markdown=\"1\"><code>8.8.8.8<\/code><br>(for referrals of type <strong>shopperip<\/strong>)<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"paymentreferencereferral\">paymentReferenceReferrals object<\/h2>\n<p>Use this object to specify which referrals to upload to or remove from the applicable block and trust list based on a provided PSP reference of a payment.<\/p>\n<p>For the request to be successful:<\/p>\n<ul>\n<li>Use the <code>paymentReferenceReferrals<\/code> object instead of <code>referralContainer<\/code>.<\/li>\n<li>Make sure that the referral types that you specify are present in the payment.<\/li>\n<\/ul>\n<p>For an example request, see <a href=\"\/risk-management\/automate-submitting-referrals#block-referrals-by-the-payment-reference\">Add referrals based on the payment reference<\/a>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Type<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>pspReference<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The PSP reference of the payment for which you want to upload referrals.<\/td>\n<\/tr>\n<tr>\n<td><code>referralTypes<\/code><\/td>\n<td>Array of String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The referral types that you want to upload to the applicable block and trust list. <br><note>The payment property must be included in the payment. If the payment does not include the property, the request will fail. <\/note><br>Possible values: <ul><li markdown=\"1\">cardnumber<\/li><li markdown=\"1\">ibannumber<\/li><li markdown=\"1\">pmowner <br>This is the shopper name referral list.<\/li><li markdown=\"1\">shopperemail<\/li><li markdown=\"1\">shopperip<\/li><li markdown=\"1\">shopperreference<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"shopperaddress\">shopperAddress object<\/h2>\n<p>Use this object to specify one or more shopper addresses to upload to the shopper address block or trust list, or remove addresses from the list.<\/p>\n<p>For the request to be successful:<\/p>\n<ul>\n<li>Use the <code>addressReferrals<\/code> object instead of <code>referralContainer<\/code>.<\/li>\n<\/ul>\n<p>For an example request, see <a href=\"\/risk-management\/automate-submitting-referrals#block-referral-addresses\">Add shopper address referrals<\/a>.<\/p>\n<table>\n<thead>\n<tr>\n<th>Field<\/th>\n<th>Type<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>street<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The name of the street.<\/td>\n<\/tr>\n<tr>\n<td><code>houseNumberOrName<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The number or name of the house.<\/td>\n<\/tr>\n<tr>\n<td><code>city<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The name of the city.<\/td>\n<\/tr>\n<tr>\n<td><code>postalCode<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries\/regions.<\/td>\n<\/tr>\n<tr>\n<td><code>countryCode<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td>The country code. <br>Format: the two-letter <a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_3166-1_alpha-2\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">ISO-3166-1 alpha-2<\/a> country code. Exception: <strong>QZ<\/strong> (Kosovo).<\/td>\n<\/tr>\n<tr>\n<td><code>stateOrProvince<\/code><\/td>\n<td>String<\/td>\n<td style=\"text-align: center;\"><\/td>\n<td>Required for the US and Canada. The two-character ISO 3166-2 state or province code. For example, <strong>CA<\/strong> in the US or <strong>ON<\/strong> in Canada.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>","url":"https:\/\/docs.adyen.com\/risk-management\/automate-submitting-referrals\/referrals-api-reference","articleFields":{"id":"27528722","type":"page","_expandable":{"operations":""},"status":"current","hide_subnavigation":"true","last_edit_on":"25-08-2020 14:03"},"algolia":{"url":"https:\/\/docs.adyen.com\/risk-management\/automate-submitting-referrals\/referrals-api-reference","title":"Referrals API reference","content":"To communicate with our API, you submit HTTP requests to applicable endpoints.\nThese endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the\u00a0Adyen payments platform.\nThis document lists all endpoints available for you to integrate with the test platform and\u00a0run QA checks.\n\nRequests to the Referrals API are rate limited to 10 referrals per request, and 10 requests per minute.\n\nEndpoints\nSOAP\nFor the\u00a0SOAP\u00a0messaging protocol, all test payment requests must be posted to the following endpoint:\n\nhttps:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\n\nThe data schema for corresponding SOAP objects is available at:\n\nhttps:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService?wsdl\n\nJSON and FORM\nThis is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an HTTP POST URL).\n\n\n\n\n\n\n\n\n\nPOST\nhttps:\/\/ca-test.adyen.com\/ca\/services\/ReferralCAService\/uploadReferralsStructured\n\n\n\n\nAfter you are ready to go live, you should switch to either generic or custom\u00a0live endpoints. For more information, refer to Live endpoints.\n\nCreate upload referrals request\nUpload one or more items to a block or trust list, or delete items from a list.\nFor the request to be successful:\n\nMake sure that the referral values match the referralType in the request.\nYou can upload one type of referral per request, and one type of action (block, trust or delete).\nDepending on the type of referral you upload, include the correct object to specify the referral details: referralContainer, addressReferrals, or paymentReferenceReferrals.\n\nFor example requests, see Automate submitting referrals.\n\n\n\nField\nType\nRequired\nDescription\n\n\n\n\naccountCode\nString\n\nThe name of the company account for which you want to upload referrals.\n\n\naction\nString\n\nThe action type. Possible values:blocktrustdelete\n\n\naddressReferrals\nArray of shopperAddress\n\nRequired when you want to manage a shopper address referral list. This field replaces referralContainer, and must be used in combination with the referral type shopperaddress.Use this object to add addresses to the referral list.\n\n\npaymentReferenceReferrals\nArray of paymentReferenceReferral\n\nRequired when you want to upload referrals connected to a payment reference. This field replaces referralContainer, and must be used in combination with the referral type paymentreference.Use this object to extract a set of specified referral types from the payment based on the provided PSP reference.\n\n\nreason\nString\n\nReason of the request. For the referral type paymentreference, the reason field is automatically generated to include the PSP reference, and you cannot specify a free-text reason.\n\n\nreferralType\nString\n\nThe type of a referral included in the request.Possible values: cardnumberemaildomainibannumberipcountryissuerreferenceissuingcountrypaymentreferenceWhen you use this referral type, you must include paymentReferenceReferral details in the request.persistentcookiephonenumberpmowner This is the shopper name referral list.shopperaddress When you use this referral type, you must include shopperAddress details in the request.shopperemailshopperipshopperreferencetxvariantshopperreference This is the PayPal Payer ID referral list.socialsecuritynumber\n\n\nreferrals\nArray of referralContainer\n\nA container object for the referral type you want to upload. Not applicable for addressReferrals or paymentReferenceReferrals.\n\n\n\nreferralContainer object\nUse this object to specify which items to upload to a block or trust list, or remove items from a list.\nFor the request to be successful:\n\nUse the referralContainer object.\nMake sure that the referral items that you submit match the referralType in the request.\nYou can upload one type of referral per request, and one type of action (block, trust or delete).\n\nFor example requests, see Add email address referrals and Add IP address referrals.\n\n\n\nField\nType\nRequired\nDescription\n\n\n\n\nreferral\nString\n\nThe value for the referral item that you want to upload. Must match the referralType. Examples:johnsmith@example.com(for referrals of type shopperemail)8.8.8.8(for referrals of type shopperip)\n\n\n\npaymentReferenceReferrals object\nUse this object to specify which referrals to upload to or remove from the applicable block and trust list based on a provided PSP reference of a payment.\nFor the request to be successful:\n\nUse the paymentReferenceReferrals object instead of referralContainer.\nMake sure that the referral types that you specify are present in the payment.\n\nFor an example request, see Add referrals based on the payment reference.\n\n\n\nField\nType\nRequired\nDescription\n\n\n\n\npspReference\nString\n\nThe PSP reference of the payment for which you want to upload referrals.\n\n\nreferralTypes\nArray of String\n\nThe referral types that you want to upload to the applicable block and trust list. The payment property must be included in the payment. If the payment does not include the property, the request will fail. Possible values: cardnumberibannumberpmowner This is the shopper name referral list.shopperemailshopperipshopperreference\n\n\n\nshopperAddress object\nUse this object to specify one or more shopper addresses to upload to the shopper address block or trust list, or remove addresses from the list.\nFor the request to be successful:\n\nUse the addressReferrals object instead of referralContainer.\n\nFor an example request, see Add shopper address referrals.\n\n\n\nField\nType\nRequired\nDescription\n\n\n\n\nstreet\nString\n\nThe name of the street.\n\n\nhouseNumberOrName\nString\n\nThe number or name of the house.\n\n\ncity\nString\n\nThe name of the city.\n\n\npostalCode\nString\n\nA maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries\/regions.\n\n\ncountryCode\nString\n\nThe country code. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).\n\n\nstateOrProvince\nString\n\nRequired for the US and Canada. The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.\n\n\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Risk management","lvl2":"Automate submitting referrals","lvl3":"Referrals API reference"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/risk-management","lvl2":"https:\/\/docs.adyen.com\/risk-management\/automate-submitting-referrals","lvl3":"\/risk-management\/automate-submitting-referrals\/referrals-api-reference"},"levels":4,"category":"Risk Management","category_color":"green","tags":["Referrals","reference"]}}