Partner Referrals API

The Partner Referrals API enables a marketplace to add PayPal seller accounts. It supports the Connected Path marketplace models.
Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.
In the Connected Path, you host a button on your website that takes sellers to PayPal to create and configure a PayPal account. The Onboarding API enables you to collect seller data and pass it to the account creation and setup forms, reducing the burden on sellers during the signup and setup process. Call the create partner referral and show referral data methods for the Connected Path.

Merchant integration (resource group)

Enables you to get information about a seller-partner integration.

Show seller status

GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}
Shows status information for sellers that the partner onboards, by partner ID.

Path parameters

  • partner_id

    string

    required

    The ID of the partner for which to show onboarded seller status information., which is the partner's PayPal account number. To find this ID, log in to the partner's PayPal business account. Navigate to Profile, click Profile and settings, and click My business info. The account number appears in the Merchant account ID section.
  • merchant_id

    string

    required

    The ID of the seller for which to show status information.

Query parameters

  • fields

    string

    Filters the fields in the response to this comma-separated list of fields.

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"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows status details.
  • tracking_id

    string

    The partner-provided tracking ID, if one was provided.
  • merchant_id

    string

    The payer ID of the seller after creation of their PayPal account.
  • products

    array (contains the product object)

    An array of statuses for all products that are integrated with the partner for the seller.
  • payments_receivable

    boolean

    Indicates whether the seller account can receive payments.
  • primary_email_confirmed

    boolean

    Indicates whether the primary email of the seller has been confirmed.
  • primary_email

    string

    The primary email address of the seller.
  • date_created

    string

    The date when the seller account was created, in Internet date and time format.
  • granted_permissions

    array (contains the granted_permission object)

    An array of permissions granted to the partner by the seller.
  • api_credentials

    object

    The API credentials of the seller.
  • oauth_integrations

    array (contains the oauth_integration object)

    An array of information about OAuth integrations between partners and sellers.
  • limitations

    array (contains the limitation object)

    An array of limitations on the seller account.

Sample Response

{
  "merchant_id": "8LQLM2ML4ZTYU",
  "products": [
    {
      "name": "EXPRESS_CHECKOUT"
    }
  ],
  "payments_receivable": true,
  "primary_email_confirmed": true,
  "oauth_integrations": [
    {
      "integration_type": "OAUTH_THIRD_PARTY",
      "integration_method": "BRAINTREE",
      "oauth_third_party": [
        {
          "partner_client_id": "AZqTbhAo7fUgX2BQW5l-yYEHYY_C8FDUkiPP_6Cw7P35cQID26rsWVWXzgRQ",
          "merchant_client_id": "ARj22pLzUWaTt_RFAlFvn_dC6OpETq1HK_n49nyuDf4i5dqPBZmDk6X1u9JytrtMGaDExCvKSGCOwRbO",
          "scopes": [
            "https://uri.paypal.com/services/payments/payment/authcapture",
            "https://uri.paypal.com/services/payments/realtimepayment"
          ],
          "access_token": "access_token$sandbox$s4dw8tjsz88cg7mh$45bdde2cfa55c1b060a409824b48b8d3",
          "refresh_token": "refresh_token$sandbox$s4dw8tjsz88cg7mh$b1dfdbbdbaa7b9165b696f916738ce2c"
        }
      ]
    }
  ]
}

Partner referrals (resource group)

Enables you to create and get information about shared customer data.

Create partner referral

POST /v1/customer/partner-referrals
Creates a partner referral that is shared by the API caller. The referrals contains the client's personal, business, and financial data.

Request body

  • customer_data

    object

    The customer's business and personal data that is required to create an account.
  • requested_capabilities

    array (contains the capability object)

    An array of capabilities to enable for the customer while he or she shares the data.
  • web_experience_preference

    object

    The preference to customize the web experience of the customer.
  • collected_consents

    array (contains the legal_consent object)

    An array of all consents that the partner has received from this seller. If SHARE_DATA_CONSENT is not granted, PayPal does not store customer data.
  • products

    array (contains the product_name object)

    An array of PayPal products to which the partner wants to onboard the customer.

