Contact module

DocsCurrent

Last updated: Apr 7th, 4:18pm

Overview

The Contact Module helps buyers view and modify the email and phone number shared with merchants for a given order. It offers greater flexibility and control to buyers, particularly for gift orders where buyers need to specify alternative contact details.

Key features

Merchant-controlled contact display: Merchants choose if shoppers can see and edit their contact information during PayPal checkout.

Add contact information: Buyers can add new email addresses and phone numbers during checkout.

Select existing contact information: Buyers can select from a list of previously added email addresses and phone numbers.

Validation: Input validation ensures the provided email addresses and phone numbers follow appropriate formats.

Merchant-provided data: If the merchant supplies contact information, the information is displayed during the transaction. The merchant can decide whether the information is editable or not.

Profile contact integration: Shows the primary email and phone number from the buyer’s PayPal account by default.

Localized support: Buyers from different countries can add and validate contact information according to regional standards.

Buyer benefits

Personalization: Allows buyers to customize contact details for each transaction.

Convenience: Buyers don’t need to update contact information outside the payment flow.

Merchant benefits

Order fulfillment: Provides merchants with precise and complete contact details for seamless communication.

Accuracy: Ensures merchants receive accurate and current contact information.

Availability

The Contact Module is currently available in the US only.

Contact preferences

Merchants can set a contact preference to control what contact information buyers see when reviewing PayPal checkout.

PayPal supports three contact preference options:

NO_CONTACT_INFO: Default. Buyers do not see any contact information during checkout.

UPDATE_CONTACT_INFO: Buyers can see and edit their contact information.

RETAIN_CONTACT_INFO: Buyers can see their contact information, but can't edit them.

Manage buyer contact information

The Orders API manages contact information as part of the purchase_units[].shipping object in the email_address field and the phone_number object when an order is created.

Use buyer contact information from PayPal or the merchant site.

Upstream presentment: Buyers begin PayPal checkout by selecting the button from the cart or product page. Buyers don't enter information on the merchant site.

Checkout presentment: Buyers select the PayPal button when checking out on the merchant site after entering information. Merchants can pass buyer information to pre-fill fields at PayPal checkout.

Hide contact information

This setting is default.

If a merchant prefers not to display contact information to buyers during checkout, the merchant can use NO_CONTACT_INFO, or omit payment_source.paypal.experience_context.contact_preference.

Even if the merchant provides contact information, PayPal will not display it to buyers if NO_CONTACT_INFO is enabled.

Display editable contact information

If a merchant wants to show editable contact information to buyers, the merchant uses UPDATE_CONTACT_INFO. After a buyer updates their details, the merchant sees the latest email and phone number. The merchant should use the latest information to communicate with their buyers.

UPDATE_CONTACT_INFO allows the buyer to edit both their phone number and email in PayPal. Individual edit preferences are not supported.

In the collapsed view, the Contact Module shows the primary email and phone number from the buyer's profile. If the merchant does not provide information, the PayPal profile information is used by default.

When expanded, the Contact Module displays:

A dropdown to select from up to 5 previously used contact entries displayed in order of most recent use.

Options to add new email addresses or phone numbers.

Inline validation for newly added contact information.

Buyer adds email

Buyer,flow,for,adding,email,during,PayPal,checkout.

Buyer selects phone number

Buyer,flow,for,selecting,phone,number,during,PayPal,checkout.

Pass UPDATE_CONTACT_INFO

In your call to the Orders API, set payment_source.paypal.experience_context.contact_preference to UPDATE_CONTACT_INFO.

If you pass information in purchase_units[].shipping.email_address and purchase_units[].shipping.phone_number, you see these values in the create order response and the get order API call after the buyer approves the transaction. This information is displayed and editable to the buyer during PayPal checkout.

Create order with UPDATE_CONTACT_INFO
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: REQUEST-ID' \
4-H 'Authorization: Bearer ACCESS-TOKEN' \
5-d '{
6  "intent": "CAPTURE",
7  "payment_source": {
8    "paypal": {
9      "experience_context": {
10        "shipping_preference": "SET_PROVIDED_ADDRESS",
11        "contact_preference": "UPDATE_CONTACT_INFO",
12        "user_action": "PAY_NOW",
13        "return_url": "https://example.com/returnUrl",
14        "cancel_url": "https://example.com/cancelUrl"
15      }
16    }
17  },
18  "purchase_units": [
19    {
20      "amount": {
21        "currency_code": "USD",
22        "value": "64.00"
23       },
24      "shipping": {
25         "name": {
26            "full_name": "Firstname Lastname"
27         },
28        "email_address": "customer@example.com",
29        "phone_number": {
30           "country_code": "1",
31           "national_number": "5555555555"
32         },
33        "address": {
34          "address_line_1": "123 Main St.",
35          "admin_area_2": "Anytown",
36          "admin_area_1": "CA",
37          "postal_code": "12345",
38          "country_code": "US"
39        }
40      }
41    }
42  ]
43}'

Retrieve buyer's latest contact information

When buyers edit their contact details and check out with PayPal, call the Orders API to retrieve the latest contact information. This ensures you have access to the buyer's details as captured during PayPal checkout.

The sample response shows updated buyer details.

Show order details
Response

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID \
2-H 'Authorization: Bearer ACCESS-TOKEN'

Display read-only contact information

If a merchant wants to show contact information to buyers without allowing them to edit it, merchants use the RETAIN_CONTACT_INFO setting.

The merchant collects the buyer's email address and phone number on their website and includes them in the create order call using purchase_units[].shipping.email_address and purchase_units[].shipping.phone_number.

Set payment_source.paypal.experience_context.contact_preference to RETAIN_CONTACT_INFO in your Orders API request.

If the merchant provides only one contact field (email or phone), PayPal assumes only that method is required to communicate with the buyer, and displays the one value.

If RETAIN_CONTACT_INFO is set without passing any contact details, PayPal defaults to NO_CONTACT_INFO and hides all contact information from the buyer.

Buyers can view the contact information provided but cannot edit it. Only the values passed in the Orders API call are displayed.

Create order with RETAIN_CONTACT_INFO
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: REQUEST-ID' \
4-H 'Authorization: Bearer ACCESS-TOKEN' \
5-d '{
6  "intent": "CAPTURE",
7  "payment_source": {
8    "paypal": {
9      "experience_context": {
10        "shipping_preference": "SET_PROVIDED_ADDRESS",
11        "contact_preference": "RETAIN_CONTACT_INFO",
12        "user_action": "PAY_NOW",
13        "return_url": "https://example.com/returnUrl",
14        "cancel_url": "https://example.com/cancelUrl"
15      }
16    }
17  },
18  "purchase_units": [
19    {
20      "amount": {
21        "currency_code": "USD",
22        "value": "64.00"
23       },
24      "shipping": {
25         "name": {
26            "full_name": "Firstname Lastname"
27         },
28        "email_address": "payer@example.com",
29        "phone_number": {
30           "country_code": "1",
31           "national_number": "5555555555"
32         },
33        "type": "SHIPPING",
34        "address": {
35          "address_line_1": "123 Main St.",
36          "admin_area_2": "Anytown",
37          "admin_area_1": "CA",
38          "postal_code": "12345",
39          "country_code": "US"
40        }
41      }
42    }
43  ]
44}'