Partner Referrals API

Partners can use the Partner Referrals API to add PayPal seller accounts. The API supports the Connected Path model.
Important: The PayPal Commerce Platform 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 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 on-boards, 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 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.
  • capabilities

    array (contains the account_capability object)

    An array of capabilities associated with the products integrated between seller and partner.

Sample Response

{
  "merchant_id": "8LQLM2ML4ZTYU",
  "products": [
    {
      "name": "PAYFLOW_PRO",
      "vetting_status": "APPROVED",
      "active": true
    },
    {
      "name": "EXPRESS_CHECKOUT",
      "active": true
    },
    {
      "name": "PPCP_STANDARD",
      "vetting_status": "SUBSCRIBED",
      "capabilities": [
        "CUSTOM_CARD_PROCESSING",
        "CARD_PROCESSING_VIRTUAL_TERMINAL",
        "FRAUD_TOOL_ACCESS",
        "AMEX_OPTBLUE",
        "DEBIT_CARD_SWITCH",
        "COMMERCIAL_ENTITY"
      ]
    },
    {
      "name": "PPCP_CUSTOM",
      "vetting_status": "IN_REVIEW",
      "capabilities": []
    }
  ],
  "capabilities": [
    {
      "name": "CUSTOM_CARD_PROCESSING",
      "status": "ACTIVE",
      "limits": [
        {
          "type": "GENERAL"
        }
      ]
    },
    {
      "name": "CARD_PROCESSING_VIRTUAL_TERMINAL",
      "status": "ACTIVE"
    },
    {
      "name": "FRAUD_TOOL_ACCESS",
      "status": "ACTIVE"
    },
    {
      "name": "AMEX_OPTBLUE",
      "status": "ACTIVE"
    },
    {
      "name": "DEBIT_CARD_SWITCH",
      "status": "ACTIVE"
    },
    {
      "name": "COMMERCIAL_ENTITY",
      "status": "ACTIVE"
    }
  ],
  "payments_receivable": true,
  "primary_email": "seller@example.com",
  "primary_email_confirmed": true,
  "date_created": "2016-09-14 12:03:25 PDT",
  "granted_permissions": [
    "AIR_TRAVEL",
    "INVOICING",
    "RECURRING_PAYMENT_REPORT"
  ],
  "api_credential": {
    "signature": {
      "api_user_name": "example_api1.gmail.com",
      "api_password": "7QPZJL5PX2TT94RX",
      "signature": "Ak0kqXY-wqI.w.dfyQrwACtkK4HcMNxGdvADyrIE8QLgZWyIDNJSDlQ1e"
    }
  },
  "oauth_integrations": [
    {
      "integration_type": "OAUTH_THIRD_PARTY",
      "oauth_third_party": [
        {
          "partner_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
          "merchant_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
          "scopes": [
            "https://uri.paypal.com/services/payments/realtimepayment",
            "https://uri.paypal.com/services/payments/payment/authcapture",
            "https://uri.paypal.com/services/payments/refund"
          ]
        },
        {
          "partner_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
          "merchant_client_id": "AafBGhBphJ66SHPtbCMTsH1q2HQC2lnf0ER0KWAVSsOqsAtVfnye5Vc8hAOC",
          "scopes": [
            "https://uri.paypal.com/services/payments/realtimepayment",
            "https://uri.paypal.com/services/payments/payment/authcapture"
          ]
        }
      ]
    }
  ],
  "limitations": [
    {
      "name": "MRCHT - Pending User Agreement",
      "restrictions": [
        "ACH IN",
        "Withdraw Money",
        "Remove Bank",
        "Refunds to Buyer",
        "Close Account",
        "Send Money",
        "Remove Card"
      ]
    },
    {
      "name": "Seller-linked merchant",
      "restrictions": [
        "ACH IN",
        "Send Money",
        "Refunds to Buyer",
        "Receive/Request Money",
        "Remove Bank",
        "Remove Card",
        "Withdraw Money",
        "Close Account"
      ]
    }
  ]
}

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_capability

  • name

    enum

    Name of the capability. The possible values are:
    • PREPAID. Accounts with PREPAID capability can hold balance in their PayPal accounts.
    • INSTANT_FUNDS. Accounts with INSTANT_FUNDS capability can access theirs funds faster, with less Risk frictions such as availability holds, withdrawal holds, etc.
    • SEND_MONEY. Send money to a Paypal account
    • RECEIVE_MONEY. Receive branded payments from a instruments in a Paypal account
    • CARD_PROCESSING_VIRTUAL_TERMINAL. Enable merchant to receive direct credit card payment via phone/fax/mail. Merchant initiates transaction enters card into virtual terminal
    • AMEX_OPTBLUE. Enable merchant to accept AMEX. They can receive marketing communication from American express.
    • CUSTOM_CARD_PROCESSING. Receive direct credit card payment (card-not-present transactions)
    • FRAUD_TOOL_ACCESS. Access Fraud Protection tool (powered by Simility)
    • DEBIT_CARD_SWITCH. Receive debit card payment
    • COMMERCIAL_ENTITY. Merchant is considered as a commercial entity and hence needs to comply with the requirements and use the benefits, such as CE agreement and treatment on the credit card descriptor
    • WITHDRAW_MONEY. Withdraw funds to an external instruments such as a bank account
    • STANDARD_CARD_PROCESSING. Receive credit card payment via inline /guest checkout
    • PAYPAL_CREDIT_PROCESSING. Receive Paypal credit as a payment method
    • VENMO_PAY_PROCESSING. Receive Venmo pay
    • ALT_PAY_PROCESSING. Receive local payment methods specific to a buyer region (eg Giropay, Ideal, Sofort)
  • status

    enum

    The status of the capability. The possible values are:
    • ACTIVE. The capability is enabled for the account and can be used.
    • SUSPENDED. The capability can no longer be used, but there are remediation steps to regain access to the corresponding functionality.
    • REVOKED. The capability can no longer be used and there are no remediation steps available to regain the functionality.

    Read only.

    Minimum length: 1.

    Maximum length: 64.

    Pattern: ^[A-Z_]+$.

  • limits

    array (contains the capability_limit object)

    An array of limitations on the capability.