Sample Request

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": {
    "customer_type": "MERCHANT",
    "person_details": {
      "email_address": "customer@example.com",
      "name": {
        "prefix": "Mr.",
        "given_name": "Shashank",
        "surname": "Wankhede",
        "middle_name": "Govind"
      },
      "phone_contacts": [
        {
          "phone_number_details": {
            "country_code": "91",
            "national_number": "9740216087"
          },
          "phone_type": "HOME"
        }
      ],
      "home_address": {
        "line1": "11, outer ring road",
        "state": "Karnataka",
        "city": "Bangalore",
        "country_code": "IN",
        "postal_code": "560103"
      },
      "date_of_birth": {
        "event_type": "BIRTH",
        "event_date": "1987-12-29T23:59:59.999Z"
      },
      "nationality_country_code": "IN",
      "identity_documents": [
        {
          "type": "SOCIAL_SECURITY_NUMBER",
          "value": "ABCDEF34646",
          "partial_value": false,
          "issuer_country_code": "US"
        }
      ]
    },
    "business_details": {
      "phone_contacts": [
        {
          "phone_number_details": {
            "country_code": "91",
            "national_number": "9740216087"
          },
          "phone_type": "FAX"
        }
      ],
      "business_address": {
        "line1": "11, outer ring road",
        "state": "Karnataka",
        "city": "Bangalore",
        "country_code": "IN",
        "postal_code": "560103"
      },
      "business_type": "PROPRIETORSHIP",
      "category": "1004",
      "sub_category": "2025",
      "merchant_category_code": "8931",
      "names": [
        {
          "type": "LEGAL",
          "name": "SHASHANK STORE"
        }
      ],
      "business_description": "Arts and handicrafts",
      "event_dates": [
        {
          "event_type": "ESTABLISHED",
          "event_date": "2009-01-31T13:59:45Z"
        }
      ],
      "website_urls": [
        "https://example.com/mystore/"
      ],
      "annual_sales_volume_range": {
        "minimum_amount": {
          "currency": "USD",
          "value": "2000"
        },
        "maximum_amount": {
          "currency": "USD",
          "value": "3000"
        }
      },
      "average_monthly_volume_range": {},
      "identity_documents": [
        {
          "type": "TAX_IDENTIFICATION_NUMBER",
          "value": "ABCDEF34646",
          "partial_value": false,
          "issuer_country_code": "US"
        }
      ],
      "email_contacts": [
        {
          "email_address": "customer-service@example.com",
          "role": "CUSTOMER_SERVICE"
        }
      ]
    },
    "financial_instrument_data": {
      "bank_details": [
        {
          "nick_name": "Bank of America",
          "account_number": "123405668293",
          "account_type": "CHECKING",
          "currency_code": "USD",
          "identifiers": [
            {
              "type": "ROUTING_NUMBER_1",
              "value": "123456789"
            }
          ]
        }
      ]
    },
    "preferred_language_code": "en_US",
    "primary_currency_code": "USD",
    "referral_user_payer_id": {
      "type": "PAYER_ID",
      "value": "RFYUH2QQDGUQU"
    },
    "partner_specific_identifiers": [
      {
        "type": "TRACKING_ID",
        "value": "ABJSDFO343SD"
      }
    ]
  },
  "requested_capabilities": [
    {
      "capability": "BANK_ADDITION"
    }
  ],
  "web_experience_preference": {
    "partner_logo_url": "https://example.com/logo/",
    "return_url": "https://example.com/",
    "action_renewal_url": "https://example.com/renew/"
  },
  "collected_consents": [
    {
      "type": "SHARE_DATA_CONSENT",
      "granted": true
    }
  ],
  "products": [
    "EXPRESS_CHECKOUT"
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that contains a HATEOAS link to show the referral data and an action_url to which you redirect the customer in a browser to complete the signup process. The partner_referral_id token is appended to the URL.

Sample Response

{
  "links": [
    {
      "href": "https://uri.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "self",
      "method": "GET",
      "description": "The read referral data shared by the partner."
    },
    {
      "href": "https://www.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "action_url",
      "method": "GET",
      "description": "The target web redirect URL for the next action."
    }
  ]
}

Show referral data

GET /v1/customer/partner-referrals/{partner_referral_id}
Shows details for referral data, by ID, that was shared by the API caller.

Path parameters

  • partner_referral_id

    string

    required

    The ID of the partner-referrals data for which to show details.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0= \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows referral data.
  • partner_referral_id

    string

    The ID to access the customer's data shared by the partner with PayPal.

    Read only.

  • submitter_payer_id

    string

    The payer ID of the partner who shared the referral data.

    Read only.

  • referral_data

    object

    The referral data that partners share with PayPal.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "partner_referral_id": "ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
  "submitter_payer_id": "RFYUH2QQDGUQU",
  "referral_data": {
    "customer_data": {
      "customer_type": "MERCHANT",
      "person_details": {
        "email_address": "customer@example.com",
        "name": {
          "prefix": "Mr.",
          "given_name": "Shashank",
          "surname": "Wankhede",
          "middle_name": "Govind"
        },
        "phone_contacts": [
          {
            "phone_number_details": {
              "country_code": "91",
              "national_number": "9740216087"
            },
            "phone_type": "HOME"
          }
        ],
        "home_address": {
          "line1": "11, outer ring road",
          "state": "Karnataka",
          "city": "Bangalore",
          "country_code": "IN",
          "postal_code": "560103"
        },
        "date_of_birth": {
          "event_type": "BIRTH",
          "event_date": "1987-12-29T23:59:59.999Z"
        },
        "nationality_country_code": "IN",
        "identity_documents": [
          {
            "type": "SOCIAL_SECURITY_NUMBER",
            "value": "ABCDEF34646",
            "partial_value": false,
            "issuer_country_code": "US"
          }
        ]
      },
      "business_details": {
        "phone_contacts": [
          {
            "phone_number_details": {
              "country_code": "91",
              "national_number": "9740216087"
            },
            "phone_type": "FAX"
          }
        ],
        "business_address": {
          "line1": "11, outer ring road",
          "state": "Karnataka",
          "city": "Bangalore",
          "country_code": "IN",
          "postal_code": "560103"
        },
        "business_type": "PROPRIETORSHIP",
        "category": "1004",
        "sub_category": "2025",
        "merchant_category_code": "8931",
        "names": [
          {
            "type": "LEGAL",
            "name": "SHASHANK STORE"
          }
        ],
        "business_description": "Arts and handicrafts",
        "event_dates": [
          {
            "event_type": "ESTABLISHED",
            "event_date": "2009-01-31T13:59:45Z"
          }
        ],
        "website_urls": [
          "https://example.com/mystore/"
        ],
        "annual_sales_volume_range": {
          "minimum_amount": {
            "currency": "USD",
            "value": "2000"
          },
          "maximum_amount": {
            "currency": "USD",
            "value": "3000"
          }
        },
        "average_monthly_volume_range": {},
        "identity_documents": [
          {
            "type": "TAX_IDENTIFICATION_NUMBER",
            "value": "ABCDEF34646",
            "partial_value": false,
            "issuer_country_code": "US"
          }
        ],
        "email_contacts": [
          {
            "email_address": "customer-service@example.com",
            "role": "CUSTOMER_SERVICE"
          }
        ]
      },
      "financial_instrument_data": {},
      "preferred_language_code": "en_US",
      "primary_currency_code": "USD",
      "referral_user_payer_id": {
        "type": "PAYER_ID",
        "value": "RFYUH2QQDGUQU"
      },
      "partner_specific_identifiers": [
        {
          "type": "TRACKING_ID",
          "value": "ABJSDFO343SD"
        }
      ]
    },
    "requested_capabilities": [
      {
        "capability": "API_INTEGRATION",
        "api_integration_preference": {
          "partner_id": "RFYUH2QQDGUQU",
          "classic_api_integration_type": "FIRST_PARTY_INTEGRATED",
          "classic_first_party_details": "SIGNATURE"
        }
      },
      {
        "capability": "BANK_ADDITION"
      }
    ],
    "web_experience_preference": {
      "partner_logo_url": "https://example.com/logo/",
      "return_url": "https://example.com/",
      "action_renewal_url": "https://example.com/renew/"
    },
    "collected_consents": [
      {
        "type": "SHARE_DATA_CONSENT",
        "granted": true
      }
    ],
    "products": [
      "EXPRESS_CHECKOUT"
    ]
  },
  "links": [
    {
      "href": "https://uri.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "self",
      "method": "GET",
      "description": "Read client data shared by the partner."
    },
    {
      "href": "https://www.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "action_url",
      "method": "GET",
      "description": "Target web redirect URL for the next action."
    }
  ]
}

