Build onboarding into your software
DocsCurrent
If you create downloadable ecommerce software packages for online sellers, you can set up your software package to include onboarding sellers with PayPal. Your software package must retrieve the REST API credentials of the seller who downloaded the package to include onboarding. This page explains how to retrieve the seller's REST API credentials.
Know before you code
- You must be an approved partner to use this integration.
- You must have an access token.
- The payment features available to your sellers vary by the type of onboarding you choose. See onboarding options for more information.
- This integration uses the Partner Referrals API. You must maintain your server for both making the request to generate the onboarding URL and to return it to the shopping cart plugin.
- 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.
Use Postman to explore and test PayPal APIs.
How it works
Your seller clicks on a sign-up link embedded in your software package, which redirects them to PayPal for sign-up. After completing sign-up, PayPal shares the seller's REST API credentials with the software package. You 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.
1. Generate sign-up link
Call the Partner Referrals API to generate a link that redirects your sellers to sign up with PayPal. Passing your seller's information during the API call will pre-fill the PayPal sign-up flow with your seller's information.
Request sample
curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-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-Nonce>"
}
}
}
}
],
"products": [
"EXPRESS_CHECKOUT"
],
"legal_consents": [
{
"type": "SHARE_DATA_CONSENT",
"granted": true
}
]
}'
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 a value from the products array. 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. - Change
Seller-Nonce
to a one-time string to identify the seller. This string must be a high-entropy cryptographic random string with a length of 43-128 bytes. This string accepts letters, numbers, dashes, and underscores, but not other special characters.
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.
Note: If you call
GET /v2/customer/partner-referrals/{partner_referral_id}
, 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.
Sample response
{
"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."
}
]
}
2. Embed sign-up link
Use the following code and the action_url
to redirect your seller to PayPal for sign up:
<script>
function onboardedCallback(authCode, sharedId) {
fetch('/seller-server/login-seller', {
method: 'POST',
headers: {
'content-type': 'application/json'
},
body: JSON.stringify({
authCode: authCode,
sharedId: sharedId
})
}).then(function(res) {
if (!res.ok) {
alert("Something went wrong!");
}
});
}
</script>
<a target="_blank" data-paypal-onboard-complete="onboardedCallback" href="<Action-URL>&displayMode=minibrowser" data-paypal-button="true">Sign up for PayPal</a>
<script id="paypal-js" src="https://www.sandbox.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js"></script>
After the seller completes onboarding, PayPal returns an authCode
and sharedId
to the seller's browser. The authCode
and sharedId
are required to get seller access token. For PayPal to return the authCode
and sharedId
, you must pass a callback in the data-paypal-onboard-complete
attribute. In this example, the onboardedCallback
function passed to the data-paypal-onboard-complete
attribute sends the authCode
and sharedId
to the seller's server.
Note: This code sample renders the PayPal sign-up flow in a minibrowser by setting the
displayMode
query parameter tominibrowser
. In addition, minibrowsers must conform to postMessage requirements.
3. Redirect seller
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. If you did not 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 no return URL is set on your account, then the button sends the seller 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 | |
---|---|---|
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. |
Sample request
https://<Return-URL>?merchantIdInPayPal=<Merchant-ID-In-PayPal>&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.
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
In this step, use the following code to get the seller's access token:
- cURL
- Node
1curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token2-u <Shared-ID>:3-d 'grant_type=authorization_code&code=<Auth-Code>&code_verifier=<Seller-Nonce>'
Sample response
{
"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"
}
Note: Only use the seller's access token returned by
grant_type=authorization_code
in Step 5. For all other REST API calls that require an access token, use your access token.
5. Get seller REST API credentials
Use the seller's access token to get your seller's REST API credentials:
Request sample
curl -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{partner_merchant_id}/merchant-integrations/credentials/ \
-H 'Authorization: Bearer <Seller-Access-Token>' \
-H 'Content-Type: application/json'
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. 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.
Sample response
{
"client_id": "Ab27r3fkrQezHdcPrn2b2SYzPEldXx2dWgv76btVfI-eYF8KRAd2WxXAZyb0ETygSNeHBthzlxjlQ_qw",
"client_secret": "EAcTvpnDHZf4icl_2MPnt2gRpOxHVtaQJChWU3PrRbYR4uyvUXV6h4DWQjm7XOfdnk_OrEEWdxY2eUG3",
"payer_id": "CG5RZJV4NR5P4"
}
Use your seller's REST API credentials for processing payments and handling refunds.