Collect merchant data

CurrentDocs

Last updated: Oct 23rd, 11:37am

While building your integration, ensure that your application user interface requests all the required data from your merchants. If done correctly, you complete data collection as a one-time activity during your integration's building and testing phases, and it will not be part of the regular verification process for each merchant.

During data collection, use PayPal's webhooks and API responses to collect all the necessary data points for your merchants to start their transactions.

Monitor for webhooks

After you've created an account, PayPal starts the verification process and sends the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook to confirm that the verification process has begun on your merchant account.

1{
2  "description": "Account creation webhook.",
3  "title": "Create Account",
4  "runnable": true,
5  "operationId": "webhook.account_created",
6  "request": {
7    "path": "v1/notifications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
8    "method": "GET",
9    "headers": {
10      "Authorization": "Bearer ACCESS-TOKEN"
11    }
12  },
13  "response": {
14    "status": "200 OK",
15    "headers": {},
16    "body": {
17      "id": "WH-3AE50806EM5305732-8C457463XB353952R",
18      "event_version": "1.0",
19      "create_time": "2019-01-25T07:18:28.264Z",
20      "resource_type": "managed-accounts",
21      "event_type": "CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED",
22      "summary": "A managed account was created.",
23      "resource": {
24        "account_id": "7G4EPEEPEF74L",
25        "external_id": "external_id_353535335",
26        "links": [
27          {
28            "rel": "self",
29            "href": "https://api-m.paypal.com/v3/customer/managed-accounts/7G4EPEEPEF74L",
30            "method": "GET"
31          }
32        ]
33      },
34      "application_context": {
35        "event_context": "INFO"
36      },
37      "links": [
38        {
39          "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
40          "rel": "self",
41          "method": "GET"
42        },
43        {
44          "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R/resend",
45          "rel": "resend",
46          "method": "POST"
47        }
48      ]
49    }
50  }
51}

Interpret JSON data to identify missing information

After you receive the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook, use the GET call link provided in the details of the webhook notification response to make a GET call and analyze the results.

A successful GET request returns the HTTP 200 OK status code and a JSON response body that shows the merchant's information and the account's status, as shown in the following example:

Sample request
Sample response

1curl --location --request GET ‘{{host}}/v3/customer/managed-accounts/ACCOUNT-ID’ --header ‘Authorization: Bearer ACCESS-TOKEN’ --header 'Content-Type: application/json '

Structure of process_view

After performing the GET request, interpret the response to ensure all required data points are available. The first step in interpreting the response is to locate the process_view object. This object lists the verification processes that PayPal applies to your merchants, as illustrated in the diagram:

Name: The name of the data collection and verification checks, called processes, that PayPal runs on the merchant. The processes include verification policies such as MANAGED_PATH_KYC_VERIFICATION and collection policies such as MANAGED_PATH_KYC_COLLECTION. For more information on various countries' data collection policies, see Data elements for account creation.

Status: The result of the data collection and verification checks that PayPal runs on the merchant. The result may show "COMPLETED" when a collection or verification process is complete or "NEED_MORE_DATA" when verification is incomplete. It may also contain a "limits" block. If "capabilities" show any status other than "ACTIVE", certain "limits" may apply.

Capabilities: This array contains information about account abilities, current statuses, and associated payment processing limits.

required: Additional data points you may need to provide.

required_correction: Additional documents you may need to provide to complete verification.

Verify all data collection processes are in the "COMPLETED" status, indicating that all required data points are available.

Note: Name, Status, and Capabilities provide a detailed breakdown of processes. However, we don't recommend parsing them and interpreting them for UI responses to your merchants. Instead, combine "status" in the "capabilities" section with "limits" and any necessary information to inform your merchants about their verification status, active capabilities, remaining limits, and information they need to provide to complete verification.

Data collection processes

The names of the data collection processes vary by country.

United States

The data collection processes in the US are as follows:

