Onboard merchants

Last updated: June 20th 2023, @ 2:08:42 pm

Note: The Managed Accounts API has been recently updated, to view the previous version of merchant onboarding see Onboard Merchants Deprecated

Onboard your merchants so they can accept payment on your site. Use the Managed Accounts API to onboard merchants by creating non-loginable merchant accounts.

To onboard merchants:

Submit a request to create a non-loginable merchant account using the Managed Accounts API.
Monitor the account status and view information needed to complete verification.
Submit any required information to complete data verification.

Know before you code

Onboarding merchants uses the Managed Accounts API.
Set up and configure your partner account for the sandbox and live environment.
Get an access token.
Review the requirements for account verification that PayPal requires in each country.

1. Create a non-loginable merchant account

Use your access token to create and configure a non-loginable merchant (NLM) account for your merchant.

Pass the following fields in the request body to /v3/customer/managed-accounts to create an account:

Parameter	Type	Description
`external_id`	string	The partner-provided ID of the managed account.
`legal_country_code`	string	The residence country with which the account is associated.
`organization`	string	Organization this managed account belongs to in the partner's hierarchy in the form of a path.
`user_id`	string	The partner's unique identifier for this user in their system.
`primary_currency_code`	string	The primary currency that this account holds. If you omit this value from the request, the value is derived from the primary currency of the account's country.
`individual_owners`	array	List of owners in the account.
`financial_instruments`	object	An array of financial instruments.
`business_entity`	object	Business entity of the account.
`agreements`	array	Agreements associated with the account.

Sample request

The following request creates an account for a corporation located in the United States. For sample requests for other types of business and countries, see Sample account creation requests.

1{
2    "external_id": "EXTERNAL-ID",
3    "legal_country_code": "US",
4    "organization": "us",
5    "user_id": "USER-ID",
6    "primary_currency_code": "USD",
7    "individual_owners": [
8        {
9            "names": [
10                {
11                    "type": "LEGAL",
12                    "given_name": "MaryAPPROVED",
13                    "surname": "Collins"
14                }
15            ],
16            "citizenship": "US",
17            "emails": [
18                {
19                    "email": "111@123.com"
20                }
21            ],
22            "phone_numbers": [
23                {
24                    "country_code": "1",
25                    "national_number": "33333333",
26                    "extension_number": "1",
27                    "type": "MOBILE"
28                }
29            ],
30            "birth_details": {
31                "date_of_birth": "2021-09-16"
32            },
33            "primary_residence": {
34                "address_line_1": "123 Main St",
35                "address_line_2": "add primary residence",
36                "admin_area_2": "Anytown",
37                "admin_area_1": "CA",
38                "postal_code": "12345",
39                "country_code": "US"
40            },
41            "identification_documents": [
42                {
43                    "type": "INDIVIDUAL_TAX_IDENTIFICATION_NUMBER",
44                    "identification_number": "923456789",
45                    "issuing_country_code": "US"
46                }
47            ]
48        }
49    ],
50    "business_entity": {
51        "type": "CORPORATION",
52        "merchant_category_code": "5932",
53        "website_info": {
54            "website_exists": true,
55            "website_url": "https://www.standardpartner.com"
56        },
57        "names": [
58            {
59                "type": "LEGAL",
60                "business_name": "MaryAPPROVED Inc."
61            }
62        ],
63        "registered_business_address": {
64            "address_line_1": "123 Main St",
65            "admin_area_1": "CA",
66            "admin_area_2": "Anytown",
67            "postal_code": "12345",
68            "country_code": "US"
69        },
70        "identification_documents": [
71            {
72                "type": "EMPLOYER_IDENTIFICATION_NUMBER",
73                "identification_number": "729265100",
74                "issuing_country_code": "US"
75            }
76        ],
77        "phone_numbers": [
78            {
79                "type": "BUSINESS",
80                "country_code": "27",
81                "national_number": "06151172"
82            }
83        ],
84        "emails": [
85            {
86                "email": "addBusinessEmail@provider.com"
87            }
88        ],
89        "beneficial_owners": {
90            "individuals": [
91                {
92                    "percentage_of_ownership": "35",
93                    "names": [
94                        {
95                            "type": "LEGAL",
96                            "given_name": "BillAPPROVED",
97                            "surname": "Smoth"
98                        }
99                    ],
100                    "birth_details": {
101                        "date_of_birth": "1995-05-30"
102                    },
103                    "addresses": [
104                        {
105                            "type": "HOME",
106                            "admin_area_1": "CA",
107                            "address_line_1": "APPROVED Street",
108                            "admin_area_2": "100",
109                            "postal_code": "12345",
110                            "country_code": "US"
111                        }
112                    ],
113                    "citizenship": "US",
114                    "identification_documents": [
115                        {
116                            "type": "SOCIAL_SECURITY_NUMBER",
117                            "identification_number": "123456789",
118                            "issuing_country_code": "US"
119                        }
120                    ],
121                    "phone_numbers": [
122                        {
123                            "country_code": "1",
124                            "national_number": "33333333",
125                            "extension_number": "1",
126                            "type": "WORK"
127                        }
128                    ],
129                    "emails": [
130                        {
131                            "email": "addEmail@126.com"
132                        }
133                    ]
134                }
135            ]
136        },
137        "office_bearers": [
138            {
139                "names": [
140                    {
141                        "type": "LEGAL",
142                        "prefix": "Mr.",
143                        "given_name": "MaryAPPROVED",
144                        "surname": "Davis",
145                        "suffix": "Sr"
146                    }
147                ],
148                "citizenship": "US",
149                "addresses": [
150                    {
151                        "type": "HOME",
152                        "admin_area_1": "CA",
153                        "address_line_1": "APPROVED 123 Main St",
154                        "admin_area_2": "100",
155                        "postal_code": "12345",
156                        "country_code": "US"
157                    }
158                ],
159                "birth_details": {
160                    "date_of_birth": "1995-05-30"
161                },
162                "identification_documents": [
163                    {
164                        "type": "SOCIAL_SECURITY_NUMBER",
165                        "identification_number": "111222343",
166                        "issuing_country_code": "US"
167                    }
168                ],
169                "phone_numbers": [
170                    {
171                        "country_code": "1",
172                        "national_number": "33333333",
173                        "extension_number": "1",
174                        "type": "WORK"
175                    }
176                ],
177                "emails": [
178                    {
179                        "email": "addEmail@126.com"
180                    }
181                ]
182            }
183        ]
184    },
185    "agreements": [
186        {
187            "type": "TERMS_ACCEPTED",
188            "accepted_time": "2022-06-02T01:23:45Z"
189        }
190    ]
191}

