Managed Path Onboarding

Docs

Last updated: Aug 15th, 8:04am

Overview

With Managed Path onboarding, you control your seller's PayPal onboarding experience.

How it works

You create a managed account through which your seller's PayPal payments are processed. This managed account created on their behalf is a PayPal business account that you can access but your sellers cannot. You use this account to:

Hold seller funds

Withdraw to a seller's financial instrument

Provide PayPal with information needed about your seller to process their payments

Onboarding steps

Creating and configuring managed accounts requires PayPal Commerce Platform approval.

Create a managed account.

Managed account webhooks.

Upload supporting documents.

Get account details.

Create a managed account

Using your access token, create and configure a managed account for your seller. Pass the following fields in the request body to /v2/customer/managed-accounts:

Parameter	Type	Description
`external_id`	string	The partner-provided ID of the managed account.
`email_id`	string	The ID of the managed account as an email.
`country_code`	string	The two character ISO 3166-1 code that identifies the country or region.
`name`	object	The name of the party.
`addresses`	array, contains the `personal_address` object	An array of account holder addresses.
`phones`	array, contains the `personal_phone` object	An array of account holder phone numbers.
`identifications`	array, contains the `personal_identification` object	An array of document numbers that verify a person's identity.
`tax_id`	object	The account holder's tax ID.
`citizenship`	string	The two character ISO 3166-1 code of the acount holder's citizenship.
`date_of_birth`	string	The account holder's date of birth in Internet date and time `full-date` format.
`business_info`	object	The account's business information.
`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.
`secondary_currency_code`	array, contains the `currency_code` object	An array of additional currencies that this account can hold.
`financial_instruments`	object	An array of financial instruments.
`cc_soft_descriptor`	string	The name that appears on the buyer's bank or credit card statement. Supports only capital letters, numbers, spaces and the `.`, `-`, and `*` characters. With special characters, you must include one alphanumeric character.
`terms_and_conditions_acceptance`	object	Indicates that the account holder has accepted PayPal's terms and conditions.
`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.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/managed-accounts \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <var>Access-Token</var>" \
4-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440000" \
5-d '{
6    "external_id": "user23_property_1"
7    "country_code": "US",
8    "email_id": "email@partner.com",
9    "name": {
10        "given_name": "John",
11        "surname": "Collins",
12    },
13    "addresses": [
14        {
15            "type": "HOME",
16            "address_line_1": "150 E San Fernando St",
17            "admin_area_1": "CA",
18            "admin_area_2": "San Jose",
19            "postal_code": "95112",
20            "country_code": "US"
21        }
22    ],
23    "tax_id": {
24        "type": "SOCIAL_SECURITY_NUMBER",
25        "identifier": "123456789",
26        "issuer": {
27            "country_code": "US",
28         }
29     },
30    "date_of_birth": "1990-01-01",
31    "business_info": {
32        "type": "PROPRIETORSHIP",
33        "names": [
34            {
35                "type": "LEGAL",
36                "business_name": "Demo 201 Inc."
37            }
38        ]
39    },
40    "terms_and_conditions_acceptance": {
41        "acceptance_time": "2018-05-12T01:23:45.678Z",
42        "accepted": true
43    },
44    "organization": "us/property_1",
45    "user_id": "partner_user23"
46}'

Sample response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows managed account details.

1{
2    "payer_id": "7G4EPEEPEF74L",
3    "external_id": "user23_property_1",
4    "links":[
5        {
6            "rel":"self",
7            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
8            "method": "GET"
9        },
10        {
11            "rel":"edit",
12            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
13            "method": "PATCH"
14        }
15    ]
16}

You will also receive a webhook that details your next steps:

Webhook name	Action
`CUSTOMER.MANAGED-ACCOUNT.CREATED`	Create next account or continue on to Create Checkout button to your sellers.
`CUSTOMER.MANAGED-ACCOUNT.UPDATED`	More information on a seller is needed. Check the `required_documents` object for necessary documents to upload.

Managed account webhooks

In some cases, more information about a particular seller is needed for that seller to receive or withdraw money.

If you receive the CUSTOMER.MANAGED-ACCOUNT.UPDATED webhook upon creation of a managed account, upload the requested documents found in the required_documents object to the link provided in the response.

Note: For a requirement state of ALL_OF, send each of the listed items. For a requirement state of ONE_OF, send one of the listed possibilities.

Sample response

