PayPal Account Authentication Service

Account
Authentication
Service
For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l’instant.
Last updated: October 2009

Account Authentication Service API Reference
Document Number: 10058.en_US-200910
© 2007-2009 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution.
PayPal FSA Register Number: 226056.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Account Authentication Service October 2009 3
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 1 About the Account Authentication Service . . . . . . . . . 7
Account Authentication Service Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Account Authentication Benefit Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7
Account Authentication Service Architecture . . . . . . . . . . . . . . . . . . . . . . . 8
Data Shared by the Account Authentication Service. . . . . . . . . . . . . . . . . . . . . . 9
Account Login for Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Account Sign Up for Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 2 Integrating the Account Authentication Service . . . . . . 11
Chapter 3 Account Authentication Service Reference . . . . . . . . .15
Authentication APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
GetAuthDetails API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SetAuthFlowParam API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Authentication Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
_account-authenticate-login Command . . . . . . . . . . . . . . . . . . . . . . . . . 21
_account-authenticate-logout Command . . . . . . . . . . . . . . . . . . . . . . . . 22

Contents
4 October 2009 Account Authentication Service

Preface
This document describes recurring payments using reference transactions.
Intended Audience
This document is intended for merchants implementing the PayPal account authentication
service, which supports store account login. Typically, the merchant will understand web
development or have access to those resources.
Revision History
Revision history for Account Authentication Service API Reference.
TABLE P.1 Revision History
Date Description
10/30/09 Added additional information about obtaining the name and email address.
10/30/07 First draft.

Revision History

1 About the Account
Authentication Service
Describes the account authentication service and the APIs and commands to integrate the
service.
Account Authentication Service Overview
Briefly describes the purpose, features, and architecture of the account authentication service.
The account authentication service enables your web site to verify the authenticity of your
customers. You can use this service to provide secure login to your site and leverage PayPal’s
database of many millions of accounts. Your customer can log in with confidence that their
financial information is protected and you can reduce the amount of effort required to provide
a secure service.
PayPal provides you with the information needed to track the customer on your site. If your
customer does not have an account with you, the information provided by PayPal will be
sufficient to identify and interact with the customer. If your customer does not have a PayPal
account, you can pre-populate information to make it easy to create a PayPal account and
continue their relationship with you.
You can use the account authentication service whether or not your customer chooses to pay
with PayPal. If your customer decides to pay with PayPal, the number of steps to complete an
order will be further reduced, streamlining the transaction and increasing order completion
rate.
Account Authentication Benefit Summary
Identifies the benefits of using the account authentication service.
The benefits to your customers of the account authentication service are as follows:
Customer logs in to your site with the confidence and security of logging into PayPal
A PayPal account holder logs in to your site without needing to provide additional
information
Because PayPal is widely used, the customer is more likely to remember his or her
username and password
The benefits to you as a merchant are as follows:
You can implement secure login with only two API calls; login occurs on paypal.com
Both PayPal and non-PayPal payment options are supported without changing your site

About the Account Authentication Service
Account Authentication Service Overview
You need not provide or maintain a separate site-specific signup process
You reduce your risk by reducing the amount of customer information that you must keep
secure
PayPal checkout flows are streamlined, increasing conversion
You gain the trust associated with PayPal in handling a customer’s financial information
Password reset is provided automatically as part of the login process
Account Authentication Service Architecture
Describes the parts of the account authentication service.
The account authentication service consists of two APIs and two commands. You call the
following APIs:
You redirect to PayPal to execute the following commands:
The following steps show the order in which you call the APIs and execute the commands to
authenticate an account:
1. Call the SetAuthFlowParam API to set up the flow and obtain a unique token.
2. Redirect to paypal.com using the _account-authenticate-login command and the
token to allow the customer to login or sign up.
3. Call the GetAuthDetails API with the token to obtain information about the customer
for tracking and communication purposes.
After successful completion of this step, you can allow your customer to perform all
operations that require security, including the placement of an order.
IMPORTANT: Authentication is complete only after successful completion of this step.
4. Redirect to paypal.com using the _account-authenticate-logout command to log
the customer off of your site if requested.
API Description
GetAuthDetails Retrieves details about the account being authenticated
SetAuthFlowParam Sets parameters used by account authentication flow
Command Description
_account-authenticate-login Invokes PayPal authentication login or signup flows
_account-authenticate-logout Invokes PayPal authentication logout flow

