Managed Onboarding Integration Guide

Important: PayPal for Marketplaces is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Overview

This guide shows you how to use the Managed path integration method to onboard your merchants so they can accept PayPal payments. With this integration, you can:

  • Create PayPal-managed reference accounts. A reference account is not accessible to your merchants.

  • Roll up and settle funds from your merchants’ reference accounts to the partner’s PayPal account.

  • Generate consolidated reports with data from your merchant accounts.

Prerequisites

Before you can use the Managed Onboarding API, you must:

Integration steps

To onboard managed sellers, you create a reference account for your merchants and set account permissions and limitations.

Tip: Try the Managed Onboarding API demo.
  • Click the Call Managed Onboarding API button to begin the demo.
  • At the end of the demo, view API history to see request and response information
1.RequiredCreate a reference account for your merchant.
2.RequiredSet account permissions.
3.RequiredSet account limitations.

Create a reference account for your merchant

Call this API endpoint and pass the listed parameters in the request body:

POST /v1/customer/partners/merchant-accounts
  • owner_info. The account holder's information. Be sure to provide a unique email address. PayPal does not allow multiple accounts to share the same email address.

  • business_info. Business information for the merchant.

  • account_currency. Three-letter ISO 4217 alphabetical currency code; for example, USD.

  • account_status. The status of the account. Set to A for “active.”

  • loginable. Set to FALSE to indicate that merchants cannot log in to the account.

  • partner_merchant_external_id. A unique ID that you assign to the account.

  • account_relations. Specify type as PARTNER to indicate that this account is tied to a partner account.

  • secondary_currency. Three-letter ISO 4217 alphabetical currency code; for example, USD.

  • payment_receiving_preferences. Preferences for receiving payments.

  • account_permissions. Permissions for the account.

  • timezone. The merchant's time zone.

  • partner_tax_reporting. Indicates whether the partner reports taxes for the merchant.

  • signup_options. The options that are applied after signup.

  • financial_info. The financial information.

A successful call includes these response fields:

  • payer_id. PayPal's ID for the account.

  • partner_merchant_external_id. The ID that you provided for the account.

  • HATEOAS links to update or replace the new account. For more information, see update account.

Here’s a sample response:

//Response
HTTP status code: 201 

HTTP Headers: 
"Content-Type": "application/json" 

Response payload:
{
  "payer_id": "7G4EPEEPEF74L",
  "partner_merchant_external_id": "abc123",
  "links": [
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "replace",
      "method": "POST"
    }
  ]
}

Note: For parameter details, see POST /v1/customer/partner-referrals in the Partner Referrals API reference.

Set account permissions

You can assign a set of permissions that allows you to perform specific types of processing for the account; for example, process direct credit card transactions, resolve disputes, and so on.

For a list of account permissions, see Managed account permissions.

Call the following API endpoint and pass the account_permissions parameter in the request body to update permissions on the account:

PATCH /v1/customer/partners/merchant-accounts/{merchant-payer-id}

Here's a code snippet for this parameter:

"account_permissions": [{
  "permissions": [
    "SETTLEMENT_REPORTING"
  ]
}]

By default, PayPal assigns the specified permissions to you, the API caller. However, you can use the third_party field to assign permissions to a specific account, identified by the payer_id. For example:

"account_permissions": [{
  "third_party": "7G4EPEEPEF74L"
  "permissions": \[
    "SETTLEMENT_REPORTING "
 ]
}]

Set account limitations

You can put a set of limitations on the managed account to block specified types of payments, such as from unconfirmed addresses, from currencies not held in the account, and so on.

Call the following API endpoint and pass the payment_receiving_preferences parameter to update the reference account:

POST /v1/customer/partners/merchant-accounts/merchant-payer-id

Here’s a code snippet for this parameter:

"payment_receiving_preferences": {
  "block_unconfirmed_us_address_payments": true,
  "block_non_us_payments": true,
  "block_echeck_payments": true,
  "block_cross_currency_payments": true,
  "block_send_money_payments": true,
  "alternate_payment_url": "www.original.com",
  "display_instructions_text_input": true,
  "cc_soft_descriptor": "USCCSOFTDES",
  "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
}

When you add, remove, update, or escalate a limitation for an account or block receipt of any type of payments for the account, a webhook notification is triggered.

Note: For parameter details, see the description of payment_receiving_preferences in the Managed Accounts API reference.

Additional options

Update account