Step result

When you submit the request to create an account, the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED webhook is sent in response. For information about how to monitor webhooks, see Webhooks.

Note: Getting this response back doesn't mean the account is fully created. More information may be required to finalize account creation.

2. Monitor webhooks

PayPal validates the data using automated data verification processes. For more information on the automated data verification processes run in each country, see Account verification requirements. If additional information is needed, additional webhooks are sent.

Make a GET call to the following webhooks to get additional onboarding requirements:

CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED, which is returned in response to a request to update the account.
CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED, which indicates that the status of the account has changed.
CUSTOMER.MANAGED-ACCOUNT-CREATED, which notifies you that the account has been created.

Account updated
Status changed
Account created

The CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED is returned in response to a request to update the account.

Note: ACCOUNT-UPDATED webhooks contain an actor field to help identify the source of an edit. If an account is edited by a PayPal representative during verification, the actor is PAYPAL. If an account is edited by the partner, the actor is CLIENT.

The following code sample shows a response that is sent in response to a PATCH operation to update the account:

Sample response: Account updated

1{
2 "description": "Account update webhook.",
3 "title": "Update Account",
4 "runnable": true,
5 "operationId": "webhook.account_updated",
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   "update_time": "2018-05-24T07:18:28.264Z",
20   "resource_type": "managed-accounts",
21   "event_type": "CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED",
22   "summary": "A managed account was updated.",
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    "event_targets": [
37     "addresses",
38     "phones"
39    ],
40    "actor" : "CLIENT"
41   },
42   "links": [
43    {
44     "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
45     "rel": "self",
46     "method": "GET"
47    },
48    {
49     "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R/resend",
50     "rel": "resend",
51     "method": "POST"
52    }
53   ]
54  }
55 }
56}

More information needed

The ACCOUNT.ACCOUNT-STATUS-CHANGED contains a process array detailing the processes that are impacted because the data required is missing.

The following sample shows a response that indicates more information is required:

Sample response: More information needed

1{
2 "description": "Account state changes for Capabilities or Processes",
3 "title": "Account state change",
4 "runnable": true,
5 "operationId": "webhook.account_status_changed",
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-STATUS-CHANGED",
22   "summary": "Managed account capability status changed.",
23   "resource": {
24    "account_id": "7G4EPEEPEF74L",
25    "external_id": "external_id_353535335",
26    "capabilities": [
27     {
28      "name": "WITHDRAW_MONEY",
29      "status": "NEED_MORE_DATA"
30     },
31     {
32      "name": "RECEIVE_MONEY",
33      "status": "NEED_MORE_DATA"
34     }
35    ],
36    "processes":[
37      {
38       "name":"MANAGED_PATH_1099_K",
39       "status":"NEED_MORE_DATA"
40       },
41       {
42       "name":"MANAGED_PATH_KYC",
43       "status":"NEED_MORE_DATA"
44       },
45       {
46       "name":"MANAGED_PATH_BO_VERIFICATION",
47       "status":"COMPLETED"
48       }
49    ],
50    "links": [
51     {
52      "rel": "self",
53      "href": "https://api-m.paypal.com/v3/customer/managed-accounts/7G4EPEEPEF74L",
54      "method": "GET"
55     },
56     {
57      "rel": "edit",
58      "href": "https://api-m.paypal.com/v3/customer/managed-accounts/7G4EPEEPEF74L",
59      "method": "PATCH"
60     }
61    ]
62   },
63   "application_context": {
64    "event_context": "ACTION"
65   },
66   "links": [
67    {
68     "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
69     "rel": "self",
70     "method": "GET"
71    },
72    {
73     "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R/resend",
74     "rel": "resend",
75     "method": "POST"
76    }
77   ]
78  }
79 }
80}

