Account Authentication Service Getting Started Guide

This guide contains these topics:

Overview

The account authentication service enables you to validate PayPal accounts and to facilitate post-transaction order management. You can use the service whether or not your customer chooses to pay with PayPal.

For more information, see the product page for the service.

Key concepts

The account authentication service provides the following authentication flow. For sample calls, see Make your first call.

  • SetAuthFlowParam. Sets up the account authentication flow and returns a token.
  • Redirect to PayPal. Redirect the customer to PayPal and include the token that was returned by SetAuthFlowParam. If the customer chooses to authenticate with PayPal, the customer is redirected back to your site.
  • GetAuthDetails. If a token from the SetAuthFlowParam call is specified on input, the GetAuthDetails call can return a customer's Payer ID, PayPal email address, first name, and last name.

After successful authentication, PayPal provides you with customer data that you can use to identify the customer on your site.

For more information about the account authentication service and a flow diagram, see the Developers Guide (PDF).

For this service, making sandbox calls with a test user other than the following one requires access; see the "How do I get this product?" section of the product page. For other information about the sandbox, see the PayPal Sandbox Getting Started Guide.

Make your first call

To validate a PayPal account in the sandbox:

  1. Set up the account authentication flow.
  2. Redirect the customer to PayPal for authorization.
  3. Retrieve the customer data for identifying the customer on your site.

This example uses the credentials of a test user. The test user already has permission to make calls to the account authentication service. For information about sandbox users, see PayPal APIs Getting Started Guide.

Set up the account authentication flow

To set up the account authentication flow and get a token for subsequent steps, call SetAuthFlowParam. For example, try the cURL command:

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=platfo_1255077030_biz_api1.gmail.com \
  -d PWD=1255077037 \
  -d SIGNATURE=Abg0gYcQyxQvnf2HDJkKtA-p6pqhA1k-KTYE0Gcy1diujFio4io5Vqjf \
  -d METHOD=SetAuthFlowParam \
  -d VERSION=88 \
  -d returnUrl=https://example.com/success \
  -d cancelUrl=https://example.com/cancel \
  -d logoutUrl=https://example.com/logout \
  -d SERVICENAME1=Name \
  -d SERVICEDEFREQ1=Required \
  -d SERVICENAME2=Email \
  -d SERVICEDEFREQ2=Required

The response looks like this:

TOKEN=HA%2dY8EHJTQJ81234&TIMESTAMP=2012%2d05%2d25T21%3a56%3a25Z&CORRELATIONID=10660ce9101ca&ACK=Success&VERSION=88&BUILD=2860716

This table describes the previous call-specific input parameters:

Name Description
returnUrl The URL to which the customer's browser is returned, after the customer chooses to log in to PayPal.
cancelUrl The URL to which the customer's browser is returned, if the customer chooses not to log in to PayPal.
logoutUrl The URL to which the customer's browser is returned after logging out from your site.
SERVICENAME1 The first customer value to be returned by this call. In the previous example, Name is specified.
SERVICEDEFREQ1 Specify Required to request the SERVICENAME1 value that you provided in this call.
SERVICENAME2 The second customer value to be returned by this call. In the previous example, Email is specified.
SERVICEDEFREQ2 Specify Required to request the SERVICENAME2 value that you provided in this call.

For more information, see Developers Guide (PDF).

Redirect the customer to PayPal for authorization

Redirect the customer with the token that SetAuthFlowParam returns.

After you URL-decode the token, append it to the PayPal authorization URL. The customer is prompted to log in using PayPal:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_account-authenticate-login&token InsertTokenHere

Get the customer data

To get the customer data that you can use to identify the customer on your site, call GetAuthDetails.

Note that the GetAuthDetails call is used after you have specified a set of customer data in the SetAuthFlowParam call (in the previous example, the customer name and email address), and the customer has logged into PayPal and then was redirected back to your site.

In this example, the URL-decoded token from the SetAuthFlowParam response is used in the following cURL command:

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=platfo_1255077030_biz_api1.gmail.com \
  -d PWD=1255077037 \
  -d SIGNATURE=Abg0gYcQyxQvnf2HDJkKtA-p6pqhA1k-KTYE0Gcy1diujFio4io5Vqjf \
  -d METHOD=GetAuthDetails \
  -d VERSION=88 \
  -d token=HA-Y8EHJTQJ81234

The response data looks like this:

PAYERID=3TXTXECKF1234&FIRSTNAME=Test&LASTNAME=User&EMAIL=sender_13212312345_per%40yahoo%2ecom&TIMESTAMP=2012%2d05%2d25T21%3a59%3a02Z&CORRELATIONID=8169cc911234&ACK=Success&VERSION=88&BUILD=2860716

This table describes the customer values returned in the previous GetAuthDetails call:

Name Description
PAYERID Unique identifier for a PayPal customer account.
FIRSTNAME The customer's first name.
LASTNAME The customer's last name.
EMAIL The customer's email address.

For more information, see Developers Guide (PDF).

Next steps

Review the information on the product page for the service.

Feedback