Partner Referrals API

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 or contact us.

This API enables a marketplace to add PayPal merchant accounts. It supports the Connected path marketplace models.
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 to during the signup and setup process.

Call these methods for the Connected path:

Merchant integration (resource group)

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

Show merchant status

GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}
Shows status information for merchants who were onboarded by a partner, by ID.

Path parameters

  • partner_id

    string

    required

    The ID of the partner for which to show onboarded merchant status information.
  • merchant_id

    string

    required

    The ID of the merchant 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 merchant 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 merchant.
  • payments_receivable

    boolean

    Indicates whether the merchant account can receive payments.
  • primary_email_confirmed

    boolean

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

    string

    The primary email address of the merchant.
  • date_created

    string

    The date when the merchant 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 merchant.
  • api_credentials

    object

    The API credentials of the merchant.
  • oauth_integrations

    array (contains the oauth_integration object)

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

    array (contains the limitation object)

    An array of limitations on the merchant 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 merchant. 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",
      "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://www.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://www.example.com/logo/",
    "return_url": "https://www.example.com/",
    "action_renewal_url": "https://www.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.

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",
        "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://www.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://www.example.com/logo/",
      "return_url": "https://www.example.com/",
      "action_renewal_url": "https://www.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.

    Possible values: MOTHER.

  • 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, street, and so on.
  • line2

    string

    Optional. The second line of the address. For example, suite, apartment number, and so on.
  • 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

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

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.

    Possible values: CHECKING, SAVINGS.

  • 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 redirect merchant 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 merchant.

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 merchant category codes.

    Pattern: ^\d+$.

  • sub_category

    string

    The customer's business subcategory code. PayPal uses the industry standard merchant 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 merchant 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 merchant.

certificate

  • api_user_name

    string

    The API user name for the merchant.
  • api_password

    string

    The API password for the merchant.
  • fingerprint

    string

    The fingerprint.
  • download_link

    string

    The URL to download the certificate.

country_code

  • country_code

    string

    A 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 merchant credentials.
  • certificate

    object

    A certificate for merchant 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

    A valid, 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

    A valid, 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.
  • 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.

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. A valid value is body, path, or query. Default is body.
  • issue

    string

    required

    The unique 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.

    Possible values: ROUTING_NUMBER_1, ROUTING_NUMBER_2, ROUTING_NUMBER_3, BI_CODE, BANK_CODE, BRANCH_CODE, INTERMEDIARY_SWIFT_CODE, BBAN, BBAN_ENCRYPTED, BBAN_HMAC, 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 merchant 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 merchant.
  • payments_receivable

    boolean

    Indicates whether the merchant account can receive payments.
  • primary_email_confirmed

    boolean

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

    string

    The primary email address of the merchant.
  • date_created

    string

    The date when the merchant 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 merchant.
  • api_credentials

    object

    The API credentials of the merchant.
  • oauth_integrations

    array (contains the oauth_integration object)

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

    array (contains the limitation object)

    An array of limitations on the merchant account.

name

  • prefix

    string

    The prefix, or title, to the party name.

    Maximum length: 140.

  • given_name

    string

    The party's given, or first, name. Required if the party is a person.

    Maximum length: 140.

  • surname

    string

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

    Maximum length: 140.

  • middle_name

    string

    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

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

    Maximum length: 300.

oauth_integration

  • integration_type

    enum

    The type of integration between the partner and the merchant.

    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 of the partner.
  • merchant_client_id

    string

    The client ID of the merchant.
  • scopes

    array (contains the scope object)

    An array of scopes that the merchant 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 merchant.

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

rest_api_integration

  • integration_method

    enum

    The REST-credential integration method. Default is PAYPAL.

    Possible values: PAYPAL.

  • integration_type

    enum

    The type of REST-endpoint integration. To integrate with Braintree vzero for PayPal REST endpoints, specify REST_THIRD_PARTY_DETAILS.

    Possible values: THIRD_PARTY.

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 merchant. The merchant 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 merchant.
  • api_password

    string

    The API password of the merchant.
  • signature

    string

    The signature credential of the merchant.

user

  • customer_type

    enum

    The type of PayPal account to create, which is consumer or merchant.

    Possible values: CONSUMER, MERCHANT.

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

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

    CONSENT_ALREADY_EXISTS. The consent between this merchant and partner already exists. Note: Use PATCH to update the content.

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

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

  • PARTNER_BUSINESS_ERROR

    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. The link between this lookup type and referral_id already exists.

  • PARTNER_BUSINESS_ERROR

    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 were not found for this account.

  • RESOURCE_NOT_FOUND_ERROR

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

  • RESOURCE_NOT_FOUND_ERROR

    INVALID_CONSENT_ID. The consent was not found.

  • RESOURCE_NOT_FOUND_ERROR

    INVALID_REFERRAL_ID. The referral ID is not valid.

  • RESOURCE_NOT_FOUND_ERROR

    LINK_NOT_FOUND. No referrals are linked with this account.

  • UNAUTHORIZED

    AUTHORIZATION_ERROR. This API call is not authorized.

  • UNAUTHORIZED

    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.