If you must update an account, you can do so in one of these ways:

  • To update any part of the account:

    PATCH /v1/customer/partners/merchant-accounts/{merchant_payer_id}
    
  • To replace the entire account (for example if the data is corrupted):

    POST /v1/customer/partners/merchant-accounts/{merchant_payer_id}
    

When you update an account, you can add, remove, or replace data in the account.

In the merchant_payer_id parameter, pass the payer_id for the merchant of the account to update.

In the request body, pass a patch object with details of the update.

This snippet shows how to add a bank account to a merchant account:

PATCH https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L  
{
  "op": "add",
  "path": "/financial_info/bank_accounts",
  "value": [{
    "transfer_type": "NORMAL",
    "account_number": "11111113",
    "account_type": "CHECKING",
    "currency_code": "AUD",
    "identifiers": [{
        "type": "ROUTING_NUMBER_1",
        "value": "645"
      },
      {
        "type": "ROUTING_NUMBER_2",
        "value": "000"
      }
    ],
    "bank_name": "Bank of Australia",
    "branch_location": {
      "city": "Sydney",
      "country_code": "AU"
    }
  }]
}

This method returns an HTTP status code.

To replace the entire account with new data:

POST /v1/customer/partners/merchant-accounts/{merchant_payer_id}

In the merchant_payer_id parameter in the URL, pass the merchant's merchant_id, and in the request, pass all the information that you want for the account. For details, see Create a reference account for your merchant.

This table lists the paths where you can replace, add, or delete information by using the PATCH operation:

