# Build onboarding into your software (/platforms/seller-onboarding/build-onboarding) Integrate PayPal seller onboarding into your software, enabling easy signup and API credential sharing to manage transactions and cart capabilities. ## How it works [#how-it-works] Set up your software package to onboard sellers with PayPal if you create a downloadable ecommerce software package for sellers. A seller signs up with PayPal with a signup link embedded in your software package. After the seller completes signup, PayPal shares the seller's REST API credentials with the software package. Use the seller's API credentials to make the API calls to PayPal. This integration only includes cart capabilities. It does not include other features such as a Platform Fee, Delayed Disbursement, Partner Reporting, or the Disputes API. > **Info:** Note: Build onboarding into software will not work with Onboarding after payment. You cannot use this integration if you want to onboard sellers after payment. Onboarding after payment only supports 3rd party-hosted SaaS platform in which you are the 3rd party that is allowed to facilitate payments on behalf of the sellers. ## Know before you code [#know-before-you-code] > **Info:** ### To use this integration, you must [#to-use-this-integration-you-must] > > * Be an [approved partner](/platforms/get-started). > * Have an access token > * Inform your sellers of [PayPal's Seller Protection policy](https://www.paypal.com/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. > > [Get access token](/platforms/get-started#exchange-your-api-credentials-for-an-access-token) > **Info:** ### This integration uses the Partner Referrals API: [#this-integration-uses-the-partner-referrals-api] > > * The payment features available to your sellers vary by the type of onboarding you choose. See [onboarding options](/platforms/seller-onboarding) for more information. > * Use Postman to explore and test PayPal APIs. > > [See Partner Referrals API](/api/partner-referrals/v2) ## 1. Generate signup link [#1-generate-signup-link] Call the Partner [Referrals API](/api/partner-referrals/v2) to generate a link that redirects your sellers to sign up with PayPal. Pass your seller's information during the API call to pre-fill the PayPal signup form with your seller's information. ### Modify the sample request [#modify-the-sample-request] Copy the sample request and modify it as follows: * Change `ACCESS-TOKEN` to 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). * Change `PRODUCTS` to a value from the [products](/api/partner-referrals/v2/definitions/product) array. The [products](/api/partner-referrals/v2/definitions/product) array value determines the type of payment your seller can accept. `Express Checkout` includes the PayPal button, debit and credit cards, PayPal Credit, and alternative payment methods. `PPCP` includes the PayPal button and advanced credit and debit cards. * Change `SELLER-SINGLE-USE-TOKEN` to a one-time string to identify the seller. Create a random string between 43-128 bytes in length using only letters, numbers, dashes, and underscores. #### 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 '{ "operations": [ { "operation": "API_INTEGRATION", "api_integration_preference": { "rest_api_integration": { "integration_method": "PAYPAL", "integration_type": "FIRST_PARTY", "first_party_details": { "features": [ "PAYMENT", "REFUND" ], "seller_nonce": "SELLER-SINGLE-USE-TOKEN" } } } } ], "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/us/merchantsignup/partner/onboardingentry?token=NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==", "rel": "action_url", "method": "GET", "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser." } ] } ``` A successful request results in the following response: * 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. Place this link in a button or link tag to redirect your sellers to sign up with PayPal. The `action_url` expires after its first use. Get another link by making a `GET` request to the `self` link or by calling the [Partner Referrals API](/api/partner-referrals/v2) again. > **Info:** Note: If you make a GET call to the [Partner Referrals API](/api/partner-referrals/v2), the response returns only user data you have passed in about the seller and not any data the seller might have provided on [paypal.com](https://www.paypal.com/). ## 2. Embed signup link [#2-embed-signup-link] Use the following code and the `action_url` to redirect your seller to sign up with PayPal. ```text lineNumbers Sign up for PayPal ``` After the seller completes onboarding, pass a callback in the `data-paypal-onboard-complete` attribute. In response to this callback, PayPal returns an `authCode` and `sharedID`, which are required to get a seller access token. In this example, the `onboardedCallback` function passed to the `data-paypal-onboard-complete` attribute sends the `authCode` and `sharedId` to the seller's server. > **Info:** Note: This code sample renders the PayPal sign-up flow in a minibrowser by setting the displayMode query parameter to minibrowser. Minibrowsers must conform to [postMessage](https://caniuse.com/?search=postMessage) requirements. ## 3. Redirect seller to a return URL [#3-redirect-seller-to-a-return-url] When your seller completes the sign-up flow, they are shown a button that redirects them 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 didn't specify a return URL in your API call, then the button redirects the seller to the return URL set on your account. Work with your account manager to set a return URL. If you don't set a return URL on your account, then the button sends the seller to the PayPal dashboard for their account. ```text lineNumbers https://?merchantIdInPayPal=&permissionsGranted=false&accountStatus=BUSINESS_ACCOUNT&consentStatus=false&productIntentID=addipmt&isEmailConfirmed=true&returnMessage=To%20start%20accepting%20payments,%20please%20log%20in%20to%20PayPal%20and%20finish%20signing%20up. ``` During the redirect, PayPal loads the return URL in your seller's browser and attaches the following query parameters: | Parameter | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------- | | `merchantIdInPayPal` | The merchant ID of your seller's PayPal account. | | `permissionsGranted` | This parameter is set to `false`. | | `accountStatus` | Indicates what kind of account was created. For example, `BUSINESS_ACCOUNT` if a business account was created. | | `consentStatus` | This parameter is set to `false`. | | `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. | ## 4. Get seller access token [#4-get-seller-access-token] When your seller completes the sign-up flow, PayPal returns an `authCode` and `sharedId` to your seller's browser. Use the `authCode` and `sharedId` to get the seller's access token. Then, use this access token to get the seller's REST API credentials. ### Sample request and response [#sample-request-and-response] Use the following code to get the seller's access token: #### cURL sample request ```text lineNumbers curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \ -u 'SHARED-ID: PASSWORD' \ -d 'grant_type=authorization_code&code=AUTH-CODE&code_verifier=SELLER-TOKEN' ``` #### node sample request ```text lineNumbers var express = require('express'); var request = require('request'); express() .post('/seller-server/login-seller', function(req, res) { request.post('https://api-m.sandbox.paypal.com/v1/oauth2/token', { auth: { user: "SHARED-ID", pass: "" }, body: 'grant_type=authorization_code&code=AUTH-CODE&code_verifier=SELLER-TOKEN' }, function(err, response, body) { if (err) { console.error(err); return res.sendStatus(500); } // Get access token console.log(body.access_token); return res.end(); }); ``` #### Sample response ```text lineNumbers { "scope": "https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/payments/payment/authcapture openid https://uri.paypal.com/services/payments/refund https://uri.paypal.com/services/applications/webhooks", "access_token": "A23AAHclqoiifoeiP9H4jLNZ7OJjcPlvdANa3UoJ2Zq5qn_kg-Mf9eaV_gW8X2H4a3cXYc4jwnwcLukxiST4SkPesqAw-rn5Q", "token_type": "Bearer", "expires_in": 28799, "refresh_token": "R23AAG9SXLtr70FIgRGYWzFeon5pA8lwC6cX7F9pvK4db83uxptI5AuTw8jao55NowN5M37_1SBjvZ5kKAhoxZ4GtT1GacZEN5zdZP0AFjKU4N0-KYY6RYEk0rU4XW7D0878W54SYfbmE5pNHPnrA", "nonce": "2020-02-05T15:43:54ZiBnhkZ7DMRJpzXd_AhUCfHgT2fPBWicqo1r7A2zbAj8" } ``` > **Info:** **Note:** Only use the seller's access token returned by `grant_type=authorization_code`. For all other REST API calls that require an access token, use your access token. ## 5. Get seller REST API credentials [#5-get-seller-rest-api-credentials] Use your seller's REST API credentials to process payments and handle refunds. Get seller REST API credentials using the seller's access token. ### Modify the sample request [#modify-the-sample-request-1] * Copy the sample request and change `ACCESS-TOKEN` to the seller's 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). * The `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](https://www.paypal.com/). Hover over your name or profile icon on the top right, select **Account Settings** > **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](https://sandbox.paypal.com/). #### Sample request ```text lineNumbers curl -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{PARTNER-MERCHANT-ID}/merchant-integrations/credentials/ \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' ``` #### Sample response ```text lineNumbers { "client_id": "Ab27r3fkrQezHdcPrn2b2SYzPEldXx2dWgv76btVfI-eYF8KRAd2WxXAZyb0ETygSNeHBthzlxjlQ_qw", "client_secret": "EAcTvpnDHZf4icl_2MPnt2gRpOxHVtaQJChWU3PrRbYR4uyvUXV6h4DWQjm7XOfdnk_OrEEWdxY2eUG3", "payer_id": "CG5RZJV4NR5P4" } ``` ## Next steps [#next-steps] Add more payment methods > **Info:** Accept Payments > > Choose your payment method.