Identity API
Userinfo (resource group)
Use the /userinfo
resource to show user information details.
Show user profile information
Query parameters
schema
string
required
Filters the response by a schema. Supported value is
paypalv1.1
.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/identity/oauth2/userinfo?schema=paypalv1.1 \
-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 user profile information.
user_id
string
The Private Personal Identifier (PPID) that is unique for the end user and Relying Party.
name
string
The full name of the user. Includes all name parts, including titles and suffixes. The user's locale and preferences determine the syntax.
given_name
string
The given, or first, name of the user.
family_name
string
The surname or family name of the user. Also known as the last name. Used also to store multiple surnames including the matronymic, or mother's, surname.
emails
array (contains the email object)
An array of email addresses for the user.
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.address
The end-user's preferred address.
verified_account
boolean
The end user’s PayPal account status. Indicates whether the account is verified or not.
payer_id
string
The end user's external PayPal account ID. Returned only if the
access_token
has thehttps://uri.paypal.com/services/paypalattributes
scope.
Sample Response
{
"user_id": "https://www.paypal.com/webapps/auth/identity/user/mWq6_1sU85v5EG9yHdPxJRrhGHrnMJ-1PQKtX6pcsmA",
"name": "identity test",
"given_name": "identity",
"family_name": "test",
"payer_id": "WDJJHEBZ4X2LY",
"address": {
"street_address": "1 Main St",
"locality": "San Jose",
"region": "CA",
"postal_code": "95131",
"country": "US"
},
"verified_account": "true",
"emails": [
{
"value": "user1@example.com",
"primary": true
}
]
}
Applications (resource group)
Use the /applications
resource to show merchant applications information.
Create merchant application
Request body
application_type
string
required
The application type, which is web.
An array of redirect URIs to configure for the application. For example,
https://example.com/callback
.client_name
string
required
The human-readable name of the client. Also, the registration name for the applicant.
logo_uri
string
The URL to the client application's logo. For example,
https://example.com/logo.png
.An array of contacts.
payer_id
string
required
The payer ID of the client to register. To validate the client, the API validates this value.
migrated_app
string
required
Indicates whether the applicant is a migrated application. For example, an Open ID or Open ID Connect client.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/identity/applications \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"redirect_uris": [
"https://example.com/callback",
"https://example.com/callback2"
],
"client_name": "AGGREGATOR",
"logo_uri": "https://example.com/logo.png",
"contacts": [
"facilitator@example.com",
"merchant@example.com"
],
"policy_uri": "https://example.com/policyuri",
"tos_uri": "https://example.com/tosuri",
"scope": "profile email address",
"token_endpoint_auth_method": "client_secret_basic",
"jwks_uri": "https://example.com/my_public_keys.jwks"
}'
Response
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows application information.
application_type
string
The application type, which is web.
redirect_uris
An array of redirect URIs to configure for the application. For example,
https://example.com/callback
.client_name
string
The human-readable name of the client. Also, the registration name for the applicant.
logo_uri
string
The URL to the client application's logo. For example,
https://example.com/logo.png
.contacts
array (contains the contact object)
An array of contacts.
payer_id
string
The payer ID of the client to register. To validate the client, the API validates this value.
migrated_app
string
Indicates whether the applicant is a migrated application. For example, an Open ID or Open ID Connect client.
Sample Response
{
"client_id": "AeTeCqaPp7JZBfUUb2d21cQ2KqyQGVhonfiUOJu99kgLhFFSrE59ruvhLOT4K3NzQoErgsUH6MY9uRqD",
"client_secret": "cf136dc3c1fc93f31185e5885805d",
"client_id_issued_at": 2893256800,
"client_secret_expires_at": 2893276800,
"redirect_uris": [
"https://example.com/callback",
"https://example.com/callback2"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"client_name": "AGGREGATOR",
"logo_uri": "https://example.com/logo.png",
"contacts": [
"facilitator@example.com",
"merchant@example.com"
],
"policy_uri": "https://example.com/policyuri",
"tos_uri": "https://example.com/tosuri",
"scope": "profile email address",
"token_endpoint_auth_method": "client_secret_basic",
"jwks_uri": "https://example.com/my_public_keys.jwks"
}
Account settings (resource group)
Use the /account-settings
resource to set and disable merchant account settings.
Set account properties
Request body
account_property
enum
required
The property for an account.
The possible values are:
BRAINTREE_MERCHANT
. A Braintree merchant.
An array of merchant preference categories.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/identity/account-settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"account_property": "BRAINTREE_MERCHANT",
"features": {
"categories": [
{
"name": "PAYMENT",
"groups": [
{
"name": "AUTH_SETTLE",
"preferences": [
{
"name": "ENABLE_ENHANCED_AUTH_SETTLE",
"value": "true"
}
]
}
]
}
]
}
}'
Response
A successful request returns the HTTP 201 Created
status code with no JSON response body.
Sample Response
201 Created
Disable account properties
Request body
account_property
enum
The name of the account property name to disable.
The possible values are:
BRAINTREE_MERCHANT
. A Braintree merchant.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/identity/account-settings/deactivate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"account_property": "BRAINTREE_MERCHANT"
}'
Response
A successful request returns the HTTP 204 No Response
status code with no JSON response body.
Sample Response
204 No Content
Common object definitions
account_property
account_property
enum
The property for an account.
The possible values are:
BRAINTREE_MERCHANT
. A Braintree merchant.
account_settings
account_property
enum
required
The property for an account.
The possible values are:
BRAINTREE_MERCHANT
. A Braintree merchant.
An array of merchant preference categories.
address
street_address
string
The full street address component. Can include house number, street name.
locality
string
The city or locality.
region
string
The state, province, prefecture, or region.
postal_code
string
The zip code or postal code.
country
string
The country name.
application
application_type
string
required
The application type, which is web.
An array of redirect URIs to configure for the application. For example,
https://example.com/callback
.client_name
string
required
The human-readable name of the client. Also, the registration name for the applicant.
logo_uri
string
The URL to the client application's logo. For example,
https://example.com/logo.png
.An array of contacts.
payer_id
string
required
The payer ID of the client to register. To validate the client, the API validates this value.
migrated_app
string
required
Indicates whether the applicant is a migrated application. For example, an Open ID or Open ID Connect client.
category
name
string
required
The category name.
description
string
The category description.
An array of groups in this category.
category_collection
categories
array (contains the category object)
An array of categories.
contact
user_type
string
required
The facilitator and merchant email details. Used to validate a PayPal account.
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.
disable_account_property
account_property
enum
The name of the account property name to disable.
The possible values are:
BRAINTREE_MERCHANT
. A Braintree merchant.
value
string
required
The email address for the user, in canonical format.
type
string
The email type. For example,
work
orhome
.primary
boolean
Indicates whether this email address is the primary email address.
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.
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.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error_details
field
string
The field that caused the error. If 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
, orquery
.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.
group
name
string
required
The group name.
description
string
The group description.
subgroups
array (contains the subgroup object)
An array of sub-groups.
preferences
array (contains the preference object)
An array of preferences in this group.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
override_notification_settings
preference
name
string
required
The preference name.
description
string
The preference description.
value
string
required
The current preference value.
status
enum
The status of the preference.
The possible values are:
A
. Active.I
. Inactive.
supported_countries
array (contains the supported_country object)
An array of supported countries supported. If you omit this parameter, default is the preference metadata country list.
supported_languages
array (contains the supported_language object)
An array of supported languages. If you omit this value, default is the preference metadata language list.
memo
string
An optional memo. Used for activity logging. Meaningful only during create and update operations.
override_notification_settings
The override notification settings. The client can override the notification settings when the preference is changed to a particular state or value. Meaningful only during create and update operations.
time_created
string
The date and time when the preference was created, in Internet date and time format. Available only for a set of preferences, such as the presentation settings. Meaningful only for the
GET
operation. This value is ignored during the update operation.time_updated
string
The date and time when the preference was last changed, in Internet date and time format. Available only for a set of preferences, such as the presentation settings. Meaningful only for the
GET
operation. This value is ignored during the update operation.
subgroup
name
string
required
The subgroup name.
description
string
The subgroup description.
An array of preferences in this group.
supported_country
supported_country
string
The country code.
supported_language
supported_language
string
The language code.
userinfo
user_id
string
required
The Private Personal Identifier (PPID) that is unique for the end user and Relying Party.
name
string
The full name of the user. Includes all name parts, including titles and suffixes. The user's locale and preferences determine the syntax.
given_name
string
The given, or first, name of the user.
family_name
string
The surname or family name of the user. Also known as the last name. Used also to store multiple surnames including the matronymic, or mother's, surname.
emails
array (contains the email object)
An array of email addresses for the user.
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.address
The end-user's preferred address.
verified_account
boolean
The end user’s PayPal account status. Indicates whether the account is verified or not.
payer_id
string
The end user's external PayPal account ID. Returned only if the
access_token
has thehttps://uri.paypal.com/services/paypalattributes
scope.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Identity API can return the following errors.