PayPal Adaptive Accounts - 2012 Developer's Guide

Adaptive Accounts Developer Guide

Last updated: May 2012

PayPal Adaptive Accounts Developer Guide

Document Number: 10109.en_US-201205

© 2012 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. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349 Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability: PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information co ntained 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 f rom 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.

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Adaptive Account Changes Corresponding for PayPal Version 89.0 . . . . . . . . . . . . . 9

Chapter 1 Introducing Adaptive Accounts . . . . . . . . . . . . . . .11

Adaptive Accounts Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Creating an Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Adding Bank Accounts as Funding Sources . . . . . . . . . . . . . . . . . . . . . . . . . 12

Adding Payment Cards as Funding Sources . . . . . . . . . . . . . . . . . . . . . . . . 12

Set Funding Sources to Confirmed Status. . . . . . . . . . . . . . . . . . . . . . . . . . 13

Verifying the Status of a PayPal Account . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Account Creation Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Account Creation Using a Minibrowser . . . . . . . . . . . . . . . . . . . . . . . . . 14

Adding a Credit Card in the Minibrowser Account Creation Flow . . . . . . . . . . . . 15

Confirming Account Creation Using a Mobile Phone . . . . . . . . . . . . . . . . . . 17

Default Account Creation From the Web . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2 Supported Formats, URLs and HTTP Request Headers . . .23

Adaptive Accounts Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Adaptive Accounts URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Supported Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

HTTP Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 3 CreateAccount API Operation . . . . . . . . . . . . . . . .27

CreateAccount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

CreateAccount Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

BusinessInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

BusinessStakeholderType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Adaptive Accounts Developer Guide May 2012 3

Contents

CreateWebOptionsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

NameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CreateAccount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CreateAccount Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CreateAccount Request Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CreateAccount Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 4 AddBankAccount API Operation . . . . . . . . . . . . . . 45

AddBankAccount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

AddBankAccount Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

WebOptionsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

AddBankAccount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

AddBankAccount Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 5 AddPaymentCard API Operation . . . . . . . . . . . . . . 51

AddPaymentCard Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

AddPaymentCard Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

NameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

CardDateType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

AddPaymentCard Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

AddPaymentCard Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

AddPaymentCard Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 6 SetFundingSourceConfirmed API Operation . . . . . . . .59

SetFundingSourceConfirmed Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

SetFundingSourceConfirmed Request Fields . . . . . . . . . . . . . . . . . . . . . . 59

RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

SetFundingSourceConfirmed Response. . . . . . . . . . . . . . . . . . . . . . . . . . . 60

ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

SetFundingSourceConfirmed Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4 May 2012 Adaptive Accounts Developer Guide

Contents

Chapter 7 GetVerifiedStatus API Operation . . . . . . . . . . . . . . 63

GetVerifiedStatus Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

GetVerifiedStatus Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

GetVerifiedStatus Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

GetVerifiedStatus Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

UserInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

GetVerifiedStatus Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Appendix A Country Codes . . . . . . . . . . . . . . . . . . . . . . . 69

Appendix B Business Categories and Subcategories . . . . . . . . . .77

Appendix C Adaptive Accounts IPN Messages. . . . . . . . . . . . . .89

Older Versions of the Adaptive Accounts API. . . . . . . . . . . . . . .91

Adaptive Account Changes Corresponding to PayPal Version 85.0. . . . . . . . . . . . . 91

Adaptive Account Changes Corresponding to PayPal Version 69.0. . . . . . . . . . . . . 92

Adaptive Account Changes Corresponding to PayPal Version 65.5 . . . . . . . . . . . . 92

Adaptive Account Changes Corresponding to PayPal Version 64.2 . . . . . . . . . . . . 92

Adaptive Account Changes Corresponding to PayPal Version 62.2. . . . . . . . . . . . . 93

Creating Business Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Adding Bank Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Verifying Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

Adaptive Accounts Developer Guide May 2012 5

Contents

6 May 2012 Adaptive Accounts Developer Guide

Preface

PayPal’s Adaptive Accounts API enables your customers to create various kinds of PayPal accounts.

Documentation Feedback

Help us improve this guide by sending feedback to: documentationfeedback@paypal.com

Adaptive Accounts Developer Guide May 2012 7

Documentation Feedback

8 May 2012 Adaptive Accounts Developer Guide

What’s New

Check out what’s new in the current release.

Adaptive Account Changes Corresponding for PayPal Version

89.0

Maintenance release.

Adaptive Accounts Developer Guide May 2012 9

Adaptive Account Changes Corresponding for PayPal Version 89.0

10 May 2012 Adaptive Accounts Developer Guide

Introducing Adaptive Accounts

The Adaptive Accounts API lets you build applications that create PayPal accounts and handle account management.

Adaptive Accounts Scenarios

The Adaptive Accounts API enables your application to create and verify PayPal accounts. You can also add bank accounts to link to PayPal accounts as funding sources.

Consider the following examples. You might create a PayPal account using the Adaptive Accounts APIs as part of the set up for a:

 marketplace. You can offer PayPal as a payment option and create PayPal accounts for

your users that do not already have them. Your users can include buyers and suppliers or clients and services providers as senders and receivers in various countries.

 social networking application, such as one that “pays for lunch” or sends a payment for any

reason. Your application may not be directly involved in the payment; however, you can enable the payment by ensuring that the user has the opportunity to create a PayPal account.

 enterprise application, such as a payroll application for small-to-medium sized businesses.

You can create PayPal accounts for each employee that does not have one and pay all employees using PayPal’s Mass Pay or Adaptive Payments capabilities.

 store checkout flow. You might provide PayPal account creation for your customers or you

might provide account creation for someone else’s customers as part of a shopping cart service.

Creating an Account

PayPal account holders traditionally create their PayPal accounts by going directly to PayPal.com or signing up during a checkout flow. The Adaptive Accounts CreateAccount method offers a new way: Creating accounts within your application or website, outside the checkout flow.

Your application sends a request using the CreateAccount method with information gathered from your website, and PayPal creates the account. At this point, the new PayPal account holder is briefly redirected to PayPal.com to enter private information, such as a password, and to accept the PayPal User Agreement. PayPal then returns the new account

Adaptive Accounts Developer Guide May 2012 11

Introducing Adaptive Accounts

Adding Bank Accounts as Funding Sources

holder to your website. This greatly reduces the chances of losing customers during the account creation flow.

That brings us to the key benefit of Adaptive Accounts: A streamlined account creation and completion process. Research shows that removing barriers from account creation and payment experience increases conversion and improves customer satisfaction.

Imagine the possibilities: With the CreateA ccount method, shopping cart application could create PayPal Business accounts for its merchants directly from the shopping cart site.

Adding Bank Accounts as Funding Sources

In addition to creating and verifying PayPal accounts, Adaptive Accounts lets your application link bank accounts to PayPal accounts as funding sources. Traditionally, PayPal account holders do this manually at PayPal.com. With the AddBankAccount method, you can now offer your customers the benefit of a smooth, uninterrupted process where PayPal account creation includes adding a funding source for the account, all in one fell swoop. If you are a financial institution, you can offer customers who are also PayPal account holders an easy way to link the bank account with your institution as a funding source for their PayPal accounts.

