How it works

DocsCurrent

Last updated: Dec 9th, 9:58am

Monitor for webhooks

If PayPal limits a merchant account, you receive a CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook. To determine the next steps, complete a GET request to /v3/customer/managed-accounts/<Account-ID>, where <Account-ID> is the ID of the merchant account.

Analyze JSON response for limitation impact

After you receive a CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook event, make a GET request to /v3/customer/managed-accounts/<Account-ID>?views=process_view and analyze the JSON response to determine the limitation's impact on your merchant, and whether they need to provide additional information. PayPal may ask you to provide the following details:

Business information: You must provide additional information about the merchant's business or operations to meet Know Your Customer (KYC) and Anti-Money Laundering (AML) requirements.

Primary authorized user (PAU) Information: You must provide additional details about the merchant's primary authorized user, who is the individual or entity responsible for managing and overseeing processing related to the account.

Beneficial owner information: You must provide information on your merchant's business owners. This process typically involves disclosing details about the individuals who have maximum ownership or control over the business in compliance with regulations.

Note: In severe cases, PayPal might permanently limit the merchant's account if specific violations or significant risks remain unaddressed. This state signifies an irreversible termination of the merchant's ability to use PayPal services.

Structure of limitation processes

After performing the GET request, interpret the response to check if the merchant account has limitations in place. The first step is to analyze the process_view object. This object lists the limitation processes that PayPal may apply to your merchants.

Sample code - Provide additional information

In the following example, the merchant needs to provide PayPal with additional information about their business:

1{
2  "process_view": {
3    "processes": [
4      {
5        "name": "REQUEST_FOR_INFORMATION_221",
6        "limitation_text": "Legal Compliance",
7        "limitation_description": "Account restricted because we found we found unapproved gambling or gaming activity related to fantasy sports.",
8        "status": "NEED_MORE_DATA",
9        "capabilities": [
10          {
11            "name": "WITHDRAW_MONEY",
12            "status": "INACTIVE"
13          },
14          {
15            "name": "SEND_MONEY",
16            "status": "INACTIVE"
17          },
18          {
19            "name": "RECEIVE_MONEY",
20            "status": "INACTIVE"
21          }
22        ],
23        "required": {
24          "op": "ALL_OF",
25          "attributes": [
26            {
27              "op": "ONE_OF",
28              "attributes": [
29                {
30                  "op": "ALL_OF",
31                  "attributes": [
32                    {
33                      "op": "ONE_OF",
34                      "attributes": [
35                        "lBRrr",
36                        "UT1CH"
37                      ]
38                    }
39                  ]
40                }
41              ]
42            }
43          ]
44        },
45        "required_corrections": {
46          "op": "ALL_OF",
47          "attributes": [
48            {
49              "op": "ONE_OF",
50              "attributes": [
51                {
52                  "op": "ALL_OF",
53                  "attributes": [
54                    {
55                      "op": "ALL_OF",
56                      "attributes": [
57                        {
58                          "op": "ONE_OF",
59                          "attributes": [
60                            "lBRrr",
61                            "UT1CH"
62                          ]
63                        }
64                      ]
65                    }
66                  ]
67                }
68              ]
69            }
70          ]
71        }
72      }
73    ],
74    "required_documents": [
75      {
76        "id": "UT1CH",
77        "name": "DRIVERS_LICENSE",
78        "entity": "$.business_entity.beneficial_owners.individuals[?(@['id']=='JATQ7BKRWGAEJ')]",
79        "links": [
80          {
81            "href": "https://msmaster1int.g.devqa.gcp.dev.paypalinc.com:17707/v1/customer/supporting-documents/1dd3be68-c5a7-4cac-86e5-ea2730a64042/upload",
82            "rel": "upload",
83            "method": "POST"
84          }
85        ]
86      },
87      {
88        "id": "lBRrr",
89        "name": "PASSPORT",
90        "entity": "$.business_entity.beneficial_owners.individuals[?(@['id']=='JATQ7BKRWGAEJ')]",
91        "links": [
92          {
93            "href": "https://msmaster1int.g.devqa.gcp.dev.paypalinc.com:17707/v1/customer/supporting-documents/1dd3be68-c5a7-4cac-86e5-ea2730a64042/upload",
94            "rel": "upload",
95            "method": "POST"
96          }
97        ]
98      }
99    ]
100  }
101}

