Connected Path URL Onboarding

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 forgo 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

Your sellers click on a link and are redirected to complete account sign up on their own.

Integration steps

  1. Place a PayPal signup link on your site.
  2. Whitelist the return URL to return users to your site.
  3. Let your sellers know to complete signup.
  4. Show seller account status.

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

Example URL

https://www.paypal.com/us/merchantsignup/partner/onboardingentry?channelId=partner&productIntentId=addipmt&partnerId=your_partner_id&returnToPartnerUrl=your_website_link&integrationType=TO&showPermissions=true&features=PAYMENT,REFUND&partnerLogoUrl=your_website_logo_link&merchantId=your_merchant_id&partnerClientId=partner_client_id
Parameter Description
channelId Set to partner.
partnerId The payer_id of your PayPal account. To find the payer_id of your PayPal account, login to your PayPal account at paypal.com, navigate to My Profile by clicking on the Settings icon, and look for your Merchant account ID in My business info. To find the payer_id of a sandbox account, follow the same instructions on sandbox.paypal.com.
partnerClientId Your client ID.
returnToPartnerUrl The URL endpoint you want to redirect your seller to after completing signup. You need to whitelist this URL to return sellers to your site.
partnerLogoUrl The URL endpoint to retrieve your logo from. 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.
productIntentId Set to addipmt.
features The permissions a seller grants you to operate on their PayPal account. For example, specifying PAYMENT allows the seller to grant you permission to initiate and capture payment on their behalf. For the full list of permissions that can be granted by the seller, please see the 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.

Whitelist the return URL

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

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

Redirect the seller back to your site

Once your seller has completed the signup flow, they will be redirected to the return URL you whitelisted in the previous step. During the redirect, the following query parameters will be added:

Parameter Description
merchantId The unique ID of the seller in your system that you specified in the sign-up URL.
merchantIdInPayPal The payer_id of your seller's PayPal account.
permissionsGranted A Boolean indicating whether the seller granted you the permissions you specified in the sign-up link.
accountStatus Indicates what kind of account was created. For example, BUSINESS_ACCOUNT if a business account was created.
consentStatus A Boolean indicating whether the seller consented to share their credentials with you.
productIntentID It is set to addipmt.
isEmailConfirmed A Boolean indicating whether the seller has confirmed their email with PayPal.
returnMessage A message containing next steps for the seller to take with PayPal.

Request sample

https://return_url?merchantId=merchantId&merchantIdInPayPal=sellers_payer_id&permissionsGranted=true&accountStatus=BUSINESS_ACCOUNT&consentStatus=true&productIntentID=addipmt&isEmailConfirmed=true&returnMessage=To%20start%20accepting%20payments,%20please%20log%20in%20to%20PayPal%20and%20finish%20signing%20up.

Complete signup

Sellers receive a welcome email from PayPal after they configure their accounts. Your sellers must click the link and follow the instructions in the email to confirm the email address associated with their account. Once the email is confirmed, the account can be begin receiving payment.

Show seller account status

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

  1. Get an access token. To get an access token, pass your OAuth 2.0 credentials in a get access token call.

    Request sample

    curl -v https://api.sandbox.paypal.com/v1/oauth2/token \
      -H "Accept: application/json" \
      -H "Accept-Language: en_US" \
      -u "client_id:secret" \
      -d "grant_type=client_credentials"
    

    Response sample

    In response, the PayPal authorization server issues an access token.

    {
      "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
      "nonce": "2017-06-08T18:30:28ZCl54Q_OlDqP6-4D03sDT8wRiHjKrYlb5EH7Di0gRrds",
      "access_token": "Access-Token",
      "token_type": "Bearer",
      "app_id": "APP-80W284485P519543T",
      "expires_in": 32398
    }
    
  2. Send your partner_id and merchant_id as path parameters in a /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id} call. Where partner_id is your payer_id and merchant_id is the payer_id of the seller's PayPal account.

    Request sample

    curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations/F585Z5KDBHY6Q \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token"
    

    Response sample

    A successful request returns the HTTP 200 OK status code and a JSON response body that shows status details.

    {
      "merchant_id": "F585Z5KDBHY6Q",
      "tracking_id": "1",
      "products": [{
        "name": "EXPRESS_CHECKOUT",
        "status": "ACTIVE"
      }],
      "payments_receivable": true,
      "primary_email": "example-seller-95@mail.com",
      "primary_email_confirmed": true,
      "oauth_integrations": [{
          "integration_type": "OAUTH_THIRD_PARTY",
          "integration_method": "PAYPAL",
          "oauth_third_party": [
            {
              "partner_client_id": "Ac9ov4d_OiPP605qvHmdHJgX3iwtstM0RuqLVxwZkrXpbhpbjEcx--yMxkZaSCUJyEMm0yBVIlfNDhSO",
              "merchant_client_id": "AXXiUnipfsYkTdT_DmHpoe-qE4kYWjaRKPm-fSU2bV_NwrjnghsVKUiY1SgKd6oKVz1_R10MDt2N9nEM",
              "scopes": ["https://uri.paypal.com/services/payments/delay-funds-disbursement", "https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/customer/merchant-integrations/read", "https://uri.paypal.com/services/payments/payment/authcapture"]
            }
          ]
        }
      ],
      "primary_currency": "USD",
      "country": "US"
    }
    

Next

Create a Checkout button.

Feedback