How does it work? Your application sends an AddBankAccount request, passing the relevant bank account information, such as the account number and routing number. The PayPal account holder is redirected briefly to PayPal.com to confirm the information, then returns to your customer’s website.

Adding Payment Cards as Funding Sources

Adaptive Accounts lets your application link the created PayPal account to a credit card or payment card. This card can then be used as a funding source (payment method) for the PayPal account. To use this feature, you use the createAccount key from the CreateAccount response and pass it with the AddPaymentCard method together with pertinent payment card information.

For standard permissions, the AddPaymentCard method requires the PayPal account user to confirm the payment card addition on paypal.com. Developers with advanced permissions can pass the AddPaymentCard with the confirmedType element (set to NONE) to add payment cards without redirecting to paypal.com.

Supported payment cards are:

 Visa  MasterCard  American Express  Discover  Maestro

12 May 2012 Adaptive Accounts Developer Guide

Set Funding Sources to Confirmed Status

 Solo  Carte Aurore  Carte Bleue  Cofinoga  4 étoiles  Carte Aura  Tarjeta Aurora  JCB

Set Funding Sources to Confirmed Status

If you call the AddBankAccount or AddPaymentCard methods, you can use the SetFundingSourceConfirmed method to set the created funding source to “confirmed”. In

certain instances, this will cause the PayPal account status to be set to Verified.

Introducing Adaptive Accounts

Verifying the Status of a PayPal Account

A huge challenge that merchants face today is fraud. The GetVerifiedStatus method is a great way to help PayPal merchants reduce the loss of profits due to fraud.

It works like this: Before a PayPal merchant engages in a transaction, the application sends a GetVerifiedStatus request. This request contains specific criteria you want to match, such as the PayPal account holder’s email address. The Adaptive Accounts web service responds with a message that indicates if the match was verified. This provides an effective method of reducing fraud. With the GetVerifiedStatus method, merchants have the security of knowing that consumers’ PayPal accounts are verified before completing a transaction.

Account Creation Flow

For account creation on the web, call CreateAccount and use the redirect URL to direct the person’s browser to PayPal. After the person creates an account, the browser is redirected to the return URL you specified in the CreateAccount request.

The following diagram shows the basic flow of control for account creation on the web:

Adaptive Accounts Developer Guide May 2012 13

Introducing Adaptive Accounts

Account Creation Flow

The following items correspond to the circled numbers in the diagram:

1. Your site or device sends a CreateAccount request to PayPal on behalf of a potential

account holder.

2. PayPal responds with a key and a URL, named the redirectURL, that you use when you

direct the person to PayPal.

3. You include the key and redirect your person’s browser to PayPal using the

redirectURL.

After the person logs on to PayPal and completes the account setup, the person is prompted to return to the URL.

Account Creation Using a Minibrowser

PayPal can enable your customer to create an account using a minibrowser flow. Set

CreateAccountRequest.CreateAccountWebOptio nsType.useMinibrowser to true in the CreateAccount request message to specify this flow.

NOTE: You must use Version 1.0.1 or higher of the Adaptive Accounts WSDL to implement

this flow.

When you redirect your customer’s browser to the URL in the CreateAccount response message, PayPal responds with the following:

14 May 2012 Adaptive Accounts Developer Guide

Introducing Adaptive Accounts

Account Creation Flow

Your customer enters the password twice and clicks Agree and Continue to create the account.

NOTE: By default, redirecting the browser to the returned URL opens the page in a default

browser window. You must provide JavaScripts to pop-up the window in a minibrowser or to display it in a lightbox within your browser window.

Adding a Credit Card in the Minibrowser Account Creation Flow

PayPal can require your customer to add a credit card using a minibrowser flow. Set

CreateAccountRequest.CreateAccountWebOptio nsType.showAddCreditCard to true in the CreateAccount request message to add a credit card during this flow.

After the customer specifies the password and agrees to create the account, PayPal responds with the following page in a minibrowser:

Adaptive Accounts Developer Guide May 2012 15

Introducing Adaptive Accounts

Account Creation Flow

Your customer enters debit or credit card information and clicks Add Card and Continue.

NOTE: Your customer can enter a phone number and associate a billing address, or add a new

address from the Billing address drop-down menu:

16 May 2012 Adaptive Accounts Developer Guide

Introducing Adaptive Accounts

Account Creation Flow

Confirming Account Creation Using a Mobile Phone

PayPal can enable your customer to confirm a mobile phone when creating an account for the following countries using the minibrowser flow: Australia, Canada, Spain, France, United Kingdom, Italy, Malaysia, Singapore, and United States. Set

CreateAccountRequest.CreateAccountWebOptio nsType.showMobileConfirm to true in the CreateAccount request message to enable account creation using a mobile

phone during this flow. After adding a debit or credit card, PayPal responds with the following page in a minibrowser:

Adaptive Accounts Developer Guide May 2012 17

Introducing Adaptive Accounts

Account Creation Flow

Your customer requests a confirmation code by clicking Send SMS, and then clicks Confirm Phone after entering the code in the SMS message.

NOTE: The phone number to confirm is the number associated with a debit or credit card for

the account, which you set on the Link a debit or credit card page. You cannot change the phone number.

Default Account Creation From the Web

To enable your customer to create a PayPal account, you call the CreateAccout API operation and use the returned URL to redirect your customer’s browser to PayPal. Your customer then signs up and agrees to the terms of the account.

18 May 2012 Adaptive Accounts Developer Guide

Introducing Adaptive Accounts

Account Creation Flow

By default, when you redirect your customer’s browser to the URL in the CreateAccount response message, PayPal responds with the following sequence of pages:

1. The Welcome page identifies the information that will be needed to create an account:

2. The Cr eate PayPal account login screen requests your customer to submit a password and

security questions, with answers:

Adaptive Accounts Developer Guide May 2012 19

Introducing Adaptive Accounts

Account Creation Flow

3. The Add Credit or Debit Card page enables your customer to specify a funding source

and billing information:

20 May 2012 Adaptive Accounts Developer Guide

Introducing Adaptive Accounts

Account Creation Flow

NOTE: The account holder can add a credit or debit card now or click Cancel to continue

without adding a card.

4. After the person logs on to PayPal and completes the account setup, the person is prompted

to return to the URL.

Adaptive Accounts Developer Guide May 2012 21

Introducing Adaptive Accounts

Account Creation Flow

22 May 2012 Adaptive Accounts Developer Guide

Supported Formats, URLs and

HTTP Request Headers

Adaptive Accounts Methods

Adaptive Accounts provides the following methods:

API Operation Description

CreateAccount Creates PayPal accounts. AddBankAccount Link bank accounts to PayPal accounts as funding sources. AddPaymentCard Link payment cards to PayPal accounts as funding sources SetFundingSourceConfirmed Set the funding source to confirmed; they may set the account to PayPal

Verified status.