Common object definitions

account_identifier

  • type

    enum

    required

    The type of ID for the account.

    Possible values: PAYER_ID.

  • value

    string

    required

    The ID of the account.

account_owner_relationship

  • name

    object

    required

    The name of the familial relation.
  • relation

    enum

    required

    The type of familial relationship. The possible values are:
    • MOTHER. Maternal relationship.
  • country_code_of_nationality

    object

    required

    The nationality of the familial relation.

address

  • line1

    string

    required

    The first line of the address. For example, number or street.
  • line2

    string

    The second line of the address. For example, suite or apartment number.
  • city

    string

    required

    The city name.
  • state

    string

    The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
  • country_code

    string

    required

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • postal_code

    string

    The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

address_postal_code_validation

bank_details

  • nick_name

    string

    The user-provided short name for the user's bank account.
  • account_number

    string

    required

    The bank account number. These are numeric values only without any additional formatting.

    Pattern: \d+.

  • account_type

    enum

    required

    The type of account, which is checking or savings. The possible values are:
    • CHECKING. Checking account.
    • SAVINGS. Savings accounts.
  • currency_code

    string

    The primary three-character ISO-4217 currency code for the account.

    Pattern: ^([A-Z]){3}$.

  • identifiers

    array (contains the identifier object)

    An array of instrument institute attributes. Used with the account number to uniquely identify the instrument. Value is:
    • For banks with IBAN information, the IBAN number.
    • For banks with BBAN information, the BBAN number.
    • For banks with both IBAN and BBAN information, the IBAN number.
  • branch_location

    object

    The branch location, if applicable.
  • mandate_agreed

    boolean

    Indicates whether the user has agreed to the mandate for financial instrument (FI) authorization.

billing_agreement

  • description

    string

    The billing agreement description.
  • billing_experience_preference

    object

    The preference that customizes the billing experience of the customer.
  • merchant_custom_data

    string

    The custom data for the billing agreement.
  • approval_url

    string

    The URL to which to redirect seller to accept the billing agreement.
  • ec_token

    string

    The billing agreement token for the agreement.

billing_experience_preference

  • experience_id

    string

    The ID of the payment web experience profile.
  • billing_context_set

    boolean

    Indicates whether the partner has already displayed the billing context to the seller.

business_details

  • phone_contacts

    array (contains the phone_details object)

    An array of phone contacts for the business.
  • business_address

    object

    The address of the business.
  • business_type

    string (contains the business_type object)

    The type of business.
  • category

    string

    The customer's business category code. PayPal uses the industry standard seller category codes.

    Pattern: ^\d+$.

  • sub_category

    string

    The customer's business subcategory code. PayPal uses the industry standard seller category codes.

    Pattern: ^\d+$.

  • merchant_category_code

    string

    The customer's business seller category code. PayPal uses the industry standard seller category codes.

    Pattern: ^\d+$.

  • purpose_code

    object (contains the purpose_code object)

    The account's purpose code.
  • names

    array (contains the business_name object)

    An array of business names.
  • business_description

    string

    The business goals description. For example, a mission statement.
  • event_dates

    array (contains the date_of_event object)

    An array of event dates for the business.
  • website_urls

    array (contains the website_url object)

    An array of website URLs for the business.
  • annual_sales_volume_range

    object

    The range for the total annual sales volume of the business.
  • average_monthly_volume_range

    object

    The range for the average monthly volume of the business.
  • identity_documents

    array (contains the identity_document object)

    An array of identity documents that uniquely identify the user. For example, a license number, social security number, and so on.
  • email_contacts

    array (contains the email_contact object)

    An array of contact email addresses for the company.
  • country_of_incorporation

    object

    The country code of the country where the business was incorporated.

business_name

  • type

    enum

    required

    The legal category of the business.

    Possible values: LEGAL, DOING_BUSINESS_AS, STOCK_TRADING_NAME.

  • name

    string

    required

    The business name.

business_type

  • business_type

    enum

    The business type.

    Possible values: INDIVIDUAL, PROPRIETORSHIP, PARTNERSHIP, CORPORATION, NONPROFIT, GOVERNMENT, PUBLIC_COMPANY, REGISTERED_COOPERATIVE, PROPRIETORY_COMPANY, ASSOCIATION, PRIVATE_CORPORATION, LIMITED_PARTNERSHIP, LIMITED_LIABILITY_PROPRIETORS, LIMITED_LIABILITY_PARTNERSHIP, PUBLIC_CORPORATION, OTHER_CORPORATE_BODY.

cancel_merchant_onboarding

  • merchant_email

    object

    The partner-provided seller email address.
  • note

    string

    A note that describes the cancellation.

capability

  • capability

    enum

    The capability to enable for the customer. To enable the collection of the API permissions that you require to integrate with the customer, specify API_INTEGRATION. BANK_ADDITION is supported only for the US.

    Possible values: API_INTEGRATION, BANK_ADDITION, BILLING_AGREEMENT, CONTEXTUAL_MARKETING_CONSENT.

  • api_integration_preference

    object

    The integration details for the partner and customer relationship. Required if capability_type is API_INTEGRATION.
  • billing_agreement

    object

    The details of the billing agreement between the partner and a seller.

certificate

  • api_user_name

    string

    The API user name for the seller.
  • api_password

    string

    The API password for the seller.
  • fingerprint

    string

    The fingerprint.
  • download_link

    string

    The URL to download the certificate.

country_code

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

create_referral_data_response

credential

  • signature

    object

    The signature portion of the seller credentials.
  • certificate

    object

    A certificate for seller credentials.

currency

currency_range

  • minimum_amount

    object

    The minimum inclusive amount for the range.
  • maximum_amount

    object

    The maximum inclusive amount for the range.

date_of_event

  • event_type

    enum

    required

    The event type for an onboarding entity.

    Possible values: BIRTH, ESTABLISHED, INCORPORATION, OPERATION.

  • event_date

    string

    required

    The date portion of the date and time when the event occurred, in Internet date and time format. For accuracy, if you do not know the exact time zone, use the UTC time zone.

email_address

  • email_address

    string

    The internationalized email address.
    Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

email_contact

  • email_address

    object

    required

    The internationalized email address.
    Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
  • role

    enum

    required

    The role of the email address.

    Possible values: CUSTOMER_SERVICE.