account_capability_names

  • account_capability_names

    enum

    The name of capability. The possible values are:
    • PREPAID. Accounts with PREPAID capability can hold balance in their PayPal accounts.
    • INSTANT_FUNDS. Accounts with INSTANT_FUNDS capability can access theirs funds faster, with less Risk frictions such as availability holds, withdrawal holds, etc.
    • SEND_MONEY. Send money to a Paypal account
    • RECEIVE_MONEY. Receive branded payments from a instruments in a Paypal account
    • CARD_PROCESSING_VIRTUAL_TERMINAL. Enable merchant to receive direct credit card payment via phone/fax/mail. Merchant initiates transaction enters card into virtual terminal
    • AMEX_OPTBLUE. Enable merchant to accept AMEX. They can receive marketing communication from American express.
    • CUSTOM_CARD_PROCESSING. Receive direct credit card payment (card-not-present transactions)
    • FRAUD_TOOL_ACCESS. Access Fraud Protection tool (powered by Simility)
    • DEBIT_CARD_SWITCH. Receive debit card payment
    • COMMERCIAL_ENTITY. Merchant is considered as a commercial entity and hence needs to comply with the requirements and use the benefits, such as CE agreement and treatment on the credit card descriptor
    • WITHDRAW_MONEY. Withdraw funds to an external instruments such as a bank account
    • STANDARD_CARD_PROCESSING. Receive credit card payment via inline /guest checkout
    • PAYPAL_CREDIT_PROCESSING. Receive Paypal credit as a payment method
    • VENMO_PAY_PROCESSING. Receive Venmo pay
    • ALT_PAY_PROCESSING. Receive local payment methods specific to a buyer region (eg Giropay, Ideal, Sofort)

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

account_capability_status

  • account_capability_status

    enum

    Status of the account capability. The possible values are:
    • ACTIVE. The capability is enabled for the account and can be used.
    • SUSPENDED. The capability can no longer be used, but there are remediation steps to regain access to the corresponding functionality.
    • REVOKED. The capability can no longer be used and there are no remediation steps available to regain the functionality.

    Read only.

    Minimum length: 1.

    Maximum length: 64.

    Pattern: ^[A-Z_]+$.

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

    string

    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, China, 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

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

beneficial_owners

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, which is returned from a create web experience profile call.
  • billing_context_set

    boolean

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

business

  • names

    array (contains the business_name object)

    An array of business names.
  • 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.

    Minimum length: 1.

    Maximum length: 128.

  • business_subtype

    enum

    The sub classification of business type. The possible values are:
    • ASSO_TYPE_INCORPORATED. The asso type incorporated.
    • ASSO_TYPE_NON_INCORPORATED. The asso type non incorporated.
    • GOVT_TYPE_ENTITY. The govt type entity.
    • GOVT_TYPE_EMANATION. The govt type emanation.
    • GOVT_TYPE_ESTD_COMM. The govt type estd comm.
    • GOVT_TYPE_ESTD_FC. The govt type estd fc.
    • GOVT_TYPE_ESTD_ST_TR. The govt type estd st tr.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

  • category

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • sub_category

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • merchant_category_code

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • purpose_code

    object (contains the purpose_code object)

    The account's purpose code.
  • website_urls

    array (contains the website_url object)

    An array of website URLs for the business.

    Minimum length: 1.

    Maximum length: 128.

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

