Create non-loginable merchant accounts
Last updated: Oct 18th, 5:02am
Use your access token to create and configure a non-loginable merchant account.
To create an account, pass the following fields in the request body to /v3/customer/managed-accounts
:
Parameter |
Type |
Description |
external_id |
string |
The partner-provided ID of the managed account. |
legal_country_code |
string |
The residence country of the account. |
organization |
string |
The organization this managed account belongs to in the partner's hierarchy, provided as a path. PayPal support team provides this value. |
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 do not specify this value in the request, the system derives it from the primary currency of the account's country |
individual_owners |
array |
Individual owner or primary authorized user of the account. Currently, PayPal supports only one individual owner. |
financial_instruments |
object |
Financial instrument. Currently, PayPal supports only one financial instrument. |
business_entity |
object |
Business entity of the account. |
agreements |
array |
Agreements associated with the account. |
Different countries and business types require different data sets to create an account that can transact.
Data elements for account creation
The create account request payload differs based on country, jurisdiction, and business type.
Regardless of the country, you provide the following categories of data:
-
Primary authorized user information: Information about the individual who completes the account opening application.
- Individual or Sole Proprietor business type: Information about the merchant or the individual who owns or runs the sole proprietorship.
Note: From a data perspective, this business type's primary authorized user information is the only individual-person information you submit.
- Any other business type: Information about the individual who completes the account opening application and whom the company authorizes to open, use, or manage an account on its behalf.
- Business entity information: Information about the merchant's business.
- Beneficial owner information: Information about the individuals who meet the beneficial ownership requirements for the merchant. These requirements vary by country. For more details on beneficial ownership, see Data collection.
- Office bearer information (for certain business types): Information about the individual(s) who has control over the day-to-day operations of the merchant's business or who is authorized to make decisions on behalf of the business.
Data elements for United States
Table 1 - Data elements for Individual or Sole Proprietor
All required data must be provided before transactions can begin.
Data requirements |
Data category |
API reference |
User legal name |
Primary authorized user |
|
User home address |
Primary authorized user |
|
User date of birth |
Primary authorized user |
|
User phone number1 |
Primary authorized user |
|
User email |
Primary authorized user |
|
User citizenship2 |
Primary authorized user |
|
Social Security number (SSN) or Individual Taxpayer Identification Number (ITIN)3 |
Primary authorized user |
|
Business type (INDIVIDUAL,PROPRIETORSHIP) |
Business entity |
|
Trading Name or Doing Business As (DBA)4 |
Business entity |
|
Merchant Category Code |
Business entity |
|
Business website information5 |
Business entity |
- 1: The Primary Authorised User (PAU) phone number type should be HOME or MOBILE. Any other type may cause an error.
- 2: Use the
citizenship
field to tell PayPal if the user has a Social Security number (SSN) or Individual Taxpayer Identification Number (ITIN). If the user has an SSN or ITIN, setcitizenship
to US. Your individual or sole proprietor merchants must provide a Social Security number or Individual Taxpayer Identification Number. You'll need to set thecitizenship
and theissuing_country_code
of these identification documents to US. - 3: Your individual or sole proprietor merchants must provide a SSN or ITIN.
- 4: Sole proprietors only need to provide this value if they use a trade name or business name.
- 5: Provide a website for users who have one. If a user doesn't have a website, set
website_info.website_exists
tofalse
in thewebsite_info
object.
Data elements for Europe and the United Kingdom
Managed Path is only available for partners in the following countries:
- Denmark
- France (not including French overseas territories)
- Germany
- Italy
- Poland
- Spain
- United Kingdom
Table 1: Data elements for Individuals and Sole Proprietor
When creating the account, provide the complete data set. Otherwise, the send and withdraw capabilities are blocked. You can still receive payments for 30 days, after which you no longer receive them.
Data Requirements
|
Data Category
|
API Reference
|
User legal name
|
Primary authorized user
|
|
User home address
|
Primary authorized user
|
/individual_owners/@id/addresses/
|
User date of birth
|
Primary authorized user
|
/individual_owners/
|
User nationality1
|
Primary authorized user
|
/individual_owners/@id/citizenship
|
Business type(
|
Business entity |
|
Business legal name
|
Business entity
|
|
Business address2 |
Business entity
|
|
VAT ID (Value Added Tax Identification Number) |
Business entity
|
/business_entity/
Type: |
Merchant Category Code
|
Business entity
|
/business_entity/
|
Business phone number (optional)
|
Business entity
|
/business_entity/phone_numbers/
|
Business website info (optional)
|
Business entity
|
|
- 1: When creating a UK NLM account, set the individual's nationality to the UK. For the EU, set the the individual's nationality to an EU country.
- 2: The business address must be in the UK for UK individuals and in the EU for EU individuals.
Data elements for Japan
All required data must be provided before transactions can begin.
Data Requirements
|
Role
|
API Reference
|
User legal name
|
Primary account user
|
|
Business type ( |
Business entity
|
|
Business legal name |
Business entity
|
|
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": "EXT-{{$timestamp}}",3 "legal_country_code": "US",4 "organization": "us",5 "user_id": "{{$timestamp}}",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 "financial_instruments": {51 "banks": [52 {53 "mandate": {54 "consent_to_debit": true55 },56 "account_number": "69228240",57 "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",58 "account_type": "CHECKING",59 "routing_number": "011200022",60 "branch_code": "08501",61 "currency_code": "USD",62 "country_code": "US",63 "bank_name": "Key Bank National Association"64 }65 ]66 },67 "business_entity": {68 "type": "CORPORATION",69 "merchant_category_code": "5932",70 "website_info": {71 "website_exists": true,72 "website_url": "https://www.standardpartner.com"73 },74 "names": [75 {76 "type": "LEGAL",77 "business_name": "MaryAPPROVED Inc."78 }79 ],80 "registered_business_address": {81 "address_line_1": "123 Main St",82 "admin_area_1": "CA",83 "admin_area_2": "Anytown",84 "postal_code": "12345",85 "country_code": "US"86 },87 "identification_documents": [88 {89 "type": "EMPLOYER_IDENTIFICATION_NUMBER",90 "identification_number": "729265100",91 "issuing_country_code": "US"92 }93 ],94 "phone_numbers": [95 {96 "type": "BUSINESS",97 "country_code": "27",98 "national_number": "06151172"99 }100 ],101 "emails": [102 {103 "email": "addBusinessEmail@provider.com"104 }105 ],106 "beneficial_owners": {107 "individuals": [108 {109 "percentage_of_ownership": "35",110 "names": [111 {112 "type": "LEGAL",113 "given_name": "BillAPPROVED",114 "surname": "Smoth"115 }116 ],117 "birth_details": {118 "date_of_birth": "1995-05-30"119 },120 "addresses": [121 {122 "type": "HOME",123 "address_line_1": "APPROVED Street",124 "admin_area_2": "100",125 "postal_code": "12345",126 "country_code": "US"127 }128 ],129 "citizenship": "US",130 "identification_documents": [131 {132 "type": "SOCIAL_SECURITY_NUMBER",133 "identification_number": "123546786",134 "issuing_country_code": "US"135 }136 ],137 "phone_numbers": [138 {139 "country_code": "1",140 "national_number": "33333333",141 "extension_number": "1",142 "type": "WORK"143 }144 ],145 "emails": [146 {147 "email": "addEmail@126.com"148 }149 ]150 }151 ]152 },153 "office_bearers": [154 {155 "names": [156 {157 "type": "LEGAL",158 "prefix": "Mr.",159 "given_name": "MaryAPPROVED",160 "surname": "Davis",161 "suffix": "Sr"162 }163 ],164 "citizenship": "US",165 "addresses": [166 {167 "type": "HOME",168 "admin_area_1": "CA",169 "address_line_1": "APPROVED 123 Main St",170 "admin_area_2": "100",171 "postal_code": "12345",172 "country_code": "US"173 }174 ],175 "birth_details": {176 "date_of_birth": "1995-05-30"177 },178 "identification_documents": [179 {180 "type": "SOCIAL_SECURITY_NUMBER",181 "identification_number": "111222343",182 "issuing_country_code": "US"183 }184 ],185 "phone_numbers": [186 {187 "country_code": "1",188 "national_number": "33333333",189 "extension_number": "1",190 "type": "WORK"191 }192 ],193 "emails": [194 {195 "email": "addEmail@126.com"196 }197 ]198 }199 ]200 },201 "agreements": [202 {203 "type": "TERMS_ACCEPTED",204 "accepted_time": "2022-06-02T01:23:45Z"205 }206 ]207}
Sample response
When you submit a request to create a merchant account, PayPal sends the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED
webhook in response. For information on monitoring webhooks, see Webhooks.
A successful POST request to create a merchant account returns an HTTP 200 OK status code. The following JSON response body shows the merchant's information and the account's status:
1{2 "account_id": "TMBGTLZJK6L38",3 "legal_country_code": "US",4 "individual_owners": [5 {6 "id": "TMBGTLZJK6L38",7 "names": [8 {9 "given_name": "MaryAPPROVED",10 "surname": "Collins",11 "id": "BXMFYHCSD2W64",12 "type": "LEGAL"13 }14 ],15 "citizenship": "US",16 "primary_residence": {17 "address_line_1": "123 Main St",18 "address_line_2": "add primary residence",19 "admin_area_2": "Anytown",20 "admin_area_1": "CA",21 "postal_code": "12345",22 "country_code": "US"23 },24 "phone_numbers": [25 {26 "country_code": "1",27 "national_number": "33333333",28 "id": "R3C5PU3QQ6RQ8",29 "type": "MOBILE"30 }31 ],32 "birth_details": {33 "date_of_birth": "2021-09-16"34 },35 "identification_documents": [36 {37 "id": "TR5FN8EBMW6W8",38 "identification_number": "****",39 "issuing_country_code": "US",40 "type": "INDIVIDUAL_TAX_IDENTIFICATION_NUMBER"41 }42 ],43 "emails": [44 {45 "id": "JBLAZXLLHU3V6",46 "email": "111@123.com"47 }48 ]49 }50 ],51 "business_entity": {52 "type": "CORPORATION",53 "merchant_category_code": "5932",54 "incorporation_details": {},55 "names": [56 {57 "business_name": "MaryAPPROVED Inc.",58 "id": "FWP6T87CQ6KKE",59 "type": "LEGAL"60 }61 ],62 "emails": [63 {64 "id": "Z2VLEXHVBP6SA",65 "email": "addBusinessEmail@provider.com"66 }67 ],68 "website_info": {69 "website_exists": true,70 "website_url": "https://www.standardpartner.com"71 },72 "registered_business_address": {73 "address_line_1": "123 Main St",74 "admin_area_2": "Anytown",75 "admin_area_1": "CA",76 "postal_code": "12345",77 "country_code": "US"78 },79 "phone_numbers": [80 {81 "country_code": "27",82 "national_number": "06151172",83 "id": "J7FWZ258CDDPL",84 "type": "BUSINESS"85 }86 ],87 "identification_documents": [88 {89 "id": "FL7YNXE9AP7ZS",90 "identification_number": "****",91 "issuing_country_code": "US",92 "type": "EMPLOYER_IDENTIFICATION_NUMBER"93 }94 ],95 "beneficial_owners": {96 "individuals": [97 {98 "id": "B47X2Q4Z6M56L",99 "names": [100 {101 "given_name": "BillAPPROVED",102 "surname": "Smoth",103 "id": "5CZQ64SWT2UWQ",104 "type": "LEGAL"105 }106 ],107 "citizenship": "US",108 "addresses": [109 {110 "address_line_1": "APPROVED Street",111 "admin_area_2": "100",112 "postal_code": "12345",113 "country_code": "US",114 "id": "MFD7GS2EHLH5S",115 "type": "HOME"116 }117 ],118 "phone_numbers": [119 {120 "country_code": "1",121 "national_number": "33333333",122 "extension_number": "1",123 "id": "8H29QBQW6S8PA",124 "type": "WORK"125 }126 ],127 "birth_details": {128 "date_of_birth": "1995-05-30"129 },130 "identification_documents": [131 {132 "id": "786PFSYQ26QP8",133 "identification_number": "****",134 "issuing_country_code": "US",135 "type": "SOCIAL_SECURITY_NUMBER"136 }137 ],138 "emails": [139 {140 "email": "addEmail@126.com"141 }142 ],143 "percentage_of_ownership": "35",144 "controlling_influence": false145 }146 ]147 },148 "office_bearers": [149 {150 "id": "TTRH4NNMTGX5C",151 "names": [152 {153 "given_name": "MaryAPPROVED",154 "surname": "Davis",155 "id": "GBPDSUWXFPLRC",156 "type": "LEGAL"157 }158 ],159 "citizenship": "US",160 "addresses": [161 {162 "address_line_1": "APPROVED 123 Main St",163 "admin_area_2": "100",164 "admin_area_1": "CA",165 "postal_code": "12345",166 "country_code": "US",167 "id": "SJ3UK766YFD5W",168 "type": "HOME"169 }170 ],171 "phone_numbers": [172 {173 "country_code": "1",174 "national_number": "33333333",175 "extension_number": "1",176 "id": "2A9WPLAEFLSXY",177 "type": "WORK"178 }179 ],180 "birth_details": {181 "date_of_birth": "1995-05-30"182 },183 "identification_documents": [184 {185 "id": "GWDXMMVXK72K8",186 "identification_number": "****",187 "issuing_country_code": "US",188 "type": "SOCIAL_SECURITY_NUMBER"189 }190 ],191 "emails": [192 {193 "email": "addEmail@126.com"194 }195 ]196 }197 ],198 "declarations": [199 {200 "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",201 "value": "YES"202 }203 ]204 },205 "agreements": [206 {207 "type": "TERMS_ACCEPTED",208 "accepted_time": "2022-06-02T01:23:45Z"209 }210 ],211 "external_id": "EXT-1714628922",212 "organization": "us",213 "user_id": "1714628922",214 "financial_instruments": {215 "banks": [216 {217 "id": "BA-57NNYBHUB3UGA",218 "last_4_digits": "8240",219 "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",220 "account_type": "CHECKING",221 "routing_number": "011200022",222 "currency_code": "USD",223 "country_code": "US",224 "account_holder_details": {225 "name": "MaryAPPROVED Inc."226 },227 "branch_code": "08501",228 "bank_name": "KEYBANK"229 }230 ]231 },232 "primary_currency_code": "USD",233 "soft_descriptor": "MARYAPPROVE",234 "capabilities": [235 {236 "name": "APPLE_PAY",237 "limits": [238 {239 "type": "AMOUNT",240 "unit": "USD",241 "value": "5000.00",242 "remaining_value": "5000.00",243 "implication_of_limit_breach": "BLOCK_CAPABILITY"244 }245 ],246 "grace_periods": [247 {248 "start_time": "2024-05-02T05:48:49.054Z",249 "expiry_time": "2024-06-01T05:48:49.054Z"250 }251 ],252 "status": "ACTIVE"253 },254 {255 "name": "GOOGLE_PAY",256 "limits": [257 {258 "type": "AMOUNT",259 "unit": "USD",260 "value": "5000.00",261 "remaining_value": "5000.00",262 "implication_of_limit_breach": "BLOCK_CAPABILITY"263 }264 ],265 "grace_periods": [266 {267 "start_time": "2024-05-02T05:48:49.054Z",268 "expiry_time": "2024-06-01T05:48:49.054Z"269 }270 ],271 "status": "ACTIVE"272 },273 {274 "name": "CUSTOM_CARD_PROCESSING",275 "limits": [276 {277 "type": "AMOUNT",278 "unit": "USD",279 "value": "5000.00",280 "remaining_value": "5000.00",281 "implication_of_limit_breach": "BLOCK_CAPABILITY"282 }283 ],284 "grace_periods": [285 {286 "start_time": "2024-05-02T05:48:49.054Z",287 "expiry_time": "2024-06-01T05:48:49.054Z"288 }289 ],290 "status": "ACTIVE"291 },292 {293 "name": "RECEIVE_MONEY",294 "limits": [295 {296 "type": "AMOUNT",297 "unit": "USD",298 "value": "5000.00",299 "remaining_value": "5000.00",300 "implication_of_limit_breach": "BLOCK_CAPABILITY"301 }302 ],303 "grace_periods": [304 {305 "start_time": "2024-05-02T05:48:49.054Z",306 "expiry_time": "2024-06-01T05:48:49.054Z"307 }308 ],309 "status": "ACTIVE"310 },311 {312 "name": "WITHDRAW_MONEY",313 "status": "NEED_DATA"314 }315 ],316 "process_view": {317 "processes": [318 {319 "name": "MANAGED_PATH_BO_COLLECTION",320 "status": "COMPLETED",321 "capabilities": [322 {323 "name": "RECEIVE_MONEY"324 },325 {326 "name": "GOOGLE_PAY"327 },328 {329 "name": "APPLE_PAY"330 },331 {332 "name": "CUSTOM_CARD_PROCESSING"333 },334 {335 "name": "WITHDRAW_MONEY"336 }337 ]338 },339 {340 "name": "MANAGED_PATH_KYC_VERIFICATION",341 "status": "NEED_MORE_DATA",342 "capabilities": [343 {344 "name": "CUSTOM_CARD_PROCESSING",345 "limits": [346 {347 "type": "AMOUNT",348 "unit": "USD",349 "value": "5000.00",350 "remaining_value": "5000.00",351 "implication_of_limit_breach": "BLOCK_CAPABILITY"352 }353 ],354 "grace_periods": [355 {356 "start_time": "2024-05-02T05:48:49.054Z",357 "expiry_time": "2024-06-01T05:48:49.054Z"358 }359 ]360 },361 {362 "name": "APPLE_PAY",363 "limits": [364 {365 "type": "AMOUNT",366 "unit": "USD",367 "value": "5000.00",368 "remaining_value": "5000.00",369 "implication_of_limit_breach": "BLOCK_CAPABILITY"370 }371 ],372 "grace_periods": [373 {374 "start_time": "2024-05-02T05:48:49.054Z",375 "expiry_time": "2024-06-01T05:48:49.054Z"376 }377 ]378 },379 {380 "name": "RECEIVE_MONEY",381 "limits": [382 {383 "type": "AMOUNT",384 "unit": "USD",385 "value": "5000.00",386 "remaining_value": "5000.00",387 "implication_of_limit_breach": "BLOCK_CAPABILITY"388 }389 ],390 "grace_periods": [391 {392 "start_time": "2024-05-02T05:48:49.054Z",393 "expiry_time": "2024-06-01T05:48:49.054Z"394 }395 ]396 },397 {398 "name": "GOOGLE_PAY",399 "limits": [400 {401 "type": "AMOUNT",402 "unit": "USD",403 "value": "5000.00",404 "remaining_value": "5000.00",405 "implication_of_limit_breach": "BLOCK_CAPABILITY"406 }407 ],408 "grace_periods": [409 {410 "start_time": "2024-05-02T05:48:49.054Z",411 "expiry_time": "2024-06-01T05:48:49.054Z"412 }413 ]414 },415 {416 "name": "WITHDRAW_MONEY"417 }418 ]419 },420 {421 "name": "MANAGED_PATH_BO_VERIFICATION",422 "status": "NEED_MORE_DATA",423 "capabilities": [424 {425 "name": "GOOGLE_PAY",426 "limits": [427 {428 "type": "AMOUNT",429 "unit": "USD",430 "value": "500000.00",431 "remaining_value": "500000.00",432 "implication_of_limit_breach": "BLOCK_CAPABILITY"433 }434 ]435 },436 {437 "name": "WITHDRAW_MONEY",438 "limits": [439 {440 "type": "AMOUNT",441 "unit": "USD",442 "value": "500000.00",443 "remaining_value": "500000.00",444 "implication_of_limit_breach": "BLOCK_CAPABILITY"445 }446 ]447 },448 {449 "name": "APPLE_PAY",450 "limits": [451 {452 "type": "AMOUNT",453 "unit": "USD",454 "value": "500000.00",455 "remaining_value": "500000.00",456 "implication_of_limit_breach": "BLOCK_CAPABILITY"457 }458 ]459 },460 {461 "name": "RECEIVE_MONEY",462 "limits": [463 {464 "type": "AMOUNT",465 "unit": "USD",466 "value": "500000.00",467 "remaining_value": "500000.00",468 "implication_of_limit_breach": "BLOCK_CAPABILITY"469 }470 ]471 },472 {473 "name": "CUSTOM_CARD_PROCESSING",474 "limits": [475 {476 "type": "AMOUNT",477 "unit": "USD",478 "value": "500000.00",479 "remaining_value": "500000.00",480 "implication_of_limit_breach": "BLOCK_CAPABILITY"481 }482 ]483 }484 ]485 },486 {487 "name": "MANAGED_PATH_KYC_COLLECTION",488 "status": "COMPLETED",489 "capabilities": [490 {491 "name": "APPLE_PAY"492 },493 {494 "name": "GOOGLE_PAY"495 },496 {497 "name": "WITHDRAW_MONEY"498 },499 {500 "name": "CUSTOM_CARD_PROCESSING"501 },502 {503 "name": "RECEIVE_MONEY"504 }505 ]506 }507 ]508 },509 "links": [510 {511 "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TMBGTLZJK6L38",512 "rel": "self",513 "method": "GET"514 },515 {516 "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TMBGTLZJK6L38",517 "rel": "edit",518 "method": "PATCH"519 }520 ]521}