error

  • name

    string

    required

    The human-readable, unique name of the error.
  • message

    string

    required

    The message that describes the error.
  • debug_id

    string

    required

    The PayPal internal ID that is used for correlation purposes.
  • information_link

    string

    The information link, or URI, that shows detailed information about this error for the developer.

    Read only.

  • details

    array (contains the error_details object)

    An array of additional details about the error.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

error_details

  • field

    string

    The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
  • value

    string

    The value of the field that caused the error.
  • location

    string

    The location of the field that caused the error. Value is body, path, or query.

    Default: body.

  • issue

    string

    required

    The unique and fine-grained application-level error code.
  • description

    string

    The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.

event_type

  • event_type

    enum

    The event type for an onboarding entity.

    Possible values: BIRTH, ESTABLISHED, INCORPORATION, OPERATION.

financial_instrument_data

  • bank_details

    array (contains the bank_details object)

    An array of bank account details for the ADD_BANK capability.

granted_permission

  • granted_permission

    enum

    The permission granted to the partner.

    Possible values: EXPRESS_CHECKOUT, REFUND, DIRECT_PAYMENT, AUTH_CAPTURE, BUTTON_MANAGER, ACCOUNT_BALANCE, TRANSACTION_DETAILS, TRANSACTION_SEARCH, REFERENCE_TRANSACTION, RECURRING_PAYMENTS, BILLING_AGREEMENT, MANAGE_PENDING_TRANSACTION_STATUS, NON_REFERENCED_CREDIT, MASS_PAY, ENCRYPTED_WEBSITE_PAYMENTS, SETTLEMENT_CONSOLIDATION, SETTLEMENT_REPORTING, MOBILE_CHECKOUT, AIR_TRAVEL, INVOICING, RECURRING_PAYMENT_REPORT, EXTENDED_PRO_PROCESSING_REPORT, EXCEPTION_PROCESSING_REPORT, TRANSACTION_DETAIL_REPORT, ACCOUNT_MANAGEMENT_PERMISSION, ACCESS_BASIC_PERSONAL_DATA, ACCESS_ADVANCED_PERSONAL_DATA.

identifier

  • type

    enum

    The bank account ID type. The possible values are:
    • ROUTING_NUMBER_1. Routing number 1.
    • ROUTING_NUMBER_2. Routing number 2.
    • ROUTING_NUMBER_3. Routing number 3.
    • BI_CODE. BI code.
    • BANK_CODE. Bank code.
    • BRANCH_CODE. Branch code.
    • INTERMEDIARY_SWIFT_CODE. Swift code.
    • BBAN. BBAN.
    • BBAN_ENCRYPTED. BBAN enrypted.
    • BBAN_HMAC. BBAN HMAC.
    • AGGREGATOR_YODLEE. Aggregator Yodlee.
  • value

    string

    The bank account ID value.

identity_document

  • type

    enum

    required

    The identifier type in the onboarding domain. Indicates the most specific type or the closest matching value. For example, SOCIAL_SECURITY_NUMBER in preference to TAX_IDENTIFICATION_NUMBER.

    Possible values: SOCIAL_SECURITY_NUMBER, EMPLOYMENT_IDENTIFICATION_NUMBER, TAX_IDENTIFICATION_NUMBER, PASSPORT_NUMBER, PENSION_FUND_ID, MEDICAL_INSURANCE_ID, CNPJ, CPF, PAN.

  • value

    string

    required

    The identifier value, such as license number, social security number, and so on.

    Pattern: ^[A-Za-z0-9]+$.

  • partial_value

    boolean

    required

    Indicates whether the value is a partial value. Specify this value when the identifier type supports a partial value, such as four SSN digits instead of the full nine values. Depending on the context, this parameter can be ignored.
  • issuer_country_code

    string

    required

    The two-character IS0-3166-1 country code for the country that issued the document.

    Pattern: ^[A-Z]([A-Z]|\d)$.

identity_document_type

  • identity_document_type

    enum

    The identifier type in the onboarding domain. Indicates the most specific type or the closest matching value. For example, SOCIAL_SECURITY_NUMBER in preference to TAX_IDENTIFICATION_NUMBER.

    Possible values: SOCIAL_SECURITY_NUMBER, EMPLOYMENT_IDENTIFICATION_NUMBER, TAX_IDENTIFICATION_NUMBER, PASSPORT_NUMBER, PENSION_FUND_ID, MEDICAL_INSURANCE_ID, CNPJ, CPF, PAN.

integration_details

  • partner_id

    string

    The payer ID of the partner who integrates with the client.
  • rest_api_integration

    object

    The integration details for PayPal REST endpoints.
  • rest_third_party_details

    object

    The integration details for PayPal REST endpoints.

limitation

  • name

    string

    The title of the limitation that is applied to the account.
  • restrictions

    array (contains the restriction object)

    An array of the restriction names.

