Adaptive Accounts API: Getting Started

Get up and running with the Adaptive Accounts API:

Overview

The Adaptive Accounts API gives merchants and developers the ability to build applications that create and manage PayPal accounts. Using the functionality in Adaptive Accounts, you can create PayPal accounts, add additional funding methods to existing accounts, and verify the status of PayPal accounts from within your applications.

Key concepts

The Adaptive Accounts API is designed to let you create and manage PayPal accounts. You can use the API to:

  • Create Business, Premier, and Personal PayPal accounts directly from your application or web site.
  • Link a bank account, or add a credit or debit card, as a payment method for existing PayPal accounts.
  • Help reduce fraud by verifying a customer's PayPal account status before processing their payment.

By integrating Adaptive Accounts calls into your applications, you can enable users to create new PayPal accounts from your transaction flows. For example, you can provide a way for a user to create a PayPal accounts during the checkout phase of a transaction. This provides a secure way for users to complete a transaction and, by verifying the account, you can be assured the payment will be completed as agreed upon.

Account Creation Process

The following diagram depicts the process flow that takes place when a user creates a PayPal account using Adaptive Accounts. After calling the CreateAccount operation, PayPal returns a key that is then used in a redirect back to PayPal where the account is created. Once the user finishes the account-creation process, they are redirected back to your application so they can complete tasks they started there.

Adaptive Accounts Overview

Process Flow for Creating a PayPal Account

Adaptive Accounts API Operations

The Adaptive Accounts API provides several operations, as outlined in the following table:

Operation Description
CreateAccount Creates a PayPal account on behalf of a third party.
AddBankAccount Sets up a bank account as a funding source for a PayPal account.
AddPaymentCard Sets up a credit card as a funding sources for a PayPal account.
SetFundingSourceConfirmed Confirms a funding source for a PayPal account.
GetVerifiedStatus Retrieves the verified status of a PayPal account. To determine whether you can use this limited-release API, contact your PayPal integration team.
GetUserAgreement Retrieves the User Agreement to enable the customer to approve their new PayPal account.

Make your first call

To make a call to the Adaptive Accounts CreateAccount operation, supply the necessary HTTP headers and call payload to the service endpoint.

A call to the CreateAccount operation involves two users:

  • API Caller, represents the business entity and the account whose credentials the application uses to make the call
  • Sender, the account making the payment

