Search

Are you looking for test card numbers?

Would you like to contact support?

Risk-management 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.

Indicators used in this section:

-white_check_mark- This field is mandatory and must be always present.
-x- This field is optional and may be required in specific scenarios.

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.

PaymentReferenceReferral

Field Type Required Description
pspReference String -white_check_mark- A PSP reference.
referralTypes Array of String -white_check_mark-

The type of a referral included in the request.

Allowed values:

  • shopperemail
  • shopperip
  • pmowner (this corresponds to the shopper name)
  • shopperaddress
  • shopperreference
  • txvariantshopperreference (this refers to the PayPal Payer ID referral)
  • emaildomain
  • socialsecuritynumber
  • phonenumber
  • cardnumber
  • ibannumber
  • issuerreference
  • issuingcountry
  • persistentcookie
  • ipcountry
  • paymentreference

If you are including shopperAddress, follow the specified structure for each referral (replace the referralContainer with addressReferrals).

ReferralContainer

A container for referrals.

Field Type Required Description
referral String  white_check_mark

Shopper referral.

Some examples of including referrals:

  • shopperIP - 8.8.8.8
  • shopperAddress - Fifth St.,5,Amsterdam,1000AA,Noord-Holland,NL
  • shopperemail - test@gmail.com

ReferralUploadExternalRequest

Field Type Required Description
accountCode String -white_check_mark- The merchant-level account code.
action String -white_check_mark-

The action type.

Allowed values:

  • block
  • trust
  • delete
addressReferrals Array of ShopperAddress -white_check_mark- The container for address referral fields. This field should be used for uploading address referrals in place of referralContainer.
paymentReferenceReferrals Array of PaymentReferenceReferral -white_check_mark-

This field extracts a set of specified referral types from the payment based on the provided PSP reference. Use this in place of referralContainer.

reason String -white_check_mark- Reason of the request. The reason field is automatically generated to include the PSP reference.
referralType String -white_check_mark-

The type of a referral included in the request.

Allowed values:

  • shopperemail
  • shopperip
  • pmowner (this corresponds to the shopper name)
  • shopperaddress
  • shopperreference
  • txvariantshopperreference (this refers to the PayPal Payer ID referral)
  • emaildomain
  • socialsecuritynumber
  • phonenumber
  • cardnumber
  • ibannumber
  • issuerreference
  • issuingcountry
  • persistentcookie
  • ipcountry

If you are including shopperAddress, follow the specified structure for each referral (replace the referralContainer with addressReferrals).

referrals  Array of ReferralContainer -white_check_mark-

A container for the referralContainer.

ShopperAddress

This object contains detailed information on a shopper address.

Field Type Required Description
city String -white_check_mark- The city name.
country String -white_check_mark- A valid value is an ISO 2-character country code.
houseNumberOrName String -white_check_mark- The house number or name.
postalCode String -white_check_mark- The postal code with a maximum of 5 characters for USA and maximum of 10 characters for any other country.
stateOrProvince String -white_check_mark-

For USA or Canada, a valid 2-character abbreviation for the state or province respectively. For other countries any abbreviation with maximum 3 characters for the state or province.

street String -white_check_mark- The street name.