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

      • 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

        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_REQUEST

          Invalid request.

        • INVALID_TOKEN

          Invalid access token.

        • INTERNAL_SERVER_ERROR

          Internal server error.