Path Replace Add Delete
/owner_info/name/prefix Yes Yes Yes
/owner_info/name/given_name Yes Yes No
/owner_info/name/surname Yes Yes No
/owner_info/name/middle_name Yes Yes Yes
/owner_info/name/suffix Yes Yes Yes
/owner_info/country_code_of_nationality Yes Yes No
/owner_info/addresses No Yes No
/owner_info/addresses/@type==home/line1 Yes Yes No
/owner_info/addresses/@type==home/line2 Yes Yes Yes
/owner_info/addresses/@type==home/city Yes Yes No
/owner_info/addresses/@type==home/state Yes Yes No
/owner_info/addresses/@type==home/country_code No Yes No
/owner_info/addresses/@type==home/postal_code Yes Yes No
/owner_info/date_of_birth Yes Yes No
/owner_info/ssn Yes Yes Yes
/owner_info/phones No Yes No
/owner_info/phones/@type==home No No Yes
/owner_info/phones/@type==home/country_code Yes Yes No
/owner_info/phones/@type==home/national_number Yes Yes No
/owner_info/phones/@type==mobile No No Yes
/owner_info/phones/@type==mobile/country_code Yes Yes No
/owner_info/phones/@type==mobile/national_number Yes Yes No
/owner_info/occupation Yes Yes Yes
/owner_info/identifications No Yes No
/owner_info/identifications/@type==social_security_number YesNo Yes
/owner_info/identifications/
@type==individual_tax_identification_number
YesNo Yes
/owner_info/identifications/@type==passport_number YesNo Yes
/owner_info/identifications/@type==pension_fund_id YesNo Yes
/owner_info/identifications/@type==medical_insurance_id YesNo Yes
/owner_info/identifications/@type==national_id YesNo Yes
/owner_info/identifications/@type==immigrant_id YesNo Yes
/owner_info/identifications/@type==drivers_license YesNo Yes
/owner_info/identifications/@type==social_insurance_number YesNo Yes
/business_info/type Yes Yes No
/business_info/sub_type Yes Yes Yes
/business_info/government_body Yes Yes Yes
/business_info/place_of_establishment No Yes No
/business_info/place_of_establishment/country_code Yes Yes No
/business_info/place_of_establishment/state Yes Yes No
/business_info/names No Yes No
/business_info/names/@type==legal/name Yes Yes No
/business_info/names/@type==doing_business_as No No Yes
/business_info/names/@type==doing_business_as/name Yes Yes No
/business_info/employer_identification_number Yes Yes Yes
/business_info/addresses/@type==work/line1 Yes Yes No
/business_info/addresses/@type==work/line2 Yes Yes Yes
/business_info/addresses/@type==work/city Yes Yes No
/business_info/addresses/@type==work/state Yes Yes No
/business_info/addresses/@type==work/country_code No Yes No
/business_info/addresses/@type==work/postal_code Yes Yes No
/business_info/addresses/@type==registered_office/line1 Yes Yes No
/business_info/addresses/@type==registered_office/line2 Yes Yes Yes
/business_info/addresses/@type==registered_office/city Yes Yes No
/business_info/addresses/@type==registered_office/state Yes Yes No
/business_info/addresses/@type==registered_office/country_code No Yes No
/business_info/addresses/@type==registered_office/postal_code Yes Yes No
/business_info/addresses/@type==mailing_address/line1 Yes Yes No
/business_info/addresses/@type==mailing_address/line2 Yes Yes Yes
/business_info/addresses/@type==mailing_address/city Yes Yes No
/business_info/addresses/@type==mailing_address/state Yes Yes No
/business_info/addresses/@type==mailing_address/country_code No Yes No
/business_info/addresses/@type==mailing_address/postal_code Yes Yes No
/business_info/phones No Yes No
/business_info/phones/@type==work/country_code Yes No No
/business_info/phones/@type==work/national_number Yes No No
/business_info/phones/@type==work/extension_number Yes Yes No
/business_info/phones/@type==business/country_code Yes No No
/business_info/phones/@type==business/national_number Yes No No
/business_info/identifications No Yes No
/business_info/identifications/@type==business_registration_number YesNo Yes
/business_info/identifications/@type==employer_identification_number YesNo Yes
/business_info/identifications/@type==value_added_tax_id YesNo Yes
/business_info/identifications/@type==association_number YesNo Yes
/business_info/identifications/@type==business_number YesNo Yes
/business_info/identifications/@type==company_number YesNo Yes
/business_info/identifications/@type==cooperative_number Yes No Yes
/business_info/category Yes Yes No
/business_info/sub_category Yes Yes No
/business_info/merchant_category_code Yes Yes No
/business_info/date_business_established Yes Yes No
/business_info/date_of_registration Yes Yes No
/business_info/dispute_email Yes Yes No
/business_info/customer_service/email Yes No No
/business_info/customer_service/phone No Yes No
/business_info/customer_service/phone/country_code Yes Yes No
/business_info/customer_service/phone/national_number Yes Yes No
/business_info/customer_service/phone/extension_number Yes Yes Yes
/business_info/business_sales_details/average_price/
minimum_amount/currency_code
No Yes No
/business_info/business_sales_details/average_price/
maximum_amount/currency_code
No Yes No
/business_info/business_sales_details/average_monthly_volume Yes Yes No
/business_info/business_sales_details/average_monthly_volume/
minimum_amount/currency_code
Yes Yes No
/business_info/business_sales_details/average_monthly_volume/
minimum_amount/value
Yes Yes No
/business_info/business_sales_details/average_monthly_volume/
maximum_amount/currency_code
Yes Yes No
/business_info/business_sales_details/average_monthly_volume/
maximum_amount/value
Yes Yes No
/business_info/business_sales_details/sales_venues No Yes No
/business_info/business_sales_details/sales_venues/
@type==ebay/ebay_id
Yes Yes Yes
/business_info/business_sales_details/sales_venues/
@type==other/description
Yes Yes Yes
/business_info/business_sales_details/website Yes Yes Yes
/business_info/business_sales_details/
revenue_from_online_sales
Yes Yes No
/business_info/country_code_of_incorporation Yes Yes Yes
/business_info/designation/title Yes Yes Yes
/business_info/designation/business_area Yes Yes Yes
/business_info/stakeholders Yes Yes Yes
/payment_receiving_preferences/
block_unconfirmed_us_address_payments
Yes Yes No
/payment_receiving_preferences/block_non_us_payments Yes Yes No
/payment_receiving_preferences/block_echeck_payments Yes Yes No
/payment_receiving_preferences/
block_cross_currency_payments
Yes Yes No
/payment_receiving_preferences/
block_send_money_payments
Yes Yes No
/payment_receiving_preferences/
alternate_payment_url
Yes Yes No
/payment_receiving_preferences/
display_instructions_text_input
Yes Yes No
/payment_receiving_preferences/
cc_soft_descriptor
Yes Yes No
/payment_receiving_preferences/
cc_soft_descriptor_extended
Yes Yes No
/secondary_currency No Yes No
/account_permissions No Yes Yes
/timezone Yes Yes No
/partner_merchant_external_id Yes Yes No
/partner_tax_reporting Yes Yes No
/inheritance/1 No Yes No
/inheritance/2 No Yes No
/inheritance/3 No Yes No
/inheritance/4 No Yes No
/inheritance/5 No Yes No
/inheritance/6 No Yes No
/inheritance/7 No Yes No
/inheritance/8 No Yes No
/financial_info/bank_accounts Yes Yes Yes

Congratulations

You’ve completed Managed path onboarding.

Next: To add PayPal to your checkout experience, see Orders Integration Guide.