URL Onboarding

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

The URL onboarding option requires less setup than Upfront onboarding, but requires that your merchants complete all signup fields. You use a URL with static parameters to direct the merchant to PayPal. You don’t have to call the REST API to prefill information, but you might have to whitelist the return URL.

Prerequisites

Before you can use the Connected Onboarding API:

Integration steps

To use the URL option to onboard your merchants:

1. Required Place a PayPal signup URL on your site.
2. Required Whitelist the return URL.
3. Required Confirm your merchant's email address.
4. Optional but recommended Show your merchant account status.

Place a PayPal signup URL on your site

Add a link or button to your site that directs merchants to create a PayPal account, or to log into an existing PayPal account and configure it to accept payments. In the URL, pass the following parameters:

channel_id The channel. Set to partner.
partner_id Your payer ID, which is your PayPal account number.
partner_client_id The partner's client ID.
return_to_partner_url The URL to return to your site. You might need to whitelist this URL.
partner_logo_url The URL to your logo. Can be displayed during the onboarding process. Applies only if the partner is not using in-context display through a mini-browser.
merchant_id The unique ID of the merchant in your system. Required if the partner intends to use REST APIs to show the merchant’s account status.
product_intent_id Set to addipmt.
features For the list of supported features, review our permissions page
show_permissions 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 merchants. To specify OAUTH_THIRD_PARTY, set to TO.

Here’s a sample 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

To return the merchant to your site, ask your PayPal account manager to whitelist the URL. If you do not whitelist this URL, the merchant is redirected to the account setup page.

Confirm your merchant's email address

After you create the merchant account, the merchant receives a welcome email. To confirm the email associated with the account, the merchant should click the link in the email and follow the instructions.

Show your merchant account status

The following sample call and parameters shows the merchant’s encrypted account number (payer_id) and HATEOAS links that let you access the status of the integration:

GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id=merchant_handle
  • partner_id. Your payer_id.

  • merchant_handle. The ID you created for the merchant when you shared customer data with the call to POST /v1/customer/partner-referrals.

The call returns the merchant ID and a HATEOAS link to access status data for the integration:

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

Use the following HATEOAS link, which includes your partner_id and the encrypted ID of the merchant, to obtain the integration data for the specified merchant:

"href": "/v1/customer/partners/XJPHPNFGXYGG6/merchant-integrations/RH6V5EPUPUW3S"

Or, use GET to retrieve the status of the account:

GET /v1/customer/partners/partner_id/merchant-integrations/merchant_id

The response includes:

  • The payer ID of the merchant if the merchant has granted permission to access their account.
  • The tracking ID of the merchant, 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 merchant has granted you
  • The product for which the merchant has been onboarded (such as Express Checkout).
  • The product status, which is active or inactive.
  • Indicates whether the merchant is restricted from receiving payments. Value is true or false.

For example:

{
  "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": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GW
      xe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu - Dq ",
      "merchant_client_id": "AUUGsIswpCCUumSVGkWrK3ZP-i3haGh_zbtygOWfquRgVIPPQgS44JBYYkZVRz3HgQ2iTOEvRNM
      iDV ",
      "scopes": [
        "https://uri.paypal.com/services/payments/realtimepayment",
        "https://uri.paypal.com/services/payments/refund",
        "https://uri.paypal.com/services/payments/payment/authcapture"
      ]
    }]
  }]
}

Webhooks

When you send a transaction to PayPal for a merchant who has not completed PayPal account setup, the status of the transaction is set to pending. PayPal sends a PAYMENT.CAPTURE.PENDING webhook with the reason code Seller_setup_pending.

Once the merchant has completed PayPal account setup, PayPal sends these webhooks:

  • PAYMENT.CAPTURE.COMPLETED to indicate that the payment capture has changed from pending to completed.
  • MERCHANT.ONBOARDING.COMPLETED to indicate that the merchant has completed account setup. You can subscribe to webhooks to be alerted when a merchant's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the merchant account is closed, or the account setup consents have been revoked.

For more information about these webhook events, see Webhook event names.

Congratulations

You have completed connected path onboarding.

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