Managed Path Onboarding

DocsLast updated: June 20th 2023, @ 1:03:22 pm

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

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/managed-accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <var>Access-Token</var>" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440000" \
-d '{
    "external_id": "user23_property_1"
    "country_code": "US",
    "email_id": "email@partner.com",
    "name": {
        "given_name": "John",
        "surname": "Collins",
    },
    "addresses": [
        {
            "type": "HOME",
            "address_line_1": "150 E San Fernando St",
            "admin_area_1": "CA",
            "admin_area_2": "San Jose",
            "postal_code": "95112",
            "country_code": "US"
        }
    ],
    "tax_id": {
        "type": "SOCIAL_SECURITY_NUMBER",
        "identifier": "123456789",
        "issuer": {
            "country_code": "US",
         }
     },
    "date_of_birth": "1990-01-01",
    "business_info": {
        "type": "PROPRIETORSHIP",
        "names": [
            {
                "type": "LEGAL",
                "business_name": "Demo 201 Inc."
            }
        ]
    },
    "terms_and_conditions_acceptance": {
        "acceptance_time": "2018-05-12T01:23:45.678Z",
        "accepted": true
    },
    "organization": "us/property_1",
    "user_id": "partner_user23"
}'

Sample response

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

{
    "payer_id": "7G4EPEEPEF74L",
    "external_id": "user23_property_1",
    "links":[
        {
            "rel":"self",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "GET"
        },
        {
            "rel":"edit",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "PATCH"
        }
    ]
}

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