Data Shared by the Account Authentication Service
Data Shared by the Account Authentication Service
Describes the data shared by PayPal with a merchant.
As a merchant, you need not share any data with PayPal. Upon successful authentication,
PayPal provides you with the customer’s Payer ID, which uniquely identifies the customer.
You can use the Payer ID to track the customer on your site.
When you call the SetAuthFlowParam API, you can request that the customer approve
sending you additional information:
Customer first and last name
Customer email address
By logging into PayPal, your customer approves the release of the required information. You
can choose to request partial information or none at all if the Payer ID is sufficient
Account Login for Authentication
Shows the account login user interface for authentication.
Use the account login user interface to emphasize login over signup; this is the default login
page. The login screen appears when you redirect to paypal.com using the _account-
authenticate-login command:
The text above the Agree and Login button changes to reflect your request for required
information.

Account Sign Up for Authentication
Account Sign Up for Authentication
Shows the PayPal account sign up user interface.
Use the account sign up user interface to easily allow a new customer to create a PayPal
account for account authentication. The signup screen appears when you redirect to
paypal.com using the _account-authenticate-login command after calling the
SetAuthFlowParam API with the INITFLOWTYPE field set to Signup:
The text above the Agree and Login button changes to reflect your request for required
information.

2 Integrating the Account
Authentication Service
Describes how to implement the account authentication service using the PayPal NVP
interface.
The following diagram shows the account authentication service flow. The pages on the left
represent your site.
The following steps match the circled numbers in the diagram. Implement these steps to
integrate the account authentication service with your site.
1. Specify values for the fields with which to invoke the account authentication service flow
and invoke the SetAuthFlowParm API.
You must set the following fields:

Integrating the Account Authentication Service
You can also set fields to customize your PayPal pages. To invoke the signup flow, you
must set the INITFLOWTYPE to Signup. You can set additional fields to pre-populate the
customer’s name and address as well.
The following example shows how to set the required fields for the SetAuthFlowParm API,
as well as how to set fields required to retrieve the name and email later using the
GetAuthDetails API, and post it as form:
<form method=post action=https://api-3tpaypal.com/nvp>
<input type=hidden name=USER value= API_username>
<input type=hidden name=PWD value= API_password>
<input type=hidden name=SIGNATURE value= API_signature>
<input type=hidden name=VERSION value=version>
<input type=hidden name=RETURNURL value=yourReturnURL>
<input type=hidden name=CANCELURL value=yourCancelURL>
<input type=hidden name=LOGOUTURL value=yourLogoutURL>
<input name=SERVICENAME1 value=Name>
<input name=SERVICEDEFREQ1 value=Required>
<input name=SERVICENAME2 value=Email>
<input name=SERVICEDEFREQ2 value=Required>
<input type=submit name=METHOD value=SetAuthFlowParam>
</form>
PayPal responds with a message, such as the one shown below.
Field Description
RETURNURL URL to which the customer’s browser is returned after choosing to
authenticate with PayPal.
NOTE: Consider setting this URL to the next page in your flow; for
example, if you require authentication to check order status, the
return URL might specify your order status page.
Character length and limitations: no limit.
CANCELURL URL to which the customer is returned if he or she does not log in.
NOTE: Consider setting this URL to the current page so that the customer is
returned to the page he or she was on before being redirected to the
login page.
Character length and limitations: no limit
LOGOUTURL URL to which the customer is returned on logout from your site.
NOTE: Consider setting this URL to your home page so that the customer is
redirected to your home page after logging out.

TIMESTAMP=2007%2d04%2d05T23%3a23%3a07Z
&CORRELATIONID=63cdac0b67b50
&ACK=Success
&VERSION=2%2e300000
&BUILD=1%2e0006
&TOKEN=HA%2d1NK66318YB717835M
The status returned in the ACK field set should be set to Success. The token is used in the
steps that follow.
2. If the operation was successful, set the following parameters and redirect your browser to
PayPal:
NOTE: You may need to replace hexadecimal codes with ASCII codes; for example, you
may need to replace %2d in the token with a hyphen ( - ).
The following example shows how to redirect to PayPal using the specified command:
https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_account-
authenticate-login&TOKEN=HA-1NK66318YB717835M
If the customer successfully logs in, the customer’s browser is redirected to the page
specified by the RETURNURL field in the SetAuthFlowParam API. If the customer clicks
the Return to merchant link, the customer’s browser is redirected to the page specified by
the CANCELURL field; otherwise, the customer stays on the login page.
3. From your return URL page, invoke the GetAuthDetails API with the token from the
SetAuthFlowParm API response.
The following example shows how to set the required fields for the GetAuthDetails API
and post it as form:
<form method=post action=https://api-3t.sandbox.paypal.com/nvp
<input type=hidden name=USER value=API_username>
<input type=hidden name=PWD value=API_password>
<input type=hidden name=SIGNATURE value=API_signature>
<input type=hidden name=VERSION value=version>
<input type=hidden name=TOKEN value=HA-1NK66318YB717835M>
<input type=submit name=METHOD value=GetAuthDetails>
</form>
PayPal responds with a message such as the one shown below, which includes a status
code.
Parameter Description
cmd
_account-authenticate-login
token Token contained in the SetAuthFlowParam API response.