Process	Description	Result
`MANAGED_PATH_KYC_COLLECTION`	This process tells you if the merchant has provided all required information for the Primary Authorized User and business details.	If any data is missing, the merchant cannot transact or withdraw.
`MANAGED_PATH_BO_COLLECTION`	This process tells you if the merchant has provided all required information for your account's beneficial owners.	If any data is missing, the merchant cannot transact or withdraw.

Europe

The data collection processes in Europe are as follows:

Process	Description	Result
`MANAGED_PATH_CIP_COLLECTION`	This process tells you if the merchant has provided all required information for the Primary Authorized User, business details, and beneficial owners.	If any data is missing, the merchant cannot send or withdraw money.They can still receive payments for 30 days, after which they can no longer receive them.

Sample response when merchant information is complete

The data collection process shows a COMPLETED status if you have provided all the necessary information.

The following is an example of a GET response for a merchant in the US who has provided all the necessary data points to begin transacting:

1{
2  ...
3  "process_view": {
4    "processes": [
5      {
6        "name": "MANAGED_PATH_BO_COLLECTION",
7        "status": "COMPLETED",
8        "capabilities": [
9          {
10            "name": "RECEIVE_MONEY"
11          },
12          {
13            "name": "APPLE_PAY"
14          },
15          {
16            "name": "GOOGLE_PAY"
17          },
18          {
19            "name": "CUSTOM_CARD_PROCESSING"
20          },
21          {
22            "name": "WITHDRAW_MONEY"
23          }
24        ]
25      },
26      {
27        "name": "MANAGED_PATH_KYC_VERIFICATION",
28        "status": "COMPLETED",
29        "capabilities": [
30          {
31            "name": "CUSTOM_CARD_PROCESSING"
32          },
33          {
34            "name": "RECEIVE_MONEY"
35          },
36          {
37            "name": "WITHDRAW_MONEY"
38          },
39          {
40            "name": "GOOGLE_PAY"
41          },
42          {
43            "name": "APPLE_PAY"
44          }
45        ]
46      },
47      {
48        "name": "MANAGED_PATH_BO_VERIFICATION",
49        "status": "COMPLETED",
50        "capabilities": [
51          {
52            "name": "APPLE_PAY"
53          },
54          {
55            "name": "GOOGLE_PAY"
56          },
57          {
58            "name": "WITHDRAW_MONEY"
59          },
60          {
61            "name": "CUSTOM_CARD_PROCESSING"
62          },
63          {
64            "name": "RECEIVE_MONEY"
65          }
66        ]
67      },
68      {
69        "name": "MANAGED_PATH_KYC_COLLECTION",
70        "status": "COMPLETED",
71        "capabilities": [
72          {
73            "name": "CUSTOM_CARD_PROCESSING"
74          },
75          {
76            "name": "RECEIVE_MONEY"
77          },
78          {
79            "name": "APPLE_PAY"
80          },
81          {
82            "name": "GOOGLE_PAY"
83          },
84          {
85            "name": "WITHDRAW_MONEY"
86          }
87        ]
88      }
89    ]
90  }
91  ...
92}

Sample response when merchant information is missing

If any information required for the merchant to start transacting is missing, the data collection response shows a NEED_MORE_DATA status. The response also includes a required object that indicates the missing critical data.

The following is an example of a US merchant account created without the Individual Owner's phone number and SSN:

1{
2  ...
3  "process_view": {
4    "processes": [
5      {
6        "name": "MANAGED_PATH_BO_VERIFICATION",
7        "status": "NEED_MORE_DATA",
8        "capabilities": [
9          {
10            "name": "RECEIVE_MONEY",
11            "limits": [
12              {
13                "type": "AMOUNT",
14                "unit": "USD",
15                "value": "500000.00",
16                "remaining_value": "500000.00",
17                "implication_of_limit_breach": "BLOCK_CAPABILITY"
18              }
19            ]
20          },
21          {
22            "name": "APPLE_PAY",
23            "limits": [
24              {
25                "type": "AMOUNT",
26                "unit": "USD",
27                "value": "500000.00",
28                "remaining_value": "500000.00",
29                "implication_of_limit_breach": "BLOCK_CAPABILITY"
30              }
31            ]
32          },
33          {
34            "name": "GOOGLE_PAY",
35            "limits": [
36              {
37                "type": "AMOUNT",
38                "unit": "USD",
39                "value": "500000.00",
40                "remaining_value": "500000.00",
41                "implication_of_limit_breach": "BLOCK_CAPABILITY"
42              }
43            ]
44          },
45          {
46            "name": "CUSTOM_CARD_PROCESSING",
47            "limits": [
48              {
49                "type": "AMOUNT",
50                "unit": "USD",
51                "value": "500000.00",
52                "remaining_value": "500000.00",
53                "implication_of_limit_breach": "BLOCK_CAPABILITY"
54              }
55            ]
56          },
57          {
58            "name": "WITHDRAW_MONEY",
59            "limits": [
60              {
61                "type": "AMOUNT",
62                "unit": "USD",
63                "value": "500000.00",
64                "remaining_value": "500000.00",
65                "implication_of_limit_breach": "BLOCK_CAPABILITY"
66              }
67            ]
68          }
69        ],
70        "required": {
71          "op": "ALL_OF",
72          "attributes": [
73            "$.business_entity.beneficial_owners.individuals[?(@['id']=='26K4GZAA65P6G')].birth_details.date_of_birth"
74          ]
75        }
76      },
77      {
78        "name": "MANAGED_PATH_KYC_COLLECTION",
79        "status": "NEED_MORE_DATA",
80        "capabilities": [
81          {
82            "name": "WITHDRAW_MONEY"
83          },
84          {
85            "name": "RECEIVE_MONEY"
86          },
87          {
88            "name": "GOOGLE_PAY"
89          },
90          {
91            "name": "APPLE_PAY"
92          },
93          {
94            "name": "CUSTOM_CARD_PROCESSING"
95          }
96        ],
97        "required": {
98          "op": "ALL_OF",
99          "attributes": [
100            "$.individual_owners[?(@['id']=='JC5APZR7UPJTN')].citizenship"
101          ]
102        }
103      },
104      {
105        "name": "MANAGED_PATH_BO_COLLECTION",
106        "status": "NEED_MORE_DATA",
107        "capabilities": [
108          {
109            "name": "GOOGLE_PAY"
110          },
111          {
112            "name": "APPLE_PAY"
113          },
114          {
115            "name": "CUSTOM_CARD_PROCESSING"
116          },
117          {
118            "name": "WITHDRAW_MONEY"
119          },
120          {
121            "name": "RECEIVE_MONEY"
122          }
123        ],
124        "required": {
125          "op": "ALL_OF",
126          "attributes": [
127            "$.business_entity.beneficial_owners.individuals[?(@['id']=='26K4GZAA65P6G')].birth_details.date_of_birth"
128          ]
129        }
130      },
131      {
132        "name": "MANAGED_PATH_KYC_VERIFICATION",
133        "status": "COMPLETED",
134        "capabilities": [
135          {
136            "name": "RECEIVE_MONEY"
137          },
138          {
139            "name": "CUSTOM_CARD_PROCESSING"
140          },
141          {
142            "name": "GOOGLE_PAY"
143          },
144          {
145            "name": "APPLE_PAY"
146          },
147          {
148            "name": "WITHDRAW_MONEY"
149          }
150        ]
151      }
152    ]
153  }
154  ...
155}

Modify user interface to collect data

When building your integration, create accounts with complete data collection policies. If you notice requests for missing data, modify your onboarding UI to require those data points before account creation to ensure future accounts have complete collection policies.

This image shows the error messages that PayPal shows its merchants when a required name, email address, or password is missing.

Note: You can collect onboarding data from your merchants progressively over time. However, we don't recommend this approach.