Paypal Adaptive Accounts 2012 Developers Guide Developer

Adaptive Accounts - 2012 - Developer Guide PP_AdaptiveAccounts_2012 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Adaptive-Accounts-2012-Developers-Guide-777924 paypal-adaptive-accounts-2012-developers-guide-777924 paypal pdf

Open the PDF directly: View PDF PDF.
Page Count: 100

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, L-
2449, 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 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.
Adaptive Accounts Developer Guide May 2012 3
Contents
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
Contents
4May 2012 Adaptive Accounts Developer Guide
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
Adaptive Accounts Developer Guide May 2012 5
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
Contents
6May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 7
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
Documentation Feedback
8May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 9
What’s New
Check out what’s new in the current release.
Adaptive Account Changes Corresponding for PayPal Version
89.0
Maintenance release.
Adaptive Account Changes Corresponding for PayPal Version 89.0
10 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 11
1Introducing 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 elses 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
Introducing Adaptive Accounts
Adding Bank Accounts as Funding Sources
1
12 May 2012 Adaptive Accounts Developer Guide
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 CreateAccount 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 customers 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
Adaptive Accounts Developer Guide May 2012 13
Introducing Adaptive Accounts
Set Funding Sources to Confirmed Status 1
-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.
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 holders 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:
Introducing Adaptive Accounts
Account Creation Flow
1
14 May 2012 Adaptive Accounts Developer Guide
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.CreateAccountWebOptionsType.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 customers browser to the URL in the CreateAccount response
message, PayPal responds with the following:
Adaptive Accounts Developer Guide May 2012 15
Introducing Adaptive Accounts
Account Creation Flow 1
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.CreateAccountWebOptionsType.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:
Introducing Adaptive Accounts
Account Creation Flow
1
16 May 2012 Adaptive Accounts Developer Guide
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:
Adaptive Accounts Developer Guide May 2012 17
Introducing Adaptive Accounts
Account Creation Flow 1
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.CreateAccountWebOptionsType.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:
Introducing Adaptive Accounts
Account Creation Flow
1
18 May 2012 Adaptive Accounts Developer Guide
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 customers browser to PayPal. Your
customer then signs up and agrees to the terms of the account.
Adaptive Accounts Developer Guide May 2012 19
Introducing Adaptive Accounts
Account Creation Flow 1
By default, when you redirect your customers 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 Create PayPal account login screen requests your customer to submit a password and
security questions, with answers:
Introducing Adaptive Accounts
Account Creation Flow
1
20 May 2012 Adaptive Accounts Developer Guide
3. The Add Credit or Debit Card page enables your customer to specify a funding source
and billing information:
Adaptive Accounts Developer Guide May 2012 21
Introducing Adaptive Accounts
Account Creation Flow 1
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.
Introducing Adaptive Accounts
Account Creation Flow
1
22 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 23
2Supported Formats, URLs and
HTTP Request Headers
Adaptive Accounts Methods
Adaptive Accounts provides the following methods:
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.com/AdaptiveAccounts/CreateAccount
You can specify the following URLs:
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 holders email address.
Environment Endpoint
Production
https://svcs.paypal.com/AdaptiveAccounts/API_operation
Sandbox
https://svcs.sandbox.paypal.com/AdaptiveAccounts/API_operation
Supported Formats, URLs and HTTP Request Headers
Supported Formats
2
24 May 2012 Adaptive Accounts Developer Guide
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
Optional 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
-JSON – 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
-JSON – JavaScript object notation
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.
Adaptive Accounts Developer Guide May 2012 25
Supported Formats, URLs and HTTP Request Headers
HTTP Request Headers 2
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-BONUS-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.
Header Description
Supported Formats, URLs and HTTP Request Headers
HTTP Request Headers
2
26 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 27
3CreateAccount 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.
CreateAccount API Operation
CreateAccount Request
3
28 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 29
CreateAccount API Operation
CreateAccount Request 3
CreateAccount API Operation
CreateAccount Request
3
30 May 2012 Adaptive Accounts Developer Guide
CreateAccount Request Fields
Field Description
accountType xs:string
(Required) The type of account to be created. Allowable values are:
-Personal – Personal account
-Premier – Premier account
-Business – Business account
address aa:AddressType
(Required) The address to be associated with the PayPal account.
businessInfo aa:BusinessInfoType
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.
Adaptive Accounts Developer Guide May 2012 31
CreateAccount API Operation
CreateAccount Request 3
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.
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-aZ-
Z]+\://){1}\S+
partnerFieldnxs:string
(Optional) A maximum of five fields for your own use, where n is a digit
between 1 and 5, inclusive.
perfermExtraVettingOnthi
sAccount
xs:boolean
(Optional) Whether to subject the account to extra vetting by PayPal before the
account can be used.
taxId xs:string
(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.
Field Description
CreateAccount API Operation
CreateAccount Request
3
32 May 2012 Adaptive Accounts Developer Guide
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) – en_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) – es_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:
-Web – Returns a URL
requestEnvelope common:RequestEnvelope
(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.
Field Description
Adaptive Accounts Developer Guide May 2012 33
CreateAccount API Operation
CreateAccount Request 3
AddressType Fields
BusinessInfoType 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.
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.
CreateAccount API Operation
CreateAccount Request
3
34 May 2012 Adaptive Accounts Developer Guide
businessSubtype aa:businessSubtypeType
(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.
Field Description
Adaptive Accounts Developer Guide May 2012 35
CreateAccount API Operation
CreateAccount Request 3
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.
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
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.
principlePlaceofBusiness
d
aa:AddressType
(Optional) The principle business address.
registeredOfficeAddress aa:AddressType
(Optional) The business address for the business registration.
Field Description
CreateAccount API Operation
CreateAccount Request
3
36 May 2012 Adaptive Accounts Developer Guide
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:string
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.
Field Description
Adaptive Accounts Developer Guide May 2012 37
CreateAccount API Operation
CreateAccount Request 3
BusinessStakeholderType Fields
CreateWebOptionsType Fields
Field Description
address aa:addressType
(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 YYYY-
MM-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
countryCode xs:string
The country code. For allowable values, refer to “Country Codes” on page 69.
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.
CreateAccount API Operation
CreateAccount Request
3
38 May 2012 Adaptive Accounts Developer Guide
NameType Fields
showAddCreditCard xs:boolean
(Optional) Whether or not to show the Add Credit Card option.
-true - show the option
-false - do not show the option (default)
showMobileConfirm xs:boolean
(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.
useMiniBrowser xs:boolean
(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.
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.
Field Description
Adaptive Accounts Developer Guide May 2012 39
CreateAccount API Operation
CreateAccount Response 3
RequestEnvelope Fields
CreateAccount Response
The CreateAccountResponse contains a key that you can use to complete the account
creation. The response also provides status information.
CreateAccount Response Fields
Field Description
detailLevel common:DetailLevelCode
(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
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.
CreateAccount API Operation
CreateAccount Request Sample
3
40 May 2012 Adaptive Accounts Developer Guide
ResponseEnvelope Fields
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.
execStatus xs:string
The status of the payment. Allowable values:
-CREATED – The account creation is complete, no redirection for approval
necessary.
-COMPLETEDThe 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 customers browser to create the account.
responseEnvelope common:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
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.
Field Description
Adaptive Accounts Developer Guide May 2012 41
CreateAccount API Operation
CreateAccount Request Sample 3
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns2:CreateAccountRequest xmlns:ns2="http://svcs.paypal.com/services">
<requestEnvelope>
<errorLanguage>en_US</errorLanguage>
</requestEnvelope>
<accountType>PERSONAL</accountType>
<emailAddress>testing-2039039@paypal.com</emailAddress>
<name>
<firstName>John</firstName>
<lastName>Smith</lastName>
</name>
<dateOfBirth>1968-01-01Z</dateOfBirth>
<address>
<line1>1968 Ape Way</line1>
<line2>Apt 123</line2>
<city>Austin</city>
<state>TX</state>
<postalCode>78750</postalCode>
<countryCode>US</countryCode>
</address>
<contactPhoneNumber>888-555-1212</contactPhoneNumber>
<currencyCode>USD</currencyCode>
<citizenshipCountryCode>US</citizenshipCountryCode>
<preferredLanguageCode>en_US</preferredLanguageCode>
<notificationURL>http://...</notificationURL>
<registrationType>WEB</registrationType>
<createAccountWebOptions>
<returnUrl>http://www.myhome.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.
CreateAccount API Operation
CreateAccount Errors
3
42 May 2012 Adaptive Accounts Developer Guide
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header />
<soapenv:Body>
<ns2:CreateAccountResponse xmlns:ns2="http://svcs.paypal.com/types/aa">
<responseEnvelope>
<timestamp>2009-09-03T15:19:12.281-07:00</timestamp>
<ack>Success</ack>
<correlationId>15bdd53cd4264</correlationId>
<build>1033575</build>
</responseEnvelope>
<createAccountKey>AA-6H279897NK391145S</createAccountKey>
<execStatus>COMPLETED</execStatus>
<redirectURL>https://...?cmd=_hostedua-
flow&amp;encrypted_second_auth_code=AwBJzCt4b8SLUn2KMiPrYa08vABRRSnCo61W3uM
lletaKWCP9XWs3WcXvnEzSlDHVa4&amp;encrypted_id=U4HE2K5TWLXQN&amp;return_url=
http://www.myhome.com</redirectURL>
</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>
Adaptive Accounts Developer Guide May 2012 43
CreateAccount API Operation
CreateAccount Errors 3
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
Code Message Additional Information
CreateAccount API Operation
CreateAccount Errors
3
44 May 2012 Adaptive Accounts Developer Guide
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
Code Message Additional Information
Adaptive Accounts Developer Guide May 2012 45
4AddBankAccount API Operation
The AddBankAccount API operation lets your application set up bank accounts as funding
sources for PayPal accounts.
AddBankAccount Request
AddBankAccount API Operation
AddBankAccount Request
4
46 May 2012 Adaptive Accounts Developer Guide
AddBankAccount Request Fields
Field Description
accountHolderDateofBirt
h
xs: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 emailAddress
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.
Adaptive Accounts Developer Guide May 2012 47
AddBankAccount API Operation
AddBankAccount Request 4
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 holders 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.
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.
Field Description
AddBankAccount API Operation
AddBankAccount Response
4
48 May 2012 Adaptive Accounts Developer Guide
WebOptionsType Fields
RequestEnvelope Fields
AddBankAccount Response
Field Description
cancelUrl xs:string
(Optional) The URL to which bank account/payment card holders return when
they cancel the bank account addition flow.
cancelUrlDescription xs:string
(Optional) A description of the cancellation URL.
returnUrl xs:string
(Optional) The URL to which bank account/payment card holders return after
they add the account or payment card.
returnUrlDescription xs:string
(Optional) A description of the return URL.
Field Description
detailLevel common:DetailLevelCode
(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
Adaptive Accounts Developer Guide May 2012 49
AddBankAccount API Operation
AddBankAccount Response 4
AddBankAccount Response Fields
ResponseEnvelope 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.
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.
AddBankAccount API Operation
AddBankAccount Errors
4
50 May 2012 Adaptive Accounts Developer Guide
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.
Adaptive Accounts Developer Guide May 2012 51
5AddPaymentCard API Operation
The AddPaymentCard API operation lets your application set up credit cards as funding
sources for PayPal accounts.
AddPaymentCard Request
AddPaymentCard API Operation
AddPaymentCard Request
5
52 May 2012 Adaptive Accounts Developer Guide
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
(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 holders 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 and the cardVerificationNumber.
Adaptive Accounts Developer Guide May 2012 53
AddPaymentCard API Operation
AddPaymentCard Request 5
AddressType Fields
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.
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.
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.
Field Description
AddPaymentCard API Operation
AddPaymentCard Request
5
54 May 2012 Adaptive Accounts Developer Guide
NameType Fields
CardDateType Fields
RequestEnvelope Fields
countryCode xs:string
(Required) The country code. For allowable values, refer to “Country Codes”
on page 69.
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.
Field Description
month xs:integer
(Optional) The month of expiration.
year xs:integer
(Required) The year of expiration.
Field Description
detailLevel common:DetailLevelCode
(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)
Field Description
Adaptive Accounts Developer Guide May 2012 55
AddPaymentCard API Operation
AddPaymentCard Response 5
AddPaymentCard Response
AddPaymentCard Response Fields
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
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
Field Description
AddPaymentCard API Operation
AddPaymentCard Errors
5
56 May 2012 Adaptive Accounts Developer Guide
ResponseEnvelope Fields
AddPaymentCard Errors
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.
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
Adaptive Accounts Developer Guide May 2012 57
AddPaymentCard API Operation
AddPaymentCard Errors 5
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
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
Variable Description
AddPaymentCard API Operation
AddPaymentCard Errors
5
58 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 59
6SetFundingSourceConfirmed 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.
SetFundingSourceConfirmed API Operation
SetFundingSourceConfirmed Response
6
60 May 2012 Adaptive Accounts Developer Guide
RequestEnvelope Fields
SetFundingSourceConfirmed Response
ResponseEnvelope Fields
Field Description
detailLevel common:DetailLevelCode
(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
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.
Adaptive Accounts Developer Guide May 2012 61
SetFundingSourceConfirmed API Operation
SetFundingSourceConfirmed Errors 6
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.
SetFundingSourceConfirmed API Operation
SetFundingSourceConfirmed Errors
6
62 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 63
7GetVerifiedStatus API Operation
The GetVerifiedStatus 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.
GetVerifiedStatus API Operation
GetVerifiedStatus Request
7
64 May 2012 Adaptive Accounts Developer Guide
RequestEnvelope Fields
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.
Field Description
detailLevel common:DetailLevelCode
(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
Field Description
Adaptive Accounts Developer Guide May 2012 65
GetVerifiedStatus API Operation
GetVerifiedStatus Response 7
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 GetVerifiedStatus 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.
GetVerifiedStatus API Operation
GetVerifiedStatus Response
7
66 May 2012 Adaptive Accounts Developer Guide
ResponseEnvelope Fields
UserInfoType 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.
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.
Adaptive Accounts Developer Guide May 2012 67
GetVerifiedStatus API Operation
GetVerifiedStatus Errors 7
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>
GetVerifiedStatus API Operation
GetVerifiedStatus Errors
7
68 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 69
ACountry Codes
Country or Region Country or Region Code
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA * DZ *
AMERICAN SAMOA AS
ANDORRA AD
ANGUILLA AI
ANTARCTICA * AQ *
ANTIGUA AND BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOSNIA-HERZEGOVINA BA
BOTSWANA BW
BOUVET ISLAND * BV *
Below are the country codes for Adaptive Accounts. Countries marked with an asterisk ( * ) are not
supported for PayPal Payments Pro and Virtual Terminal.
Country Codes
A
70 May 2012 Adaptive Accounts Developer Guide
BRAZIL BR
BRITISH INDIAN OCEAN TERRITORY * IO *
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN REPUBLIC * CF *
CHILE CL
CHINA CN
CHRISTMAS ISLAND * CX *
COCOS (KEELING) ISLANDS CC
COLOMBIA CO
COOK ISLANDS CK
COSTA RICA CR
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
ESTONIA EE
FALKLAND ISLANDS (MALVINAS) FK
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
Country or Region Country or Region Code
Adaptive Accounts Developer Guide May 2012 71
Country Codes A
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN TERRITORIES TF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUERNSEY GG
GUYANA GY
HEARD ISLAND AND MCDONALD ISLANDS * HM *
HOLY SEE (VATICAN CITY STATE) VA
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
Country or Region Country or Region Code
Country Codes
A
72 May 2012 Adaptive Accounts Developer Guide
JORDAN JO
KAZAKHSTAN KZ
KIRIBATI KI
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LATVIA LV
LESOTHO LS
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA MK
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA, FEDERATED STATES OF FM
MOLDOVA, REPUBLIC OF MD
MONACO MC
MONGOLIA MN
MONTENEGRO ME
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
Country or Region Country or Region Code
Adaptive Accounts Developer Guide May 2012 73
Country Codes A
NAMIBIA NA
NAURU NR
NEPAL * NP *
NETHERLANDS NL
NETHERLANDS ANTILLES AN
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA ISLANDS MP
NORWAY NO
OMAN OM
PALAU PW
PALESTINE PS
PANAMA PA
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND NEVIS KN
Country or Region Country or Region Code
Country Codes
A
74 May 2012 Adaptive Accounts Developer Guide
SAINT LUCIA LC
SAINT PIERRE AND MIQUELON PM
SAINT VINCENT AND THE GRENADINES VC
SAMOA WS
SAN MARINO SM
SAO TOME AND PRINCIPE * ST *
SAUDI ARABIA SA
SENEGAL SN
SERBIA RS
SEYCHELLES SC
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOUTH AFRICA ZA
SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS
SPAIN ES
SURINAME SR
SVALBARD AND JAN MAYEN SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
TAIWAN, PROVINCE OF CHINA TW
TANZANIA, UNITED REPUBLIC OF TZ
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND TOBAGO TT
TUNISIA TN
Country or Region Country or Region Code
Adaptive Accounts Developer Guide May 2012 75
Country Codes A
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS ISLANDS TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR OUTLYING ISLANDS UM
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRITISH VG
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
ZAMBIA ZM
Country or Region Country or Region Code
Country Codes
A
76 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 77
BBusiness Categories and
Subcategories
Below are the codes for the business categories and subcategories that are passed for the
category and subcategory fields in CreateAccount requests for PayPal Business
accounts.
Categories
Category Description
1000 Arts, crafts, and collectibles
1001 Baby
1002 Beauty and fragrances
1003 Books and magazines
1004 Business to business
1005 Clothing, accessories, and shoes
1006 Computers, accessories, and services
1007 Education
1008 Electronics and telecom
1009 Entertainment and media
1010 Financial services and products
1011 Food retail and service
1012 Gifts and flowers
1013 Government
1014 Health and personal care
1015 Home and garden
1016 Nonprofit
1017 Pets and animals
1018 Religion and spirituality (for profit)
1019 Retail (not elsewhere classified)
1020 Services - other
1021 Sports and outdoors
1022 Toys and hobbies
1023 Travel
Business Categories and Subcategories
B
78 May 2012 Adaptive Accounts Developer Guide
Subcategories
1024 Vehicle sales
1025 Vehicle service and accessories
Subcategory Description Category Merchant Category
2000 Antiques 1000 5932
2001 Art and craft supplies 1000 5970
2002 Art dealers and galleries 1000 5971
2003 Camera and photographic supplies 1000 5946
2004 Digital art 1000 5971
2005 Memorabilia 100 5999
2006 Music store (instruments and sheet music) 1000 5733
2007 Sewing, needlework, and fabrics 1000 5949
2008 Stamp and coin 1000 5972
2009 Stationary, printing and writing paper 1000 5111
2010 Vintage and collectibles 1000 5931
2011 Clothing 1001 5641
2012 Furniture 1001 5712
2013 Baby products (other) 1001 5999
2014 Safety and health 1001 5999
2015 Bath and body 1002 5122
2016 Fragrances and perfumes 1002 5977
2017 Makeup and cosmetics 1002 5977
2018 Audio books 1003 5942
2019 Digital content 1003 5999
2020 Educational and textbooks 1003 5942
2021 Fiction and nonfiction 1003 5942
2022 Magazines 1003 5192
2023 Publishing and printing 1003 2741
2024 Rare and used books 1003 5942
2025 Accounting 1004 8931
Category Description
Adaptive Accounts Developer Guide May 2012 79
Business Categories and Subcategories B
2026 Advertising 1004 7311
2027 Agricultural 1004 780
2028 Architectural, engineering, and surveying
services
1004 8911
2029 Chemicals and allied products 1004 5169
2030 Commercial photography, art, and graphics 1004 7333
2031 Construction 1004 5039
2032 Consulting services 1004 7392
2033 Educational services 1004 8299
2034 Equipment rentals and leasing services 1004 7394
2035 Equipment repair services 1004 7699
2036 Hiring services 1004 7361
2037 Industrial and manufacturing supplies 1004 5085
2038 Mailing lists 1004 5969
2039 Marketing 1004 5969
2040 Multi-level marketing 1004 5969
2041 Office and commercial furniture 1004 5021
2042 Office supplies and equipment 1004 5943
2043 Publishing and printing 1004 2741
2044 Quick copy and reproduction services 1004 7338
2045 Shipping and packing 1004 7399
2046 Stenographic and secretarial support services 1004 7339
2047 Wholesale 1004 7399
2048 Children’s clothing 1005 5641
2049 Men’s clothing 1005 5611
2050 Women’s clothing 1005 5621
2051 Shoes 1005 5661
2052 Military and civil service uniforms 1005 5699
2053 Accessories 1005 5699
2054 Retail (fine jewelry and watches) 1005 5094
2055 Wholesale (precious stones and metals) 1005 5094
Subcategory Description Category Merchant Category
Business Categories and Subcategories
B
80 May 2012 Adaptive Accounts Developer Guide
2056 Fashion jewelry 1005 5944
2057 Computer and data processing services 1006 7372
2058 Desktops, laptops, and notebooks 1006 5045
2059 Digital content 1006 5999
2060 eCommerce services 1006 4816
2061 Maintenance and repair services 1006 7379
2062 Monitors and projectors 1006 7379
2063 Networking 1006 4816
2064 Online gaming 1006 7999
2065 Parts and accessories 1006 5045
2066 Peripherals 1006 5045
2067 Software 1006 5734
2068 Training services 1006 8299
2069 Web hosting and design 1006 4816
2070 Business and secretarial schools 1007 8244
2071 Child daycare services 1007 8351
2072 Colleges and universities 1007 8220
2073 Dance halls, studios, and schools 1007 7911
2074 Elementary and secondary schools 1007 8211
2075 Vocational and trade schools 1007 8249
2076 Cameras, camcorders, and equipment 1008 5732
2078 Cell phones, PDAs, and pagers 1008 4812
2079 General electronic accessories 1008 5732
2080 Home audio 1008 5732
2081 Home electronics 1008 5732
2082 Security and surveillance 1008 5732
2083 Telecommunication equipment and sales 1008 4812
2084 Telecommunication services 1008 4814
2085 Telephone cards 1008 4814
2086 Memorabilia 1009 5999
2087 Movie tickets 1009 7832
Subcategory Description Category Merchant Category
Adaptive Accounts Developer Guide May 2012 81
Business Categories and Subcategories B
2088 Movies (DVDs, videotapes) 1009 5999
2089 Music (CDs, cassettes and albums) 1009 5735
2090 Cable, satellite, and other pay TV and radio 1009 4899
2091 Adult digital content 1009 5999
2092 Concert tickets 1009 7929
2093 Theater tickets 1009 7922
2094 Toys and games 1009 5945
2095 Slot machines 1009 5999
2096 Digital content 1009 5999
2097 Entertainers 1009 7929
2098 Gambling 1009 7995
2099 Online games 1009 7999
2100 Video games and systems 1009 5945
2101 Accounting 1010 8931
2102 Collection agency 1010 7321
2103 Commodities and futures exchange 1010 4829
2104 Consumer credit reporting agencies 1010 7321
2105 Debt counseling service 1010 7277
2106 Credit union 1010 6012
2107 Currency dealer and currency exchange 1010 4829
2108 Escrow 1010 4829
2109 Finance company 1010 6012
2110 Financial and investment advice 1010 8999
2111 Insurance (auto and home) 1010 5960
2112 Insurance (life and annuity) 1010 5960
2113 Investments (general) 1010 4829
2114 Money service business 1010 6012
2115 Mortgage brokers or dealers 1010 4829
2116 Online gaming currency 1010 4829
2117 Paycheck lender or cash advance 1010 6051
2118 Prepaid and stored value cards 1010 5999
Subcategory Description Category Merchant Category
Business Categories and Subcategories
B
82 May 2012 Adaptive Accounts Developer Guide
2119 Real estate agent 1010 6513
2120 Remittance 1010 4829
2121 Rental property management 1010 6513
2122 Security brokers and dealers 1010 6211
2123 Wire transfer and money order 1010 4829
2124 Alcoholic beverages 1011 5921
2125 Catering services 1011 5811
2126 Coffee and tea 1011 5499
2127 Gourmet foods 1011 5499
2128 Specialty and miscellaneous food stores 1011 5499
2129 Restaurant 1011 5812
2130 Tobacco 1011 0
2131 Vitamins and supplements 1011 5122
2132 Florist 1012 5193
2133 Gift, card, novelty, and souvenir shops 1012 5947
2134 Gourmet foods 1012 5499
2135 Nursery plants and flowers 1012 5261
2136 Party supplies 1012 5947
2137 Government services (not elsewhere classified) 1013 9399
2138 Drugstore (excluding prescription drugs) 1014 5122
2139 Drugstore (including prescription drugs) 1014 5912
2140 Dental care 1014 8021
2141 Medical care 1014 8011
2142 Medical equipment and supplies 1014 5047
2143 Vision care 1014 8043
2144 Vitamins and supplements 1014 5122
2145 Antiques 1015 5932
2146 Appliances 1015 5722
2147 Art dealers and galleries 1015 5971
2148 Bed and bath 1015 5712
2149 Construction material 1015 5039
Subcategory Description Category Merchant Category
Adaptive Accounts Developer Guide May 2012 83
Business Categories and Subcategories B
2150 Drapery, window covering, and upholstery 1015 5714
2151 Exterminating and disinfecting services 1015 7342
2152 Fireplace, and fireplace screens 1015 5718
2153 Furniture 1015 5712
2154 Garden supplies 1015 5261
2155 Glass, paint, and wallpaper 1015 5231
2156 Hardware and tools 1015 5251
2157 Home decor 1015 5719
2158 Housewares 1015 5719
2159 Kitchenware 1015 5719
2160 Landscaping 1015 780
2161 Rugs and carpets 1015 5713
2162 Security and surveillance equipment 1015 5732
2163 Swimming pools and spas 1015 5996
2164 Charity 1016 8398
2165 Political 1016 8398
2166 Religious 1016 8398
2167 Other 1016 8398
2168 Personal 1016 8398
2169 Educational 1016 8398
2171 Medication and supplements 1017 5995
2172 Pet shops, pet food, and supplies 1017 5995
2173 Specialty or rare pets 1017 5995
2174 Veterinary services 1017 742
2175 Membership services 1018 8699
2176 Merchandise 1018 5973
2177 Services (not elsewhere classified) 1018 8999
2178 Chemicals and allied products 1019 5169
2179 Department store 1019 5311
2180 Discount store 1019 5310
2181 Durable goods 1019 5099
Subcategory Description Category Merchant Category
Business Categories and Subcategories
B
84 May 2012 Adaptive Accounts Developer Guide
2182 Non-durable goods 1019 5199
2183 Used and secondhand store 1019 5931
2184 Variety store 1019 5331
2185 Advertising 1020 7311
2186 Shopping services and buying clubs 1020 7278
2187 Career services 1020 7361
2188 Carpentry 1020 1750
2189 Child care services 1020 8351
2190 Cleaning and maintenance 1020 2842
2191 Commercial photography 1020 7333
2192 Computer and data processing services 1020 7372
2193 Computer network services 1020 4816
2194 Consulting services 1020 7392
2195 Counseling services 1020 7277
2196 Courier services 1020 4215
2197 Dental care 1020 8021
2198 eCommerce services 1020 4816
2199 Electrical and small appliance repair 1020 7629
2200 Entertainment 1020 7929
2201 Equipment rental and leasing services 1020 7394
2202 Event and wedding planning 1020 8999
2203 Gambling 1020 7995
2204 General contractors 1020 1520
2205 Graphic and commercial design 1020 7333
2206 Health and beauty spas 1020 7298
2207 IDs, licenses, and passports 1020 8999
2208 Importing and exporting 1020 7399
2209 Information retrieval services 1020 7375
2210 Insurance - auto and home 1020 5960
2211 Insurance - life and annuity 1020 5960
2212 Landscaping and horticultural 1020 780
Subcategory Description Category Merchant Category
Adaptive Accounts Developer Guide May 2012 85
Business Categories and Subcategories B
2213 Legal services and attorneys 1020 8111
2214 Local delivery service 1020 4215
2215 Lottery and contests 1020 8999
2216 Medical care 1020 8011
2217 Membership clubs and organizations 1020 7991
2218 Misc. publishing and printing 1020 2741
2219 Moving and storage 1020 8999
2220 Online dating 1020 7273
2221 Photofinishing 1020 7395
2222 Photographic studios - portraits 1020 7221
2223 Protective and security services 1020 7393
2224 Quick copy and reproduction services 1020 7338
2225 Radio, television, and stereo repair 1020 7622
2226 Real estate agent 1020 6513
2227 Rental property management 1020 6513
2228 Reupholstery and furniture repair 1020 7641
2229 Services (not elsewhere classified) 1020 8999
2230 Shipping and packing 1020 7399
2231 Swimming pool services 1020 5996
2232 Tailors and alterations 1020 5697
2233 Telecommunication service 1020 4814
2234 Utilities 1020 4900
2235 Vision care 1020 8043
2236 Watch, clock, and jewelry repair 1020 7631
2237 Athletic shoes 1021 5661
2238 Bicycle shop, service, and repair 1021 5940
2239 Boating, sailing and accessories 1021 5551
2240 Camping and outdoors 1021 5941
2241 Dance halls, studios, and schools 1021 7911
2242 Exercise and fitness 1021 5941
2243 Fan gear and memorabilia 1021 5947
Subcategory Description Category Merchant Category
Business Categories and Subcategories
B
86 May 2012 Adaptive Accounts Developer Guide
2244 Firearm accessories 1021 5999
2245 Firearms 1021 5999
2246 Hunting 1021 5941
2247 Knives 1021 5941
2248 Martial arts weapons 1021 5941
2249 Sport games and toys 1021 5941
2250 Sporting equipment 1021 5941
2251 Swimming pools and spas 1021 5996
2252 Arts and crafts 1022 5970
2253 Camera and photographic supplies 1022 5946
2254 Hobby, toy, and game shops 1022 5945
2255 Memorabilia 1022 5999
2256 Music store - instruments and sheet music 1022 5733
2257 Stamp and coin 1022 5972
2258 Stationary, printing, and writing paper 1022 5111
2259 Vintage and collectibles 1022 5931
2260 Video games and systems 1022 5945
2261 Airline 1023 4511
2262 Auto rental 1023 3351
2263 Bus line 1023 4131
2264 Cruises 1023 4411
2265 Lodging and accommodations 1023 7011
2266 Luggage and leather goods 1023 5948
2267 Recreational services 1023 7999
2268 Sporting and recreation camps 1023 7032
2269 Taxicabs and limousines 1023 4121
2270 Timeshares 1023 7012
2271 Tours 1023 4722
2272 Trailer parks or campgrounds 1023 7033
2273 Transportation services - other 1023 4789
2274 Travel agency 1023 4722
Subcategory Description Category Merchant Category
Adaptive Accounts Developer Guide May 2012 87
Business Categories and Subcategories B
2275 Auto dealer - new and used 1024 5511
2276 Auto dealer - used only 1024 5521
2277 Aviation 1024 5599
2278 Boat dealer 1024 5551
2279 Mobile home dealer 1024 5271
2280 Motorcycle dealer 1024 5571
2281 Recreational and utility trailer dealer 1024 5561
2282 Recreational vehicle dealer 1024 5561
2283 Vintage and collectibles 1024 5521
2284 New parts and supplies - motor vehicle 1025 5533
2285 Used parts - motor vehicle 1025 5533
2286 Audio and video 1025 5732
2287 Auto body repair and paint 1025 7531
2288 Auto rental 1025 3351
2289 Auto service 1025 7538
2290 Automotive tire supply and service 1025 5532
2291 Boat rental and leases 1025 4457
2292 Car wash 1025 7542
2293 Motor home and recreational vehicle rental 1025 7519
2294 Tools and equipment 1025 5533
2295 Towing service 1025 7549
2296 Truck and utility trailer rental 1025 7513
2297 Accessories 1025 5533
Subcategory Description Category Merchant Category
Business Categories and Subcategories
B
88 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 89
CAdaptive Accounts IPN Messages
PayPal sends an IPN message whenever a PayPal account is created using the
CreateAccount API operation.
Example IPN message in response to CreateAccount request
notify_version=UNVERSIONED&first_name=Someone&verify_sign=AI.LzRiNYreJbZLZ8
BV5FbGKL8hSAupAtXf3haOHWI2NmcJ5C4VqdQrx&charset=windows-
1252&last_name=Something&account_key=AA6N5043354R131103K&confirmation_code=
15531193754629193930
Example IPN message in response to account holder setting the password
first_name=Someone&account_key=AA-
6N5043354R131103K&notify_version=UNVERSIONED&charset=windows-
1252&email_address=abawany-20110208-
01%40paypal.com&event_type=%5BACCOUNT_CONFIRMED%5D&last_name=Something&veri
fy_sign=AcIPKnsgPsoX2ONJgU17uAl9h-ZIAKJMRvhEULLvD9mOzH3WjdRNfEte
Field Description
notify_version Message’s version number
first_name Account holders first name
last_name Account holders last name
verify_sign Encrypted string used to validate the authenticity of the transaction
charset Character set
account_key Account key returned by the CreateAccount API operation
confirmation_code Confirmation code
event_type The kind of event:
-ACCOUNT_CONFIRMED indicates that the account holder has set a password
and the account has been created.
-LOGIN_CONFIRMED indicates that the account holder logged into the
account.
Adaptive Accounts IPN Messages
C
90 May 2012 Adaptive Accounts Developer Guide
NOTE:This message indicates that the account setup is complete.
Example IPN message in response to account login
first_name=Someone&account_key=AA-
6N5043354R131103K&notify_version=UNVERSIONED&charset=windows-
1252&email_address=abawany-20110208-
01%40paypal.com&event_type=%5BLOGIN_CONFIRMED%5D&last_name=Something&verify
_sign=ANqF6tuR41eB.S.2I9dCskJuSSvrAI8Monbec4U2PZCnoKYffnv156mN
Adaptive Accounts Developer Guide May 2012 91
Older Versions of the Adaptive
Accounts API
Unless you specify the version, PayPal defaults to the latest version of an API operation. APIs
are backwards compatible with previous versions; however, PayPal recommends that you use
the most recent version.
Adaptive Account Changes Corresponding to PayPal Version
85.0
This document includes corrections to the explanations of the account creation flow and
updates to Adaptive Accounts methods. The 85.0 release includes the following new features:
-In the CreateAccount API, a new taxId field.
-Updates to the error codes listings for multiple APIs.
-New UserInfo fields for the GetVerifiedStatus API
New UserInfo Fields in GetVerifiedStatus API
Field Description
accountType sample xs:boolean
(Optional) sample Whether or not to show the mobile confirmation option.
-true - show the option
-false - do not show the option (default)
name
businessName
accountId
emailAddress
Adaptive Account Changes Corresponding to PayPal Version 69.0
92 May 2012 Adaptive Accounts Developer Guide
Adaptive Account Changes Corresponding to PayPal Version
69.0
Version 1.0.3 of Adaptive Accounts corresponds to Release 69.0 of the PayPal API. It
includes the following changes to the minibrowser account creation feature and adds a
supporting field in the CreateWebOptionsType structure:
-Enhanced the minibrowser account creation flow to optionally include adding a bank card
with a shipping address and confirmed phone number.
Changes to CreateWebOptionsType fields
Adaptive Account Changes Corresponding to PayPal Version
65.5
This release corresponds to Version 65.2 of the PayPal API. It includes the following new
Adaptive Accounts feature:
-Added an account creation flow that displays the Create your PayPal account flow in a
minibrowser.
NOTE:You must use Version 1.0.1 or higher of the Adaptive Accounts WSDL to implement
this flow.
Adaptive Account Changes Corresponding to PayPal Version
64.2
This release includes the following new features:
-Ability to add payment cards as funding sources (new AddPaymentCard method.
-Ability to set the status for funding sources to confirmed (new
SetFundingSourceConfirmed method.
-Ability to add bank accounts without redirecting to PayPal.com (new confirmedType
element)
-Added country support for CreateAccount and AddBankAccount methods.
Field Description
showMobileConfirm xs:boolean
(Optional) Whether or not to show the mobile confirmation option.
-true - show the option
-false - do not show the option (default)
Adaptive Accounts Developer Guide May 2012 93
Adaptive Account Changes Corresponding to PayPal Version 62.2
-Ability to have PayPal perform extra vetting before activating an account (new
performExtraVettingOnThisAccount parameter in CreateAccount).
-Support for Merchant Referral Bonus functionality for CreateAccount
(Business/Premier accounts only) via the new HTTP request header X-PAYPAL-
MERCHANT-REFERRAL-BONUS-ID.
-Added country support for Malaysia, Singapore, China, Taiwan, Thailand, and Hong Kong
for AddPaymentCard (confirmationType WEB only)
Adaptive Account Changes Corresponding to PayPal Version
62.2
The 62.2 release included the following new features:
-Ability to create business accounts
-Adding bank accounts as funding sources
-Account verification
Creating Business Accounts
You can now use the CreateAccount API to create PayPal Business accounts. To this end,
the CreateAccountRequest message lets you pass a new parameter, businessInfoType.
Adding Bank Accounts
This release provides the AddBankAccount API, which lets your application link the PayPal
account to a bank account as the funding source.
Verifying Accounts
Adaptive Accounts now provides a new API, GetVerifiedStatus. This API lets you check
the PayPal account status. PayPal accounts can be verified or unverified. 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 to PayPal that there is a history of
payment. For more information about account verified status, refer to PayPal.com.
Adaptive Account Changes Corresponding to PayPal Version 62.2
94 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 95
Revision History
Revision history for Adaptive Accounts Service documentation.
Date Description
5/2/12 Maintenance release.
12/09/11 Corrections and updates corresponding to modifications and changes through
release 85, including new fields in the GetVerifiedStatus API.
02/23/11 Updated information about the account creation minibrowser flow for version
1.0.3, corresponding to release 69.
08/12/10 Added information about merchant referral bonus invitations.
01/12/10 Added country codes for Australia and Israel.
10/02/09 Beta draft for version 1.0.1.
09/12/09 Revised draft for version 1.0.1.
06/11/09 Initial draft for version 1.0.1.
96 May 2012 Adaptive Accounts Developer Guide
Adaptive Accounts Developer Guide May 2012 97
Index
A
Account creation, adding credit card 15
Account creation, default 19
Account creation, using minibrowser 14
accountHolderDateofBirth request field 46
accountId request field 46, 52, 59
accountId response field 39
accountStatus response field 65
accountType request field 30, 66
ack response field 40, 49, 56, 60, 66
AddBankAccount API operation 45
AddBankAccount request fields 46
AddBankAccount request message 45
AddBankAccount response fields 49
AddBankAccount response message 48
AddPaymentCard request fields 52
AddPaymentCard request message 51
AddPaymentCard response fields 55
AddPaymentCard response message 55
address request field 30, 37
AddressType request fields 33, 53
API methods 23
averageMonthlyVolume request field 33
averagePrice request field 33
B
bankAccountNumber request field 46
bankAccountType request field 46
bankCode request field 46
bankCountryCode request field 46
bankName request field 46
bankTransitNumber request field 46
billingAddress request field 52
branchCode request field 46
branchLocation request field 46
bsbNumber request field 46
build response field 40, 49, 56, 60, 66
businessAddress request field 33
businessInfo request field 30
BusinessInfoType request fields 33
businessName field 66
businessName request field 33
businessStakeholder request field 33
BusinessStakeholderType request fields 37
businessSubtype request field 34
businessType request field 34
C
cancelUrl request field 48
cancelUrlDescription request field 48
CardDateType request fields 54
cardNumber request field 52
cardOwnerDateOfBirth request field 52
cardType request field 52
cardVerificationNumber request field 52
category request field 34
citizenshipCountryCode request field 30
city request field 33, 53
clabe request field 46
clientDetails request field 30
commercialRegistrationLocation request field 34
companyId request field 34
confirmationType request field 47, 52
contactPhoneNumber request field 30
controlDigit request field 47
correlationId response field 40, 49, 56, 60, 66
countryCode request field 33, 37, 54, 65
CreateAccount API operation 27
CreateAccount request fields 30, 66
CreateAccount Request message 27
CreateAccount response fields 39
CreateAccount Response message 39
createAccountKey request field 53
createAccountKey response field 39
createAccountWebOptions request field 31
CreateWebOptionsType request fields 37
credit card, adding during account creation 15
currencyCode request field 31
customerServiceEmail request field 34
customerServicePhone request field 35
Index
98 May 2012 Adaptive Accounts Developer Guide
D
dateOfBirth request field 31, 37
dateOfEstablishment request field 35
detailLevel request field 39, 48, 54, 60, 64
disputeEmail request field 35
doingBusinessAs request field 35
E
emailAddress request field 31, 47, 53, 59, 63, 66
errorLanguage request field 39, 48, 55, 60, 64
establishmen tCountryCode request field 35
establishmentState request field 35
execStatus response field 40
execstatus response field 49, 55
expirationDate request field 53
F
firstName request field 38, 54, 63
fullLegalName request field 37
fundingSourceKey request field 59
fundingSourceKey response field 49, 55
G
GetVerifiedStatus API operation 63
GetVerifiedStatus request fields 63
GetVerifiedStatus request message 63
GetVerifiedStatus response fields 65
GetVerifiedStatus response message 65
H
homePhoneNumber request field 30
I
iban request field 47
incorporationId request fi eld 35
institionNumber request field 47
issueNumber request field 53
L
lastName request field 38, 54, 63
line1 request field 33, 53
line2 request field 33, 53
M
matchCriteria request field 64
merchantCategoryCode request field 35
methods, Adaptive Accounts 23
middleName request field 38, 54
mobilePhoneNumber request field 31
month request field 54
N
name request field 31, 37, 66
nameOnCard request field 53
NameType request fields 38, 54
notificationURL request field 31
P
partnerFieldn request field 31
partnerInfo request field 47
percentageRevenueFromOnline request field 35
perfermExtraVettingOnthisAccount request field 31
postalCode request field 33, 53
principlePlaceofBusinessd request field 35
R
redirectURL response field 49, 55
registeredOfficeAddress request field 35
requestEnvelope request field 47, 53, 59, 64
RequestEnvelope request fields 39, 48, 54, 60, 64
ResponseEnvelope fields 40, 49, 56, 60, 66
responseEnvelope response field 40, 49, 55, 65
returnUrl request field 37, 38, 48, 54
returnURL response field 40
returnUrlDescription request field 37, 48
ribkey request field 47
role request field 37
routingNumber request field 47
S
salesVenue request field 36
Adaptive Accounts Developer Guide May 2012 99
Index
salesVenueDesc request field 36
SetFundingSourceConfirmed API operation 59
SetFundingSourceConfirmed request fields 59
SetFundingSourceConfirmed request message 59
SetFundingSourceConfirmed response message 60
showAddCreditCard request field 38
showMobileConfirm request field 38, 92
sortCode request field 47
startDate request field 53
state request field 33, 53
subcategory request field 36
suffix request field 38, 54
T
taxId field 31
taxIdNumber 47
taxIdType 47
timestamp response field 40, 49, 56, 60, 66
U
useMiniBrowser request field 38
userInfoType information 65
V
vatCountryCode request field 36
vatId request field 36
W
webOptions request field 53
webOptionsType request field 47
WebOptionsType request fields 48
webSite request field 36
workPhone request field 36
Y
year request field 54
Index
100 May 2012 Adaptive Accounts Developer Guide

Navigation menu