Merchant-level onboarding

DocsCurrentLast updated: September 19th 2024, @ 11:07:28 am

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.

1. Onboard merchants

Onboard merchants with the Partner Referrals API
Verify merchant eligibility by tracking merchant onboarding status

Include the VAULT and BILLING_AGREEMENT values in the Partner Referral API call:

1"features": [
2    "PAYMENT",
3    "REFUND",
4    "PARTNER_FEE",
5    "VAULT",
6    "BILLING_AGREEMENT"
7  ]

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_CHECKOUT and ADVANCED_VAULTING.

1"products": [
2    "PPCP",
3    "ADVANCED_VAULTING"
4  ]

Add capabilities with the value of PAYPAL_WALLET_VAULTING_ADVANCED:

1"products": [
2    "PPCP",
3    "ADVANCED_VAULTING"
4  ]
5  "capabilities": [
6    "PAYPAL_WALLET_VAULTING_ADVANCED"
7  ]

Sample request

1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS-TOKEN' \
4 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
5 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
6 -d '{
7          "email": "email@example.com",
8          "individual_owners": [
9              {
10                  "names": [
11                      {
12                          "given_name": "Firstname Lastname",
13                          "full_name": "Firstname Lastname",
14                          "type": "LEGAL",
15                          "surname": "Vtwo"
16                      }
17                  ],
18                  "citizenship": "US",
19                  "addresses": [
20                      {
21                          "address_line_1": "Brent Park",
22                          "address_line_2": "",
23                          "admin_area_2": "San Jose",
24                          "admin_area_1": "CA",
25                          "postal_code": "95054",
26                          "country_code": "US",
27                          "type": "HOME"
28                      }
29                  ],
30                  "phones": [
31                      {
32                          "country_code": "1",
33                          "national_number": "4089383848",
34                          "type": "MOBILE"
35                      }
36                  ],
37                  "birth_details": {
38                      "date_of_birth": "1990-01-01"
39                  },
40                  "type": "PRIMARY"
41              }
42          ],
43          "business_entity": {
44              "business_type": {
45                  "type": "INDIVIDUAL",
46                  "subtype": "ASSO_TYPE_INCORPORATED"
47              },
48              "business_industry": {
49                  "category": "1004",
50                  "sub_category": "2025"
51              },
52              "business_incorporation": {
53                  "incorporation_country_code": "US",
54                  "incorporation_date": "1986-12-29"
55              },
56              "names": [
57                  {
58                      "business_name": "XYZ Enterprise",
59                      "type": "LEGAL_NAME"
60                  }
61              ],
62              "emails": [
63                  {
64                      "type": "CUSTOMER_SERVICE",
65                      "email": "customerservice@example.com"
66                  }
67              ],
68              "website": "https://mystore.testenterprises.com",
69              "addresses": [
70                  {
71                      "address_line_1": "Brent Park",
72                      "address_line_2": "",
73                      "admin_area_2": "San Jose",
74                      "admin_area_1": "CA",
75                      "postal_code": "95054",
76                      "country_code": "US",
77                      "type": "WORK"
78                  }
79              ],
80              "phones": [
81                  {
82                      "country_code": "1",
83                      "national_number": "4083938484",
84                      "type": "CUSTOMER_SERVICE"
85                  }
86              ],
87              "annual_sales_volume_range": {
88                  "minimum_amount": {
89                      "currency_code": "USD",
90                      "value": "10000"
91                  },
92                  "maximum_amount": {
93                      "currency_code": "USD",
94                      "value": "50000"
95                  }
96              },
97              "average_monthly_volume_range": {
98                  "minimum_amount": {
99                      "currency_code": "USD",
100                      "value": "1000"
101                  },
102                  "maximum_amount": {
103                      "currency_code": "USD",
104                      "value": "50000"
105                  }
106              },
107              "purpose_code": "P0104"
108          },
109          "preferred_language_code": "en-US",
110          "tracking_id": "tes_12345",
111          "partner_config_override": {
112              "partner_logo_url": "https://example.com/logo.png",
113              "action_renewal_url": "http://partner-example.com/renew-prefill-url",
114              "return_url": "http://example.com",
115              "show_add_credit_card": true
116          },
117          "operations": [
118              {
119                  "operation": "API_INTEGRATION",
120                  "api_integration_preference": {
121                      "rest_api_integration": {
122                          "integration_method": "PAYPAL",
123                          "integration_type": "THIRD_PARTY",
124                          "third_party_details": {
125                              "features": [
126                                  "PAYMENT",
127                                  "REFUND",
128                                  "PARTNER_FEE",
129                                  "DELAY_FUNDS_DISBURSEMENT",
130                                  "VAULT",
131                                  "BILLING_AGREEMENT"
132                              ]
133                          }
134                      }
135                  }
136              }
137          ],
138          "products": [
139              "PPCP",
140              "ADVANCED_VAULTING"
141          ],
142          "capabilities": [
143              "PAYPAL_WALLET_VAULTING_ADVANCED"
144          ],
145          "legal_consents": [
146              {
147                  "type": "SHARE_DATA_CONSENT",
148                  "granted": true
149              }
150          ]
151      }'

Sample response

1{
2      "links": [
3          {
4              "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/OGUwMTRhMGMtYTE4Mi00ZjM2LWIwMjUtMGI2YmNkOGMzNGU5M3B1a2NNdnJWZTV4V21WNlZQek42c1V5Zys2a3BGMWZkSW9jVEx4eS9qST12Mg==",
5              "rel": "self",
6              "method": "GET",
7              "description": "Read Referral Data shared by the Caller."
8          },
9          {
10              "href": "https://www.sandbox.paypal.com/bizsignup/partner/entry?referralToken=OGUwMTRhMGMtYTE4Mi00ZjM2LWIwMjUtMGI2YmNkOGMzNGU5M3B1a2NNdnJWZTV4V21WNlZQek42c1V5Zys2a3BGMWZkSW9jVEx4eS9qST12Mg==",
11              "rel": "action_url",
12              "method": "GET",
13              "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser."
14          }
15      ]
16  }

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:

1<div dir="ltr" style="text-align: left;" trbidi="on">
2    <script>
3      (function(d, s, id) {
4        var js, ref = d.getElementsByTagName(s)[0];
5        if (!d.getElementById(id)) {
6          js = d.createElement(s);
7          js.id = id;
8          js.async = true;
9          js.src = "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";
10          ref.parentNode.insertBefore(js, ref);
11        }
12      }(document, "script", "paypal-js"));
13    </script>
14    <a data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame">Sign up for PayPal</a>
15  </div>

