Connected Path Upfront Onboarding
Overview
With Upfront onboarding, you ask your sellers to connect with PayPal before buyers make PayPal payments through your platform.
Upfront onboarding allows you to onboard both business sellers with PayPal business accounts and casual sellers with their personal PayPal accounts.
How it works
You post a PayPal signup link on your website for your sellers and PayPal handles the rest.
This signup flow uses an in-context experience through an integrated mini-browser to keep your sellers on your website and minimizes the number of pages to navigate.
Note: If your sellers already have a PayPal account, the sellers must agree to grant permission to you to facilitate payments on their behalf. After they agree, they can accept PayPal payments. If your sellers do not have a PayPal account, they are prompted to create one, after which they can grant you consent.
Integration steps
- Make a Partner Referrals API call.
- Display the sign-up form in a mini-browser.
- Get seller's onboarding status.
1. Make a Partner Referrals API call
Call the Partner Referrals API to provide your sellers with required PayPal account and permissions fields in the mini-browser.
Sample request
Using your access token, send the following items in the request body to /v1/customer/partner-referrals
:
Parameter | Type | Description |
---|---|---|
customer_data |
object | The seller's business or personal data required to create an account. |
requested_capabilities |
An array. Contains the capability object. |
An array of capabilities to enable for the seller.
Important: To call PayPal APIs on the seller's behalf, you must enable the |
web_experience_preference |
object | The preference to customize the web experience of the customer. |
collected_consents |
An array. Contains the legal_consent object |
An array of all consents to collect from sellers.
Important: If
|
products |
An array. Contains the product_name object. |
An array of PayPal products. Set to EXPRESS_CHECKOUT . |
Note:1The
integration_details
object defines the integration information. This object contains therest_third_party_details
object, which defines a group of third-party REST properties, including therest_endpoint_feature
object that defines an array of features that the partner can access in PayPal on behalf of the merchant. The merchant grants permission for these features to the partner:
PAYMENT
. Use PayPal to process the seller's payments and initiate steps to authorize and capture the seller's payments.REFUND
. Initiate a refund for a specific transaction.PARTNER_FEE
. Automatically deduct the partner's fee from each PayPal transaction before the remaining balance settles to the seller's PayPal account. The fee amount is subject to the seller's agreement with the partner.DELAY_FUNDS_DISBURSEMENT
. Hold and release the seller's funds in accordance with partner's policy.READ_SELLER_DISPUTE
Share the seller's PayPal dispute data from the PayPal Resolution Center with the partner.UPDATE_SELLER_DISPUTE
. Enable the partner to manage PayPal disputes and chargebacks on behalf of the seller. Includes permission to furnish the seller's information and supporting documents to PayPal.
curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partner-referrals \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"customer_data": {
"partner_specific_identifiers": [{
"type": "TRACKING_ID",
"value": "1506721845"
}]
},
"requested_capabilities": [{
"capability": "API_INTEGRATION",
"api_integration_preference": {
"partner_id": "BSD55M2TSQT72",
"rest_api_integration": {
"integration_method": "PAYPAL",
"integration_type": "THIRD_PARTY"
},
"rest_third_party_details": {
"partner_client_id": "AViNcnTmPaYZ3VltsmWEN3UmogFcZnjKsnqaitDo2cHrEEl1Rlns4GSz36CSUl69q9eADJwEItR0Rq7M",
"feature_list": [
"PAYMENT",
"REFUND",
"PARTNER_FEE",
"DELAY_FUNDS_DISBURSEMENT"
]
}
}
}],
"web_experience_preference": {
"partner_logo_url": "https://example.com/paypal.jpg",
"return_url": "https://example.com/return",
"action_renewal_url": "https://example.com/renew-prefill-url"
},
"collected_consents": [{
"type": "SHARE_DATA_CONSENT",
"granted": true
}],
"products": [
"EXPRESS_CHECKOUT"
]
}'
Sample response
A successful call returns a 201 created
status code and these HATEOAS links:
- A
self
link that shows the referral data - An
action_url
link that redirects sellers to complete the sign-up process
Note: The
action_url
will expire after its first use. If the seller did not complete the onboarding flow, you can make aGET
call on theself
link to re-initialize theaction_url
or make a newPOST
to the ``/v1/customer/partner-referrals` API.
{
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
"rel": "self",
"method": "GET",
"description": "The read referral data shared by the partner."
},
{
"href": "https://api.sandbox.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
"rel": "action_url",
"method": "GET",
"description": "The target web redirect URL for the next action."
}]
}
2. Display the sign-up form in a mini-browser
Use the returned action_url
to redirect users to the PayPal integrated sign-up flow in a mini-browser.
<div dir="ltr" style="text-align: left;" trbidi="on">
<script>
(function(d, s, id) {
var js, ref = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s);
js.id = id;
js.async = true;
js.src = "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";
ref.parentNode.insertBefore(js, ref);
}
}(document, "script", "paypal-js"));
</script>
<a data-paypal-button="true" href="<action_url>&displayMode=minibrowser" target="PPFrame">Sign up for PayPal</a>
</div>
Sellers click on the link and return to your site upon sign-up completion.
3. Get seller's onboarding status
You must ensure sellers have confirmed their email address before you can process transactions. To do this, check seller onboarding status information by passing your partner_id
and their merchant_id
as path parameters to /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}
.
Sample request
curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations/8LQLM2ML4ZTYU \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Sample response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows referral data. You can process transactions when the response shows:
payments_receivable
flag is trueprimary_email_confirmed
flag is trueoauth_third_party
is not blank and has third party permissions
{
"merchant_id": "8LQLM2ML4ZTYU",
"products": [{
"name": "PAYFLOW_PRO",
"vetting_status": "APPROVED",
"active": true
},
{
"name": "EXPRESS_CHECKOUT",
"active": true
}],
"payments_receivable": true,
"primary_email": "example@gmail.com",
"primary_email_confirmed": true,
"date_created": "2016-09-14 12:03:25 PDT",
"granted_permissions": ["AIR_TRAVEL", "INVOICING", "RECURRING_PAYMENT_REPORT"],
"api_credential": {
"signature": {
"api_user_name": "example_api1.gmail.com",
"api_password": "7QPZJL5PX2TT94RX",
"signature": "Ak0kqXY-wqI.w.dfyQrwACtkK4HcMNxGdvADyrIE8QLgZWyIDNJSDlQ1e"
}
},
"oauth_integrations": [{
"integration_type": "OAUTH_THIRD_PARTY",
"oauth_third_party": [{
"partner_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
"merchant_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
"scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/payment/authcapture", "https://uri.paypal.com/services/payments/refund"]
},
{
"partner_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
"merchant_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
"scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/payment/authcapture"]
}]
}],
"limitations": [{
"name": "MRCHT - Pending User Agreement",
"restrictions": ["ACH IN", "Withdraw Money", "Remove Bank", "Refunds to Buyer", "Close Account", "Send Money", "Remove Card"]
},
{
"name": "Seller linked merchant",
"restrictions": ["ACH IN", "Send Money", "Refunds to Buyer", "Receive/Request Money", "Remove Bank", "Remove Card", "Withdraw Money", "Close Account"]
}]
}