partners

Managed Path Onboarding

Important: PayPal for Partners 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.

Overview

You create PayPal business accounts for your sellers and manage all money movement in and out of the accounts to your sellers.

How it works

You create a managed account for each of your sellers. A managed account is a PayPal business account that you can access but your sellers cannot. You roll up and settle funds, to include disputes and chargebacks, from the managed account to your own PayPal account.

Integration steps

Creating and configuring managed accounts requires PayPal for Partners approval and a PayPal REST API access token.

  1. Create a managed account.

Create a managed account

Using your access token, create and configure a managed account. Pass the following parameters in the request body to POST /v1/customer/partners/merchant-accounts:

Parameter Type Description
owner_info object The account holder's information.
Important: Provide a unique email address as PayPal does not allow multiple accounts to share the same email address
business_info object The business information for the seller.
account_status enum The account status. Set to A for active. Other allowed values.
account_currency string The three-character ISO-4217 currency code for the account.
secondary_currency array, contains the currency_code object An array of the three-character ISO-4217 currency code for the secondary currencies.
payment_receiving_preferences object Available preferences.
account_relations array, contains the account_relations object An array of account relationships.
account_permissions array, contains the account_permissions object Available permissions.
timezone enum The time zone. Possible values
partner_merchant_external_id string An ID that the partner creates for the merchant account.
loginable Boolean Indicates whether the account allows the seller to log in. Set to FALSE.
partner_tax_reporting Boolean Indicates whether you report taxes for the account.
display_instructions_text_input Boolean Indicates whether to show the Special instructions to merchant field during checkout, unless the field is suppressed through other means. To display special instructions, set to TRUE.
signup_options object The options, preferences, and agreements for the account.

Request

Note the account permissions (account_permissions) and limitations (payment_receiving_preferences).

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "owner_info": {
    "email": "sydney@example.com",
    "name": {
      "prefix": "Mr",
      "given_name": "Victoria",
      "surname": "Asmania",
      "middle_name": "T.",
      "suffix": ""
    },
    "country_code_of_nationality": "AU",
    "addresses": [
      {
        "type": "HOME",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      }
    ],
    "date_of_birth": "1990-01-01",
    "phones": [
      {
        "type": "HOME",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      }
    ],
    "identifications": [
      {
        "value": "LICENSE_ABCD123",
        "type": "DRIVERS_LICENSE",
        "issuer_country_code": "AU",
        "masked": false
      }
    ]
  },
  "business_info": {
    "type": "ASSOCIATION",
    "sub_type": "ASSO_TYPE_INCORPORATED",
    "names": [
      {
        "type": "LEGAL",
        "name": "AU Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "value": "123423456723",
        "type": "ASSOCIATION_NUMBER",
        "issuer_country_code": "AU",
        "masked": false
      }
    ],
    "addresses": [
      {
        "type": "REGISTERED_OFFICE",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      },
      {
        "type": "MAILING_ADDRESS",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      },
      {
        "type": "WORK",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "61",
        "national_number": "0491570156"
      }
    ],
    "category": "1004",
    "sub_category": "2940",
    "merchant_category_code": "3011",
    "date_business_established": "2001-01-17",
    "date_of_registration": "2011-04-17",
    "dispute_email": "dispute@example.com",
    "business_sales_details": {
      "average_price": {
        "minimum_amount": {
          "currency_code": "AUD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "AUD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "AUD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "AUD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://www.example.AU.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      },
      "message": [
        {
          "type": "ONLINE",
          "headline": "Your online purchase",
          "logo_image_url": "https://example.com/logo/online/",
          "service_image_url": "https://example.com/service/online/",
          "seller_message": "Your online purchase"
        },
        {
          "type": "RETAIL",
          "headline": "Your retail purchase",
          "logo_image_url": "https://example.com/logo/retail/",
          "service_image_url": "https://example.com/service/retail/",
          "seller_message": "Your retail purchase"
        }
      ]
    },
    "country_code_of_incorporation": "AU",
    "stakeholders": [
      {
        "type": "CHAIRMAN",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "Victoria",
          "surname": "Asmania",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      },
      {
        "type": "SECRETARY",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "John",
          "surname": "Snow",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123JS",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      },
      {
        "type": "TREASURER",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "Josh",
          "surname": "Snow",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123JSY",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      }
    ]
  },
  "account_status": "A",
  "account_currency": "AUD",
  "secondary_currency": [
    "USD"
  ],
  "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": "https://example.com/alternate/",
    "display_instructions_text_input": true,
    "cc_soft_descriptor": "USCCSOFTDES",
    "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
    {
      "type": "PARTNER"
    }
  ],
  "account_permissions": [
    {
      "permissions": [
        "EXPRESS_CHECKOUT",
        "RECURRING_PAYMENT",
        "EXTENDED_PRO_PROCESSING",
        "EXCEPTION_PROCESSING",
        "MASS_PAY",
        "ENCRYPTED_WEBSITE_PAYMENTS"
      ]
    }
  ],
  "timezone": "Australia/Adelaide",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true
}'

Response

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

{
  "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"
    }
  ]
}

For any changes to account settings after creation, see Update Managed Accounts.

Next

Create a Checkout button

Feedback