1{
2  "id": "WH-3AE50806EM5305732-8C457463XB353952R",
3  "event_version": "1.0",
4  "create_time": "2018-05-24T07:18:28.264Z",
5  "resource_type": "managed-accounts",
6  "event_type": "CUSTOMER.MANAGED-ACCOUNT.UPDATED",
7  "summary": "A merchant account was updated.",
8  "resource": {
9    "update_time": "2018-05-24T07:18:28.264Z",
10    "payer_id": "7G4EPEEPEF74L",
11    "external_id": "user23_property_1",
12    "country_code": "US",
13    "email_id": "email@partner.com",
14    "name": {
15        "given_name": "John",
16        "surname": "Collins",
17    },
18    "addresses": [
19        {
20            "type": "HOME",
21            "address_line_1": "150 E San Fernando St",
22            "admin_area_1": "CA",
23            "admin_area_2": "San Jose",
24            "postal_code": "95112",
25            "country_code": "US"
26        }
27    ],
28    "tax_id": {
29        "type": "SOCIAL_SECURITY_NUMBER",
30        "identifier": "123456789",
31        "issuer": {
32            "country_code": "US",
33        }
34    },
35    "date_of_birth": "1990-01-01",
36    "business_info": {
37        "type": "PROPRIETORSHIP",
38        "names": [
39            {
40                "type": "LEGAL",
41                "business_name": "Demo 201 Inc."
42            }
43        ]
44    },
45    "terms_and_conditions_acceptance": {
46        "acceptance_time": "2018-05-12T01:23:45.678Z",
47        "accepted": true
48    },
49    "organization": "us/property_1",
50    "user_id": "partner_user23",
51    "capabilities": [
52        {
53            "name": "WITHDRAW_MONEY",
54            "status": "SUSPENDED",
55            "limits": [
56                {
57                    "type": "AMOUNT",
58                    "value": "5000.00 USD",
59                    "remaining_value": "1000.00 USD"
60                }
61            ],
62            "required_fields": [
63                {
64                    "requirement": "ALL_OF",
65                    "fields": [
66                        {
67                            "path": "/identifications",
68                            "link": {
69                                "rel":"edit",
70                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
71                                "method": "PATCH"
72                            }
73                        },
74                        {
75                            "path": "/business_info/identifications",
76                            "link": {
77                                "rel":"edit",
78                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
79                                "method": "PATCH"
80                            }
81                        }
82                    ]
83                }
84            ],
85            "required_documents": [
86                {
87                    "requirement": "ONE_OF",
88                    "documents": [
89                        {
90                            "name": "DRIVERS_LICENSE",
91                            "entity": "STAKEHOLDER",
92                            "entity_identifier": "ext_stakeholer_01",
93                            "link": {
94                                "rel":"upload",
95                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
96                                "method": "POST"
97                            }
98                        },
99                        {
100                            "name": "PASSPORT",
101                            "entity": "STAKEHOLDER",
102                            "entity_identifier": "ext_stakeholer_01",
103                            "link": {
104                                "rel":"upload",
105                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
106                                "method": "POST"
107                            }
108                        }
109                    ]
110                },
111                {
112                    "requirement": "ALL_OF",
113                    "documents": [
114                        {
115                            "name": "UTILITY_BILL",
116                            "entity": "BUSINESS",
117                            "link": {
118                                "rel":"upload",
119                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
120                                "method": "POST"
121                            }
122                        },
123                        {
124                            "name": "PROOF_OF_SHIPPING",
125                            "entity": "ACCOUNT",
126                            "additional_information": {
127                                "type": "TRANSACTION",
128                                "identifier": "2GG279541U471931P"
129                            },
130                            "link": {
131                                "rel":"upload",
132                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
133                                "method": "POST"
134                            }
135                        }
136                    ]
137                }
138            ]
139        }
140    ],
141    "regulatory_obligations": [
142        {
143            "name": "MANAGED_PATH_KYC",
144            "status": "NEED_MORE_DATA"
145        },
146        {
147            "name": "MANAGED_PATH_1099_K",
148            "status": "NEED_MORE_DATA"
149        }
150    ],
151    "links":[
152        {
153            "rel":"self",
154            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
155            "method": "PATCH"
156        },
157        {
158            "rel":"edit",
159            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
160            "method": "PATCH"
161        }
162    ]
163  }
164  "links": [
165      {
166          "href": "https://api-m.sandbox.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
167          "rel": "self",
168          "method": "GET"
169      },
170      {
171          "href": "https://api-m.sandbox.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R/resend",
172          "rel": "resend",
173          "method": "POST"
174      }
175  ]
176  }
177}

Upload supporting documents

For certain sellers and markets, PayPal requires you to upload documents to verify the information you've provided.

Note: For more information on what documents are supported, ask your account manager. For more information about the endpoints, see Supporting Documents API Reference.

Sample request

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/customer/supporting-documents' \
2 -H "Client-Info: anw" \
3 -H "Authorization: Bearer <Access-Token>"" \
4 -H "Content-Type: multipart/form-data; boundary=WebKitFormBoundarydCVmGbjc9rWllBlE' -F 'input={"manual_review_required": false,"verification_purpose": "PROOF_OF_IDENTITY"};type=application/json' \
5 -F 'file1=@doc.jpeg" \

Sample response

A successful request returns the HTTP 201 CREATED status code and a JSON response body that shows file upload details.

1{
2  "file_reference": {
3    "id": "12312",
4    "reference_url": "/content/dam/paypal/s03/001/01/001/c0/3a/1f/s03-001-01-001-c03a1f5a-02a4-4cf9-bffa-aea05e4e90b8",
5    "content_type": "image/jpeg"
6  },
7  "links": [
8    {
9      "href": "https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/52055",
10      "rel": "self",
11      "method": "GET"
12    }
13  ]
14}

Get account details

Using your access token, pass the seller's payer_id for the value of merchant_payer_id to /v2/customer/managed-accounts/{merchant_payer_id} to get a managed account's details.

Sample request

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <var>Access-Token</var>" \
4-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440000"

Sample response

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

1{
2    "payer_id": "7G4EPEEPEF74L",
3    "external_id": "user23_property_1",
4    "country_code": "US",
5    "email_id": "email@partner.com",
6    "name": {
7        "given_name": "John",
8        "surname": "Collins",
9    },
10    "addresses": [
11        {
12            "type": "HOME",
13            "address_line_1": "150 E San Fernando St",
14            "admin_area_1": "CA",
15            "admin_area_2": "San Jose",
16            "postal_code": "95112",
17            "country_code": "US"
18        }
19    ],
20    "tax_id": {
21        "type": "SOCIAL_SECURITY_NUMBER",
22        "identifier": "123456789",
23        "issuer": {
24            "country_code": "US",
25         }
26     },
27    "date_of_birth": "1990-01-01",
28    "business_info": {
29        "type": "PROPRIETORSHIP",
30        "names": [
31            {
32                "type": "LEGAL",
33                "business_name": "Demo 201 Inc."
34            }
35        ]
36    },
37    "terms_and_conditions_acceptance": {
38        "acceptance_time": "2018-05-12T01:23:45.678Z",
39        "accepted": true
40    },
41    "organization": "us/property_1",
42    "user_id": "partner_user23",
43    "capabilities": [
44        {
45            "name": "WITHDRAW_MONEY",
46            "status": "SUSPENDED",
47            "limits": [
48                {
49                    "type": "AMOUNT",
50                    "value": "5000.00 USD",
51                    "remaining_value": "1000.00 USD"
52                }
53            ],
54            "required_fields": [
55                {
56                    "requirement": "ALL_OF",
57                    "fields": [
58                        {
59                            "path": "/identifications",
60                            "link": {
61                                "rel":"edit",
62                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
63                                "method": "PATCH"
64                            }
65                        },
66                        {
67                            "path": "/business_info/identifications",
68                            "link": {
69                                "rel":"edit",
70                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
71                                "method": "PATCH"
72                            }
73                        }
74                    ]
75                }
76            ],
77            "required_documents": [
78                {
79                    "requirement": "ONE_OF",
80                    "documents": [
81                        {
82                            "name": "DRIVERS_LICENSE",
83                            "entity": "STAKEHOLDER",
84                            "entity_identifier": "ext_stakeholer_01",
85                            "link": {
86                                "rel":"upload",
87                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
88                                "method": "POST"
89                            }
90                        },
91                        {
92                            "name": "PASSPORT",
93                            "entity": "STAKEHOLDER",
94                            "entity_identifier": "ext_stakeholer_01",
95                            "link": {
96                                "rel":"upload",
97                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
98                                "method": "POST"
99                            }
100                        }
101                    ]
102                },
103                {
104                    "requirement": "ALL_OF",
105                    "documents": [
106                        {
107                            "name": "UTILITY_BILL",
108                            "entity": "BUSINESS",
109                            "link": {
110                                "rel":"upload",
111                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
112                                "method": "POST"
113                            }
114                        },
115                        {
116                            "name": "PROOF_OF_SHIPPING",
117                            "entity": "ACCOUNT",
118                            "additional_information": {
119                                "type": "TRANSACTION",
120                                "identifier": "2GG279541U471931P"
121                            },
122                            "link": {
123                                "rel":"upload",
124                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
125                                "method": "POST"
126                            }
127                        }
128                    ]
129                }
130            ]
131        }
132    ],
133    "regulatory_obligations": [
134        {
135            "name": "MANAGED_PATH_KYC",
136            "status": "NEED_MORE_DATA"
137        },
138        {
139            "name": "MANAGED_PATH_1099_K",
140            "status": "NEED_MORE_DATA"
141        }
142    ],
143    "links":[
144        {
145            "rel":"self",
146            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
147            "method": "PATCH"
148        },
149        {
150            "rel":"edit",
151            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
152            "method": "PATCH"
153        }
154    ]
155}

Create Checkout button.

Managed Path Onboarding

Overview

How it works

Onboarding steps

Create a managed account

Sample request

Sample response

Managed account webhooks

Sample response

Upload supporting documents

Sample request

Sample response

Get account details

Sample request

Sample response

Next