The following steps outline the inputs needed to make the call.

  1. Obtain the endpoint for the environment you are addressing.

    The Sandbox endpoint for the CreateAccount operation is:

    https://svcs.sandbox.paypal.com/AdaptiveAccounts/CreateAccount
    
  2. Format the HTTP headers needed to make the call.

    To call the CreateAccount operation, supply the following HTTP headers:

     // Sandbox API credentials for the API Caller account
     X-PAYPAL-SECURITY-USERID : Sandbox-Caller-User-Id
     X-PAYPAL-SECURITY-PASSWORD : Sandbox-Caller-Password
     X-PAYPAL-SECURITY-SIGNATURE : Sandbox-Caller-Security-Signature
    

    // Sandbox Application ID X-PAYPAL-APPLICATION-ID : APP-80W284485P519543T

    // Input and output formats X-PAYPAL-REQUEST-DATA-FORMAT : JSON X-PAYPAL-RESPONSE-DATA-FORMAT : JSON

    // Call-specific headers X-PAYPAL-DEVICE-IPADDRESS : Device-IP-Address // Not used for web apps X-PAYPAL-SANDBOX-EMAIL-ADDRESS : Sandbox-Caller-eMail-Address // Sandbox use only

  3. Format the call payload.

    The CreateAccount operation requires the following payload input fields, formatted here as a JSON object:

     {
       "accountType":"PERSONAL",  // Specify the type of account to create
       "name": {                  // Name of the new account owner
       "firstName":"Lenny",
       "lastName":"Riceman"
     },
       "address": {               // Address of the new account owner
       "line1":"123 Main St",
       "city":"Austin",
       "state":"TX",
       "postalCode":"78759",
       "countryCode":"US"
     },
     "citizenshipCountryCode":"US",         // The country in which account owner lives
     "contactPhoneNumber":"512-555-5555",   // Phone number of the account owner
     "dateOfBirth":"1968-01-01Z"            // Date of birth of the account owner
    

    // The URL to where the user is redirected after completing the PayPal account setup "createAccountWebOptions": { "returnUrl":"https://example.com/success.html" }, "currencyCode":"USD", // Currency used by the account "emailAddress":"lr12345@example.com", // eMail address of the account owner "preferredLanguageCode":"en_US", // Language associated with the account "registrationType":"Web", // From where the account is created "requestEnvelope": { "errorLanguage":"en_US" // Language used to display errors },

    // Sandbox eMail address of the account owner (for testing only) "sandboxEmailAddress":"Sandbox-Sender-eMail-Address", }

    That's it, you're now set to make the call.

  4. Make the call.

    If the CreateAccount call is successful (the ack field in the response contains Success), the user is redirected to PayPal to finalize the account details (including assigning an account password and accepting the PayPal User Agreement). Once the new account process is complete on PayPal, the user is redirected back to your application (or web site) so they can complete any transactions they have started there.

Try it

Run the following cURL command that calls the CreateAccount operation. Run the command by copying and pasting it into a code window. (If cURL is not installed on your system, you can download the free cURL executable from https://curl.haxx.se/download.html.)

curl https://svcs.sandbox.paypal.com/AdaptiveAccounts/CreateAccount \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: caller_1312486258_biz_api1.gmail.com" \
  -H "X-PAYPAL-SECURITY-PASSWORD: 1312486294" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CTeylixNNxDZUu0iO87e" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T" \
  -H "X-PAYPAL-DEVICE-IPADDRESS: 192.0.2.0" \
  -H "X-PAYPAL-SANDBOX-EMAIL-ADDRESS: caller_1312486258_biz@gmail.com" \
  -d '{
  "sandboxEmailAddress":"sender_1312486456_per@gmail.com",
  "accountType":"PERSONAL",
  "name":{
    "firstName":"Lenny",
    "lastName":"Riceman"
  },
  "address":{
    "line1":"123 Main St",
    "city":"Austin",
    "state":"TX",
    "postalCode":"78759",
    "countryCode":"US"
  },
  "citizenshipCountryCode":"US",
  "contactPhoneNumber":"512-555-5555",
  "dateOfBirth":"1968-01-01Z",
  "createAccountWebOptions":{
    "returnUrl":"https://example.com/success.html"
  },
  "currencyCode":"USD",
  "emailAddress":"lr12345@example.com",
  "preferredLanguageCode":"en_US",
  "registrationType":"Web",
  "requestEnvelope":{
    "errorLanguage":"en_US"
  }
}'

Voilà! You have made your first call to the Adaptive Accounts API.

After issuing the command, the Adaptive Accounts service should return a successful response.

The above call is made possible by the use of a publicly-available set of Sandbox credentials (highlighted in the call). To get a feel for working with the APIs, complete the entire transaction flow in the Sandbox by substituting your own Sandbox credentials and user accounts into the above command.

If your original call is not successful, review the call response for the error details and address the problem before resubmitting the call.

Next steps

Use the following suggestions to enhance your understanding of the Adaptive Accounts API:

  1. Set up your sandbox environment.

    To make PayPal API test calls, you need a Sandbox account, test users, and PayPal API credentials. If you're not familiar with how to make a PayPal call or how to use the PayPal Sandbox, visit Apps 101.

  2. Substitute your own Sandbox credentials and user-specific inputs in the above cURL command, then reissue the command to ensure you have correctly set up your Sandbox users. Note that the cURL example makes use of two users: an API Caller and a Sender.

  3. Review the Adaptive Accounts Integration Guide for a complete reference to each of the available operations, and their input and output fields.

  4. To get help with API questions, discuss issues and share ideas, go to: