marketplaces

Marketplaces Upfront Onboarding for Managed Path

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.

Overview

With Upfront onboarding, you create PayPal accounts for your sellers and manage all money movement in and out of the accounts to your sellers.

Upfront onboarding enables you to onboard sellers using PayPal business accounts.

How it works

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

Integration steps

Creating and configuring reference accounts requires PayPal for Marketplaces approval and a PayPal REST API access token. See Marketplaces Prerequisites.

  1. Create a seller reference account.

Create a seller reference account

Using your access token, create and configure a seller reference 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 Reference Accounts.

Next

Feedback