business_beneficial_owner

  • names

    array (contains the business_name object)

    An array of business names.
  • 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.

    Minimum length: 1.

    Maximum length: 128.

  • business_subtype

    enum

    The sub classification of business type. The possible values are:
    • ASSO_TYPE_INCORPORATED. The asso type incorporated.
    • ASSO_TYPE_NON_INCORPORATED. The asso type non incorporated.
    • GOVT_TYPE_ENTITY. The govt type entity.
    • GOVT_TYPE_EMANATION. The govt type emanation.
    • GOVT_TYPE_ESTD_COMM. The govt type estd comm.
    • GOVT_TYPE_ESTD_FC. The govt type estd fc.
    • GOVT_TYPE_ESTD_ST_TR. The govt type estd st tr.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

  • category

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • sub_category

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • merchant_category_code

    string

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

    Minimum length: 1.

    Maximum length: 50.

    Pattern: ^\d+$.

  • purpose_code

    object (contains the purpose_code object)

    The account's purpose code.
  • website_urls

    array (contains the website_url object)

    An array of website URLs for the business.

    Minimum length: 1.

    Maximum length: 128.

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

    string

    The percentage of shares this person owns in the company.

    Minimum length: 1.

    Maximum length: 20.

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

    enum

    Sub classification of the business type. The possible values are:
    • ASSO_TYPE_INCORPORATED. The asso type incorporated.
    • ASSO_TYPE_NON_INCORPORATED. The asso type non incorporated.
    • GOVT_TYPE_ENTITY. The govt type entity.
    • GOVT_TYPE_EMANATION. The govt type emanation.
    • GOVT_TYPE_ESTD_COMM. The govt type estd comm.
    • GOVT_TYPE_ESTD_FC. The govt type estd fc.
    • GOVT_TYPE_ESTD_ST_TR. The govt type estd st tr.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

  • 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

    string

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

    object

    List of beneficial owners part of the entity. They can be either a Person or a business entity.
  • office_bearers

    array (contains the office_bearer object)

    List of office bearers as part of the business entity.

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_sub_type

  • business_sub_type

    enum

    Sub classification of the business type. The possible values are:
    • ASSO_TYPE_INCORPORATED. The asso type incorporated.
    • ASSO_TYPE_NON_INCORPORATED. The asso type non incorporated.
    • GOVT_TYPE_ENTITY. The govt type entity.
    • GOVT_TYPE_EMANATION. The govt type emanation.
    • GOVT_TYPE_ESTD_COMM. The govt type estd comm.
    • GOVT_TYPE_ESTD_FC. The govt type estd fc.
    • GOVT_TYPE_ESTD_ST_TR. The govt type estd st tr.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

business_sub_type

  • business_sub_type

    enum

    Sub classification of the business type. The possible values are:
    • ASSO_TYPE_INCORPORATED. The asso type incorporated.
    • ASSO_TYPE_NON_INCORPORATED. The asso type non incorporated.
    • GOVT_TYPE_ENTITY. The govt type entity.
    • GOVT_TYPE_EMANATION. The govt type emanation.
    • GOVT_TYPE_ESTD_COMM. The govt type estd comm.
    • GOVT_TYPE_ESTD_FC. The govt type estd fc.
    • GOVT_TYPE_ESTD_ST_TR. The govt type estd st tr.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

business_type

  • business_type

    enum

    The business type. The possible values are:
    • INDIVIDUAL. The individual.
    • PROPRIETORSHIP. The proprietorship.
    • PARTNERSHIP. The partnership.
    • CORPORATION. The corporation.
    • NONPROFIT. The nonprofit.
    • GOVERNMENT. The government.
    • GENERAL_PARTNERSHIP. The general partnership.
    • LIMITED_PARTNERSHIP. The limited partnership.
    • LIMITED_LIABILITY_PARTNERSHIP. The limited liability partnership.
    • PRIVATE_CORPORATION. The private corporation.
    • PUBLIC_CORPORATION. The public corporation.
    • PROPRIETORSHIP_CRAFTSMAN. The proprietorship craftsman.
    • PUBLIC_PARTNERSHIP. The public partnership.
    • LIMITED_LIABILITY_PROPRIETORS. The limited liability proprietors.
    • LIMITED_LIABILITY_PRIVATE_CORPORATION. The limited liability private corporation.
    • LIMITED_PARTNERSHIP_PRIVATE_CORPORATION. The limited partnership private corporation.
    • PRIVATE_PARTNERSHIP. The private partnership.
    • PROPRIETARY_COMPANY. The proprietory company.
    • PUBLIC_COMPANY. The public company.
    • ASSOCIATION. The association.
    • REGISTERED_COOPERATIVE. Registered Co-operative.
    • OTHER_CORPORATE_BODY. The other corporate body.
    • ANY_OTHER_BUSINESS_ENTITY. The any other business entity.
    • ONLY_BUY_OR_SEND_MONEY. The only buy and send money.

    Minimum length: 1.

    Maximum length: 255.

