marketplaces

Marketplaces URL Onboarding

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

URL onboarding is a variation of Upfront onboarding that streamlines the onboarding process.

In standard Upfront onboarding, you make an API call to pre-fill information in some of the PayPal account onboarding fields offered to your sellers. You forego this API call in URL onboarding and require your sellers to complete all sign-up fields.

URL onboarding allows you to onboard both business sellers with PayPal business accounts and casual sellers with their personal PayPal accounts.

How it works

You send your sellers a URL with static parameters, and your sellers complete account signup on their own.

Integration steps

Onboarding sellers using the URL method requires PayPal for Marketplaces approval and a PayPal REST API access token. See Marketplaces Prerequisites for more information.

  1. Place a PayPal signup URL on your site.
  2. Whitelist the return URL to return users to your site.
  3. Let your sellers know to complete signup.

Place a PayPal signup URL on your site

Add a sign-up URL to your site in a link or button that directs sellers to either create a PayPal account or log into an existing PayPal account and configure it to accept payments.

channelId The channel. Set to partner.
partnerId Your PayPal account number.
partnerClientId Your client ID.
returnToPartnerUrl The URL to return to your site. You need to whitelist this URL to return sellers to your site.
partnerLogoUrl The URL to your logo. Can be displayed during the onboarding process. Applies only if you're not using in-context display through a mini-browser.
merchantId The unique ID of the seller in your system. Required if you intend to use REST APIs to show the seller’s account status.
productIntentId Set to addipmt.
features For the list of supported features, review our permissions page.
showPermissions A Boolean that if set to true shows permissions in the onboarding flow.
Note: PayPal generates permissions based on the feature list that you specify.
integrationType The type of integration between you and your sellers. To specify OAUTH_THIRD_PARTY, set to TO.

Example URL

https://www.paypal.com/us/merchantsignup/partner/onboardingentry?channelId=partner&productIntentId=addipmt&partnerId=your_partner_id&returnToPartnerUrl=https://www.YourWebsite.com&integrationType=TO&showPermissions=true&features=PAYMENT,REFUND&partnerLogoUrl=https://www.YourWebsite.com/logo.png&merchantId=your_merchant_id&partnerClientId=partner_client_id

Whitelist the return URL

Send your PayPal account manager the return URL passed in returnToPartnerUrl. to whitelist your URL and return your sellers to your site.

Note: If you do not whitelist your return URL. the seller is redirected to the account set-up page.

Complete signup

Sellers will receive a welcome email from PayPal after they configure their accounts. Your sellers need to confirm the email address associated with their account by clicking the link provided and following the accompanying instructions.

Show seller account status

You can, optionally, discover where your sellers are in the account integration process.

  1. Send your partner_id and merchant_handle as path parameters in a GET /v1/customer/partners call. Where partner_id is your payer_id and merchant_handle is the merchantId set for a seller.

    GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id=merchant_handle
    
  2. A successful call returns the merchant_id and a HATEOAS link to access status data for the integration. Use the HATEOAS link returned to obtain the integration data for the specified seller.

    {
      "merchant_id": "RH6V5EPUPUW3S",
      "tracking_id": "karricepnoint1",
      "links": [{
        "href": "https://api.sandbox.paypal.com/v1/customer/partners/XJPHPNFGXYGG6/merchant-integrations/RH6V5EPUPUW3S",
        "rel": "get",
        "method": "GET"
      }]
    }
    

Show account status

  1. Send your partner_id and merchantId as path parameters in a GET /v1/customer/partners call. Where partner_id is your payer_id and merchant_id is the merchantId set for a seller.

    GET /v1/customer/partners/partner_id/merchant-integrations/merchant_id
    
  2. A successful response returns:

    • The payer ID of the seller if the seller has granted permission to access their account.
    • The tracking ID of the seller, which is the ID that you created when you shared customer data.
    • The email confirmation status. The value is true or false.
    • A list of permissions that the seller has granted you
    • The product for which the seller has been onboarded (such as Express Checkout).
    • The product status, which is active or inactive.
    • Indicates whether the seller is restricted from receiving payments. Value is true or false.
    {
      "merchant_id": "T49KQUTWRGKBJ",
      "tracking_id": "Karrisunitrackingid",
      "products": [{
        "name": "EXPRESS_CHECKOUT"
      }],
      "payments_receivable": true,
      "primary_email_confirmed": false,
      "oauth_integrations": [{
      "integration_type": "OAUTH_THIRD_PARTY",
        "integration_method": "PAYPAL",
        "oauth_third_party": [{
          "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu - Dq ",
          "merchant_client_id": "AUUGsIswpCCUumSVGkWrK3ZP-i3haGh_zbtygOWfquRgVIPPQgS44JBYYkZVRz3HgQ2iTOEvRNMiDV ",
          "scopes": [
          "https://uri.paypal.com/services/payments/realtimepayment",
          "https://uri.paypal.com/services/payments/refund",
          "https://uri.paypal.com/services/payments/payment/authcapture"
          ]
        }]
      }]
    }
    

Next

Feedback