TIMESTAMP=2007%2d10%2d22T20%3a29%3a01Z
&CORRELATIONID=e03800e3cdc32
&ACK=Success
&VERSION=3%2e000000
&BUILD=1%2e0006
&PAYERID=PayerID
&FIRSTNAME=FirstName
&LASTNAME=LastName
&EMAIL=username%40domail%2esuffix
IMPORTANT: The status returned in the ACK field must be Success. If the operation is
not successful, the customer has not been authenticated.
If the operation is successful, the message also includes the required information about the
customer, such as the name and e-mail address.
4. When authentication is no longer required, set the following parameters and redirect your
browser to PayPal:
NOTE: You may need to replace hexadecimal codes with ASCII codes; for example, you
may need to replace %2d in the token with a hyphen ( - ).
The following example shows how to redirect to PayPal using the specified command:
https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_account-
authenticate-logout&TOKEN=HA-1NK66318YB717835M
When the customer logs out, the customer’s browser is redirected to the page specified by
the LOGOUTURL field in the SetAuthFlowParam API. If the customer cancels, the
customer’s browser is redirected to the page specified by the CANCELURL field.
cmd
_account-authenticate-logout
token Token contained in the SetAuthFlowParam response.

3 Account Authentication Service
Reference
Identifies APIs and commands for the account authentication service.
Authentication APIs
Identifies Authentication APIs.
GetAuthDetails API
Identifies GetAuthDetails API fields.
GetAuthDetails Summary
The following diagram shows the request and response fields for the GetAuthDetails API:
GetAuthDetails Request Fields
Identifies request fields for the GetAuthDetails API.
API Description
GetAuthDetails Retrieves details about the account being authenticated
SetAuthFlowParam Sets parameters used by account authentication flow

Account Authentication Service Reference
Authentication APIs
GetAuthDetails Response Fields
Identifies response fields for the GetAuthDetails API
GetAuthDetails Return Codes
Identifies errors and messages for the GetAuthDetails API.
Field Description
TOKEN A timestamped token, the value of which was returned in the
SetAuthFlowParam response.
Character length and limitations: 20 single-byte characters
Field Description
PAYERID The Payer ID of the authenticated customer.
Character length and limitations: 13 single-byte alphanumeric
characters
EMAIL The email address of the authenticated customer.
NOTE: To retrieve this information, you must specify Required
in the SERVICEDEFREQn field corresponding to
SERVICENAMEn = Email in the SetAuthFlowParm
API operation.
FIRSTNAME The first name of the authenticated customer.
SERVICENAMEn = Name in the SetAuthFlowParm API
operation.
LASTNAME The last name of the authenticated customer.
SERVICENAMEn = Name in the SetAuthFlowParm API
operation.
Code Short Message Long Message
10062 The Token has Expired The Token has Expired. For a new token make the API
call again
10063 The Token is Invalid The Token is Invalid. For a valid token make the API
call again

Authentication APIs
SetAuthFlowParam API
Identifies fields for the SetAuthFlowParam API.
SetAuthFlowParm Summary
The following diagram shows the request and response fields for the SetAuthFlowParam
API.
SetAuthFlowParam Request Fields
Identifies request fields for the SetAuthFlowParam API.

Authentication APIs
Required Fields.
Optional Fields.
Field Description
RETURNURL URL to which the customer’s browser is returned after choosing to
authenticate with PayPal.
NOTE: Consider setting this URL to the next page in your flow; for
example, if you require authentication to check order status, the
return URL might specify your order status page.
Character length and limitations: no limit.
CANCELURL URL to which the customer is returned if he or she does not log in.
NOTE: Consider setting this URL to the current page so that the customer is
returned to the page he or she was on before being redirected to the
login page.
LOGOUTURL URL to which the customer is returned on logout from your site.
NOTE: Consider setting this URL to your home page so that the customer is
redirected to your home page after logging out.
Field Description
LOCALECODE Locale of pages displayed by PayPal during authentication.
Character length and limitations: Any two-character country code.
The following two-character country codes are supported by PayPal:
AU
DE
FR
IT
GB
ES
US
Any other value will default to US.
PAGESTYLE Sets the Custom Payment Page Style of PayPal pages associated with this
button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name
you chose when adding or editing the page style from the Profile subtab
of the My Account tab of your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters.

Authentication APIs
HDRIMG URL for the image you want to appear at the top left of PayPal pages. The
image has a maximum size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored on a secure (https)
server.
Character length and limit: 127 single-byte alphanumeric characters
HDRBORDERCOLOR Sets the border color around the header on PayPal pages. The border is a 2-
pixel perimeter around the header space, which is 750 pixels wide by 90
pixels high.
Character length and limitations: Six character HTML hexadecimal color
code in ASCII
HDRBACKCOLOR Sets the background color for the header on PayPal pages.
Character length and limitation: Six character HTML hexadecimal color
code in ASCII
PAYFLOWCOLOR Sets the background color for the payment page.
Character length and limitation: Six character HTML hexadecimal color
code in ASCII
INITFLOWTYPE The initial flow, which is one of the following values:
login specifies the login flow
signup specifies the sign-up flow
If not specified, the default is login.
SERVICENAMEn A value to be returned, where n equal to 1 specifies the first value and n
equal to 2 specifies the next value, and so on. Allowable values are
Name specifies retuning the first name and last name fields
Email specifies returning the email address
SERVICEDEFREQn Whether the value specified by service name is required or optional, where n
equal to 1 specifies the first value and n equal to 2 specifies the next value,
and so on. Choices are
Required specifies that the value must be returned
Optional specifies that the value is not required
NOTE: You must specify Required if you want to retrieve the information
using GetAuthDetails.
FIRSTNAME Customer’s first name.
LASTNAME Customer’s last name.
Field Description

Authentication APIs
SetAuthFlowParam Response Fields
Identifies response fields SetAuthFlowParam API
SetAuthParam Return Codes
Identifies error and message codes for the SetAuthParam API.
Field Description
SHIPTONAME Person’s name associated with this address.
Character length and limitations: 32 single-byte
characters.
SHIPTOSTREET First street address.
characters.
SHIPTOSTREET2 Second street address.
characters.
SHIPTOCITY Name of city.
characters.
SHIPTOSTATE State or province.
characters.
Required for U.S. addresses only.
SHIPTOZIP U.S. ZIP code or other country-specific postal code.
characters.
SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte
characters.
Field Description
TOKEN A timestamped token, which is used by the account authentication
service.
10002 Authentication/Authorization Failed Username/Password is incorrect
10055 This account is not approved for the
authentication service
This account is not approved for the authentication
service. To enable this service, contact PayPal customer
service.

Authentication Commands
Identifies account authentication service commands.
_account-authenticate-login Command
Describes the login command for the account authentication service.
Redirect to PayPal using the _account-authenticate-login command
https://www.paypal.com/us/cgi-bin/webscr?
cmd=_account-authenticate-login&token=value
10056 Transaction refused because of an invalid
argument.
The Return URL parameter is missing. Please provide a
valid URL.
argument.
The Cancel URL parameter is missing. Please provide a
valid URL.
argument.
The Logout URL parameter is missing. Please provide a
valid URL.
argument.
The Return URL parameter is missing. Please provide a
URL.
argument.
The Cancel URL parameter is missing. Please provide a
URL.
argument.
The Logout URL parameter is missing. Please provide a
URL.
Command Description
_account-authenticate-login Invokes PayPal authentication login or signup flows
_account-authenticate-logout Invokes PayPal authentication logout flow

Response to _account-authenticate-login command from PayPal
url
_account-authenticate-logout Command
Describes the logout command for the account authentication service
Redirect to PayPal using the _account-authenticate-logout command
https://www.paypal.com/us/cgi-bin/webscr?
cmd=_account-authenticate-logout&token=value
Response to _account-authenticate-logout command from PayPal
logoutURL
cmd
_account-authenticate-login
token Token contained in the SetAuthFlowParam API response.
url URL set in one of the following fields of the
SetAuthFlowParam request:
returnURL if the buyer completed the login or signup
cancelURL if the buyer canceled the login or signup
cmd
_account-authenticate-logout
token Token contained in the SetAuthFlowParam response.
logoutURL Logout URL set in the SetAuthFlowParam request.

PayPal Account Authentication Service

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (14)

Semelhante a PayPal Account Authentication Service

Semelhante a PayPal Account Authentication Service (20)

Mais de Sherief Razzaque

Mais de Sherief Razzaque (20)

Último

Último (20)

PayPal Account Authentication Service