Account verification requirements

Note: Account verification requirements has been recently updated, to view the new requirements see Account Verification Requirements.

Verify your merchants to complete onboarding.

Review merchant verification status

The following GET call to fetch the top-level capability array that shows the merchant account status.

Note: account_id and merchant_payer_id are the same. Take the account_id from the response of the create_managed_account POST request.

Using your access token, pass the merchant's payer_id for the value of merchant_payer_id to /v3/vustomer/managed-accounts/MERCHANT-PAYER-ID to get a managed account's details.

Sample request

1{
2"path": "v3/customer/managed-accounts/MERCHANT-PAYER-ID",
3"method": "GET",
4"headers": {
5     "Authorization": "Bearer ACCESS-TOKEN",
6     "Content-Type": "application/json"
7}

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the merchant's managed account details.

Capabilities

The capabilities array is sent as a top-level entity in the GET API response. This array provides information on account capabilities, current statuses and any associated payment processing limits. Different types of capabilities are returned in the API response.

Each capability must have the "status":"ACTIVE" to be used. The limit array will be included if there is a payment processing limit associated with a capability. Each limit will contain the limit amount and the amount remaining before the limit is reached.

The top-level array is returned when you make a generic GET call without passing process_view in the request and provides the status of the account. If the status is inactive, use process_view and perform the action listed to remove the limitation. For more information about process_view, see Process View.

Note: Sellers can't send money in Managed Path.

Limits

The limits array is sent under the capabilities section in the API response. This sub-array provides the complete details around account limitations. These limitations are triggered when data verification is incomplete. These limitations may vary between countries.

Process view

Process view helps you get more information on the status of the merchant account. After you submit a createAccount request, a webhook is sent asynchronously that provides the next steps for enabling processing on the account. To get this response, make a GET request with the merchant's payer ID.

The response to the GET request contains a list of compliance processes and statuses that indicate whether the merchant account onboarding has been completed and is ready to start accepting payments.

The data verification processes required vary by country:

When the data verification process is complete, the status will show COMPLETED. A NEED_MORE_DATA status indicates that more data is needed to complete the process.

1. The process_view option is only returned in the response when views="process_view" has been provided in the GET request, either in the preferring HTTP header or as a URL query parameter.
2. If a process is missing any required information, then the process includes a required object. This means eKYC hasn't been triggered due to insufficient data. The required object in the relevant process includes the missing data.
3. If a process has any incorrect information, then the process includes a required_corrections object that lists the fields or documents to be corrected. It also means that at least one attempt to e-verify was made and failed.
4. If any documents are referenced in the required or required_corrections object, then the process_view includes a required_documents array containing the list of documents. If PayPal requires documents to verify the merchant manually, then the process_view includes a required_documents section containing the list of documents required, including document upload links. It also means that all e-verify attempts have failed. Upload physical documents to move foward with the manual verification process.
5. Each process in the process_view may contain a list of capabilities impacted by the process. Each capability contains associated and corresponding payment processing limits.

Note: account_id and merchant_payer_id are the same. You need to use account_id from the response of create_managed_account (POST).

Using your access token, pass the merchant's payer_id as the value of merchant_payer_id to /v3/customer/managed-accounts/{merchant_payer_id} to get a managed account's details.

Sample request

1{
2"path": "v3/customer/managed-accounts/9FF9LB633FSFC?views=process_view",
3"method": "GET",
4"headers": {
5     "Authorization": "Bearer ACCESS-TOKEN",
6     "Content-Type": "application/json"
7}

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the merchant's managed account details:

Sample response

1{
2  "account_id": "5B56QC6PFKYTG",
3  "legal_country_code": "US",
4  "individual_owners": [
5    {
6      "id": "5B56QC6PFKYTG",
7      "names": [
8        {
9          "given_name": "Sunny",
10          "surname": "Jose",
11          "id": "VX9PM8C7VSGD4",
12          "type": "LEGAL"
13        }
14      ],
15      "primary_residence": {
16        "address_line_1": "644 N 100 E",
17        "address_line_2": "100",
18        "admin_area_2": "100",
19        "postal_code": "29212",
20        "country_code": "US"
21      },
22      "birth_details": {
23        "date_of_birth": "1995-05-30"
24      }
25    }
26  ],
27  "business_entity": {
28    "type": "INDIVIDUAL",
29    "merchant_category_code": "5999",
30    "incorporation_details": {},
31    "names": [
32      {
33        "business_name": "E2E Inc.",
34        "id": "FRA7ALLJC5BL2",
35        "type": "LEGAL"
36      }
37    ]
38  },
39  "agreements": [
40    {
41      "type": "TERMS_ACCEPTED",
42      "accepted_time": "2019-06-02T01:23:45Z"
43    }
44  ],
45  "balances": [
46    {
47      "available": {
48        "currency_code": "USD",
49        "value": "0.00"
50      },
51      "reserved": {
52        "currency_code": "USD",
53        "value": "0.00"
54      }
55    }
56  ],
57  "external_id": "EXT-1654566097",
58  "organization": "us/marketplaces",
59  "user_id": "1654566097",
60  "primary_currency_code": "USD",
61  "soft_descriptor": "E2E INC",
62  "capabilities": [
63    {
64      "name": "CUSTOM_CARD_PROCESSING",
65      "limits": [
66        {
67          "type": "AMOUNT",
68          "unit": "USD",
69          "value": "500.00",
70          "remaining_value": "500.00"
71        }
72      ],
73      "status": "ACTIVE"
74    },
75    {
76      "name": "SEND_MONEY",
77      "status": "ACTIVE"
78    },
79    {
80      "name": "RECEIVE_MONEY",
81      "limits": [],
82      "status": "ACTIVE"
83    },
84    {
85      "name": "WITHDRAW_MONEY",
86      "limits": [
87        {
88          "type": "AMOUNT",
89          "unit": "USD",
90          "value": "500.00",
91          "remaining_value": "500.00"
92        }
93      ],
94      "status": "ACTIVE"
95    },
96    {
97      "name": "CUSTOM_BANK_PROCESSING",
98      "limits": [
99        {
100          "type": "AMOUNT",
101          "unit": "USD",
102          "value": "500.00",
103          "remaining_value": "500.00"
104        }
105      ],
106      "status": "ACTIVE"
107    }
108  ],
109  "process_view": {
110    "processes": [
111      {
112        "name": "MANAGED_PATH_KYC",
113        "status": "NEED_MORE_DATA",
114        "capabilities": [
115          {
116            "name": "CUSTOM_CARD_PROCESSING",
117            "limits": [
118              {
119                "type": "AMOUNT",
120                "unit": "USD",
121                "value": "500.00",
122                "remaining_value": "500.00"
123              }
124            ]
125          },
126          {
127            "name": "WITHDRAW_MONEY",
128            "limits": [
129              {
130                "type": "AMOUNT",
131                "unit": "USD",
132                "value": "500.00",
133                "remaining_value": "500.00"
134              }
135            ]
136          },
137          {
138            "name": "CUSTOM_BANK_PROCESSING",
139            "limits": [
140              {
141                "type": "AMOUNT",
142                "unit": "USD",
143                "value": "500.00",
144                "remaining_value": "500.00"
145              }
146            ]
147          }
148        ],
149        "required": {
150          "op": "ALL_OF",
151          "attributes": [
152            {
153              "op": "ONE_OF",
154              "attributes": [
155                "$.individual_owners[?(@['id']=='5B56QC6PFKYTG')].identification_documents[?(@['type']=='INDIVIDUAL_TAX_IDENTIFICATION_NUMBER')]",
156                "$.individual_owners[?(@['id']=='5B56QC6PFKYTG')].identification_documents[?(@['type']=='SOCIAL_SECURITY_NUMBER')]"
157              ]
158            }
159          ]
160        }
161      },
162      {
163        "name": "MANAGED_PATH_BO_VERIFICATION",
164        "status": "COMPLETED",
165        "capabilities": [
166          {
167            "name": "CUSTOM_CARD_PROCESSING"
168          },
169          {
170            "name": "WITHDRAW_MONEY"
171          }
172        ]
173      }
174    ]
175  },
176  "links": [
177    {
178      "href": "https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/5B56QC6PFKYTG",
179      "rel": "self",
180      "method": "GET"
181    },
182    {
183      "href": "https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/5B56QC6PFKYTG",
184      "rel": "edit",
185      "method": "PATCH"
186    }
187  ]
188}

Data verification processes

The response to the request for data verification contains a list of compliance processes. The requirements for data verification varies by country.

Recommendations for partners in the US, EU, and CA

PayPal recommends a simplified approach to tracking and communication capabilities, limits, and processes to the merchant. This approach requires the following in the API response:

1. Status of each capability: Check the status of each capability to control which capabilities should be made available to a merchant. Allowing a merchant to process payments using an inactive capability could lead to a poor user experience for buyers.

The current status of each capability is contained in the top-level capabilities array in the API response. Sellers can use any capability with a status value of ACTIVE. Sellers cannot use capabilities showing any other status value. If the capability is INACTIVE, the capability should be made unavailable or disabled for the merchant.

Note: The WITHDRAW_MONEY capability refelcts a merchant's ability to receive payouts to their bank account at the end of the day. The capability doesn't apply to partners who are using the settlement consolidation model. Please see the capabilities section to learn more.

2. The lowest remaining value crosses all limits: Sellers can be impacted by multiple different limits if they have no provided enough information to meet compliance process requirements. Partners should communicate to merchants how close they are to reaching their limit before any capabilities are impacted.

To simplify how tracking and communication limits to merchants, identify the payment processing limit with the lowest remaining_value left. Partners can communicate the lowest remaining_value amount found across all limits to their merchants. The top-level capabilities array in the API response contains all associated payment processing limits. The lowest remaining_value amount can be found by searching this top-level capabilities array.

Note: You can have multiple remaining_value amounts that are the same.

3. Any required information from the merchant is found in process_view: Sellers may need to provide information to use or continue using a capability. Sellers may also need to correct information that they have previously provided.

To simplify completing all compliance processes, identify and collect the required information found in the process_view from the merchant. Multiple compliance processes may ask for the same information from the merchant such as their Social Security Number.

The process_view object in the API response contains all required information that needs to be collected to complete all compliance processes. Required information can be found in the required andrequired_corrections object, and the require_documents array.

Retry data validation

To avoid reaching the data validation limit, monitor the process=Need_more_data field for missing data. Call the PATCH API with the updated data and the self-certification flag to re-trigger data verification.

The number of times data validation can be triggered per non-loginable merchant account (NLM) varies by country:

Note: Data validation can't be triggered after the maximum number data validations is reached, and your merchant must be manually verified.