Collect merchant data
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 asMANAGED_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.
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.