Referrals API reference

To communicate with the Adyen API you should submit HTTP POST requests to corresponding endpoints. 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 Adyen payments platform.

This document lists all endpoints available for you to integrate with the test platform and run QA checks.

Endpoints

SOAP

For the SOAP messaging protocol, all test payment requests must be posted to the following endpoint:

• https://ca-test.adyen.com/ca/services/ReferralCAService

The data schema for corresponding SOAP objects is available at:

• https://ca-test.adyen.com/ca/services/ReferralCAService?wsdl

JSON and FORM

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).

Create upload referrals request

Upload one or more items to a block or trust list, or delete items from a list.

For the request to be successful:

• Make sure that the referral values match the referralType in the request.
• You can upload one type of referral per request, and one type of action (block, trust or delete).
• Depending on the type of referral you upload, include the correct object to specify the referral details: referralContainer, addressReferrals, or paymentReferenceReferrals.

For example requests, see Automate submitting referrals.

Field	Type	Required	Description
accountCode	String		The name of the company account for which you want to upload referrals.
action	String		The action type. Possible values: block trust delete
addressReferrals	Array of shopperAddress		Required 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.
paymentReferenceReferrals	Array of paymentReferenceReferral		Required 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.
reason	String		Reason 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.
referralType	String		The type of a referral included in the request. Possible values: cardnumber emaildomain ibannumber ipcountry issuerreference issuingcountry paymentreference When you use this referral type, you must include paymentReferenceReferral details in the request. persistentcookie phonenumber pmowner This is the shopper name referral list. shopperaddress When you use this referral type, you must include shopperAddress details in the request. shopperemail shopperip shopperreference txvariantshopperreference This is the PayPal Payer ID referral list. socialsecuritynumber
referrals	Array of referralContainer		A container object for the referral type you want to upload. Not applicable for addressReferrals or paymentReferenceReferrals.

referralContainer object

Use this object to specify which items to upload to a block or trust list, or remove items from a list.

For the request to be successful:

• Use the referralContainer object.
• Make sure that the referral items that you submit match the referralType in the request.
• You can upload one type of referral per request, and one type of action (block, trust or delete).

For example requests, see Add email address referrals and Add IP address referrals.

Field	Type	Required	Description
referral	String		The 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)

paymentReferenceReferrals object

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.

For the request to be successful:

• Use the paymentReferenceReferrals object instead of referralContainer.
• Make sure that the referral types that you specify are present in the payment.

For an example request, see Add referrals based on the payment reference.

Field	Type	Required	Description
pspReference	String		The PSP reference of the payment for which you want to upload referrals.
referralTypes	Array of String		The 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: cardnumber ibannumber pmowner This is the shopper name referral list. shopperemail shopperip shopperreference

shopperAddress object

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.

For the request to be successful:

• Use the addressReferrals object instead of referralContainer.

For an example request, see Add shopper address referrals.

Field	Type	Required	Description
street	String		The name of the street.
houseNumberOrName	String		The number or name of the house.
city	String		The name of the city.
postalCode	String		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.
countryCode	String		The country code. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
stateOrProvince	String		Required 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.