3. Redirect merchants

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.`

Sample redirect URL

Use the following code to redirect the merchant back to your site:

1<pre><code class="xml">https://<var>&lt;Return-URL&gt;</var>?merchantId=<var>&lt;Tracking-ID&gt;</var>&merchantIdInPayPal=<var>&lt;Merchant-ID-In-PayPal&gt;</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>

4. Track merchant onboarding status

Merchant onboarding is complete when the merchant has:

Created a PayPal account.
Granted you permission for the features you set.
Confirms the email address of the account.

To track your merchant's status in meeting these requirements, make a show merchant status call.

Sample request

1curl --location --request GET 'https://api-m.sandbox.paypal.com/v1/customer/partners/<PARTNER-ID>/merchant-integrations/<MERCHANT-ID>' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Basic ACCESS-TOKEN' \
4 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
5 -H 'PayPal-Partner-Attribution-Id: BN-CODE'

Modify the code

Modify the code in the sample request as follows:

Change the ACCESS_TOKEN to your access token.
Change the PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
Change the BN-CODEto your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
The 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}.
Change 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.

Sample response

1{
2      "merchant_id": "<MERCHANT-ID>",
3      "tracking_id": "<TRACKING-ID>",
4      "products": [
5          {
6              "name": "ADVANCED_VAULTING",
7              "vetting_status": "SUBSCRIBED",
8              "capabilities": [
9                  "PAYPAL_WALLET_VAULTING_ADVANCED"
10              ]
11          },
12          {
13              "name": "PPCP_CUSTOM",
14              "vetting_status": "SUBSCRIBED",
15              "capabilities": [
16                  "AMEX_OPTBLUE",
17                  "CARD_PROCESSING_VIRTUAL_TERMINAL",
18                  "COMMERCIAL_ENTITY",
19                  "CUSTOM_CARD_PROCESSING",
20                  "DEBIT_CARD_SWITCH",
21                  "FRAUD_TOOL_ACCESS"
22              ]
23          },
24          {
25              "name": "PPCP_STANDARD",
26              "vetting_status": "SUBSCRIBED",
27              "capabilities": [
28                  "ALT_PAY_PROCESSING",
29                  "PAYPAL_CREDIT_PROCESSING",
30                  "RECEIVE_MONEY",
31                  "SEND_MONEY",
32                  "STANDARD_CARD_PROCESSING",
33                  "VENMO_PAY_PROCESSING",
34                  "WITHDRAW_MONEY"
35              ]
36          }
37      ],
38      "capabilities": [
39          {
40              "name": "PAYPAL_WALLET_VAULTING_ADVANCED",
41              "status": "ACTIVE"
42          },
43          {
44              "name": "AMEX_OPTBLUE",
45              "status": "ACTIVE"
46          },
47          {
48              "name": "CARD_PROCESSING_VIRTUAL_TERMINAL",
49              "status": "ACTIVE"
50          },
51          {
52              "name": "COMMERCIAL_ENTITY",
53              "status": "ACTIVE"
54          },
55          {
56              "name": "CUSTOM_CARD_PROCESSING",
57              "status": "ACTIVE"
58          },
59          {
60              "name": "DEBIT_CARD_SWITCH",
61              "status": "ACTIVE"
62          },
63          {
64              "name": "FRAUD_TOOL_ACCESS",
65              "status": "ACTIVE"
66          },
67          {
68              "name": "ALT_PAY_PROCESSING",
69              "status": "ACTIVE"
70          },
71          {
72              "name": "PAYPAL_CREDIT_PROCESSING",
73              "status": "ACTIVE"
74          },
75          {
76              "name": "RECEIVE_MONEY",
77              "status": "ACTIVE"
78          },
79          {
80              "name": "SEND_MONEY",
81              "status": "ACTIVE"
82          },
83          {
84              "name": "STANDARD_CARD_PROCESSING",
85              "status": "ACTIVE"
86          },
87          {
88              "name": "VENMO_PAY_PROCESSING",
89              "status": "ACTIVE"
90          },
91          {
92              "name": "WITHDRAW_MONEY",
93              "status": "ACTIVE"
94          }
95      ],
96      "payments_receivable": true,
97      "legal_name": "XYZ Enterprise",
98      "primary_email_confirmed": true,
99      "oauth_integrations": [
100          {
101              "integration_type": "OAUTH_THIRD_PARTY",
102              "integration_method": "PAYPAL",
103              "oauth_third_party": [
104                  {
105                      "partner_client_id": "AQm8FbJgSpfhxlRlp_cVK6dGfCRJFz73KsaXUlJvHGjMP2N2msfja9kQIr3Pl2fnA_DcZ2_182zyg_OT",
106                      "merchant_client_id": "AWdvAa0xWDOvhy1HzKg2RLFrMc6ghp7WPeu1eDieU6fHPVk_2NG59EgJkCUORadgcz4YC9e8513EbXRM",
107                      "scopes": [
108                          "https://uri.paypal.com/services/payments/delay-funds-disbursement",
109                          "https://uri.paypal.com/services/payments/realtimepayment",
110                          "https://uri.paypal.com/services/payments/partnerfee",
111                          "https://uri.paypal.com/services/payments/refund",
112                          "https://uri.paypal.com/services/payments/payment/authcapture",
113                          "Braintree:Vault",
114                          "https://uri.paypal.com/services/billing-agreements",
115                          "https://uri.paypal.com/services/vault/payment-tokens/read",
116                          "https://uri.paypal.com/services/vault/payment-tokens/readwrite"
117                      ]
118                  }
119              ]
120          }
121      ]
122  }

Next steps

After you've onboarded your merchants, choose the integration method that best suits your needs:

Feature	JavaScript SDK	Orders API	Vault Payment Method 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

Merchant-level onboarding

1. Onboard merchants

Sample request

Sample response

2. Add signup link to your site

3. Redirect merchants

Sample redirect URL

4. Track merchant onboarding status

Sample request

Modify the code

Sample response

Next steps