GetVerifiedStatus Verify PayPal accounts by matching account holder criteria such as the

account holder’s email address.

Adaptive Accounts URLs

The endpoint is determined by the method and the environment in which you want to execute the API operation. For example, if you want to send a CreateAccount request to the sandbox, specify the following URL:

https://svcs.sandbox.paypal.co m/AdaptiveAccounts /CreateAccount

You can specify the following URLs:

Environment Endpoint

Production

https://svcs.paypal.com/AdaptiveAccounts/API_operation

Sandbox

https://svcs.sandbox.paypal.com/AdaptiveAccounts/API_operation

Adaptive Accounts Developer Guide May 2012 23

Supported Formats, URLs and HTTP Request Headers

Supported Formats

Adaptive Accounts supports both RESTful and SOAP-based web services. When making RESTful calls, you can use the following data formats:

 XML  Name-value pair (NV)  JSON

HTTP Request Headers

Required HTTP Request Headers

Header Description

X-PAYPAL-SECURITY-USERID Your API username as assigned to you on x.com. X-PAYPAL-SECURITY-PASSWORD Your API password as assigned to you on x.com. X-PAYPAL-SECURITY-SIGNATURE Your API signature. This header is only required if you use

3-token authorization. Do not pass this header if you use a certificate.

X-PAYPAL-APPLICATION-ID Your application’s identification, which is issued at x.com. X-PAYPAL-DEVICE-IPADDRESS The IP address of the caller. This header is required for

CreateAccount requests.

X-PAYPAL-REQUEST-DATA-FORMAT The payload format for the request.

Allowable values are:

 NV – Name-value pairs  XML – Extensible markup language  JSO N – JavaScript object notation

X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response.

Allowable values are:

 NV – Name-value pairs  XML – Extensible markup language  JSO N – JavaScript object notation

Optional HTTP Request Headers

Header Description

X-PAYPAL-SANDBOX-EMAIL-ADDRESS The email address that the API caller uses to log into the

sandbox or beta sandbox; not required outside of the sandbox.

24 May 2012 Adaptive Accounts Developer Guide

Supported Formats, URLs and HTTP Request Headers

HTTP Request Headers

Header Description

X-PAYPAL-DEVICE-ID Client’s device ID, such as a mobile device’s IMEI number.

This field is required for mobile application and is not used for web application.

X-PAYPAL-MERCHANT-REFERRAL-BONU S-ID When creating a Business or Premier account, this header

enables the Merchant Referral Bonus invitation.

X-PAYPAL-SERVICE-VERSION The version of an API operation to use. By default, PayPal

executes a request with the current version of an API operation.

NOTE: PayPal recommends not specifying a version unless

it is absolutely required.

Adaptive Accounts Developer Guide May 2012 25

Supported Formats, URLs and HTTP Request Headers

HTTP Request Headers

26 May 2012 Adaptive Accounts Developer Guide

CreateAccount API Operation

The CreateAccount API operation enables you to create a PayPal account on behalf of a third party.

CreateAccount Request

The CreateAccountRequest contains the information required to create a PayPal account for a business customer.

Adaptive Accounts Developer Guide May 2012 27

CreateAccount API Operation

CreateAccount Request

28 May 2012 Adaptive Accounts Developer Guide

CreateAccount API Operation

CreateAccount Request

Adaptive Accounts Developer Guide May 2012 29

CreateAccount API Operation

CreateAccount Request

CreateAccount Request Fields

Field Description

accountType xs:string

(Required) The type of account to be created. Allowable values are:

 Pe rsonal – Personal account  Pr emier – Premier account  Bu siness – Business account

address aa:Ad dressType

(Required) The address to be associated with the PayPal account.

businessInfo aa:BusinessInfoTyp e

This field is required for business account creation.

citizenshipCountryCode xs:string

(Required) The code of the country to be associated with the account. For allowable values, refer to “Country Codes” on page 69.

clientDetails Do not use this field. contactPhoneNumber xs:string

(Required) Phone number to be associated with the account.

homePhoneNumber xs:string

(Optional) Home phone number to be associated with the account.

30 May 2012 Adaptive Accounts Developer Guide

Field Description

mobilePhoneNumber xs:string

(Optional) Mobile phone number to be associated with the account. You must specify a value to invoke the mobile confirmation option.

createAccountWebOptions aa:CreateAccountWebOptionsType

(Required) The URL to which the business redirects the PayPal user for PayPal account setup completion; also used for various other. configuration settings for the web flow.

currencyCode xs:string

(Required) The three letter code for the currency to be associated with the account.

dateOfBirth xs:date

The date of birth of the person for whom the PayPal account is created. Required for Czech Republic, Japan, New Zealand, Israel, Switzerland, Sweden, Denmark, and Australia; otherwise optional. Use YYYY-MM-DDZ format; for example 1970-01-01Z.

CreateAccount API Operation

CreateAccount Request

emailAddress xs:string

(Required) Email address of person for whom the PayPal account is created.

name aa:NameType

(Required) The name of the person for whom the PayPal account is created.

notificationURL xs:string

(Optional) The URL to post instant payment notification (IPN) messages to regarding account creation. This URL supersedes the IPN notification URL set in the merchant profile.

Maximum string length: between 1 and 1024 characters of the pattern <[a-aZZ]+\://){1}\S+

partnerField

perfermExtraVettingOnthi sAccount

taxId xs:string

n xs:string

(Optional) A maximum of five fields for your own use, where between 1 and 5, inclusive.

xs:boolean

(Optional) Whether to subject the account to extra vetting by PayPal before the account can be used.

(Optional) Tax Id (equivalent to SSN in US).

NOTE: This is only supported for Brazil, which uses tax ID numbers such as

the CPF and CNPJ.

n is a digit

Adaptive Accounts Developer Guide May 2012 31

CreateAccount API Operation

CreateAccount Request

Field Description

preferredLanguageCode xs:string

(Required) The code indicating the language to be associated with the account. What value is allowed depends on the country code passed in the countryCode parameter for the address. Examples:

 Argentina (AR) – en_US, es_XC  Australia (AU) – en_AU  Austria (AT) – de_DE, en_US  Brazil (BR) – en_US  Canada (CA) – en_US, fr_XC  China (CN) – e n_US  Czech Republic (CZ) – en_US  Denmark (DK) – en_US  France (FR) – fr_ FR  Germany (DE) – de_ DE  Israel (IL) – en_US, he_IL  Italy (IT) – it_IT  Japan (JP) – ja_JP  Malaysia (MY) – en_US  Mexico (MX) – e s_XC  Netherlands (NL) – nl_NL  New Zealand (NZ) – en_US  Russian Federation (RU) – en_US  Spain (ES) – es_ES  Switzerland (CH) – de_DE  Sweden (SE) – en_US  United Kingdom (GB) – en_GB  United States (US) – en_ US

registrationType xs:string

(Required) This attribute determines whether a key or a URL is returned for the redirect URL. Allowable value(s) currently supported:

 We b – Returns a URL

requestEnvelope common:RequestEnve lope

(Required) Information common to each API operation, such as the language in which an error message is returned.

