Managed Onboarding Integration Guide

Important: PayPal for Marketplaces is a limited-release solution at this time. It 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:

  • Register your PayPal marketplace.

  • Learn about REST API authentication and headers.

  • Learn how to handle webhooks. PayPal sends webhook notifications whenever limitations on merchant accounts are added or modified, or when any type of payment is blocked for an account.

Integration steps

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

1. Required Create a reference account for your merchant.
2. Required Set account permissions.
3. Required Set 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/partners/merchant-accounts in the 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.

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 API Reference.

Additional options

Get merchant account status

After the account is created, show merchant status to show status for the account. Pass your payer_id and the payer_id of the managed account in the URI.

Note: You can get the account's payer_id from the create account response.

Here's a sample call to show the account status:

GET https://api.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations/7G4EPEEPEF74L

The response includes:

  • Email confirmation status (true or false).

  • List of permissions (if you requested them).

  • Whether the merchant has restrictions (true or false) on receiving payments.

Here’s a sample response:

{
  "merchant_id": "7G4EPEEPEF74L",
  "payments_receivable": true,
  "primary_email_confirmed": true,
  "date_created": "2017-10-12 17:08:14 PDT",
  "permissions": [
    "Account Management",
    "Settlement Reporting"
  ]
}

Update account

If you must update an account, you can do so in one of two 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 json_patch object with details of the update.

Here’s a snippet that 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 retrieve the updated account:

GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_payer_id}

For details, see Get status.

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.

Congratulations

You’ve completed Managed path onboarding.

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