# Onboard sellers before payment (/platforms/seller-onboarding/before-payment) ## How it works [#how-it-works] You can connect your sellers with PayPal before they accept PayPal payments from payers on your platform. How it works ## Know before you code [#know-before-you-code] > **Info:** ### To use this integration, you must: [#to-use-this-integration-you-must] > > * You must be an approved partner to use this integration. > * You must have an [access token](/platforms/create-account/#link-exchangeyourapicredentialsforanaccesstoken/). > * This integration uses the [Partner Referrals API](/api/partner-referrals/v2/) > * Inform your sellers of [PayPal's Seller Protection policy](https://www.paypal.com/us/webapps/mpp/security/seller-protection/), 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. Set up webhooks [#1-set-up-webhooks] Webhooks are HTTP callbacks that receive notification messages for events. You can subscribe to webhooks from the developer portal or by making an API call. You'll need to subscribe to the following webhooks for onboarding: * `MERCHANT.ONBOARDING.COMPLETED`: This webhook is triggered when the seller has fulfilled all onboarding required and has given you permissions. * `MERCHANT.PARTNER-CONSENT.REVOKED`: This webhook is triggered when the seller has removed your permissions. To subscribe to webhooks from your developer portal: 1. Select **Apps & Credentials**. 2. Select the name of your REST app. 3. Go to **Sandbox Webhooks** > **Add Webhook**. 4. Enter the URL for your listener. 5. Add the event name by clicking the associated check boxes and select **Save**. To subscribe to webhooks by making an API call, see [Webhooks](/api/webhooks/v1#webhooks_post/) for the sample requests and responses. ## 2. Generate a signup link [#2-generate-a-signup-link] Pass your seller's information in the [Partner Referrals API](/api/partner-referrals/v2/) call. The PayPal signup flow will automatically fill with your seller's information. Generate a signup link that redirects your sellers to sign up with PayPal. ### Modify the code [#modify-the-code] Copy the sample request and modify it as follows: * Replace `ACCESS-TOKEN` with your access token. * Replace `BN-CODE` to your [PayPal Attribution ID](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution. To find your BN code, see [Code and Credential Reference.](/platforms/create-account/#link-bncode) * Set `products` to the type of payment you want for your sellers. The products array value determines which payment types your sellers can accept. For more information, see `products` in the [Partner Referrals API](/api/partner-referrals/v2/) page. The two payment types include: * `EXPRESS_CHECKOUT` includes debit and credit cards * `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. For more information, see `tracking_id` in the [List seller tracking information](/api/partner-referrals/v2) page. ### Sample request and response [#sample-request-and-response] #### Sample request ```text lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -d '{ "tracking_id": "merchantref1", "operations": [ { "operation": "API_INTEGRATION", "api_integration_preference": { "rest_api_integration": { "integration_method": "PAYPAL", "integration_type": "THIRD_PARTY", "third_party_details": { "features": [ "PAYMENT", "REFUND" ] } } } }], "products": [ "EXPRESS_CHECKOUT" ], "legal_consents": [ { "type": "SHARE_DATA_CONSENT", "granted": true } ] }' ``` #### Sample response ```text lineNumbers { "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==", "rel": "self", "method": "GET", "description": "Read referral data shared by the caller." }, { "href": "https://www.sandbox.paypal.com/partnerexp/appEntry?referralToken=ZGY2M2NjN2YtMjFhZi00NzBjLTlmMzMtNGU3NWNjNWM0ZjE4SlVTSEFJRG9vSmQ4QVpQVDFxaFUzbjhNWlBjemhHLy96VWFwNHp3amJkST12Mg==", "rel": "action_url", "method": "GET", "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser." } ] } ``` ### Step result [#step-result] A successful request results in the following: * A return status code of HTTP 201 Created. * A HATEOAS self link. Make a GET request to this link to retrieve the referral data and to reinitialize the action\_url. * A HATEOAS action\_url link. Make a note of this link. The link can be placed in a button or link tag to redirect your sellers to sign up with PayPal. The action\_url expires after one use. Refresh the link by making a GET request to the self link or by making another [Partner Referrals API](/api/partner-referrals/v2/) call. > **Info:** **Note:** If you call GET /v2/customer/partner-referrals/\{partner\_referral\_id}, the response only returns the user data you have passed for the seller. It won't return any data the seller might have provided on paypal.com. ## 3. Add signup link to your site [#3-add-signup-link-to-your-site] Insert the `action_url` in a button or a link to redirect the seller to the PayPal signup page. You can also render the PayPal signup flow in a mini-browser by using the following code: ```text lineNumbers
Sign up for PayPal
``` ## 4. Redirect seller to a return URL [#4-redirect-seller-to-a-return-url] After your seller signs up, they are redirected to the return URL you specified in the `partner_config_override/return_url` field of the [Partner Referrals API](/api/partner-referrals/v2/). If you don't specify a return URL, then the seller is redirected to the PayPal dashboard for their account. The following code sample redirects the seller back to your site in the Partner Referrals API. ### Sample request [#sample-request] ```text lineNumbers https://?merchantId=&merchantIdInPayPal=&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. ``` | 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` | 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:
**SUBSCRIBED:** Product provisioning is complete and no additional details are required.**SUBSCRIBED\_WITH\_LIMIT:** Product provisioning is complete with a feature limitation, such as a transaction limit.**IN\_REVIEW:** Review is in progress for product provisioning.**NEED\_MORE\_DATA:** The merchant needs to provide supplementary data for product provisioning.**DENIED:** Not approved. The merchant needs to try again. | ## 5. Track seller onboarding status [#5-track-seller-onboarding-status] Onboarding is complete when the seller has done the following: * Created a PayPal account. * Granted you permission for the [features](/api/partner-referrals/v2#definition-third_party_details) you set. * Confirmed the email address of the account. Make a [show seller status](/api/partner-referrals/v2) call to track your seller's onboarding status. You can receive a notification when your seller completes onboarding by subscribing to the `MERCHANT.ONBOARDING.COMPLETED` webhook. This webhook is triggered when the seller has fulfilled all onboarding requirements. ### Modify the code [#modify-the-code-1] Copy the sample request and modify it as follows: * Replace `ACCESS-TOKEN` with your access token. * Replace `BN-CODE` with your [PayPal Attribution ID](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution. To find your BN code, see [Code and Credential Reference.](/platforms/create-account/#link-bncode) * Replace `PARTNER-MERCHANT-ID` with your merchant ID. * To get your merchant ID, log in to your PayPal account at [paypal.com](/dashboard/). Hover over your name or profile icon on the top right and select **Account Settings** > **Business information** > **PayPal Merchant ID**. * To find the merchant ID of your sandbox account, follow the same instructions on [sandbox.paypal.com](https://www.sandbox.paypal.com/us/home/). * Replace `SELLER-MERCHANT-ID` with the merchant ID of the seller's PayPal account. * To get your seller's merchant ID, look at 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}`. For more information, see [List seller tracking information](/api/partner-referrals/v2). ### Sample request [#sample-request-1] ```text lineNumbers curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{PARTNER-MERCHANT-ID}/merchant-integrations/{SELLER-MERCHANT-ID} \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' ``` ### Step result [#step-result-1] 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 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 [#sample-response] In this response, `products` is set to `Express_Checkout`. ```text lineNumbers { "merchant_id": "5VT3RDX64P5Z6", "tracking_id": "merchantref1", "products": [{ "name": "EXPRESS_CHECKOUT", "status": "ACTIVE" }, { "name": "PPCP_STANDARD", "vetting_status": "SUBSCRIBED", "capabilities": [ "INSTALLMENTS", "SUBSCRIPTIONS", "ACCEPT_DONATIONS", "PAYPAL_CHECKOUT", "GUEST_CHECKOUT", "PAYPAL_CHECKOUT_ALTERNATIVE_PAYMENT_METHODS", "SEND_INVOICE", "QR_CODE", "WITHDRAW_FUNDS_TO_DOMESTIC_BANK", "PAYPAL_CHECKOUT_PAY_WITH_PAYPAL_CREDIT" ] } ], "capabilities": [{ "name": "INSTALLMENTS", "status": "ACTIVE" }, { "name": "PAYPAL_CHECKOUT", "status": "ACTIVE" }, { "name": "SEND_INVOICE", "status": "ACTIVE" }, { "name": "ACCEPT_DONATIONS", "status": "ACTIVE" }, { "name": "SUBSCRIPTIONS", "status": "ACTIVE" }, { "name": "PAYPAL_CHECKOUT_PAY_WITH_PAYPAL_CREDIT", "status": "ACTIVE" }, { "name": "GUEST_CHECKOUT", "status": "ACTIVE" }, { "name": "QR_CODE", "status": "ACTIVE" }, { "name": "PAYPAL_CHECKOUT_ALTERNATIVE_PAYMENT_METHODS", "status": "ACTIVE" } ], "payments_receivable": true, "legal_name": "Firstname Lastname", "primary_email": "test@example.com", "primary_email_confirmed": false, "oauth_integrations": [{ "integration_type": "OAUTH_THIRD_PARTY", "integration_method": "PAYPAL", "oauth_third_party": [{ "partner_client_id": "B_AhEDQSJmQb9fK4lIyGOQZEwPVBrrk44Fz2vjfXmv2Tpuc1pt16Mb9h6Ua9pnq1SYvjSy1fOuKXFA2NLw", "merchant_client_id": "B_AGDGPKGC1P28B65QYRvOmmNe-7JKnEMqIt_H_CMFsXAR_ZuaSLaQBtIKiatmJsv5_ZtxLvp_qPkptoHg", "scopes": [ "https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/reporting/search/read", "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" } ``` ### Sample response [#sample-response-1] In this response, `products` is set to `PPCP_CUSTOM`. ```text lineNumbers { "merchant_id": "CG5RZJV4NR5P4", "tracking_id": "merchantref1", "products": [ { "name": "PPCP_CUSTOM" } ], "payments_receivable": true, "primary_email_confirmed": true, "products.vetting status": "SUBSCRIBED", "capabilities[name==CUSTOM_CARD_PROCESSING].status": "ACTIVE", "capabilities[name==CUSTOM_CARD_PROCESSING].limits": "undefined", "oauth_integrations": [{ "integration_type": "OAUTH_THIRD_PARTY", "integration_method": "PAYPAL", "oauth_third_party": [ { "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq", "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ", "scopes": [ "https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture" ] } ] }] } ``` ## URL onboarding [#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 signup fields. Sellers must also have a PayPal business account. Casual sellers are not supported. **Note:** For new integrations, use the Partner Referrals API to onboard your sellers. ### Example URL [#example-url] ```text lineNumbers https://www.paypal.com/bizsignup/partner/entry?&partnerClientId=&partnerId=&partnerLogoUrl=&returnToPartnerUrl=&product=ppcp&integrationType=TO&features=PAYMENT,REFUND ``` ## Reference [#reference] | 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](/dashboard). Hover over your name or profile icon on the top right and select **Account Settings**\*\*>\*\* **Business information**\*\*>\*\* **PayPal Merchant ID**. To find the merchant ID of your sandbox account, follow the same instructions on [sandbox.paypal.com](http://sandbox.paypal.com/). | | `partnerClientId` | Your client ID. | | `returnToPartnerUrl` | The URL you want to redirect your seller to after completing signup. Not specifying a return URL in this signup link follows the same behavior as not specifying a return URL when calling the Partner Referrals API. | | `partnerLogoUrl` | The URL for the logo to be displayed during the onboarding process. This applies only if you're not loading the signup flow in a mini-browser. If you do not specify a logo URL in this signup 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 signup 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`. | ## Next steps [#next-steps] Add more payment methods > **Info:** Accept Payments > > Choose your payment method.