merchant_integration

  • tracking_id

    string

    The partner-provided tracking ID, if one was provided.
  • merchant_id

    string

    The payer ID of the seller after creation of their PayPal account.
  • products

    array (contains the product object)

    An array of statuses for all products that are integrated with the partner for the seller.
  • payments_receivable

    boolean

    Indicates whether the seller account can receive payments.
  • primary_email_confirmed

    boolean

    Indicates whether the primary email of the seller has been confirmed.
  • primary_email

    string

    The primary email address of the seller.
  • date_created

    string

    The date when the seller account was created, in Internet date and time format.
  • granted_permissions

    array (contains the granted_permission object)

    An array of permissions granted to the partner by the seller.
  • api_credentials

    object

    The API credentials of the seller.
  • oauth_integrations

    array (contains the oauth_integration object)

    An array of information about OAuth integrations between partners and sellers.
  • limitations

    array (contains the limitation object)

    An array of limitations on the seller account.

name

  • prefix

    string

    The prefix, or title, to the party's name.

    Maximum length: 140.

  • given_name

    string

    When the party is a person, the party's given, or first, name.

    Maximum length: 140.

  • surname

    string

    When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

    Maximum length: 140.

  • middle_name

    string

    When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

    Maximum length: 140.

  • suffix

    string

    The suffix for the party's name.

    Maximum length: 140.

  • alternate_full_name

    string

    DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

    Maximum length: 300.

  • full_name

    string

    When the party is a person, the party's full name.

    Maximum length: 300.

name_validation

oauth_integration

  • integration_type

    enum

    The type of integration between the partner and the seller.

    Possible values: FIRST_PARTY_INTEGRATED, FIRST_PARTY_NON_INTEGRATED, THIRD_PARTY, OAUTH_THIRD_PARTY.

  • integration_method

    enum

    The integration method that the partner uses to integrate with PayPal APIs.

    Possible values: PAYPAL, BRAINTREE.

  • status

    enum

    The integration status.

    Possible values: A, I.

  • oauth_third_party

    array (contains the oauth_third_party object)

    An array of combinations of partner_client_id and merchant_client_id values and their associated scopes.

oauth_third_party

  • partner_client_id

    string

    The client ID for the partner.
  • merchant_client_id

    string

    The client ID of the seller.
  • scopes

    array (contains the scope object)

    An array of scopes that the seller granted the partner.
  • access_token

    string

    The access token for the partner-selected integration method.
  • refresh_token

    string

    The refresh token for the partner-selected integration method.

partner_specific_identifier

  • type

    enum

    required

    The identifier type.

    Possible values: TRACKING_ID.

  • value

    string

    required

    The identifier value.

person_details

  • email_address

    string

    The primary email address of the account.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • name

    object

    The legal name of the customer.
  • phone_contacts

    array (contains the phone_details object)

    An array of contact phone numbers for the customer.
  • home_address

    object

    The home address of the account holder.
  • date_of_birth

    object

    The date of birth of the primary account holder.
  • nationality_country_code

    string

    The two-character IS0-3166-1 country code for the nationality of the account holder. Can include one of the PayPal-supported countries.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • identity_documents

    array (contains the identity_document object)

    An array of documents that uniquely identify the user, such as a license number, social security number, and so on.
  • account_owner_relationships

    array (contains the account_owner_relationship object)

    An array of familial relationships that are attached to a seller.

phone

  • country_code

    string

    required

    The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

    Minimum length: 1.

    Maximum length: 3.

    Pattern: ^[0-9]{1,3}?$.

  • national_number

    string

    required

    The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

    Minimum length: 1.

    Maximum length: 14.

    Pattern: ^[0-9]{1,14}?$.

  • extension_number

    string

    The extension number.

    Minimum length: 1.

    Maximum length: 15.

    Pattern: ^[0-9]{1,15}?$.

phone_details

  • phone_number_details

    object

    required

    The phone number details.
  • phone_type

    enum

    required

    The phone type.

    Possible values: FAX, HOME, MOBILE, OTHER, PAGER.

phone_type

  • phone_type

    enum

    The phone type.

    Possible values: FAX, HOME, MOBILE, OTHER, PAGER.

product

  • name

    enum

    The name of the product.

    Possible values: EXPRESS_CHECKOUT, WEBSITE_PAYMENTS_STANDARD, MASS_PAYMENT, EMAIL_PAYMENTS, EBAY_CHECKOUT, PAYFLOW_LINK, PAYFLOW_PRO, WEBSITE_PAYMENTS_PRO_3_0, WEBSITE_PAYMENTS_PRO_2_0, VIRTUAL_TERMINAL, HOSTED_SOLE_SOLUTION, BILL_ME_LATER, MOBILE_EXPRESS_CHECKOUT, PAYPAL_HERE, MOBILE_IN_STORE, PAYPAL_STANDARD, MOBILE_PAYPAL_STANDARD, MOBILE_PAYMENT_ACCEPTANCE, PAYPAL_ADVANCED, PAYPAL_PRO, ENHANCED_RECURRING_PAYMENTS.

  • vetting_status

    enum

    The vetting status of the product, if applicable.

    Possible values: APPROVED, PENDING, DECLINED.

  • active

    boolean

    Indicates whether the product is active.