suppressWelcomeEmail xs:boolean

(Optional) Whether or not to suppress the PayPal welcome email.

32 May 2012 Adaptive Accounts Developer Guide

AddressType Fields

Field Description

line1 xs:string

(Required) The street address.

line2 xs:string

(Optional) The second line of the address.

NOTE: This field is required for Brazilian addresses.

city xs:string

(Required) The city.

state xs:string

(Optional) The state code.

postalCode xs:string

(Optional) The zip or postal code.

countryCode xs:string

(Required) The country code. For allowable values, refer to “Country Codes”

on page 69.

CreateAccount API Operation

CreateAccount Request

BusinessInfoType Fields

Field Description

averageMonthlyVolume xs:decimal

The average monthly transaction volume of the business for which the PayPal account is created. Required for all countries except Japan and Australia.

IMPORTANT: Do not specify this field for Japan or Australia.

averagePrice xs:decimal

The average price per transaction. Required for all countries except Japan and Australia.

IMPORTANT: Do not specify this field for Japan or Australia.

businessAddress aa:addressType

(Required) The address for the business for which the PayPal account is created.

businessName xs:string

(Required) The name of the business for which the PayPal account is created.

businessStakeholder aa:businessStakeholderType

(Optional) The stakeholders in the business.

Adaptive Accounts Developer Guide May 2012 33

CreateAccount API Operation

CreateAccount Request

Field Description

businessSubtype aa:businessSubtype Type

(Optional) The sub type of the business for which the PayPal account is created. Allowable values are:

 ENTITY  EMANATION  ESTD_COMMONWEALTH  ESTD_UNDER_STATE_TERRITORY  ESTD_UNDER_FOREIGH_COUNTY  INCORPORATED  NON_INCORPORATED

businessType aa:businessType

(Required) The type of the business for which the PayPal account is created. Allowable values are:

 CORPORATION  GOVERNMENT  INDIVIDUAL  NONPROFIT  PARTNERSHIP  PROPRIETORSHIP

NOTE: The WSDL lists additional business types, but the types above are the

only ones supported for this release.

category xs:integer

The category describing the business for which the PayPal account is created, for example; 1004 for Baby. Required unless you specify merchantCategoryCode. PayPal uses the industry standard Merchant Category Codes. Refer to the business’ Association Merchant Category Code documentation for a list of codes.

commercialRegistrationLo cation

xs:string

Official commercial registration location for the business for which the PayPal account is created. Required for Germany.

IMPORTANT: Do not specify this field for other countries.

companyId xs:string

The identification number, equivalent to the tax ID in the United States, of the business for which the PayPal account is created. Optional for business accounts in: United States, United Kingdom, France, Spain, Italy, Netherlands, Sweden, and Denmark. Required for business accounts in the following countries: Canada, and some accounts in Australia and Germany,

IMPORTANT: Do not specify this field for other countries.

customerServiceEmail xs:string

(Required) The email address for the customer service department of the business.

34 May 2012 Adaptive Accounts Developer Guide

Field Description

customerServicePhone xs:string

The phone number for the customer service department of the business. Required for United States business accounts; otherwise, optional.

dateOfEstablishment xs:date

The date of establishment for the business. Optional for France business accounts and required for business accounts in the following countries: United States, United Kingdom, Canada, Germany, Spain, Italy, Netherlands, Czech Republic, Sweden, and Denmark.

IMPORTANT: Do not specify this field for other countries.

disputeEmail xs:string

(Optional) The email address to contact to dispute charges.

doingBusinessAs xs:string

(Optional) The business name being used if it is not the actual name of the business.

establishmentCountryCode xs:string

(Optional) The code of the country where the business was established. For allowable values, refer to “Country Codes” on page 69.

CreateAccount API Operation

CreateAccount Request

establishmentState xs:string

(Optional) The state in which the business was established.

incorporationId xs:string

(Optional) The incorporation identification number for the business.

merchantCategoryCode xs:string

The category code for the business. state in which the business was established. Required unless you specify both category and subcategory. PayPal uses the industry standard Merchant Category Codes. Refer to the business’ Association Merchant Category Code documentation for a list of codes.

percentageRevenueFromOnl ine

principlePlaceofBusinessdaa:AddressType

registeredOfficeAddress aa:AddressType

xs:integer

The percentage of online sales for the business from 0 through 100. Required for business accounts in the following countries: United States, Canada, United Kingdom, France, Czech Republic, New Zealand, Switzerland, and Israel.

IMPORTANT: Do not specify this field for other countries.

(Optional) The principle business address.

(Optional) The business address for the business registration.

Adaptive Accounts Developer Guide May 2012 35

CreateAccount API Operation

CreateAccount Request

Field Description

salesVenue aa:salesVenueType

The venue type for sales. Required for business accounts in all countries except Czech Republic and Australia. Allowable values are:

 WEB  EBAY  OTHER_MARKETPLACE  OTHER

IMPORTANT: Do not specify this field for Czech Republic or Australia.

salesVenueDesc xs:string

A description of the sales venue. Required if salesVenue is OTHER for all countries except Czech Republic and Australia.

IMPORTANT: Do not specify this field for Czech Republic or Australia.

subcategory xs:integer

The subcategory describing the business for which the PayPal account is created. Required unless you specify merchantCategoryCode. PayPal uses the industry standard Merchant Category Codes. Refer to the business’ Association Merchant Category Code documentation for a list of codes.

vatCountryCode xs:string

The country for the VAT. Optional for business accounts in the following countries: United Kingdom, France, Germany, Spain, Italy, Netherlands, Switzerland, Sweden, and Denmark. For allowable values, refer to “Country

Codes” on page 69.

IMPORTANT: Do not specify this field for other countries.

vatId xs:string

The VAT identification number of the business. Optional for business accounts in the following countries: United Kingdom, France, Germany, Spain, Italy, Netherlands, Switzerland, Sweden, and Denmark.

IMPORTANT: Do not specify this field for other countries.

webSite xs:st ring

The URL for the website of the business in the following format: http://www.example.com. Required if the salesVenue is WEB; otherwise optional. The URL must be to a hosted website.

workPhone xs:string

(Required)* The phone number for the business. Not required for businesses in Mexico.

36 May 2012 Adaptive Accounts Developer Guide

BusinessStakeholderType Fields

Field Description

address aa:ad dressType

(Optional) The address of the stakeholder in the business for which the PayPal account is created.

dateOfBirth xs:date

(Optional) The date of birth of the stakeholder in the business. Use YYYYMM-DDZ format; for example 1970-01-01Z.

fullLegalName xs:string

(Optional) The legal name of the stakeholder in the business for which the PayPal account is created.

name aa:NameType

(Optional) The name of the stakeholder in the business for which the PayPal account is created.

role aa:StakeholderRoleType

(Optional) The role of the stakeholder in the business for which the PayPal account is created. Allowable values are:

 CHAIRMAN  SECRETARY  TREASURER  BENEFICIAL_OWNER  PRIMARY_CONTACT  INDIVIDUAL_PARTNER  NON_INDIVIDUAL_PARTNER  PRIMARY_INDIVIDUAL_PARTNER  DIRECTOR  NO_BENEFICIAL_OWNER