Sample code - Account in terminal state

The following example shows a merchant account in a terminal state:

1{
2  "process_view": {
3    "processes": [
4      {
5        "name": "REQUEST_FOR_INFORMATION_235",
6        "limitation_text": "Regulatory Compliance",
7        "limitation_description": "We are no longer able to process activity for you due to account created with unsupported citizenship.",
8        "status": "FAILED",
9        "capabilities": [
10          {
11            "name": "WITHDRAW_MONEY",
12            "status": "INACTIVE"
13          },
14          {
15            "name": "SEND_MONEY",
16            "status": "INACTIVE"
17          },
18          {
19            "name": "RECEIVE_MONEY",
20            "status": "INACTIVE"
21          }
22        ]
23      }
24    ]
25  }
26}

The following table lists the attributes in the response and their meanings:

Detail	Meaning
name	The unique identifier for this limitation.
limitation_category	Specifies the category of the limitation.
limitation_text	Describes the reason the limitation was placed on the account.
status	Describes the status of the associated capability. The merchant can use only those capabilities with a status of `ACTIVE`. If a capability has any other status, it cannot be used.
(Optional) required, required_corrections, required_documents	Specifies the information or documents the merchant must provide to remove the limitation. Note: The required sections don't apply to a terminal limitation.

List of limitation processes

The following table lists the possible limitations, their categories, and descriptions. The names of the limitation processes vary depending on the limitations imposed.

Limitation name	Limitation category	Description
REQUEST_FOR_INFORMATION_4	Legal Compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_221	Legal Compliance limitation	PayPal may ask for additional data or documents to verify the merchant. The merchant cannot transact or withdraw before completing the verification.
REQUEST_FOR_INFORMATION_222	Business Model Evaluation	PayPal is reviewing this merchant and may ask for information about the merchant's business nature, including business type (sole proprietor, partnership, corporation), industry or sector, and registration or incorporation details.
REQUEST_FOR_INFORMATION_224	Regulatory Compliance limitation	PayPal may ask for transaction details, activity, or profile information.
REQUEST_FOR_INFORMATION_225	Regulatory Compliance limitation	PayPal reviews the merchant profile, transaction details, or activity. The merchant cannot transact or withdraw.
REQUEST_FOR_INFORMATION_231	Regulatory compliance limitation	PayPal reviews this account. The merchant cannot transact or withdraw.
REQUEST_FOR_INFORMATION_235	Regulatory compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_241	Legal compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_242	Legal compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_243	Legal compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_244	Legal compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.
REQUEST_FOR_INFORMATION_245	Legal compliance limitation	A terminal and irreversible limitation that terminates the merchant's ability to use PayPal services.

Use the capabilities section and the additional limitation information in process_view to communicate to your customers the limitation and the required additional information or documents.

For a list of potential reasons an account can be limited, see Account limitation reasons.

Start manual verification

Determine the limits applied to the merchant account by analyzing the /process_view/processes[]/capabilities array. Use the PATCH request to /v3/customer/managed-accounts/<Account-ID> or Documents API at /v1/customer/supporting-documents/<Doc-ID> to send the required information to PayPal.

Monitor for webhooks

Similar to the initial account creation process, monitor webhooks to track account status and determine the next steps. After you send the information or documentation, PayPal begins the electronic or manual verification.

Verify or request more information

Use the capabilities array to determine if the merchant has completed the re-verification.

Conclude verification

Repeat steps 1-5 until the merchant passes all verification checks and all sections under the capabilities array show status: ACTIVE with no limits.

1"capabilities": [
2  {
3    "name": "APPLE_PAY",
4    "status": "ACTIVE"
5  },
6  {
7    "name": "GOOGLE_PAY",
8    "status": "ACTIVE"
9  },
10  {
11    "name": "CUSTOM_CARD_PROCESSING",
12    "status": "ACTIVE"
13  },
14  {
15    "name": "RECEIVE_MONEY",
16    "status": "ACTIVE"
17  },
18  {
19    "name": "WITHDRAW_MONEY",
20    "status": "ACTIVE"
21  }
22]