Risk-team icon

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.

Requests to the Referrals API are rate limited to 10 referrals per request, and 10 requests per minute.

Endpoints

SOAP

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

The data schema for corresponding SOAP objects is available at:

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

POST https://ca-test.adyen.com/ca/services/ReferralCAService/uploadReferralsStructured

After you are ready to go live, you should switch to either generic or custom live endpoints. For more information, refer to Live endpoints.

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 -white_check_mark- The name of the company account for which you want to upload referrals.
action String -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- The PSP reference of the payment for which you want to upload referrals.
referralTypes Array of String -white_check_mark- 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 -white_check_mark- The name of the street.
houseNumberOrName String -white_check_mark- The number or name of the house.
city String -white_check_mark- The name of the city.
postalCode String -white_check_mark- 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 -white_check_mark- The two-character ISO-3166-1 alpha-2 country code. For example, US.
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.