CreateAccount API Operation

CreateAccount Request

countryCode xs:string

The country code. For allowable values, refer to “Country Codes” on page 69.

CreateWebOptionsType Fields

Field Description

returnUrl xs:string

(Required) The URL to which PayPal returns the account holder after the account is created.

returnUrlDescription xs:string

(Optional) A description of the return URL.

Adaptive Accounts Developer Guide May 2012 37

CreateAccount API Operation

CreateAccount Request

Field Description

showAddCreditCard xs:boolean

showMobileConfirm xs:boolean

useMiniBrowser xs:boolean

(Optional) Whether or not to show the Add Credit Card option.

 true - show the option  false - do not show the option (default)

(Optional) Whether or not to show the mobile confirmation option.

 true - show the option  false - do not show the option (default)

This option displays only if you specify a value for mobilePhoneNumber in the CreateAccount request.

NOTE: This option is only available for Australia, Canada, Spain, France,

United Kingdom, Italy, Malaysia, Singapore, and United States.

(Optional) Whether or not to use the minibrowser flow. It is one of the following values:

 true - use the minibrowser flow  false - use the traditional flow (default)

NOTE: If you specify true for useMiniBrowser, do not specify values for

returnUrl or returnUrlDescription as they are not used in the

minibrowser flow.

NameType Fields

Field Description

salutation xs:string

(Optional) A salutation for the account or payment card holder.

firstName xs:string

(Required) First name of the account or payment card holder.

middleName xs:string

(Optional) Middle name of the account or payment card holder.

lastName xs:string

(Required) Last name of the account or payment card holder.

suffix xs:string

(Optional) A suffix for the account or payment card holder.

38 May 2012 Adaptive Accounts Developer Guide

RequestEnvelope Fields

Field Description

detailLevel common:DetailLevel Code

(Optional) The level of detail required by the client application for component such as Item, Transaction. Possible values are:

 ReturnAll – This value provides the maximum level of detail (default)

errorLanguage xs:string

