Merchant-level onboarding

DOCSCURRENT

Last updated: Feb 27th, 8:10am

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_CHECKOUTand 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 }
              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_CHECKOUTincludes 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 "https://uri.paypal.com/services/billing-agreements",
                    114 "https://uri.paypal.com/services/vault/payment-tokens/read",
                    115 "https://uri.paypal.com/services/vault/payment-tokens/readwrite"
                    116 ]
                    117 }
                    118 ]
                    119 }
                    120 ]
                    121 }

                    Next steps

                    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

                    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more