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

  • contacts

    array (contains the contact object)

    required

    An array of contacts.

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 allowed 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 allowed 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

  • name

    string

    required

    The category name.
  • description

    string

    The category description.
  • groups

    array (contains the group object)

    required

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

    Default: body.

  • issue

    string

    required

    The unique, fine-grained application-level error code.
  • description

    string

    The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

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.

override_notification_settings

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

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.

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.

  • INVALID_CLIENT

    Invalid client credentials. Invalid credentials provided in authentication header. Set the correct Base64-encoded clientID:clientsecret in the authentication header.

  • INVALID_REQUEST

    Invalid request. Incorrect parameter provided. Check for typos and send the correct input parameter.

  • INVALID_TOKEN

    Invalid access token. Incorrect access token provided as bearer token. Send a valid access token as the bearer token.

  • INTERNAL_SERVER_ERROR

    Internal server error. An internal server error has occurred. Check for error messages in the response.

Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community