Onboard Before Payment
Last updated: Aug 15th, 7:03am
You can connect your sellers with PayPal before they accept PayPal payments from buyers on your platform.
Know before you code
- You must be an approved partner to use this integration.
- You must have an access token.
- This integration uses the Partner Referrals API.
- You can use webhooks during seller onboarding. See the webhooks reference for more information.
- It is crucial that you inform your sellers of PayPal's Seller Protection policy , so they are aware of use cases that invalidate that protection, such as shipping to an address other than the one in the transaction confirmation.
-
1. Review the onboarding checklist with your account manager
Before generating the PayPal sign-up link, work with your account manager to determine what types of PayPal accounts you will allow for your sellers, the types of payment options you will make available to them, and more. Use the onboarding checklist to learn more.
2. Generate a PayPal sign-up link
Passing your seller's information during the API call will pre-fill the PayPal sign-up flow with your seller's information. To generate a sign-up link that redirects your sellers to sign up with PayPal, copy the following code and modify it.
Sample request
API used: Partner Referrals API
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer <Access-Token>" \4 -d '{5 "tracking_id": "<Tracking-ID>",6 "operations": [7 {8 "operation": "API_INTEGRATION",9 "api_integration_preference": {10 "rest_api_integration": {11 "integration_method": "PAYPAL",12 "integration_type": "THIRD_PARTY",13 "third_party_details": {14 "features": [15 "PAYMENT",16 "REFUND"17 ]18 }19 }20 }21 }22 ],23 "products": [24 "EXPRESS_CHECKOUT"25 ],26 "legal_consents": [27 {28 "type": "SHARE_DATA_CONSENT",29 "granted": true30 }31 ]32}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Token
to your access token. - Change
products
to the value you want for your sellers. The products array value determines which type of payment your seller can accept.Express Checkout
includes the debit and credit cards, PayPal button, PayPal Credit, and alternative payment methods.PPCP
includes the PayPal button and advanced credit and debit cards. Sellers can also accept alternative payment methods such as Pay upon Invoice. - Optional: Pass a tracking ID in the tracking_id field. You can use this ID to track the status of your seller as they complete onboarding.
Step result
A successful request results in the following:
- A return status code of HTTP
201 Created
. - A HATEOAS
self
link. You can make aGET
request to this link to retrieve the referral data and to reinitialize theaction_url
. - A HATEOAS
action_url
link. You can place this link in a button or link tag to redirect your sellers to sign up with PayPal. Theaction_url
expires after its first use. You can reinitialize it by making aGET
request to theself
link or by making another Partner Referrals API call.
Sample response
1{2 "links": [3 {4 "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",5 "rel": "self",6 "method": "GET",7 "description": "Read Referral Data shared by the Caller."8 },9 {10 "href": "https://www.sandbox.paypal.com/us/merchantsignup/partner/onboardingentry?token=NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",11 "rel": "action_url",12 "method": "GET",13 "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser."14 }15 ]16}
3. Add the PayPal sign-up link on your site
You can place the action_url
in a button or link to redirect the seller to PayPal for sign up. Alternatively, you can render the PayPal sign-up flow in a mini-browser by using the following code:
1<div dir="ltr" style="text-align: left;" trbidi="on">2 <script>3 (function(d, s, id) {4 var js, ref = d.getElementsByTagName(s)[0];5 if (!d.getElementById(id)) {6 js = d.createElement(s);7 js.id = id;8 js.async = true;9 js.src = "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";10 ref.parentNode.insertBefore(js, ref);11 }12 }(document, "script", "paypal-js"));1314 </script>15 <a data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame">Sign up for PayPal</a>16</div>
4. Redirect the seller back to your site
When your seller completes the sign-up flow, they are redirected to the return URL you specified in the partner_config_override/return_url
field of the Partner Referrals API. If no return URL is set on your account, then the seller is redirected to the PayPal dashboard for their account.
During the redirect, PayPal loads the return URL in your seller's browser and attaches the following query parameters:
Parameter | Description |
---|---|
merchantId |
The unique ID of the seller in your system that you specified in the Partner Referrals API call in the tracking_id field. |
merchantIdInPayPal |
The merchant ID of your seller's PayPal account. |
permissionsGranted |
A Boolean indicating whether the seller granted you the permissions you specified in the Partner Referrals API call. |
accountStatus |
PayPal sends BUSINESS_ACCOUNT if a business account was created; otherwise, nothing is sent. |
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 hardcoded message containing next steps for the seller to take with PayPal. PayPal only sends this message for business accounts where the email address is not confirmed. PayPal does not send this message for any account where product name is PPCP . |
riskStatus |
The product provisioning status. PayPal only sends this for accounts where product name is PPCP . Possible values are SUBSCRIBED , SUBSCRIBED_WITH_LIMIT , DECLINED , MANUAL_REVIEW , and NEED_MORE_DATA. |
Sample request
Copy the following code and use it to redirect the seller back to your site.
https://<Return-URL>?merchantId=<Tracking-ID>&merchantIdInPayPal=<Merchant-ID-In-PayPal>&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.
5. Track seller onboarding status
Seller onboarding is complete when the following requirements are met:
- Seller creates a PayPal account.
- Seller grants you permission for the features you set.
- Seller confirms the email address of the account.
To track your seller's status in meeting these requirements, you can make a show seller status call.
Sample request
Copy the following code and modify it:
1curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{partner_merchant_id}/merchant-integrations/{seller_merchant_id} \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer <Access-Token>"
Modify the code
After you copy the code in the sample request, change Access-Token
to your access token and modify the partner_merchant_id
and the seller_merchant_id
as follows:
partner_merchant_id
is the merchant ID of your PayPal account. To find the merchant ID of your PayPal account, log in to your PayPal account at paypal.com, click on the Settings icon, click on Business information, and look for PayPal Merchant ID. To find the merchant ID of your sandbox account, follow the same instructions on sandbox.paypal.com.
seller_merchant_id
is the merchant ID of the seller's PayPal account. To get your seller's merchant ID, you can read the merchantIdInPayPal
query parameter attached to the return URL when the seller is redirected back to your site. You can also query it directly by the tracking ID you specified in the Partner Referrals call by calling GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id={tracking_id}
.
Step result
A successful request results in the following:
- A return status code of HTTP
200 OK
. - A JSON response body that shows referral data. This response body does not return user data but returns information on whether or not the merchant is onboarded and is eligible to process transactions.
- The
payments_receivable
is true. - The
primary_email_confirmed
is true. - The
oauth_third_party
contains permissions granted.
Sample response with products set to PPCP
1{2 "merchant_id": "CG5RZJV4NR5P4",3 "tracking_id": "1537989077589",4 "products": [5 {6 "name": "PPCP_CUSTOM"7 }8 ],9 "payments_receivable": true,10 "primary_email_confirmed": true,11 "products.vetting status": "SUBSCRIBED",12 "capabilities[name==CUSTOM_CARD_PROCESSING].status": "ACTIVE",13 "capabilities[name==CUSTOM_CARD_PROCESSING].limits": "undefined",14 "oauth_integrations": [{15 "integration_type": "OAUTH_THIRD_PARTY",16 "integration_method": "PAYPAL",17 "oauth_third_party": [18 {19 "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",20 "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",21 "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]22 }23 ]24 }]25}
Sample response with products set to EXPRESS_CHECKOUT
1{2 "merchant_id": "CG5RZJV4NR5P4",3 "tracking_id": "1537989077589",4 "products": [5 {6 "name": "EXPRESS_CHECKOUT"7 }8 ],9 "payments_receivable": false,10 "primary_email_confirmed": false,11 "oauth_integrations": [{12 "integration_type": "OAUTH_THIRD_PARTY",13 "integration_method": "PAYPAL",14 "oauth_third_party": [15 {16 "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",17 "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",18 "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]19 }20 ]21 }]22}
URL onboarding
Use URL onboarding only if you have already onboarded with URL onboarding or if you have a specific use case for URL onboarding. With URL onboarding, sellers are required to complete all sign-up fields. Sellers must also have a PayPal business account. Casual sellers are not supported.
Example URL
1https://www.paypal.com/bizsignup/partner/entry?&partnerClientId=<var><partner_client_id></var>&partnerId=<var><partner_payer_id></var>&partnerLogoUrl=<var><partner_logo_url></var>&returnToPartnerUrl=<var><return_url_for_done_page_button></var>&product=ppcp&integrationType=FO&features=PAYMENT,REFUND</var>
Parameter | Description |
---|---|
channelId |
Set to partner . |
partnerId |
The merchant ID of your PayPal account. To find the merchant ID of your PayPal account, log in to your PayPal account at paypal.com, click on the Settings icon, click on Business information and look for PayPal Merchant ID. To find the merchant ID of a sandbox account, follow the same instructions on sandbox.paypal.com. |
partnerClientId |
Your client ID. |
returnToPartnerUrl |
The URL you want to redirect your seller to after completing sign up. Not specifying a return URL in this sign-up link follows the same behavior as not specifying a return URL when calling the Partner Referrals API. |
partnerLogoUrl |
The URL to retrieve your logo from to be displayed during the onboarding process. Applies only if you're not loading the sign-up flow in a mini-browser. If you do not specify a logo URL in this sign-up link, the logo URL set on your account will be used. You can work with your account manager to set the logo URL on your account. |
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. If you do not specify features in this sign-up link, the features enabled for your account are used. Work with your account manager to enable features. |
showPermissions |
A Boolean that if set to true shows permissions in the onboarding flow. |
integrationType |
The type of integration between you and your sellers. To specify OAUTH_THIRD_PARTY , set to TO . |