How it works
Last updated: Oct 18th, 9:29am
Monitor for webhooks
If PayPal limits a merchant account, you receive a CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook. After receiving this webhook, complete a GET request to /v3/customer/managed-accounts/<ACCOUNT-ID> to determine the next steps.
Analyze JSON response for limitation impact
Similar to merchant account creation, analyze the JSON response in the GET request to /v3/customer/managed-accounts/ACCOUNT-ID and determine if your merchant needs to provide more 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.
- Terminal State: 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.
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_category": "ADDITIONAL_VERIFICATION",7 "limitation_text": "We need additional information to verify what is being sold on your account.",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"process_view": {2 "processes": [3 {4 "name": "REQUEST_FOR_INFORMATION_235",5 "limitation_category": "TERMINAL"6 "limitation_text": "Due to potential risks with this account, we can no longer do business with you."7 "status": "FAILED",8 "capabilities": [9 {10 "name": "WITHDRAW_MONEY",11 "status": "INACTIVE"12 },13 {14 "name": "SEND_MONEY",15 "status": "INACTIVE"16 },17 {18 "name": "RECEIVE_MONEY",19 "status": "INACTIVE"20 }21 ]22 }23 ]24}
If PayPal has limited a merchant account and you want to understand the reason for the limitation, send a GET request to /v3/customer/managed-accounts/ACCOUNT-ID.
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 action the merchant needs to take. |
|
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. |
The following table lists the possible limitation categories and their descriptions:
|
Category Name |
Description |
|
TERMINAL |
Due to potential risks, PayPal has decided not to do business with this account.
|
|
ADDITIONAL_VERIFICATION |
Additional information is required to ensure the account activity complies with PayPal's global regulatory obligations.
|
|
LEGAL_AND_REGULATORY_COMPLIANCE |
Provides information on what PayPal and marketplaces should adhere to as businesses when operating with their consumers or merchants.
|
|
FINANCIALS_VERIFICATION |
Verifies financial transactions and mitigates risks similar to chargebacks and unauthorized activities including data related to financial validations, bank account details, and verification processes for ensuring secure and authorized transactions.
|
|
US_FINCEN_BENEFICIAL_OWNER_VERIFICATION |
Requires the user to confirm the business type. If the business type is not correct, the user should update it on the profile page of the account. |
|
BUSINESS_MODEL_EVALUATION |
Requires information about the structure and nature of the merchant's business, including business type (sole proprietor, partnership, corporation), industry or sector, and registration or incorporation details. |
|
IDENTITY_VERIFICATION |
Requires data for anti-money laundering (AML), fraud, and Know Your Customer (KYC) processes and includes verifying the authenticity and establishing the identity of the customers. |
|
TAX_COMPLIANCE |
Requires tax documents or certifications from account holders outside the United States. FATCA enforces this requirement. |
|
BUSINESS_IDENTITY_VERIFICATION |
Requires additional documentation to support the business identity of the account. |
|
ACCOUNT_LIMITATION |
PayPal limits the merchant account for another reason
|
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.
Start manual verification
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 shows "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]