Consumer Referrals Integration Guide

Last updated: Sept 14th, 12:34am

Partners can use the Consumer Referrals API to refer consumers to PayPal.

Internal applications can use this API to list and onboard the referred consumers.

Integration steps


1.	Required	Set up your development environment.
2.	Required	Create a consumer referral.

Set up your development environment

Before you can integrate Consumer Referrals, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Consumer Referrals.

Create consumer referral

A partner can create a consumer referral that contains the details for the referred consumer.

To create a consumer referral, you must include a paypal_account_properties object in the request. You can optionally include the following objects in the request:

Object	Description
`person_details`	The consumer's personal details.
`partner_specific_identifiers`	The IDs for the consumer in the partner's system.
`financial_instruments`	The financial instruments (FI) to add to the account.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/consumer-referrals \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5    "person_details": {
6        "names": [{
7            "given_name": "Niklas",
8            "surname": "Frangos"
9        }],
10        "phone_contacts": [{
11            "phone": {
12                "country_code": "43",
13                "national_number": "123456789"
14            },
15            "phone_type": "MOBILE"
16        }],
17        "addresses": [{
18            "address": {
19                "line1": "20/Wolfengasse 3",
20                "line2": "Fleischmarkt",
21                "city": "Vienna",
22                "country_code": "AT",
23                "postal_code": "A-1010"
24            },
25            "address_type": "HOME"
26        }],
27        "email_addresses": [{
28            "email_address": "consumer@example.com",
29            "primary": true,
30            "confirmed": false
31        }],
32        "locale": "en_US"
33    },
34    "paypal_account_properties": {
35        "account_country_code": "AT"
36    },
37    "financial_instruments": {
38        "bank_accounts": [{
39            "account_number": "AT045723300000057855",
40            "account_number_type": "IBAN",
41            "account_type": "CHECKING",
42            "currency_code": "EUR",
43            "country_code": "AT"
44        }],
45        "card_accounts": [{
46            "account_number": "4238017685994436",
47            "type": "VISA",
48            "expiry_month": "11",
49            "expiry_year": "2018",
50            "billing_address": {
51                "line1": "20/Wolfengasse 3",
52                "line2": "Fleischmarkt",
53                "city": "Vienna",
54                "country_code": "AT",
55                "postal_code": "A-1010"
56            }
57        }]
58    }
59}'

The response shows the details for the consumer referral:

1{
2    "referral_id": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48RmluYW5jaWFsSW5zdHJ1bWVudF9EZXByZW",
3    "person_details": {
4        "names": [{
5            "given_name": "Niklas",
6            "surname": "Frangos"
7        }],
8        "phone_contacts": [{
9            "phone": {
10                "country_code": "43",
11                "national_number": "123456789"
12            },
13            "phone_type": "MOBILE"
14        }],
15        "addresses": [{
16            "address": {
17                "line1": "20/Wolfengasse 3",
18                "line2": "Fleischmarkt",
19                "city": "Vienna",
20                "country_code": "AT",
21                "postal_code": "A-1010"
22            },
23            "address_type": "HOME"
24        }],
25        "email_addresses": [{
26            "email_address": "consumer@example.com",
27            "primary": true,
28            "confirmed": false
29        }]
30    },
31    "links": [{
32        "href": "https://www.paypal.com/consumeronboarding?referral_id=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48RmluYW5jaWFsSW5zdHJ1bWVudF9EZXByZW",
33        "rel": "action_url",
34        "method": "POST"
35    }]
36}

Continue to the Consumer Referrals API Reference.

Consumer Referrals Integration Guide

Integration steps

Set up your development environment

Create consumer referral

Next