On this page
No Headings
Last updated: June 26, 2026
Merchant-level vaulting supports a payer using a saved payment method with one merchant. For example, a payer saves their payment method at a merchant's website. The merchant's ecommerce is hosted by a third party. The third party saves payment methods for the merchant.
Take the following steps to onboard merchants for merchant-level vaulting.
Include the VAULT and BILLING_AGREEMENT values in the Partner Referral API call:
"features": [
"PAYMENT",
"REFUND",
"PARTNER_FEE",
"VAULT",
"BILLING_AGREEMENT"
]To process credit cards, debit cards, and PayPal, pass the products as PPCP and ADVANCED_VAULTING. To process PayPal only, pass the products as EXPRESS_CHECKOUTand ADVANCED_VAULTING.
"products": [
"PPCP",
"ADVANCED_VAULTING"
]Add capabilities with the value of PAYPAL_WALLET_VAULTING_ADVANCED:
"products": [
"PPCP",
"ADVANCED_VAULTING"
],
"capabilities": [
"PAYPAL_WALLET_VAULTING_ADVANCED"
]curl -L -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' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-d '{
"email": "[email protected]",
"individual_owners": [
{
"names": [
{
"given_name": "Firstname Lastname",
"full_name": "Firstname Lastname",
"type": "LEGAL",
"surname": "Vtwo"
}
],
"citizenship": "US",
"addresses": [
{
"address_line_1": "Brent Park",
"address_line_2": "",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95054",
"country_code": "US",
"type": "HOME"
}
],
"phones": [
{
"country_code": "1",
"national_number": "4089383848",
"type": "MOBILE"
}
],
"birth_details": {
"date_of_birth": "1990-01-01"
},
"type": "PRIMARY"
}
],
"business_entity": {
"business_type": {
"type": "INDIVIDUAL",
"subtype": "ASSO_TYPE_INCORPORATED"
},
"business_industry": {
"category": "1004",
"sub_category": "2025"
},
"business_incorporation": {
"incorporation_country_code": "US",
"incorporation_date": "1986-12-29"
},
"names": [
{
"business_name": "XYZ Enterprise",
"type": "LEGAL_NAME"
}
],
"emails": [
{
"type": "CUSTOMER_SERVICE",
"email": "[email protected]"
}
],
"website": "https://mystore.testenterprises.com",
"addresses": [
{
"address_line_1": "Brent Park",
"address_line_2": "",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95054",
"country_code": "US",
"type": "WORK"
}
],
"phones": [
{
"country_code": "1",
"national_number": "4083938484",
"type": "CUSTOMER_SERVICE"
}
],
"annual_sales_volume_range": {
"minimum_amount": {
"currency_code": "USD",
"value": "10000"
},
"maximum_amount": {
"currency_code": "USD",
"value": "50000"
}
},
"average_monthly_volume_range": {
"minimum_amount": {
"currency_code": "USD",
"value": "1000"
},
"maximum_amount": {
"currency_code": "USD",
"value": "50000"
}
},
"purpose_code": "P0104"
},
"preferred_language_code": "en-US",
"tracking_id": "tes_12345",
"partner_config_override": {
"partner_logo_url": "https://example.com/logo.png",
"action_renewal_url": "http://partner-example.com/renew-prefill-url",
"return_url": "http://example.com",
"show_add_credit_card": true
},
"operations": [
{
"operation": "API_INTEGRATION",
"api_integration_preference": {
"rest_api_integration": {
"integration_method": "PAYPAL",
"integration_type": "THIRD_PARTY",
"third_party_details": {
"features": [
"PAYMENT",
"REFUND",
"PARTNER_FEE",
"DELAY_FUNDS_DISBURSEMENT",
"VAULT",
"BILLING_AGREEMENT"
]
}
}
}
}
],
"products": [
"PPCP",
"ADVANCED_VAULTING"
],
"capabilities": [
"PAYPAL_WALLET_VAULTING_ADVANCED"
],
"legal_consents": [
{
"type": "SHARE_DATA_CONSENT",
"granted": true
}
]
}'To redirect the merchant to PayPal to sign up, place the action_url in a button or link. You can also render the PayPal sign-up flow in a mini-browser by using the following code:
<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>After your merchant completes the signup flow, they are redirected to the return URL specified in the partner_config_override/return_url field of the Partner Referrals API. If no return URL is set, the merchant is redirected to the PayPal dashboard for their account.
During the redirect, PayPal loads the return URL in your merchant's browser and attaches the following query parameters:
| Parameter | Description |
|---|---|
merchantId | The unique ID of the merchant in your system that you specified in the Partner Referrals API call in the tracking_id field. |
merchantIdInPayPal | The merchant ID of your merchant's PayPal account. |
permissionsGranted | A Boolean indicating whether the merchant granted you the permissions you specified in the Partner Referrals API call. |
accountStatus | BUSINESS_ACCOUNT is sent if a business account was created. If a business account was not created, nothing is sent. |
consentStatus | A Boolean indicating whether the merchant consented to share their credentials with you. |
productIntentId | This value is set to addipmt. |
isEmailConfirmed | A Boolean indicating whether the merchant has confirmed their email address with PayPal. |
returnMessage | A message containing next steps for the merchant to take with PayPal. PayPal only sends this message for business accounts that do not have a confirmed email address. 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. |
Use the following code to redirect the merchant back to your site:
<pre><code class="xml">https://<var><RETURN-URL></var>?merchantId=<var><TRACKING-ID></var>&merchantIdInPayPal=<var><MERCHANT-ID-IN-PAYPAL></var>&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.</code></pre>Merchant onboarding is complete when the merchant has:
To track your merchant's status in meeting these requirements, make a show merchant status call.
Modify the code in the sample request as follows:
ACCESS_TOKEN to your access token.BN-CODE to your PayPal attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.AUTH-ASSERTION-JWT to your PayPal auth assertion token.PARTNER-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, select the Settings icon, select 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.MERCHANT-ID is the merchant ID of the merchant's PayPal account. To get your merchant's merchant ID, you can read the merchantIdInPayPal query parameter attached to the return URL when the merchant 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}.products to the value you want for your merchants. The products array value determines which type of payment your merchant can accept. EXPRESS_CHECKOUT includes debit and credit cards, the PayPal button, and PayPal Credit. PPCP includes the PayPal button and advanced credit and debit cards.curl -L -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{PARTNER-ID}/merchant-integrations/{MERCHANT-ID} \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT'After you've onboarded your merchants, choose the integration method that best suits your needs:
| Feature | JavaScript SDK | Orders API | Payment Method Tokens API |
|---|---|---|---|
| Credit and debit cards | Supported | Supported | Supported |
| PayPal | Supported | Supported | Supported |
| Venmo | Supported | Not supported | Not supported |
| Save during purchase | Supported | Supported | Not supported |
| Save for purchase later | Supported | Not supported | Supported |