{ "openapi": "3.0.3", "info": { "title": "Partner Referrals", "description": "Use the Partner Referrals API to add PayPal seller accounts to PayPal Complete Payments Platform for Marketplaces and Platforms.
Important: This endpoint is available to approved partners only. Fill out this form to get approved and a PayPal representative will reach out to you shortly.For more information about partner integrations and onboarding sellers, see PayPal Complete Payments Platform for Marketplaces and Platforms.", "version": "2.5", "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": "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": "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": { "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" ] } } } ] } } } }, "account": { "title": "Account", "type": "object", "description": "Common account object to hold the account related details of the customer.", "properties": { "individual_owners": { "$ref": "#/components/schemas/individual_owner_list" }, "business_entity": { "description": "Business entity of the account.", "type": "object", "$ref": "#/components/schemas/business_entity" } } }, "address_details": { "type": "object", "title": "Address Details", "description": "The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
Craven House.",
"maxLength": 100
},
"sub_building": {
"type": "string",
"description": "The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.",
"maxLength": 100
}
}
},
"address_portable": {
"type": "object",
"title": "Portable Postal Address (Medium-Grained)",
"description": "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).",
"properties": {
"address_line_1": {
"type": "string",
"description": "The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address.",
"maxLength": 300
},
"address_line_2": {
"type": "string",
"description": "The second line of the address. For example, suite or apartment number.",
"maxLength": 300
},
"address_line_3": {
"type": "string",
"description": "The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address.",
"maxLength": 100
},
"admin_area_4": {
"type": "string",
"description": "The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "country_code-2": { "type": "string", "description": "The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region.GBand notUKas 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.
Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "country_transfer_method_currency_selection": { "type": "object", "title": "Requested country, transfer method and currency", "additionalProperties": false, "description": "Requested country, transfer method and currency.", "properties": { "country": { "description": "Country.", "$ref": "#/components/schemas/country_code" }, "transfer_methods": { "$ref": "#/components/schemas/transfer_method_list" } } }, "country_transfer_method_currency_selection_list": { "type": "array", "description": "Requested country, transfer method and currency.", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/country_transfer_method_currency_selection" } }, "create_referral_data_response": { "type": "object", "title": "Create Referral Data Response", "description": "The shared referral data.", "properties": { "links": { "$ref": "#/components/schemas/definitions-link_description_list" } } }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.", "type": "string", "format": "ppaas_common_currency_code_v2", "minLength": 3, "maxLength": 3 }, "currency_code-2": { "description": "The [three-character ISO-4217 currency code](/docs/api/reference/currency-codes/) that identifies the currency.", "type": "string", "format": "ppaas_common_currency_code_v2", "minLength": 3, "maxLength": 3 }, "currency_code_list": { "type": "array", "description": "Requested Currencies for a Transfer Method.", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/currency_code-2" } }, "currency_range": { "type": "object", "title": "Currency Range", "description": "The currency range, from the minimum inclusive amount to the maximum inclusive amount.", "additionalProperties": false, "properties": { "minimum_amount": { "description": "The minimum inclusive amount for the range.", "$ref": "#/components/schemas/money" }, "maximum_amount": { "description": "The maximum inclusive amount for the range.", "$ref": "#/components/schemas/money" } } }, "date_no_time": { "type": "string", "description": "The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.", "format": "ppaas_date_notime_v2", "minLength": 10, "maxLength": 10, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$" }, "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 required while fractional seconds are optional.GBand notUKas 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.
Note: The regular expression provides guidance but does not reject all invalid dates.", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 64, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$" }, "definitions-link_description_list": { "type": "array", "title": "Links", "description": "An array of request-related [HATEOAS links](/docs/api/overview/#hateoas-links).", "readOnly": true, "additionalProperties": true, "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description" } }, "dependent_process": {}, "dependent_process_list": { "type": "array", "description": "An array of dependent processes.", "items": { "$ref": "#/components/schemas/dependent_process" }, "minItems": 1, "maxItems": 5 }, "document": { "type": "object", "title": "Document", "description": "The document object.", "properties": { "id": { "type": "string", "description": "The encrypted identifier for the document.", "readOnly": true, "minLength": 1, "maxLength": 20, "pattern": "^[0-9A-Z]+$" }, "labels": { "$ref": "#/components/schemas/labels_list" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[0-9A-Za-z_-]+$", "description": "The file name." }, "identification_number": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9-]+$", "description": "The number for the document. It is the ID number if the document is `ID CARD`, the passport number if the document is `PASSPORT`, etc." }, "issue_date": { "$ref": "#/components/schemas/date_no_time", "description": "The issue date of the document." }, "expiry_date": { "$ref": "#/components/schemas/date_no_time", "description": "The expire data of the document." }, "issuing_country_code": { "$ref": "#/components/schemas/country_code", "description": "The country code of the document." }, "files": { "$ref": "#/components/schemas/file_reference_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "email": { "title": "Email of a person orbusiness", "description": "An email address at which the person or business can be contacted.", "type": "object", "properties": { "type": { "type": "string", "description": "The role of the email address.", "minLength": 1, "maxLength": 50, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "CUSTOMER_SERVICE", "description": "The email ID to be used to contact the customer service of the business." } ], "enum": ["CUSTOMER_SERVICE"] }, "email": { "$ref": "#/components/schemas/email_address" } }, "required": ["email", "type"] }, "email_address": { "type": "string", "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the", "format": "ppaas_common_email_address_v2", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" }, "email_list": { "description": "Email addresses of the business.", "type": "array", "items": { "$ref": "#/components/schemas/email" }, "minItems": 0, "maxItems": 5 }, "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" } }, "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_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_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_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" }, "file_reference": { "type": "object", "title": "File Reference", "description": "The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or another custom store.", "properties": { "id": { "type": "string", "description": "The ID of the referenced file.", "minLength": 1, "maxLength": 255 }, "reference_url": { "type": "string", "description": "The reference URL for the file.", "format": "uri", "minLength": 1, "maxLength": 2000 }, "content_type": { "type": "string", "description": "The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml)." }, "create_time": { "$ref": "#/components/schemas/date_time", "description": "The date and time when the file was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6)." }, "size": { "type": "string", "description": "The size of the file, in bytes.", "pattern": "^[0-9]+$" } } }, "file_reference_list": { "type": "array", "items": { "$ref": "#/components/schemas/file_reference" }, "minItems": 1, "maxItems": 50, "description": "The files contained in the document. For example, a document could be represented by a front page file and a back page file, etc." }, "financial_instruments": { "type": "object", "title": "Financial instrument.", "description": "Financial instruments attached to this account.", "additionalProperties": false, "properties": { "banks": { "$ref": "#/components/schemas/bank_list" } } }, "first_party_details": { "type": "object", "title": "REST First-Party Details", "description": "The integration details for PayPal first party REST endpoints.", "properties": { "features": { "$ref": "#/components/schemas/rest_endpoint_features_enum_list" }, "seller_nonce": { "type": "string", "description": "S256 - The code verifier must be high-entropy cryptographic random string with a byte length of 43-128 range.", "minLength": 44, "maxLength": 128, "pattern": "^[a-zA-Z0-9-_:]+$" } }, "required": ["features", "seller_nonce"] }, "identifier": { "type": "object", "title": "Bank Account Identifier", "additionalProperties": false, "description": "The bank account ID. An ID with `ROUTING_NUMBER_1` is required.", "properties": { "type": { "type": "string", "description": "The bank account ID type.", "minLength": 1, "maxLength": 125, "pattern": "^[0-9A-Z_-]+$", "x-enumDescriptions": [ { "value": "BANK_CODE", "description": "The bank code." }, { "value": "BI_CODE", "description": "The BI code." }, { "value": "BRANCH_CODE", "description": "The bank branch code." }, { "value": "ROUTING_NUMBER_1", "description": "The bank routing number." }, { "value": "ROUTING_NUMBER_2", "description": "The bank routing number." }, { "value": "ROUTING_NUMBER_3", "description": "The bank routing number." }, { "value": "SWIFT_CODE", "description": "The bank swift code." }, { "value": "BRANCH_CODE", "description": "Branch code." }, { "value": "INTERMEDIARY_SWIFT_CODE", "description": "Swift code." }, { "value": "BBAN", "description": "BBAN." }, { "value": "BBAN_ENCRYPTED", "description": "BBAN enrypted." }, { "value": "BBAN_HMAC", "description": "BBAN HMAC." }, { "value": "AGGREGATOR_YODLEE", "description": "Aggregator Yodlee." } ], "enum": [ "BANK_CODE", "BI_CODE", "BRANCH_CODE", "ROUTING_NUMBER_1", "ROUTING_NUMBER_2", "ROUTING_NUMBER_3", "SWIFT_CODE", "BRANCH_CODE", "INTERMEDIARY_SWIFT_CODE", "BBAN", "BBAN_ENCRYPTED", "BBAN_HMAC", "AGGREGATOR_YODLEE" ] }, "value": { "description": "The value of account identifier.", "type": "string", "minLength": 1, "maxLength": 125, "pattern": "^[A-Za-z0-9-_.+/ =]+" } } }, "identifier_list": { "type": "array", "description": "An array of instrument institute attributes. Used with the account number to uniquely identify the instrument. Value is:@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Note: This field is not applicable for POST [/v2/customer/partner-referrals](/docs/api/partner-referrals/v2/#partner-referrals_create) API calls.", "type": "array", "items": { "$ref": "#/components/schemas/person_document" }, "minItems": 0, "maxItems": 20 }, "person_document_type": { "type": "string", "title": "Document type", "description": "The type of documents.", "pattern": "^[0-9A-Z_]+$", "minLength": 1, "maxLength": 255, "x-enumDescriptions": [ { "description": "A social security number.", "value": "SOCIAL_SECURITY_NUMBER" }, { "description": "The employee identification number.", "value": "EMPLOYMENT_IDENTIFICATION_NUMBER" }, { "description": "A tax identification number.", "value": "TAX_IDENTIFICATION_NUMBER" }, { "description": "The passport number.", "value": "PASSPORT_NUMBER" }, { "description": "A pension fund ID.", "value": "PENSION_FUND_ID" }, { "description": "The medical insurance ID.", "value": "MEDICAL_INSURANCE_ID" }, { "description": "The identification number issued to Brazilian companies by the Department of Federal Revenue of Brazil.", "value": "CNPJ" }, { "description": "A Brazilian individual's taxpayer registry identification number.", "value": "CPF" }, { "description": "The permanent account number issued by the Indian Income Tax Department.", "value": "PAN" }, { "description": "A National ID card number.", "value": "NATIONAL_ID_CARD" } ], "enum": [ "SOCIAL_SECURITY_NUMBER", "EMPLOYMENT_IDENTIFICATION_NUMBER", "TAX_IDENTIFICATION_NUMBER", "PASSPORT_NUMBER", "PENSION_FUND_ID", "MEDICAL_INSURANCE_ID", "CNPJ", "CPF", "PAN", "NATIONAL_ID_CARD" ] }, "person_name": { "allOf": [ { "$ref": "#/components/schemas/name" }, { "properties": { "type": { "description": "The type of name. Currently supported values are: `LEGAL`.", "$ref": "#/components/schemas/person_name_type" } } }, { "type": "object", "title": "Person name", "description": "The name of the person.", "required": ["type"] } ] }, "person_name_list": { "description": "The name of the person.", "type": "array", "items": { "$ref": "#/components/schemas/person_name" }, "minItems": 0, "maxItems": 5 }, "person_name_type": { "description": "The person's name type.", "title": "Person name type", "type": "string", "pattern": "^[0-9A-Z_]+$", "minLength": 1, "maxLength": 255, "x-enumDescriptions": [ { "value": "LEGAL", "description": "Indicates that this name is the legal name of the user." } ], "enum": ["LEGAL"] }, "person_phone_detail": { "allOf": [ { "$ref": "#/components/schemas/phone" }, { "properties": { "type": { "$ref": "#/components/schemas/phone_type", "description": "The type of phone number provided. For example, home, work, or mobile." } } }, { "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).", "required": ["type"] } ] }, "person_phone_detail_list": { "description": "The list of phone numbers associated with the person.", "type": "array", "items": { "$ref": "#/components/schemas/person_phone_detail" }, "minItems": 0, "maxItems": 5 }, "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"] }, "phone_type": { "type": "string", "title": "Phone Type", "description": "The phone type.", "x-enumDescriptions": [ { "value": "FAX", "description": "A fax machine." }, { "value": "HOME", "description": "A home phone." }, { "value": "MOBILE", "description": "A mobile phone." }, { "value": "OTHER", "description": "Other." }, { "value": "PAGER", "description": "A pager." } ], "enum": ["FAX", "HOME", "MOBILE", "OTHER", "PAGER"] }, "product": { "type": "string", "description": "The PayPal product for which the customer is onboarded.", "title": "Product Name", "minLength": 1, "maxLength": 127, "pattern": "^[0-9A-Z_-]+$", "x-enumDescriptions": [ { "value": "ALIPAY", "description": "Alipay is a China-based payment method that allows customers to complete transactions online using their Alipay wallet. Include only if Alipay alone is required. You can use PPCP if all features are required." }, { "value": "BANCONTACT", "description": "Bancontact is a Belgium-based payment method that allows customers to complete transactions online using their bank credentials. Include only if Bancontact alone is required. You can use PPCP if all features are required." }, { "value": "BLIK", "description": "Blik is a Poland-based payment method that allows customers to complete transactions online using their bank credentials. Include only if Blik alone is required. You can use PPCP if all features are required." }, { "value": "EPS", "description": "EPS is an Austria-based payment method that allows customers to complete transactions online using their bank credentials. Include only if EPS alone is required. You can use PPCP if all features are required." }, { "value": "PPCP", "description": "PayPal Complete Payments product, which includes Express Checkout, advanced credit and debit card payments, Apple Pay, and Google Pay. Use PPCP if all features are required." }, { "value": "EXPRESS_CHECKOUT", "description": "Express checkout product." }, { "value": "PAYMENT_METHODS", "description": "PayPal Alternative Payment Methods product. Include only if Apple Pay or Google Pay or both are required alone. You can use PPCP if all features are required." }, { "value": "ADVANCED_VAULTING", "description": "PayPal Advanced Vaulting product. Must be requested along with either EXPRESS_CHECKOUT or PPCP. Include only if ADVANCED_VAULTING alone is required. You can use PPCP if all features are required." }, { "value": "IDEAL", "description": "iDEAL is a Netherlands-based payment method that allows customers to complete transactions online using their bank credentials. Include only if iDEAL alone is required. You can use PPCP if all features are required." }, { "value": "MB_WAY", "description": "MB Way is a Portugal-based payment method that allows customers to complete transactions online using their MB Way wallet. Include only if MB Way alone is required. You can use PPCP if all features are required." }, { "value": "MULTIBANCO", "description": "Multibanco is a Portugal-based payment method that allows customers to complete transactions online using their bank credentials or pay in cash at a bank branch. Include only if Multibanco alone is required. You can use PPCP if all features are required." }, { "value": "PAYPAL_COMMERCE_PLATFORM_BUSINESS", "description": "PayPal PayIn product." }, { "value": "PPPLUS", "description": "PayPal PLUS product." }, { "value": "PRZELEWY24", "description": "Przelewy24 is a Poland-based payment method that allows customers to complete transactions online. Include only if Przelewy24 alone is required. You can use PPCP if all features are required." }, { "value": "SATISPAY", "description": "Satispay is an Italy-based payment method that allows customers to complete transactions online using their bank credentials. Include only if Satispay alone is required. You can use PPCP if all features are required." }, { "value": "TRUSTLY", "description": "Trustly is a payment method that allows customers from (Austria (AT), Germany (DE), Denmark (DK), Estonia (EE), Spain (ES), Finland (FI), Great Britain (GB), Lithuania (LT), Latvia (LV), Netherlands (NL), Norway (NO), Sweden (SE)) to complete transactions online using their bank credentials. Include only if Trustly alone is required. You can use PPCP if all features are required." }, { "value": "WECHAT_PAY", "description": "WeChat Pay is a China-based payment method that allows customers to complete transactions online using their WeChat Pay wallet. Include only if WeChat Pay alone is required. You can use PPCP if all features are required." }, { "value": "WEBSITE_PAYMENT_PRO", "description": "PayPal Professional product." }, { "value": "ZETTLE", "description": "PayPal Zettle in-person payments product." }, { "value": "PAYPAL_COMMERCE_PLATFORM_BUSINESS", "description": "PayPal PayIn product." }, { "value": "HYPERWALLET_PAYOUTS", "description": "Hyperwallet payouts product" } ], "enum": [ "ALIPAY", "BANCONTACT", "BLIK", "EPS", "PPCP", "EXPRESS_CHECKOUT", "PAYMENT_METHODS", "ADVANCED_VAULTING", "IDEAL", "MB_WAY", "MULTIBANCO", "PAYPAL_COMMERCE_PLATFORM_BUSINESS", "PPPLUS", "PRZELEWY24", "SATISPAY", "TRUSTLY", "WECHAT_PAY", "WEBSITE_PAYMENT_PRO", "ZETTLE", "PAYPAL_COMMERCE_PLATFORM_BUSINESS", "HYPERWALLET_PAYOUTS" ] }, "product_list": { "type": "array", "description": "An array of PayPal products to which the partner wants to onboard the customer.", "items": { "$ref": "#/components/schemas/product" }, "minItems": 1, "maxItems": 5 }, "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:
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.