PayPal Partner-Referrals API

openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Partner-Referrals API
  description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  version: '1.6'
  contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
  description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
  description: PayPal Live Environment
tags:
- name: Partner-Referrals
  description: Enables you to create and get information about shared customer data.
paths:
  /v2/customer/partner-referrals:
    post:
      summary: Paypal Create partner referral
      description: Creates a partner referral that is shared by the partner or API caller. The partner referral is used to onboard the seller, and contains the seller's personal, business, financial and operations.
      operationId: partner-referrals.create
      responses:
        '201':
          description: A successful request returns the HTTP `201 Created` status code and a JSON response body that contains a [HATEOAS link](/docs/api/overview/#hateoas-links) 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_referral_data_response'
        '400':
          description: Request is not well-formed, syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_400'
                - $ref: '#/components/schemas/400'
        '401':
          description: The API call is not authorized.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_401'
                - $ref: '#/components/schemas/401'
        '403':
          description: Authorization failed due to insufficient permissions or missing scopes on the caller account.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_403'
                - $ref: '#/components/schemas/403'
        '422':
          description: The caller is not a business account or the account is closed or locked.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_422'
                - $ref: '#/components/schemas/422'
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_500'
        default:
          $ref: '#/components/responses/default'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/referral_data'
        required: true
      security:
      - Oauth2:
        - https://uri.paypal.com/services/customer/partner-referrals/readwrite
      tags:
      - Partner-Referrals
  /v2/customer/partner-referrals/{partner_referral_id}:
    get:
      summary: Paypal Show referral data
      description: Shows details by ID for referral data that was shared by the partner or API caller.
      operationId: partner-referrals.read
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows referral data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/referral_data_response'
              examples:
                referral_data:
                  value:
                    individual_owners:
                    - names:
                      - prefix: Mr.
                        given_name: John
                        surname: Doe
                        middle_name: Middle
                        suffix: Jr.
                        full_name: John Middle Doe Jr.
                        type: LEGAL
                      citizenship: US
                      addresses:
                      - address_line_1: One Washington Square
                        address_line_2: Apt 123
                        admin_area_2: San Jose
                        admin_area_1: CA
                        postal_code: '95112'
                        country_code: US
                        type: HOME
                      phones:
                      - country_code: '1'
                        national_number: '6692468839'
                        extension_number: '1234'
                        type: MOBILE
                      birth_details:
                        date_of_birth: '1955-12-29'
                      type: PRIMARY
                    business_entity:
                      business_type:
                        type: INDIVIDUAL
                        subtype: ASSO_TYPE_INCORPORATED
                      business_industry:
                        category: '1004'
                        mcc_code: '8931'
                        subcategory: '2025'
                      business_incorporation:
                        incorporation_country_code: US
                        incorporation_date: '1986-12-29'
                      names:
                      - business_name: Test Enterprise
                        type: LEGAL_NAME
                      emails:
                      - type: CUSTOMER_SERVICE
                        email: customerservice@example.com
                      website: https://mystore.testenterprises.com
                      addresses:
                      - address_line_1: One Washington Square
                        address_line_2: Apt 123
                        admin_area_2: San Jose
                        admin_area_1: CA
                        postal_code: '95112'
                        country_code: US
                        type: WORK
                      phones:
                      - country_code: '1'
                        national_number: '6692478833'
                        extension_number: '1234'
                        type: CUSTOMER_SERVICE
                      beneficial_owners:
                        individual_beneficial_owners:
                        - names:
                          - prefix: Mr.
                            given_name: John
                            surname: Doe
                            middle_name: Middle
                            suffix: Jr.
                            full_name: John Middle Doe Jr.
                            type: LEGAL
                          citizenship: US
                          addresses:
                          - address_line_1: One Washington Square
                            address_line_2: Apt 123
                            admin_area_2: San Jose
                            admin_area_1: CA
                            postal_code: '95112'
                            country_code: US
                            type: HOME
                          phones:
                          - country_code: '1'
                            national_number: '6692468839'
                            extension_number: '1234'
                            type: MOBILE
                          birth_details:
                            date_of_birth: '1955-12-29'
                          percentage_of_ownership: '50'
                        business_beneficial_owners:
                        - business_type:
                            type: INDIVIDUAL
                            subtype: ASSO_TYPE_INCORPORATED
                          business_industry:
                            category: '1004'
                            mcc_code: '8931'
                            subcategory: '2025'
                          business_incorporation:
                            incorporation_country_code: US
                            incorporation_date: '1986-12-29'
                          names:
                          - business_name: Test Enterprise
                            type: LEGAL_NAME
                          emails:
                          - type: CUSTOMER_SERVICE
                            email: customerservice@example.com
                          website: https://mystore.testenterprises.com
                          addresses:
                          - address_line_1: One Washington Square
                            address_line_2: Apt 123
                            admin_area_2: San Jose
                            admin_area_1: CA
                            postal_code: '95112'
                            country_code: US
                            type: WORK
                          phones:
                          - country_code: '1'
                            national_number: '6692478833'
                            extension_number: '1234'
                            type: CUSTOMER_SERVICE
                          percentage_of_ownership: '50'
                      office_bearers:
                      - names:
                        - prefix: Mr.
                          given_name: John
                          surname: Doe
                          middle_name: Middle
                          suffix: Jr.
                          full_name: John Middle Doe Jr.
                          type: LEGAL
                        citizenship: US
                        addresses:
                        - address_line_1: One Washington Square
                          address_line_2: Apt 123
                          admin_area_2: San Jose
                          admin_area_1: CA
                          postal_code: '95112'
                          country_code: US
                          type: HOME
                        phones:
                        - country_code: '1'
                          national_number: '6692468839'
                          extension_number: '1234'
                          type: MOBILE
                        birth_details:
                          date_of_birth: '1955-12-29'
                        role: DIRECTOR
                      annual_sales_volume_range:
                        minimum_amount:
                          currency_code: USD
                          value: '10000'
                        maximum_amount:
                          currency_code: USD
                          value: '50000'
                      average_monthly_volume_range:
                        minimum_amount:
                          currency_code: USD
                          value: '1000'
                        maximum_amount:
                          currency_code: USD
                          value: '50000'
                      purpose_code: P0104
                    email: accountemail@example.com
                    preferred_language_code: en-US
                    tracking_id: testenterprices123122
                    partner_config_override:
                      partner_logo_url: https://www.paypalobjects.com/webstatic/mktg/logo/pp_cc_mark_111x69.jpg
                      return_url: https://testenterprises.com/merchantonboarded
                      return_url_description: the url to return the merchant after the paypal onboarding process.
                      action_renewal_url: https://testenterprises.com/renew-exprired-url
                      show_add_credit_card: true
                    operations:
                    - operation: BANK_ADDITION
                    financial_instruments:
                      banks:
                      - nick_name: Bank of America
                        account_number: '123405668293'
                        account_type: CHECKING
                        currency_code: USD
                        identifiers:
                        - type: ROUTING_NUMBER_1
                          value: '123456789'
                    legal_consents:
                    - type: SHARE_DATA_CONSENT
                      granted: true
                    products:
                    - EXPRESS_CHECKOUT
        '401':
          description: The API call is not authorized.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_401'
                - $ref: '#/components/schemas/401'
        '403':
          description: Authorization failed due to insufficient permissions or missing scopes on the caller Account.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_403'
                - $ref: '#/components/schemas/403'
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_500'
        default:
          $ref: '#/components/responses/default'
      parameters:
      - $ref: '#/components/parameters/partner_referral_id'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/customer/partner-referrals/readwrite
      - Oauth2:
        - https://uri.paypal.com/services/customer/partner-referrals
      tags:
      - Partner-Referrals
components:
  schemas:
    phone_number_tag:
      description: Tag associated with the phone number.
      title: Phone number tag
      type: string
      pattern: ^[0-9A-Z_]+$
      minLength: 1
      maxLength: 255
      enum:
      - MOBILE
      - LANDLINE
    billing_experience_preference:
      type: object
      title: Billing Experience Preference
      description: The preference that customizes the billing experience of the customer.
      additionalProperties: false
      properties:
        experience_id:
          type: string
          description: The ID of the payment web experience profile.
          minLength: 1
          maxLength: 20
          pattern: ^[a-zA-Z0-9-]+$
        billing_context_set:
          type: boolean
          description: Indicates whether the partner has already displayed the billing context to the seller.
    person:
      title: Person
      description: Details of the person or party.
      properties:
        id:
          description: The encrypted party ID.
          type: string
          readOnly: true
          minLength: 1
          maxLength: 20
          pattern: ^[0-9A-Z]+$
        names:
          description: The name of the person.
          type: array
          items:
            $ref: '#/components/schemas/person_name'
          minItems: 0
          maxItems: 5
        citizenship:
          description: The citizenship country code of the person.
          $ref: '#/components/schemas/country_code'
        addresses:
          description: The list of addresses associated with the person.
          type: array
          items:
            $ref: '#/components/schemas/person_address_detail'
          minItems: 0
          maxItems: 5
        phones:
          description: The list of phone numbers associated with the person.
          type: array
          items:
            $ref: '#/components/schemas/person_phone_detail'
          minItems: 0
          maxItems: 5
        birth_details:
          description: The person's birth details.
          $ref: '#/components/schemas/birth_details'
        documents:
          description: A person's or party's related document data collected from the customer. For example SSN, ITIN, or business registration number collected from the user. <blockquote><strong>Note:</strong> This field is not applicable for POST [/v2/customer/partner-referrals](/docs/api/partner-referrals/v2/#partner-referrals_create) API calls.</blockquote>
          type: array
          items:
            $ref: '#/components/schemas/person_document'
          minItems: 0
          maxItems: 20
    link_description:
      type: object
      title: Link Description
      description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
      required:
      - href
      - rel
      properties:
        href:
          type: string
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
        rel:
          type: string
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - HEAD
          - CONNECT
          - OPTIONS
          - PATCH
    error_422:
      type: object
      title: Unprocessable Entity Error
      description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
      properties:
        name:
          type: string
          enum:
          - UNPROCESSABLE_ENTITY
        message:
          type: string
          enum:
          - The requested action could not be performed, semantically incorrect, or failed business validation.
        details:
          type: array
          items:
            $ref: '#/components/schemas/error_details'
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            $ref: '#/components/schemas/error_link_description'
    billing_agreement:
      type: object
      title: Billing Agreement
      description: The details of the billing agreement between the partner and a seller.
      additionalProperties: false
      properties:
        description:
          type: string
          description: The billing agreement description.
          minLength: 1
          maxLength: 125
          pattern: ^.+$
        billing_experience_preference:
          $ref: '#/components/schemas/billing_experience_preference'
        merchant_custom_data:
          type: string
          description: The custom data for the billing agreement.
          minLength: 1
          maxLength: 125
          pattern: ^[a-zA-Z0-9-]+$
        approval_url:
          type: string
          format: uri
          description: The URL to which to redirect seller to accept the billing agreement.
          minLength: 1
          maxLength: 125
        ec_token:
          type: string
          description: The billing agreement token for the agreement.
          minLength: 1
          maxLength: 50
          pattern: ^[0-9A-Z_-]+$
    product:
      type: string
      description: The PayPal product for which the customer is onboarded.
      title: Product Name
      minLength: 1
      maxLength: 127
      pattern: ^[0-9A-Z_-]+$
      enum:
      - EXPRESS_CHECKOUT
      - PAYPAL_COMMERCE_PLATFORM_BUSINESS
      - PPPLUS
      - WEBSITE_PAYMENT_PRO
      - PAYMENT_METHODS
      - PPCP
      - ADVANCED_VAULTING
      - IZETTLE
    error_link_description:
      title: Link Description
      description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
      type: object
      required:
      - href
      - rel
      properties:
        href:
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          type: string
          minLength: 0
          maxLength: 20000
          pattern: ^.*$
        rel:
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          type: string
          minLength: 0
          maxLength: 100
          pattern: ^.*$
        method:
          description: The HTTP method required to make the related call.
          type: string
          minLength: 3
          maxLength: 6
          pattern: ^[A-Z]*$
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
    phone:
      type: object
      title: Phone
      description: The phone number in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
      properties:
        country_code:
          type: string
          description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).
          minLength: 1
          maxLength: 3
          pattern: ^[0-9]{1,3}?$
        national_number:
          type: string
          description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).
          minLength: 1
          maxLength: 14
          pattern: ^[0-9]{1,14}?$
        extension_number:
          type: string
          description: The extension number.
          minLength: 1
          maxLength: 15
          pattern: ^[0-9]{1,15}?$
      required:
      - country_code
      - national_number
    individual_owner:
      title: Individual_owner
      description: The individual owner of the account.
      allOf:
      - $ref: '#/components/schemas/person'
      - properties:
          type:
            description: The actual role of this user on the account, PRIMARY/SECONDARY.
            $ref: '#/components/schemas/individual_owner_type'
    business_incorporation:
      title: Business_incorporation
      type: object
      description: Business incorporation information.
      properties:
        incorporation_country_code:
          description: The incorporation country code.
          $ref: '#/components/schemas/country_code'
        incorporation_date:
          description: date of incorporation
          $ref: '#/components/schemas/date_no_time'
        incorporation_province_code:
          description: The province of incorporation.
          type: string
          minLength: 1
          maxLength: 50
          pattern: ^[A-Z]{2}-([A-Z]{2,3}|[0-9]{2,3})$
    error_default:
      description: The default error response.
      oneOf:
      - $ref: '#/components/schemas/error_400'
      - $ref: '#/components/schemas/error_401'
      - $ref: '#/components/schemas/error_403'
      - $ref: '#/components/schemas/error_404'
      - $ref: '#/components/schemas/error_409'
      - $ref: '#/components/schemas/error_415'
      - $ref: '#/components/schemas/error_422'
      - $ref: '#/components/schemas/error_500'
      - $ref: '#/components/schemas/error_503'
    business_name_detail:
      type: object
      title: Business name
      description: Name of the business provided.
      allOf:
      - $ref: '#/components/schemas/business_name'
      - properties:
          id:
            description: The encrypted ID for the business name.
            type: string
            readOnly: true
            minLength: 1
            maxLength: 20
          type:
            description: The type of business name. For example, trading name.
            $ref: '#/components/schemas/business_name_type'
      required:
      - type
    business_name:
      type: object
      title: Business Name
      description: The business name of the party.
      properties:
        business_name:
          type: string
          description: Required. The business name of the party.
          maxLength: 300
    '401':
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: AUTHORIZATION_ERROR
              properties:
                issue:
                  type: string
                  enum:
                  - AUTHORIZATION_ERROR
                description:
                  type: string
                  enum:
                  - This API call is not authorized
    person_phone_detail:
      type: object
      title: Phone details
      description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
      allOf:
      - $ref: '#/components/schemas/phone'
      - properties:
          contact_name:
            type: string
            description: The name that the phone number is connected to.
            minLength: 1
            maxLength: 900
          inactive:
            type: boolean
            description: Whether this phone number has been inactivated by the user.
            readOnly: true
          primary:
            type: boolean
            description: Whether this is the primary contact phone number of the user.
          primary_mobile:
            type: boolean
            description: Whether this is the primary mobile phone number of the user.
          type:
            $ref: '#/components/schemas/phone_type'
            description: The type of phone number provided. For example, home, work, or mobile.
          tags:
            type: array
            description: Array of tags for this phone number.
            items:
              $ref: '#/components/schemas/phone_number_tag'
            minItems: 0
            maxItems: 20
      required:
      - type
    business_sub_type:
      description: Sub classification of the business type
      title: The business sub type.
      type: string
      pattern: ^[0-9A-Z_]+$
      minLength: 1
      maxLength: 255
      enum:
      - ASSO_TYPE_INCORPORATED
      - ASSO_TYPE_NON_INCORPORATED
      - GOVT_TYPE_ENTITY
      - GOVT_TYPE_EMANATION
      - GOVT_TYPE_ESTD_COMM
      - GOVT_TYPE_ESTD_FC
      - GOVT_TYPE_ESTD_ST_TR
    business_beneficial_owner:
      title: Business_beneficial_owner
      description: The business beneficial owner of the account.
      allOf:
      - $ref: '#/components/schemas/business'
      - properties:
          percentage_of_ownership:
            description: The percentage of shares this person owns in the company.
            $ref: '#/components/schemas/percentage'
    payout_attributes:
      type: object
      title: Payout Attributes
      additionalProperties: false
      description: Payout specific attributes.
      properties:
        marketplace:
          type: boolean
          description: If `true`, specifies that the merchant or platform is offering goods or services on behalf of 3rd party sellers.
        kyc_required:
          type: boolean
          description: If `true`, specifies that the Kyc is required for the merchant.
        country_transfer_method_currency_selection:
          type: array
          description: Requested country, transfer method and currency.
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/country_transfer_method_currency_selection'
    error_401:
      type: object
      title: Unauthorized Error
      description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
      properties:
        name:
          type: string
          enum:
          - AUTHENTICATION_FAILURE
        message:
          type: string
          enum:
          - Authentication failed due to missing authorization header, or invalid authentication credentials.
        details:
          type: array
          items:
            $ref: '#/components/schemas/error_details'
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            $ref: '#/components/schemas/error_link_description'
    person_document:
      title: Person document
      description: The documents associated with the person.
      allOf:
      - $ref: '#/components/schemas/document'
      - properties:
          type:
            description: The actual type of the document. It could be `ID_CARD`, `PASSPORT`, etc.
            $ref: '#/components/schemas/person_document_type'
    purpose_code_enum:
      type: string
      title: Purpose Code
      description: The purpose code. Required only for India. For more information, see the Reserve Bank Of India web site. Value is:<ul><li><code>P0104</code>. Cross border delivery of goods and services.</li><li><code>P0301</code>. Business related travel purchase.</li><li><code>P0801</code>. Hardware consulting.</li><li><code>P0802</code>. Software consulting.</li><li><code>P0803</code>. Data processing consulting.</li><li><code>P0805</code>. Freelance journalism.</li><li><code>P0806</code>. Other information services.</li><li><code>P0902</code>. Licensing revenues.</li><li><code>P1004</code>. Legal.</li><li><code>P1005</code>. Accounting and tax.</li><li><code>P1006</code>. Business and management consultancy.</li><li><code>P1007</code>. Advertising and market research.</li><li><code>P1008</code>. Research and development.</li><li><code>P1009</code>. Architectural services.</li></ul>
      minLength: 1
      maxLength: 50
      pattern: ^[a-zA-Z0-9]([a-zA-Z0-9_ ])+$
      enum:
      - P0104
      - P0301
      - P0801
      - P0802
      - P0803
      - P0805
      - P0806
      - P0902
      - P1004
      - P1005
      - P1006
      - P1007
      - P1008
      - P1009
    account:
      title: Account
      type: object
      description: Common account object to hold the account related details of the customer.
      properties:
        individual_owners:
          description: List of owners in the account. There should be only one primary account owner which is mentioned in their role_type.
          type: array
          items:
            $ref: '#/components/schemas/individual_owner'
          minItems: 0
          maxItems: 2
        business_entity:
          description: Business entity of the account.
          type: object
          $ref: '#/components/schemas/business_entity'
    person_name_type:
      description: The person's name type.
      title: Person name type
      type: string
      pattern: ^[0-9A-Z_]+$
      minLength: 1
      maxLength: 255
      enum:
      - LEGAL
    email_address:
      type: string
      description: The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
      format: ppaas_common_email_address_v2
      minLength: 3
      maxLength: 254
      pattern: ^.+@[^"\-].+$
    date_time:
      type: string
      description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are re

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-partner-referrals-api-openapi.yml