Identity API

Connect with PayPal (formerly Log In with PayPal) is a commerce identity solution that enables your customers to sign in to your web site quickly and securely using their PayPal login credentials. Connect with PayPal uses the latest security standards. You do not need to store user data on your system. For more information, see Connect with PayPal.

Userinfo (resource group)

Use the /userinfo resource to show user information details.

Show user profile information

GET/v1/identity/oauth2/userinfo

Shows user profile information. Filters the response by a schema. Supported schema value is `paypalv1.1`.

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
object
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 the https://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

POST/v1/identity/applications

Creates a merchant application.

Request body

application_type
string
required
The application type, which is web.
redirect_uris
array
required
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.
contacts
array (contains the contact object)
required
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.
Read only.
redirect_uris
array
An array of redirect URIs to configure for the application. For example, https://example.com/callback.
Read only.
client_name
string
The human-readable name of the client. Also, the registration name for the applicant.
Read only.
logo_uri
string
The URL to the client application's logo. For example, https://example.com/logo.png.
Read only.
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.
Read only.
migrated_app
string
Indicates whether the applicant is a migrated application. For example, an Open ID or Open ID Connect client.
Read only.

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

POST/v1/identity/account-settings

Sets the account properties.

Request body

account_property
enum
required
The property for an account.
The possible values are:
- BRAINTREE_MERCHANT. A Braintree merchant.
features
object
required
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

POST/v1/identity/account-settings/deactivate

Disables 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.
features
object
required
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.
Read only.
redirect_uris
array
required
An array of redirect URIs to configure for the application. For example, https://example.com/callback.
Read only.
client_name
string
required
The human-readable name of the client. Also, the registration name for the applicant.
Read only.
logo_uri
string
The URL to the client application's logo. For example, https://example.com/logo.png.
Read only.
contacts
array (contains the contact object)
required
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.
Read only.
migrated_app
string
required
Indicates whether the applicant is a migrated application. For example, an Open ID or Open ID Connect client.
Read only.

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.
email
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.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.

disable_account_property

account_property
enum
The name of the account property name to disable.
The possible values are:
- BRAINTREE_MERCHANT. A Braintree merchant.

email

value
string
required
The email address for the user, in canonical format.
type
string
The email type. For example, work or home.
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.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.

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.
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. The href 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.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

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
object
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.
preferences
array (contains the preference object)
required
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
object
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 the https://uri.paypal.com/services/paypalattributes scope.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Identity API can return the following errors.

INVALID_CLIENT
Invalid client credentials.
INVALID_REQUEST
Invalid request.
INVALID_TOKEN
Invalid access token.
INTERNAL_SERVER_ERROR
Internal server error.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

schema

Sample Request

user_id

name

given_name

family_name

emails

address

verified_account

payer_id

Sample Response

application_type

redirect_uris

client_name

logo_uri

contacts

payer_id

migrated_app

Sample Request

application_type

redirect_uris

client_name

logo_uri

contacts

payer_id

migrated_app

Sample Response

account_property

features

Sample Request

Sample Response

account_property

Sample Request

Sample Response

account_property

account_property

features

street_address

locality

region

postal_code

country

application_type

redirect_uris

client_name

logo_uri

contacts

payer_id

migrated_app

name

description

groups

categories

user_type

email

account_property

value

type

primary

email_address

name

message

debug_id

information_link

details

links

field

value

location

issue

description

name

description

`schema`

`user_id`

`name`

`given_name`

`family_name`

`emails`

`address`

`verified_account`

`payer_id`

`application_type`

`redirect_uris`

`client_name`

`logo_uri`

`contacts`

`payer_id`

`migrated_app`

`application_type`

`redirect_uris`

`client_name`

`logo_uri`

`contacts`

`payer_id`

`migrated_app`

`account_property`

`features`

`account_property`

`account_property`

`account_property`

`features`

`street_address`

`locality`

`region`

`postal_code`

`country`

`application_type`

`redirect_uris`

`client_name`

`logo_uri`

`contacts`

`payer_id`

`migrated_app`

`name`

`description`

`groups`

`categories`

`user_type`

`email`

`account_property`

`value`

`type`

`primary`

`email_address`

`name`

`message`

`debug_id`

`information_link`

`details`

`links`

`field`

`value`

`location`

`issue`

`description`

`name`

`description`

`subgroups`

`preferences`

`href`

`rel`

`method`

`name`

`description`

`value`

`status`

`supported_countries`

`supported_languages`

`memo`

`override_notification_settings`

`time_created`

`time_updated`