PayPal Partner Referrals API
The PayPal Partner Referrals API enables platforms and marketplaces to onboard merchants onto PayPal, generate referral links, and track partner account creation status.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Partner Referrals
description: Use the Partner Referrals API to add PayPal seller accounts to PayPal Complete Payments Platform for Marketplaces and Platforms. <blockquote><strong>Important:</strong> This endpoint is available to approved partners only. <a href="/docs/multiparty/#link-tellusaboutyourplatform">Fill out this form</a> to get approved and a PayPal representative will reach out to you shortly.</blockquote> For more information about partner integrations and onboarding sellers, see <a href="/docs/multiparty">PayPal Complete Payments Platform for Marketplaces and Platforms.
version: '2.4'
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.
externalDocs:
url: https://developer.paypal.com/docs/platforms/seller-onboarding/before-payment/
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: [email protected]
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: [email protected]
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: [email protected]
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:
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/customer/partner: Manage seller resources.
https://uri.paypal.com/services/customer/partner-referrals/readwrite: Manage external referral data with PayPal
https://uri.paypal.com/services/customer/partner-referrals: Manage referral data shared by Partner with PayPal. To be used by only internal apps
responses:
default:
description: The default response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_default"
schemas:
'400':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- the value of a field is either too short or too long
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- the value of a field does not conform to the expected format
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- the value of a field is invalid
- title: INVALID_ARRAY_LENGTH
properties:
issue:
type: string
enum:
- INVALID_ARRAY_LENGTH
description:
type: string
enum:
- the number of items in an array parameter is too small or too large
'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
'403':
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- You do not have permission to access or perform operations on this resource.
'422':
properties:
details:
type: array
items:
anyOf:
- title: USER_NOT_FOUND
properties:
issue:
type: string
enum:
- USER_NOT_FOUND
description:
type: string
enum:
- Account for this Partner ID does not exist.
- title: ACCOUNT_STATUS_ERROR
properties:
issue:
type: string
enum:
- ACCOUNT_STATUS_ERROR
description:
type: string
- title: PRODUCT_PPCP_UNAUTHORIZED
properties:
issue:
type: string
enum:
- PRODUCT_PPCP_UNAUTHORIZED
description:
type: string
enum:
- Account has not been configured to use PayPal Complete Payments
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: 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:
type: string
description: The value of the field that caused the error.
location:
"$ref": "#/components/schemas/error_location"
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: 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.
required:
- issue
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
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"
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
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
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"
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"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
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"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
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"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
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"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
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"
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"
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
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"
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
error_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
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"
example:
name: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: 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.
maxLength: 140
middle_name:
type: string
description: 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.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
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
person_name:
type: object
title: Person name
description: The name of the person.
allOf:
- "$ref": "#/components/schemas/name"
- properties:
type:
description: 'The type of name. Currently supported values are: `LEGAL`.'
"$ref": "#/components/schemas/person_name_type"
required:
- type
country_code:
type: string
description: The [two-character ISO 3166-1 code](/docs/api/reference/country-codes/) that identifies the country or region.<blockquote><strong>Note:</strong> The country code for Great Bri
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-customer-partner-referrals-openapi-original.yml