3. Complete account verification

Accounts may require more information before they can be created. When you get a NEED_MORE_DATA status in the process array of a response, make another call to view required information. Then, submit the missing information.

View required information

Call the Managed Accounts API to view the data or documents required to complete the verification:

Sample request

1curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/customer/managed-accounts?external_id=EXTERNAL-ID&views=process_view' 
2 -H 'Authorization: Bearer ACCESS-TOKEN' 
3 -H 'Content-Type: application/json'

Sample response

1...
2 "process_view": {
3  "processes": [{
4    "name": "MANAGED_PATH_BO_VERIFICATION",
5    "status": "NEED_MORE_DATA",
6    "capabilities": [{
7      "name": "WITHDRAW_MONEY",
8      "limits": [{
9        "type": "AMOUNT",
10        "unit": "USD",
11        "value": "100000.00",
12        "remaining_value": "100000.00"
13      }]
14    }, {
15      "name": "CUSTOM_CARD_PROCESSING"
16    }],
17    "required": {
18      "op": "ALL_OF",
19      "attributes": ["V10iF", {
20        "op": "ALL_OF",
21        "attributes": ["nqz69"]
22      }]
23    }
24  }, {
25    "name": "MANAGED_PATH_1099_K",
26    "status": "COMPLETED",
27    "capabilities": [{
28      "name": "RECEIVE_MONEY"
29    }, {
30      "name": "CUSTOM_BANK_PROCESSING"
31    }, {
32      "name": "CUSTOM_CARD_PROCESSING"
33    }]
34  }, {
35    "name": "MANAGED_PATH_KYC",
36    "status": "COMPLETED",
37    "capabilities": [{
38      "name": "CUSTOM_BANK_PROCESSING"
39    }, {
40      "name": "CUSTOM_CARD_PROCESSING"
41    }, {
42      "name": "WITHDRAW_MONEY"
43    }]
44  }, {
45    "name": "MANAGED_PATH_CIP_COLLECTION",
46    "status": "NEED_MORE_DATA",
47    "capabilities": [{
48      "name": "CUSTOM_CARD_PROCESSING"
49    }, {
50      "name": "CUSTOM_BANK_PROCESSING"
51    }],
52    "required": {
53      "op": "ALL_OF",
54      "attributes": ["$.business_entity.merchant_category_code", {
55        "op": "ALL_OF",
56        "attributes": ["$.individual_owners[?(@['id']=='UGS6LDJ5H7DQN')].primary_residence"]
57      }]
58    }
59  }],
60  "required_documents": [{
61    "id": "V10iF",
62    "name": "SSN",
63    "entity": "$.business_entity.beneficial_owners.individuals[?(@['id']=='XC72KL4LGNL7Y')]",
64    "links": [{
65      "href": "https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/05ae9e8e-5958-4e1a-8e2e-3e2d46a06ce4/upload",
66      "rel": "upload",
67      "method": "POST"
68    }]
69  }, {
70    "id": "nqz69",
71    "name": "SSN",
72    "entity": "$.business_entity.office_bearers[?(@['id']=='L338E6LZU6XXL')]",
73    "links": [{
74      "href": "https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/f983fab2-1b84-42e2-b8cf-c996067a4a5b/upload",
75      "rel": "upload",
76      "method": "POST"
77    }]
78  }]
79...

Send required information

Send additional information or documentation if required in the response from the call:

Send information if the account is missing information in text fields such as name or address.
Send documentation if the account is missing documents, such as a passport.

Information
Documentation

If the PROCESS_VIEW requires you to provide documents, use the Identification Documents API to send merchant documentation. Submit the missing information and set SELF_CERTIFICATION to true to trigger data verification.

Note: In the United States, you can only edit onboarding information and manually trigger data verification once. For information about how many times the verification process can be triggered by country, see Retry data validation.

The following request shows a submission adding the social security number for a person living in the United States:

Sample request

1curl -v -k -X PATCH 'https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/ACCOUNT-ID' 
2 -H 'Authorization: Bearer ACCESS-TOKEN' 
3 -H 'Content-Type: application/json' 
4 -d '[
5    {
6  "op": "add",
7  "path": "/individual_owners/@id=='PERSON-ID'/identification_documents",
8  "value": [
9   {
10    "type": "SOCIAL_SECURITY_NUMBER",
11    "identification_number": "111222333",
12    "issuing_country_code": "US"
13   }
14  ]
15 },
16 {
17  "op": "add",
18  "path": "/attributes",
19  "value": [
20   {
21    "name": "SELF_CERTIFICATION",
22    "value": "true"
23   }
24  ]
25 }
26]'

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