product_name

  • product_name

    enum

    The PayPal product for which the customer is onboarded.

    Possible values: EXPRESS_CHECKOUT, PPPLUS, WP_PRO.

purpose_code

  • purpose_code

    enum

    The purpose code. Required only for India. For more information, see the Reserve Bank Of India web site. Value is:
    • P0104. Cross border delivery of goods and services.
    • P0301. Business related travel purchase.
    • P0801. Hardware consulting.
    • P0802. Software consulting.
    • P0803. Data processing consulting.
    • P0805. Freelance journalism.
    • P0806. Other information services.
    • P0902. Licensing revenues.
    • P1004. Legal.
    • P1005. Accounting and tax.
    • P1006. Business and management consultancy.
    • P1007. Advertising and market research.
    • P1008. Research and development.
    • P1009. Architectural services.

    Possible values: P0104, P0301, P0801, P0802, P0803, P0805, P0806, P0902, P1004, P1005, P1006, P1007, P1008, P1009.

referral_data

  • customer_data

    object

    The customer's business and personal data that is required to create an account.
  • requested_capabilities

    array (contains the capability object)

    An array of capabilities to enable for the customer while he or she shares the data.
  • web_experience_preference

    object

    The preference to customize the web experience of the customer.
  • collected_consents

    array (contains the legal_consent object)

    An array of all consents that the partner has received from this seller. If SHARE_DATA_CONSENT is not granted, PayPal does not store customer data.
  • products

    array (contains the product_name object)

    An array of PayPal products to which the partner wants to onboard the customer.

referral_data_response

  • partner_referral_id

    string

    The ID to access the customer's data shared by the partner with PayPal.

    Read only.

  • submitter_payer_id

    string

    The payer ID of the partner who shared the referral data.

    Read only.

  • referral_data

    object

    The referral data that partners share with PayPal.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

rest_api_integration

  • integration_method

    enum

    The REST-credential integration method. The possible values are:
    • BRAINTREE. Braintree integration method.
    • PAYPAL. PayPal integration method.

    Default: PAYPAL.

  • integration_type

    enum

    The type of REST-endpoint integration. To integrate with Braintree v.zero for PayPal REST endpoints, specify REST_THIRD_PARTY_DETAILS. The possible values are:
    • THIRD_PARTY. A third-party integration.

rest_endpoint_feature

  • rest_endpoint_feature

    enum

    The REST endpoint.

    Possible values: PAYMENT, REFUND, PARTNER_FEE, DELAY_FUNDS_DISBURSEMENT, SWEEP_FUNDS_EXTERNAL_SINK, READ_SELLER_DISPUTE, UPDATE_SELLER_DISPUTE, ADVANCED_TRANSACTIONS_SEARCH.

rest_third_party_details

  • partner_client_id

    string

    The payer ID of the partner.
  • feature_list

    array (contains the rest_endpoint_feature object)

    An array of features that partner can access, or use, in PayPal on behalf of the seller. The seller grants permission for these features to the partner.

restriction

  • restriction

    string

    A restriction name.

scope

  • scope

    string

    The individual scope name.

signature

  • api_user_name

    string

    The API user name of the seller.
  • api_password

    string

    The API password of the seller.
  • signature

    string

    The signature credential of the seller.

user

  • customer_type

    enum

    The type of PayPal account to create, which is consumer or seller. The possible values are:
    • CONSUMER. Consumer account.
    • MERCHANT. Seller account.
  • person_details

    object

    The customer's personal details.
  • business_details

    object

    The customer's business details.
  • financial_instrument_data

    object

    The customer's financial instrument. Use it to add a financial instrument to the customer's PayPal account.
  • preferred_language_code

    string

    The locale code for the user.

    Pattern: ^([a-z]){2}_([A-Z]){2}$.

  • primary_currency_code

    object

    The primary three-character ISO-4217 currency code of the account.
  • referral_user_payer_id

    object

    The PayPal account ID.
  • partner_specific_identifiers

    array (contains the partner_specific_identifier object)

    An array of customer identifiers in the partner's system.