(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

CreateAccount Response

The CreateAccountResponse contains a key that you can use to complete the account creation. The response also provides status information.

CreateAccount API Operation

CreateAccount Response

CreateAccount Response Fields

Field Description

accountId xs:string

The ID for the PayPal account. This is only for Premier and Business accounts.

createAccountKey xs:string

A unique key that identifies the account that was created.

Adaptive Accounts Developer Guide May 2012 39

CreateAccount API Operation

CreateAccount Request Sample

Field Description

execStatus xs:string

The status of the payment. Allowable values:

 CREATED – The account creation is complete, no redirection for approval

necessary.

 COMPLETED – The account creation request was successful (user

redirection for approval required).

 CREATED PENDING VERIFICATION – The account creation is complete

but verification/approval process has not been completed.

returnURL xs:string

The URL to which you direct your customer’s browser to create the account.

responseEnvelope common:ResponseEnv elope

Common response information, including a timestamp and the response acknowledgement status.

ResponseEnvelope Fields

Field Description

ack common:AckCode

Acknowledgment code. Possible values are:

 Success – Operation completed successfully  Failure – Operation failed  Warning – warning  SuccessWithWarning – Operation completed successfully; however,

there is a warning message

 FailureWithWarning – Operation failed with a warning message

build Build number; used only by Developer Technical Support. correlationId Correlation ID; used only by Developer Technical Support. timestamp The date on which the response was sent. The time is not supported.

CreateAccount Request Sample

SOAP request

To create an account, the SOAP request specifies the name, address, and other identifying information about the account holder for whom you want to create an account. You can specify additional information to associate with the account in the partner information fields.

40 May 2012 Adaptive Accounts Developer Guide

CreateAccount API Operation

CreateAccount Request Sample

<soapenv:Envelope xmlns:soapenv="http://schemas. xmlsoap.org/soap/e nvelope/"> <soapenv:Body> <ns2:CreateAccountRequest xmlns:ns2= "http://svcs.paypal.c om/services"> <requestEnvelope> <errorLanguage>en_US</erro rLanguage> </requestEnvelope> <accountType>PERSONAL</acco untType> <emailAddress>testing-20390 39@paypal.com</ema ilAddress> <name> <firstName>John</firstName > <lastName>Smith</lastName> </name> <dateOfBirth>1968-01-01Z</d ateOfBirth> <address> <line1>1968 Ape Way</line1 > <line2>Apt 123</line2> <city>Austin</city> <state>TX</state> <postalCode>78750</postalC ode> <countryCode>US</countryCo de> </address> <contactPhoneNumber>888-555 -1212</contactPhon eNumber> <currencyCode>USD</currency Code> <citizenshipCountryCode>US< /citizenshipCountr yCode> <preferredLanguageCode>en_U S</preferredLangua geCode> <notificationURL>http://... </notificationURL> <registrationType>WEB</regi strationType> <createAccountWebOptions> <returnUrl>http://www.myh ome.com</returnUrl > </createAccountWebOptions> </ns2:CreateAccountRequest> </soapenv:Body> </soapenv:Envelope>

SOAP response

The response contains the PayPal URL to which you redirect the person’s browser. The current status of the request is COMPLETED until the customer logs into PayPal and confirms that he or she wants to create the account. The returned account key can be used to retrieve the end user license agreement (EULA) associated with the account.

Adaptive Accounts Developer Guide May 2012 41

CreateAccount API Operation

CreateAccount Errors

<soapenv:Envelope xmlns:soapenv="http://schemas. xmlsoap.org/soap/e nvelope/"> <soapenv:Header /> <soapenv:Body> <ns2:CreateAccountResponse xml ns:ns2="http://svc s.paypal.com/types/aa "> <responseEnvelope> <timestamp>2009-09-03T15:19:12 .281-07:00</timest amp> <ack>Success</ack> <correlationId>15bdd53cd4264</ correlationId> <build>1033575</build> </responseEnvelope> <createAccountKey>AA-6H279897N K391145S</createAc countKey> <execStatus>COMPLETED</execSta tus> <redirectURL>https://...?cmd=_ hosteduaflow&encrypted_second_auth _code=AwBJzCt4b8SL Un2KMiPrYa08vABRRSnCo 61W3uM lletaKWCP9XWs3WcXvnEzSlDHVa4&a mp;encrypted_id=U4 HE2K5TWLXQN&retur n_url= http://www.myhome.com</redirec tURL> </ns2:CreateAccountResponse> </soapenv:Body> </soapenv:Envelope>

CreateAccount Errors

Code Message Additional Information

500000 Framework failure. Retry.

520002 Internal error

520003 Invalid credentials

550001 User is not allowed to perform this action

560022 Invalid header.

560029 The required <name> header is missing from the HTTP request

580001 Invalid request:

 User has exceeded call limit set for the API  Personal account is not allowed for the country  Language not supported  <name>

42 May 2012 Adaptive Accounts Developer Guide

CreateAccount API Operation

CreateAccount Errors

Code Message Additional Information

580022 Invalid request parameter:

 accountType  address  averageMonthlyVolume  averagePrice  city  countryCode  line1  line2  state  postalCode  state  businessStakeholder  businessSubtype  businessType  category  citizenshipCountryCode  city  commercialRegistrationLocation  companyId  contactPhoneNumber  currencyCode  customerServiceEmail  customerServicePhone  dateOfBirth  dateOfEstablishment  Account already exists for the specified email address  emailAddress  establishmentCountryCode  establishmentState  firstName  Interest Tax Id already exists  ipAddress  lastName  percentageRevenueFromOnline  preferredLanguageCode  returnUrl  salesVenue  salutation  sandboxEmailAddress  role  subCategory  vatId  website  workPhone

Adaptive Accounts Developer Guide May 2012 43

CreateAccount API Operation

CreateAccount Errors

Code Message Additional Information

580023 The argument is inconsistent with the rest of the request

580027 The parameter is not supported

580029 A required parameter is missing from the request:

 postalCode  state  businessStakeholder  city  countryCode  firstName  incorporationId  lastName  line1  postalCode  salesVenueDesc  state  mobilePhoneNumber

44 May 2012 Adaptive Accounts Developer Guide

AddBankAccount API Operation

The AddBankAccount API operation lets your application set up bank accounts as funding sources for PayPal accounts.

AddBankAccount Request

Adaptive Accounts Developer Guide May 2012 45

AddBankAccount API Operation

AddBankAccount Request

AddBankAccount Request Fields

Field Description

accountHolderDateofBirthxs:date

(Optional) The date of birth of the account holder in YYYY-MM-DDZ format, for example 1970-01-01Z.

accountId xs:string

(Optional) The identification number of the PayPal account for which a bank account is added. You must specify either the accountId or emailAd dress for this request.

agencyNumber xs:string

(Optional) For the Brazil Agency Number.

bankAccountNumber xs:string

(Optional) The account number (BBAN) of the bank account to be added.

bankAccountType aa:BankAccountType

(Optional) The type of bank account to be added. Allowable values are:

 CHECKING  SAVINGS  BUSINESS_SAVINGS  BUSINESS_CHECKINGS  NORMAL  UNKNOWN

bankCode xs:string

(Optional) The code that identifies the bank where the account is held.

bankCountryCode xs:string

(Required) The country code. For allowable values, refer to “Country Codes” on

page 69.

bankName xs:string

(Optional) The default value is UNKNOWN.

bankTransitNumber xs:string

(Optional) The transit number of the bank.

branchCode xs:string

(Optional) The branch code for the bank.

branchLocation xs:string

(Optional) The branch location.

bsbNumber xs:string

(Optional) The Bank/State/Branch number for the bank.

clabe xs:string

CLABE represents the bank information for countries like Mexico.

46 May 2012 Adaptive Accounts Developer Guide

Field Description

confirmationType aa:ConfirmationType

(Required) Whether PayPal account holders are redirected to PayPal.com to confirm the payment card addition. When you pass NONE for this element, the addition is made without the account holder’s explicit confirmation. If you pass WEB, a URL is returned.

Allowable string values are:

 WEB  NONE

NOTE: ConfirmationType NONE requires advanced permission levels. You

must pass the createAccount key.

controlDigit xs:string

(Optional) The control digits for the bank.

emailAddress xs:string

(Optional) The email address for the PayPal account. You must specify either the accountId or emailAddress for this request.

AddBankAccount API Operation

AddBankAccount Request

iban xs:string

(Optional) The IBAN for the bank.

institionNumber xs:string

(Optional) The institution number for the bank.

partnerInfo xs:string

(Optional) The partner information for the bank.

requestEnvelope common:RequestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

ribkey xs:string

(Optional) The RIB key for the bank.

routingNumber xs:string

(Optional) The bank’s routing number.

sortCode xs:string

(Optional) The branch sort code.

taxIdType xs:string

(Optional) Tax id type of CNPJ or CPF, only supported for Brazil.

taxIdNumber xs:string

(Optional) Tax id number for Brazil.

webOptionsType aa:WebOptionsType

(Optional) Additional structure to define the URLs for the cancellation and return web flows.

Adaptive Accounts Developer Guide May 2012 47

AddBankAccount API Operation

AddBankAccount Response

WebOptionsType Fields

Field Description

cancelUrl xs:string

cancelUrlDescription xs:string

returnUrl xs:string

returnUrlDescription xs:string

RequestEnvelope Fields

(Optional) The URL to which bank account/payment card holders return when they cancel the bank account addition flow.

(Optional) A description of the cancellation URL.

(Optional) The URL to which bank account/payment card holders return after

they add the account or payment card.

(Optional) A description of the return URL.

Field Description

detailLevel common:DetailLevel Code

(Optional) The level of detail required by the client application for component such as Item, Transaction. Possible values are:

 ReturnAll – This value provides the maximum level of detail (default)

errorLanguage xs:string

(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

AddBankAccount Response

48 May 2012 Adaptive Accounts Developer Guide

AddBankAccount Response Fields

Field Definition

execStatus xs:string

Execution status for the request. Possible values are:

 COMPLETED  CREATED  CREATED PENDING VERIFICATION

fundingSourceKey xs:string

The key for the funding source to use in subsequent Adaptive Accounts API request messages.

redirectURL xs:string

The URL to direct the PayPal account holder to redirection after the Add Bank Account web flow is completed.

responseEnvelope common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgement status.

AddBankAccount API Operation

AddBankAccount Response

ResponseEnvelope Fields

Field Description

ack common:AckCode

Acknowledgment code. Possible values are:

 Success – Operation completed successfully  Failure – Operation failed  Warning – warning  SuccessWithWarning – Operation completed successfully; however,

there is a warning message

 FailureWithWarning – Operation failed with a warning message

Adaptive Accounts Developer Guide May 2012 49

AddBankAccount API Operation

AddBankAccount Errors

Variable Description

500000 Framework failure. Retry.

520002 Internal error

520003 Invalid credentials.

550001 User is not allowed to perform this action

560022 Invalid header.

560029 The required <name> header is missing from the HTTP request

580001 Invalid request:

 PA_Invalid_Currency  Maximum attempts of Random deposits reached  Invalid request parameter: bankAccountType  Invalid request parameter: accountNumber  Unsupported countryCode  Invalid request parameter: countryCode  Invalid input  Invalid request parameter: dateOfBirth  Missing required request parameter: countryCode  There are maximum number of bank accounts  The bank account is already associated with another PayPal account  Bank account is already a part of the end user PayPal account  AddBankAccount has been rejected  Invalid bank account information  More than one inactive bank account matches the routing number and the

account number

 Invalid beneficiary ID  PayPal account specified in the request is locked  PayPal account specified in the request is closed  Operation is not supported: PA_Replaceable_Value  Invalid request: PA_Replaceable_Value

580022 Request parameter is invalid:

 Invalid request parameter: PA_Replaceable_Value  Expired createAccountKey  Invalid request parameter: ipAddressExpired createAccountKey  Invalid request parameter: createAccountKey

580023 The argument is inconsistent with the rest of the request.

50 May 2012 Adaptive Accounts Developer Guide

AddPaymentCard API Operation

The AddPaymentCard API operation lets your application set up credit cards as funding sources for PayPal accounts.

AddPaymentCard Request

Adaptive Accounts Developer Guide May 2012 51

AddPaymentCard API Operation

AddPaymentCard Request

AddPaymentCard Request Fields

Field Description

accountId xs:string

(Optional) The identification number of the PayPal account for which a payment card is added. You must specify either the accountId or

emailAddress for this request.

billingAddress aa:AddressType

(Optional) The element AddressType. See “AddressType Fields” on page 33.

cardNumber xs:string

(Required) The credit card number.

cardOwnerDateOfBirth xs:date

(Optional) The date of birth of the card holder.

cardType aa:CardTypeType

(Required) The type of card to be added. Allowable values are:

 Visa  MasterCard  AmericanExpress  Discover  SwitchMaestro  Solo  CarteAurore  CarteBleue  Cofinoga  4etoiles  CarteAura  TarjetaAurora  JCB

cardVerificationNumber xs:string

The verification code for the card. This parameter is generally required for calls where confirmationType is set to NONE. With the appropriate account review, this parameter can be optional.

confirmationType aa:ConfirmationType

Allowable string values are:

 WEB  NONE

NOTE: ConfirmationType NONE requires advanced permission levels. You

must pass the createAccount key and the cardVerificationNumber.

52 May 2012 Adaptive Accounts Developer Guide

Field Description

createAccountKey xs:string

The createaccount key returned in the CreateAccount response. This parameter is required for calls where the confirmationType is set to NONE.

emailAddress xs:string

(Optional) The email address for the PayPal account. You must specify either the accountId or emailAddress for this request.

expirationDate aa:CardDateType

(Optional) The element containing the expiration date for the payment card.

issueNumber xs:string

(Optional) The 2-digit issue number for Switch, Maestro, and Solo cards.

nameOnCard aa:Nametype

(Required) The element containing the name of the card holder.

requestEnvelope common:RequestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

AddPaymentCard API Operation

AddPaymentCard Request

startDate aa:CardDateType

(Optional) The element containing the start date for the payment card.

webOptions aa:WebOptionsType

(Optional) Additional structure to define the URLs for the cancelation and return web flows.

AddressType Fields

Field Description

line1 xs:string

(Required) The street address.

line2 xs:string

(Optional) The second line of the address.

NOTE: This field is required for Brazilian addresses.

city xs:string

(Required) The city.

state xs:string

(Optional) The state code.

postalCode xs:string

(Optional) The zip or postal code.

Adaptive Accounts Developer Guide May 2012 53

AddPaymentCard API Operation

AddPaymentCard Request

Field Description

countryCode xs:string

NameType Fields

Field Description

salutation xs:string

firstName xs:string

middleName xs:string

(Required) The country code. For allowable values, refer to “Country Codes”

on page 69.

(Optional) A salutation for the account or payment card holder.

(Required) First name of the account or payment card holder.

(Optional) Middle name of the account or payment card holder.

lastName xs:string

(Required) Last name of the account or payment card holder.

suffix xs:string

(Optional) A suffix for the account or payment card holder.

CardDateType Fields

Field Description

month xs:integer

(Optional) The month of expiration.

year xs:integer

(Required) The year of expiration.

RequestEnvelope Fields

Field Description

detailLevel common:DetailLevel Code

(Optional) The level of detail required by the client application for component such as Item, Transaction. Possible values are:

 ReturnAll – This value provides the maximum level of detail (default)

54 May 2012 Adaptive Accounts Developer Guide

Field Description

errorLanguage xs:string

(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

AddPaymentCard Response

AddPaymentCard API Operation

AddPaymentCard Response

AddPaymentCard Response Fields

Field Definition

execStatus xs:string

Execution status for the request. Possible values are:

 COMPLETED  CREATED  CREATED PENDING VERIFICATION

fundingSourceKey xs:string

The funding source key returned by the AddBankAccount response.

redirectURL xs:string

The URL to send the PayPal account holder to after the AddPaymentCard web flow is completed.

responseEnvelope common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgement status. See “ResponseEnvelope Fields” on page 40

Adaptive Accounts Developer Guide May 2012 55

AddPaymentCard API Operation

AddPaymentCard Errors

ResponseEnvelope Fields

Field Description

ack common:AckCode

Acknowledgment code. Possible values are:

 Success – Operation completed successfully  Failure – Operation failed  Warning – warning  SuccessWithWarning – Operation completed successfully; however,

there is a warning message

 FailureWithWarning – Operation failed with a warning message

AddPaymentCard Errors

Variable Description

500000 Framework failure. Retry.

520002 Internal error

520003 Invalid credentials.

550001 User is not allowed to perform this action

560022 Invalid header.

560029 The required <name> header is missing from the HTTP request

580001 Invalid request:

 Card is already added to some other account  Card is already added to the account specified in the request  Payment card unavailable  The payment card was refused  The payment card has expired  PayPal account specified in the request is locked  PayPal account specified in the request is closed  Operation is not supported: PA_Replaceable_Value  Invalid request: PA_Replaceable_Value

56 May 2012 Adaptive Accounts Developer Guide

Variable Description

580022 Request parameter is invalid:

 Invalid request parameter: billingAddress  Invalid request parameter: line1  Invalid request parameter: line2  Invalid request parameter: city  Invalid request parameter: state  Invalid request parameter: postalCode  Invalid request parameters: city, state, postalCode  Invalid request parameter: startDate  Invalid request parameter: cardType  Address for UPS cannot be a PO Box  Invalid request parameter: accountId  Invalid request parameter: cardOwnerDateOfBirth  Invalid request parameter: cardNumber  Invalid request parameter: expirationDate  Invalid request parameter: cardVerificationNumber  Expired createAccountKey  Invalid request parameter: PA_Replaceable_Value  Invalid request parameter: createAccountKey  Invalid request parameter: ipAddress

AddPaymentCard API Operation

AddPaymentCard Errors

580023 The argument is inconsistent with the rest of the request

 Country of billing address must match country of account holder address  Account associated with createAccountKey is different from the one

provided in the request

580027 The parameter is not supported

 Prohibited request parameter: PA_Replaceable_Value  The parameter is not supported

580029 Required parameter is missing in the request:

 Missing required request parameter: firstName  Missing required request parameter: lastName  Missing required request parameter: line1  Missing required request parameter: city  Missing required request parameter: state  Missing required request parameter: postalCode  Missing required request parameter: countryCode  Missing required request parameter: billingAddress  Missing required request parameter: line2  Missing required request parameter: cardVerificationNumber  Missing required request parameter: createAccountKey  Missing required request parameter: PA_Replaceable_Value

Adaptive Accounts Developer Guide May 2012 57

AddPaymentCard API Operation

AddPaymentCard Errors

58 May 2012 Adaptive Accounts Developer Guide

SetFundingSourceConfirmed API

Operation

The SetFundingSourceConfirmed API operation allows your application to mark a funding source as confirmed, after it is added successfully with AddPaymentCard or AddBankAccount.

SetFundingSourceConfirmed Request

SetFundingSourceConfirmed Request Fields

Field Description

accountId xs:string

(Optional) The merchant account Id of the PayPal account to which the funding source was added in the AddPaymentCard or AddBankAccount request. You must specify either the accountId or mailAddress when making this request, but never both in the same request.

emailAddress xs:string

(Optional) The email address of the PayPal account to which the funding source was added in the AddPaymentCard or AddBankAccount request. You must specify either the accountId or mailAddress when making this request, but never both in the same request.

fundingSourceKey xs:string

The funding source key returned in the AddBankAccount or AddPaymentCard response.

requestEnvelope common:RequestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

Adaptive Accounts Developer Guide May 2012 59

SetFundingSourceConfirmed API Operation

SetFundingSourceConfirmed Response

RequestEnvelope Fields

Field Description

detailLevel common:DetailLevel Code

(Optional) The level of detail required by the client application for component such as Item, Transaction. Possible values are:

 ReturnAll – This value provides the maximum level of detail (default)

errorLanguage xs:string

(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

SetFundingSourceConfirmed Response

ResponseEnvelope Fields

Field Description

ack common:AckCode

Acknowledgment code. Possible values are:

 Success – Operation completed successfully  Failure – Operation failed  Warning – warning  SuccessWithWarning – Operation completed successfully; however,

there is a warning message

 FailureWithWarning – Operation failed with a warning message

60 May 2012 Adaptive Accounts Developer Guide

SetFundingSourceConfirmed API Operation

SetFundingSourceConfirmed Errors

Variable Description

500000 Framework failure. Retry.

520002 Internal error

520003 Invalid credentials.

550001 User is not allowed to perform this action

560022 Invalid header.

560029 The required <name> header is missing from the HTTP request.

580001 Invalid request:

 PayPal account specified in the request is locked  PayPal account specified in the request is closed  Operation is not supported: PA_Replaceable_Value  Invalid request: PA_Replaceable_Value

580022 Request parameter is invalid:

 Expired createAccountKey  Invalid request parameter: PA_Replaceable_Value  Invalid request parameter: createAccountKey  Invalid request parameter: ipAddress

580023 The argument is inconsistent with the rest of the request

 Account cannot be confirmed with the request parameter provided  Account associated with createAccountKey is different from the one

provided in the request

580027 The parameter is not supported.

Adaptive Accounts Developer Guide May 2012 61

SetFundingSourceConfirmed API Operation

SetFundingSourceConfirmed Errors

62 May 2012 Adaptive Accounts Developer Guide

GetVerifiedStatus API Operation

The GetVerified Status API operation lets you check if a PayPal account status is verified. A PayPal account gains verified status under a variety of circumstances, such as when an account is linked to a verified funding source. Verified status serves to indicate a trust relationship. For more information about account verified status, refer to PayPal.com.

GetVerifiedStatus Request

The GetVerifiedStatus request allows you to verify that a customer is indeed the holder of the PayPal account information that was supplied.

GetVerifiedStatus Request Fields

Field Description

emailAddress xs:string

(Required) The email address of the PayPal account holder.

firstName xs:string

(Required) The first name of the PayPal account holder. Required if

matchCriteria is NAME.

lastName xs:string

(Required) The last name of the PayPal account holder. Required if

matchCriteria is NAME.

Adaptive Accounts Developer Guide May 2012 63

GetVerifiedStatus API Operation

GetVerifiedStatus Request

Field Description

matchCriteria xs:string

(Required) The criteria that must be matched in addition to emailAddress. Currently, only NAME is supported.

Allowable string values are:

 NAME  NONE

NOTE: To use ConfirmationType NONE you must request and be granted

advanced permission levels.

requestEnvelope common:RequestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

RequestEnvelope Fields

Field Description

detailLevel common:DetailLevel Code

(Optional) The level of detail required by the client application for component such as Item, Transaction. Possible values are:

 ReturnAll – This value provides the maximum level of detail (default)

errorLanguage xs:string

(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

64 May 2012 Adaptive Accounts Developer Guide

GetVerifiedStatus Response

GetVerifiedStatus API Operation

GetVerifiedStatus Response

GetVerifiedStatus Response Fields

Field Definition

accountStatus xs:string

This field returns VERIFIED or UNVERIFIED to indicate the account status.

responseEnvelope common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgement status.

countryCode xs:string

(Required) The country code. For allowable values, refer to “Country Codes” on

page 69.

NOTE: In order to receive a countryCode value in the response, you must

specify matchCriteria=NONE in the GetVe rifiedStatus request. To use matchCriteria=NONE, you must request and be granted advanced permission levels.

userInfoType aa:UserInfoType

This set of data includes unique account identifiers.

Adaptive Accounts Developer Guide May 2012 65

GetVerifiedStatus API Operation

GetVerifiedStatus Response

ResponseEnvelope Fields

Field Description

ack common:AckCode

Acknowledgment code. Possible values are:

 Success – Operation completed successfully  Failure – Operation failed  Warning – warning  SuccessWithWarning – Operation completed successfully; however,

there is a warning message

 FailureWithWarning – Operation failed with a warning message

UserInfoType Fields

Field Description

accountType xs:string

(Required) The type of account. Allowable values are:

 Personal – Personal account  Premier – Premier account  Business – Business account

name aa:NameType

(Required) The name of the person for whom the PayPal account is created.

businessName Business name of the PayPal account holder. accountId Identifies the PayPal account.

NOTE: A call to this API must use either emailAddress or accountId as

the unique identifier for the account, but must never include both in the same call.

emailAddress xs:string

(Required)Email address associated with the PayPal account: one of the unique identifiers for the account.

NOTE: A call to this API must use either emailAddress or accountId as

the unique identifier for the account, but must never include both in the same call.

66 May 2012 Adaptive Accounts Developer Guide

GetVerifiedStatus API Operation

GetVerifiedStatus Errors

Variable Description

500000 There is a system error.

520002 Internal error

520003 Username/password is incorrect.

550001 User is not allowed to perform this action.

560027 The argument value is unsupported.

560029 The required <name> header is missing from the HTTP request.

580001 Invalid Request:

 User has exceeded call limit set for the API.  Personal account is not allowed for the country.  Language not supported.  Invalid request: <value>.

580023 Cannot determine PayPal account status

580022 Invalid request parameter: <name>

580023 Invalid Request.

580029 Missing required request parameter: <name>

Adaptive Accounts Developer Guide May 2012 67

GetVerifiedStatus API Operation

GetVerifiedStatus Errors

68 May 2012 Adaptive Accounts Developer Guide

Country Codes

Below are the country codes for Adaptive Accounts. Countries marked with an asterisk ( * ) are not supported for PayPal Payments Pro and Virtual Terminal.