cancel_merchant_onboarding

  • merchant_email

    string

    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.

capability_limit

  • type

    enum

    Type of the limit. The possible values are:
    • GENERAL. Type of the limit.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

capability_limit_types

  • capability_limit_types

    enum

    The type of limit. The possible values are:
    • GENERAL. The type of limit.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

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

    string

    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. 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 this field is in the body, set this value to the field's JSON pointer value. 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, fine-grained application-level error code.
  • description

    string

    The human-readable description for an issue. The description can 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.

individual_beneficial_owner

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

    string

    The citizenship country code of the person
  • percentage_of_ownership

    string

    The percentage of shares this person owns in the company.

    Minimum length: 1.

    Maximum length: 20.

integration_details

  • partner_id

    string

    The payer ID of the partner who integrates with the client. 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.
  • rest_api_integration

    object

    The integration details for PayPal REST endpoints.
  • rest_third_party_details

    object

    The integration details for PayPal REST endpoints.
  • rest_first_party_details

    object

    The integration details for PayPal First Party 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 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.
  • capabilities

    array (contains the account_capability object)

    An array of capabilities associated with the products integrated between seller and partner.

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

  • 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 of the partner's API caller account.
  • 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.

office_bearer

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

    string

    The citizenship country code of the person
  • role

    enum

    The role of the person in the company. The possible values are:
    • CEO. The ceo.
    • CHAIRMAN. The chairman.
    • DIRECTOR. Director of the business
    • SECRETARY. The secretary.
    • TREASURER. The treasurer.
    • TRUSTEE. The trustee.

office_bearer

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

    string

    The citizenship country code of the person
  • role

    enum

    The role of the person in the company. The possible values are:
    • CEO. The ceo.
    • CHAIRMAN. The chairman.
    • DIRECTOR. Director of the business
    • SECRETARY. The secretary.
    • TREASURER. The treasurer.
    • TRUSTEE. The trustee.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

office_bearer_role

  • office_bearer_role

    enum

    Role of the person party played in the business. The possible values are:
    • CEO. The ceo.
    • CHAIRMAN. The chairman.
    • DIRECTOR. Director of the business
    • SECRETARY. The secretary.
    • TREASURER. The treasurer.
    • TRUSTEE. The trustee.

    Minimum length: 1.

    Maximum length: 255.

    Pattern: ^[0-9A-Z_]+$.

partner_specific_identifier

  • type

    enum

    required

    The identifier type.

    Possible values: TRACKING_ID.

  • value

    string

    required

    The identifier value.

person

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

    string

    The citizenship country code of the person

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.
  • 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, PPCP_STANDARD, PPCP_CUSTOM.

  • vetting_status

    enum

    The vetting status of the product, if applicable.

    Possible values: APPROVED, PENDING, DECLINED, SUBSCRIBED, IN_REVIEW, DENIED.

  • active

    boolean

    Indicates whether the product is active.
  • capabilities

    array (contains the account_capability_names object)

    An array of the capability names bundled in the parent product.

product_name

  • product_name

    enum

    The PayPal product for which the customer is onboarded.

    Possible values: EXPRESS_CHECKOUT, PPPLUS, WP_PRO, PPCP.

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:
    • FIRST_PARTY. Rest First Party Integration Type
    • 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_first_party_details

  • partner_client_id

    string

    The client ID of the partner.

    Minimum length: 1.

    Maximum length: 50.

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

    string

    S256 - The code verifier must be high-entropy cryptographic random string with a byte length of 43-128 range.

    Minimum length: 44.

    Maximum length: 128.

rest_third_party_details

  • partner_client_id

    string

    The client ID of the partner's API caller account.
  • 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 the 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-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-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_REFERRAL_ID

    INVALID_REFERRAL_ID. The referral ID is not valid.

  • UNAUTHORIZED-AUTHORIZATION_ERROR

    AUTHORIZATION_ERROR. This API call is not authorized.

  • 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