{
  "id": "WH-3AE50806EM5305732-8C457463XB353952R",
  "event_version": "1.0",
  "create_time": "2018-05-24T07:18:28.264Z",
  "resource_type": "managed-accounts",
  "event_type": "CUSTOMER.MANAGED-ACCOUNT.UPDATED",
  "summary": "A merchant account was updated.",
  "resource": {
    "update_time": "2018-05-24T07:18:28.264Z",
    "payer_id": "7G4EPEEPEF74L",
    "external_id": "user23_property_1",
    "country_code": "US",
    "email_id": "email@partner.com",
    "name": {
        "given_name": "John",
        "surname": "Collins",
    },
    "addresses": [
        {
            "type": "HOME",
            "address_line_1": "150 E San Fernando St",
            "admin_area_1": "CA",
            "admin_area_2": "San Jose",
            "postal_code": "95112",
            "country_code": "US"
        }
    ],
    "tax_id": {
        "type": "SOCIAL_SECURITY_NUMBER",
        "identifier": "123456789",
        "issuer": {
            "country_code": "US",
        }
    },
    "date_of_birth": "1990-01-01",
    "business_info": {
        "type": "PROPRIETORSHIP",
        "names": [
            {
                "type": "LEGAL",
                "business_name": "Demo 201 Inc."
            }
        ]
    },
    "terms_and_conditions_acceptance": {
        "acceptance_time": "2018-05-12T01:23:45.678Z",
        "accepted": true
    },
    "organization": "us/property_1",
    "user_id": "partner_user23",
    "capabilities": [
        {
            "name": "WITHDRAW_MONEY",
            "status": "SUSPENDED",
            "limits": [
                {
                    "type": "AMOUNT",
                    "value": "5000.00 USD",
                    "remaining_value": "1000.00 USD"
                }
            ],
            "required_fields": [
                {
                    "requirement": "ALL_OF",
                    "fields": [
                        {
                            "path": "/identifications",
                            "link": {
                                "rel":"edit",
                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                                "method": "PATCH"
                            }
                        },
                        {
                            "path": "/business_info/identifications",
                            "link": {
                                "rel":"edit",
                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                                "method": "PATCH"
                            }
                        }
                    ]
                }
            ],
            "required_documents": [
                {
                    "requirement": "ONE_OF",
                    "documents": [
                        {
                            "name": "DRIVERS_LICENSE",
                            "entity": "STAKEHOLDER",
                            "entity_identifier": "ext_stakeholer_01",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        },
                        {
                            "name": "PASSPORT",
                            "entity": "STAKEHOLDER",
                            "entity_identifier": "ext_stakeholer_01",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        }
                    ]
                },
                {
                    "requirement": "ALL_OF",
                    "documents": [
                        {
                            "name": "UTILITY_BILL",
                            "entity": "BUSINESS",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        },
                        {
                            "name": "PROOF_OF_SHIPPING",
                            "entity": "ACCOUNT",
                            "additional_information": {
                                "type": "TRANSACTION",
                                "identifier": "2GG279541U471931P"
                            },
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "regulatory_obligations": [
        {
            "name": "MANAGED_PATH_KYC",
            "status": "NEED_MORE_DATA"
        },
        {
            "name": "MANAGED_PATH_1099_K",
            "status": "NEED_MORE_DATA"
        }
    ],
    "links":[
        {
            "rel":"self",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "PATCH"
        },
        {
            "rel":"edit",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "PATCH"
        }
    ]
  }
  "links": [
      {
          "href": "https://api-m.sandbox.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R",
          "rel": "self",
          "method": "GET"
      },
      {
          "href": "https://api-m.sandbox.paypal.com/v1/notfications/webhooks-events/WH-3AE50806EM5305732-8C457463XB353952R/resend",
          "rel": "resend",
          "method": "POST"
      }
  ]
  }
}

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

curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/customer/supporting-documents' \
 -H "Client-Info: anw" \
 -H "Authorization: Bearer <Access-Token>"" \
 -H "Content-Type: multipart/form-data; boundary=WebKitFormBoundarydCVmGbjc9rWllBlE' -F 'input={"manual_review_required": false,"verification_purpose": "PROOF_OF_IDENTITY"};type=application/json' \
 -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.

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

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

curl -v -X GET https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <var>Access-Token</var>" \
-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.

{
    "payer_id": "7G4EPEEPEF74L",
    "external_id": "user23_property_1",
    "country_code": "US",
    "email_id": "email@partner.com",
    "name": {
        "given_name": "John",
        "surname": "Collins",
    },
    "addresses": [
        {
            "type": "HOME",
            "address_line_1": "150 E San Fernando St",
            "admin_area_1": "CA",
            "admin_area_2": "San Jose",
            "postal_code": "95112",
            "country_code": "US"
        }
    ],
    "tax_id": {
        "type": "SOCIAL_SECURITY_NUMBER",
        "identifier": "123456789",
        "issuer": {
            "country_code": "US",
         }
     },
    "date_of_birth": "1990-01-01",
    "business_info": {
        "type": "PROPRIETORSHIP",
        "names": [
            {
                "type": "LEGAL",
                "business_name": "Demo 201 Inc."
            }
        ]
    },
    "terms_and_conditions_acceptance": {
        "acceptance_time": "2018-05-12T01:23:45.678Z",
        "accepted": true
    },
    "organization": "us/property_1",
    "user_id": "partner_user23",
    "capabilities": [
        {
            "name": "WITHDRAW_MONEY",
            "status": "SUSPENDED",
            "limits": [
                {
                    "type": "AMOUNT",
                    "value": "5000.00 USD",
                    "remaining_value": "1000.00 USD"
                }
            ],
            "required_fields": [
                {
                    "requirement": "ALL_OF",
                    "fields": [
                        {
                            "path": "/identifications",
                            "link": {
                                "rel":"edit",
                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                                "method": "PATCH"
                            }
                        },
                        {
                            "path": "/business_info/identifications",
                            "link": {
                                "rel":"edit",
                                "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                                "method": "PATCH"
                            }
                        }
                    ]
                }
            ],
            "required_documents": [
                {
                    "requirement": "ONE_OF",
                    "documents": [
                        {
                            "name": "DRIVERS_LICENSE",
                            "entity": "STAKEHOLDER",
                            "entity_identifier": "ext_stakeholer_01",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        },
                        {
                            "name": "PASSPORT",
                            "entity": "STAKEHOLDER",
                            "entity_identifier": "ext_stakeholer_01",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        }
                    ]
                },
                {
                    "requirement": "ALL_OF",
                    "documents": [
                        {
                            "name": "UTILITY_BILL",
                            "entity": "BUSINESS",
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        },
                        {
                            "name": "PROOF_OF_SHIPPING",
                            "entity": "ACCOUNT",
                            "additional_information": {
                                "type": "TRANSACTION",
                                "identifier": "2GG279541U471931P"
                            },
                            "link": {
                                "rel":"upload",
                                "href":"https://api-m.sandbox.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                                "method": "POST"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "regulatory_obligations": [
        {
            "name": "MANAGED_PATH_KYC",
            "status": "NEED_MORE_DATA"
        },
        {
            "name": "MANAGED_PATH_1099_K",
            "status": "NEED_MORE_DATA"
        }
    ],
    "links":[
        {
            "rel":"self",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "PATCH"
        },
        {
            "rel":"edit",
            "href":"https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
            "method": "PATCH"
        }
    ]
}

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