web_experience_preference

  • partner_logo_url

    string

    The partner logo URL to display in the seller onboarding flow.
  • return_url

    string

    The URL to which to redirect the customer upon completion of the onboarding process.
  • return_url_description

    string

    The description of the return URL.
  • action_renewal_url

    string

    If renew_action_url expires, redirect the customer to this URL.
  • show_add_credit_card

    boolean

    Indicates whether to show an add credit card page.
  • show_mobile_confirm

    boolean

    Indicates whether to ask the customer to initiate confirmation of their mobile phone (the phone that the partner designated as MOBILE in the customer data). Default isfalse.
  • use_mini_browser

    boolean

    Indicates whether to provide a single page signup flow in a mini browser. Default is to provide a full-size, multi-page flow.
  • use_hua_email_confirmation

    boolean

    Indicates whether to use the hosted_user_agreement_url to confirm the customer's email address. If true, PayPal appends the email confirmation code to hosted_user_agreement_url, and when a customer successfully accesses the hosted user agreement URL, confirms the customer's email address. If false, PayPal does not append the confirmation code to the URL and does not confirm the email address.

website_url

  • website_url

    string

    The URL for the business website.

Additional API information

Error messages

In addition to common HTTP status codes that the REST APIs return, the Partner Referrals API can return the following errors.

  • INTERNAL_ERROR

    The process cannot be processed due to internal error. An internal error occurred.

  • PARTNER_BUSINESS_ERROR-BUSINESS_ERROR

    BUSINESS_ERROR. The caller is not a business account or the account is closed or locked.

  • PARTNER_BUSINESS_ERROR-CONSENT_ALREADY_EXISTS

    CONSENT_ALREADY_EXISTS. The consent between this seller and partner already exists.

    Note: Use PATCH to update the content.

  • PARTNER_BUSINESS_ERROR-FAILED_TO_SET_OAUTH_INTEGRATION

    FAILED_TO_SET_OAUTH_INTEGRATION. The OAuth integrations could not be set for the partner and seller.

  • PARTNER_BUSINESS_ERROR-FAILED_WHILE_GETTING_OAUTH_INTEGRATION

    FAILED_WHILE_GETTING_OAUTH_INTEGRATION. The OAuth integrations could not be fetched for the partner and seller.

  • PARTNER_BUSINESS_ERROR-MERCHANT_ID_SAME_AS_PARTNER_ID

    MERCHANT_ID_SAME_AS_PARTNER_ID. The seller ID is same as the partner ID.

  • PARTNER_BUSINESS_ERROR-NO_ATTRIBUTION_WITH_MERCHANT

    NO_ATTRIBUTION_WITH_MERCHANT. The partner can only get the seller details if the seller is referred by the partner.

  • PARTNER_BUSINESS_ERROR-PARTNER_MERCHANT_CLIENT_ASSOC_ALREADY_PRESENT

    PARTNER_MERCHANT_CLIENT_ASSOC_ALREADY_PRESENT. The seller client ID already exists for the PartnerId-MerchantId-PartnerClientId combination.

  • PARTNER_BUSINESS_ERROR-PARTNER_MERCHANT_CLIENT_ID_COMBINATION_INCORRECT

    PARTNER_MERCHANT_CLIENT_ID_COMBINATION_INCORRECT. The combination of partnerClientId-merchantClientId is incorrect for this partnerId-merchantId.

  • PARTNER_BUSINESS_ERROR-PARTNER_REFERRAL_LINK_ALREADY_EXISTS

    PARTNER_REFERRAL_LINK_ALREADY_EXISTS. The link between this lookup type and referral_id already exists.

  • PARTNER_BUSINESS_ERROR-PREFERENCES_ALREADY_EXIST

    PREFERENCES_ALREADY_EXIST. The preferences already exist for this partner account. Note: Use PATCH to update the content.

  • RESOURCE_NOT_FOUND_ERROR-AGREEMENTS_NOT_FOUND

    AGREEMENTS_NOT_FOUND. Agreements were not found for this account.

  • RESOURCE_NOT_FOUND_ERROR-INTEGRATIONS_NOT_FOUND

    INTEGRATIONS_NOT_FOUND. No integration was found between the partner and seller.

  • RESOURCE_NOT_FOUND_ERROR-INVALID_CONSENT_ID

    INVALID_CONSENT_ID. The consent was not found.

  • RESOURCE_NOT_FOUND_ERROR-INVALID_REFERRAL_ID

    INVALID_REFERRAL_ID. The referral ID is not valid.

  • RESOURCE_NOT_FOUND_ERROR-LINK_NOT_FOUND

    LINK_NOT_FOUND. No referrals are linked with this account.

  • UNAUTHORIZED-AUTHORIZATION_ERROR

    AUTHORIZATION_ERROR. This API call is not authorized.

  • UNAUTHORIZED-INVALID_CONSENT_OWNERSHIP

    INVALID_CONSENT_OWNERSHIP. The user is not the owner of the consent.

  • UNAUTHORIZED

    INVALID_PARTNER_RELATIONSHIP. The partner cannot use another partner for this API.

  • Unprocessable Entity

    SUCCESS_WITH_WARNING. The request is not valid.

  • USER_BUSINESS_ERROR

    USER_NOT_FOUND. The account for this ID does not exist.

Feedback

Have feedback?

Let us know.