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
.
Page Count: 100
| Download | |
| Open PDF In Browser | View PDF |
Adaptive Accounts
Developer Guide
Last updated: May 2012
PayPal Adaptive Accounts Developer Guide
Document Number: 10109.en_US-201205
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information 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.
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
Adaptive Accounts Developer Guide
May 2012
3
Contents
CreateWebOptionsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
NameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
CreateAccount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
CreateAccount Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
CreateAccount Request Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
CreateAccount Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 4
AddBankAccount API Operation
. . . . . . . . . . . . . . 45
AddBankAccount Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
AddBankAccount Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
WebOptionsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
AddBankAccount Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
AddBankAccount Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Chapter 5
AddPaymentCard API Operation
. . . . . . . . . . . . . . 51
AddPaymentCard Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
AddPaymentCard Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
AddressType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
NameType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
CardDateType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
AddPaymentCard Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
AddPaymentCard Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
AddPaymentCard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Chapter 6
SetFundingSourceConfirmed API Operation . . . . . . . . 59
SetFundingSourceConfirmed Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
SetFundingSourceConfirmed Request Fields . . . . . . . . . . . . . . . . . . . . . . 59
RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
SetFundingSourceConfirmed Response. . . . . . . . . . . . . . . . . . . . . . . . . . . 60
ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
SetFundingSourceConfirmed Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
4
May 2012
Adaptive Accounts Developer Guide
Contents
Chapter 7
GetVerifiedStatus API Operation . . . . . . . . . . . . . . 63
GetVerifiedStatus Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
GetVerifiedStatus Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
GetVerifiedStatus Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
GetVerifiedStatus Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
UserInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
GetVerifiedStatus Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Appendix A Country Codes
. . . . . . . . . . . . . . . . . . . . . . . 69
Appendix B Business Categories and Subcategories . . . . . . . . . . 77
Appendix C Adaptive Accounts IPN Messages . . . . . . . . . . . . . . 89
Older Versions of the Adaptive Accounts API . . . . . . . . . . . . . . . 91
Adaptive Account Changes Corresponding to PayPal Version 85.0 . . . . . . . . . . . . . 91
Adaptive Account Changes Corresponding to PayPal Version 69.0 . . . . . . . . . . . . . 92
Adaptive Account Changes Corresponding to PayPal Version 65.5 . . . . . . . . . . . . 92
Adaptive Account Changes Corresponding to PayPal Version 64.2 . . . . . . . . . . . . 92
Adaptive Account Changes Corresponding to PayPal Version 62.2 . . . . . . . . . . . . . 93
Creating Business Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Adding Bank Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Verifying Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Adaptive Accounts Developer Guide
May 2012
5
Contents
6
May 2012
Adaptive Accounts Developer Guide
Preface
PayPal’s Adaptive Accounts API enables your customers to create various kinds of PayPal
accounts.
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
Adaptive Accounts Developer Guide
May 2012
7
Documentation Feedback
8
May 2012
Adaptive Accounts Developer Guide
What’s New
Check out what’s new in the current release.
Adaptive Account Changes Corresponding for PayPal Version
89.0
Maintenance release.
Adaptive Accounts Developer Guide
May 2012
9
Adaptive Account Changes Corresponding for PayPal Version 89.0
10
May 2012
Adaptive Accounts Developer Guide
1
Introducing Adaptive Accounts
The Adaptive Accounts API lets you build applications that create PayPal accounts and handle
account management.
Adaptive Accounts Scenarios
The Adaptive Accounts API enables your application to create and verify PayPal accounts.
You can also add bank accounts to link to PayPal accounts as funding sources.
Consider the following examples. You might create a PayPal account using the Adaptive
Accounts APIs as part of the set up for a:
marketplace. You can offer PayPal as a payment option and create PayPal accounts for
your users that do not already have them. Your users can include buyers and suppliers or
clients and services providers as senders and receivers in various countries.
social networking application, such as one that “pays for lunch” or sends a payment for any
reason. Your application may not be directly involved in the payment; however, you can
enable the payment by ensuring that the user has the opportunity to create a PayPal
account.
enterprise application, such as a payroll application for small-to-medium sized businesses.
You can create PayPal accounts for each employee that does not have one and pay all
employees using PayPal’s Mass Pay or Adaptive Payments capabilities.
store checkout flow. You might provide PayPal account creation for your customers or you
might provide account creation for someone else’s customers as part of a shopping cart
service.
Creating an Account
PayPal account holders traditionally create their PayPal accounts by going directly to
PayPal.com or signing up during a checkout flow. The Adaptive Accounts CreateAccount
method offers a new way: Creating accounts within your application or website, outside the
checkout flow.
Your application sends a request using the CreateAccount method with information
gathered from your website, and PayPal creates the account. At this point, the new PayPal
account holder is briefly redirected to PayPal.com to enter private information, such as a
password, and to accept the PayPal User Agreement. PayPal then returns the new account
Adaptive Accounts Developer Guide
May 2012
11
1
Introducing Adaptive Accounts
Adding Bank Accounts as Funding Sources
holder to your website. This greatly reduces the chances of losing customers during the
account creation flow.
That brings us to the key benefit of Adaptive Accounts: A streamlined account creation and
completion process. Research shows that removing barriers from account creation and
payment experience increases conversion and improves customer satisfaction.
Imagine the possibilities: With the 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 customer’s website.
Adding Payment Cards as Funding Sources
Adaptive Accounts lets your application link the created PayPal account to a credit card or
payment card. This card can then be used as a funding source (payment method) for the PayPal
account. To use this feature, you use the createAccount key from the CreateAccount
response and pass it with the AddPaymentCard method together with pertinent payment card
information.
For standard permissions, the AddPaymentCard method requires the PayPal account user to
confirm the payment card addition on paypal.com. Developers with advanced permissions can
pass the AddPaymentCard with the confirmedType element (set to NONE) to add payment
cards without redirecting to paypal.com.
Supported payment cards are:
12
Visa
MasterCard
American Express
Discover
Maestro
May 2012
Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Set Funding Sources to Confirmed Status
Solo
Carte Aurore
Carte Bleue
Cofinoga
4 étoiles
Carte Aura
Tarjeta Aurora
JCB
1
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 holder’s email address. The Adaptive Accounts web service responds
with a message that indicates if the match was verified. This provides an effective method of
reducing fraud. With the GetVerifiedStatus method, merchants have the security of
knowing that consumers’ PayPal accounts are verified before completing a transaction.
Account Creation Flow
For account creation on the web, call CreateAccount and use the redirect URL to direct the
person’s browser to PayPal. After the person creates an account, the browser is redirected to
the return URL you specified in the CreateAccount request.
The following diagram shows the basic flow of control for account creation on the web:
Adaptive Accounts Developer Guide
May 2012
13
1
Introducing Adaptive Accounts
Account Creation Flow
The following items correspond to the circled numbers in the diagram:
1. Your site or device sends a CreateAccount request to PayPal on behalf of a potential
account holder.
2. PayPal responds with a key and a URL, named the redirectURL, that you use when you
direct the person to PayPal.
3. You include the key and redirect your person’s browser to PayPal using the
redirectURL.
After the person logs on to PayPal and completes the account setup, the person is prompted to
return to the URL.
Account Creation Using a Minibrowser
PayPal can enable your customer to create an account using a minibrowser flow. Set
CreateAccountRequest.CreateAccountWebOptionsType.useMinibrowser to
true in the CreateAccount request message to specify this flow.
NOT E :
You must use Version 1.0.1 or higher of the Adaptive Accounts WSDL to implement
this flow.
When you redirect your customer’s browser to the URL in the CreateAccount response
message, PayPal responds with the following:
14
May 2012
Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
1
Your customer enters the password twice and clicks Agree and Continue to create the
account.
NOT E :
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:
Adaptive Accounts Developer Guide
May 2012
15
1
Introducing Adaptive Accounts
Account Creation Flow
Your customer enters debit or credit card information and clicks Add Card and Continue.
NOT E :
16
Your customer can enter a phone number and associate a billing address, or add a new
address from the Billing address drop-down menu:
May 2012
Adaptive Accounts Developer Guide
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:
Adaptive Accounts Developer Guide
May 2012
17
1
Introducing Adaptive Accounts
Account Creation Flow
Your customer requests a confirmation code by clicking Send SMS, and then clicks Confirm
Phone after entering the code in the SMS message.
NOT E :
The phone number to confirm is the number associated with a debit or credit card for
the account, which you set on the Link a debit or credit card page. You cannot
change the phone number.
Default Account Creation From the Web
To enable your customer to create a PayPal account, you call the CreateAccout API
operation and use the returned URL to redirect your customer’s browser to PayPal. Your
customer then signs up and agrees to the terms of the account.
18
May 2012
Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
1
By default, when you redirect your customer’s browser to the URL in the CreateAccount
response message, PayPal responds with the following sequence of pages:
1. The Welcome page identifies the information that will be needed to create an account:
2. The Create PayPal account login screen requests your customer to submit a password and
security questions, with answers:
Adaptive Accounts Developer Guide
May 2012
19
1
Introducing Adaptive Accounts
Account Creation Flow
3. The Add Credit or Debit Card page enables your customer to specify a funding source
and billing information:
20
May 2012
Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
NOT E :
1
The account holder can add a credit or debit card now or click Cancel to continue
without adding a card.
4. After the person logs on to PayPal and completes the account setup, the person is prompted
to return to the URL.
Adaptive Accounts Developer Guide
May 2012
21
1
22
Introducing Adaptive Accounts
Account Creation Flow
May 2012
Adaptive Accounts Developer Guide
2
Supported Formats, URLs and
HTTP Request Headers
Adaptive Accounts Methods
Adaptive Accounts provides the following methods:
API Operation
Description
CreateAccount
Creates PayPal accounts.
AddBankAccount
Link bank accounts to PayPal accounts as funding sources.
AddPaymentCard
Link payment cards to PayPal accounts as funding sources
SetFundingSourceConfirmed
Set the funding source to confirmed; they may set the account to PayPal
Verified status.
GetVerifiedStatus
Verify PayPal accounts by matching account holder criteria such as the
account holder’s email address.
Adaptive Accounts URLs
The endpoint is determined by the method and the environment in which you want to execute
the API operation. For example, if you want to send a CreateAccount request to the
sandbox, specify the following URL:
https://svcs.sandbox.paypal.com/AdaptiveAccounts/CreateAccount
You can specify the following URLs:
Environment
Endpoint
Production
https://svcs.paypal.com/AdaptiveAccounts/API_operation
Sandbox
https://svcs.sandbox.paypal.com/AdaptiveAccounts/API_operation
Adaptive Accounts Developer Guide
May 2012
23
2
Supported Formats, URLs and HTTP Request Headers
Supported Formats
Supported Formats
Adaptive Accounts supports both RESTful and SOAP-based web services. When making
RESTful calls, you can use the following data formats:
XML
Name-value pair (NV)
JSON
HTTP Request Headers
Required HTTP Request Headers
Header
Description
X-PAYPAL-SECURITY-USERID
Your API username as assigned to you on x.com.
X-PAYPAL-SECURITY-PASSWORD
Your API password as assigned to you on x.com.
X-PAYPAL-SECURITY-SIGNATURE
Your API signature. This header is only required if you use
3-token authorization. Do not pass this header if you use a
certificate.
X-PAYPAL-APPLICATION-ID
Your application’s identification, which is issued at x.com.
X-PAYPAL-DEVICE-IPADDRESS
The IP address of the caller. This header is required for
CreateAccount requests.
X-PAYPAL-REQUEST-DATA-FORMAT
The payload format for the request.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
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
Optional HTTP Request Headers
24
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.
May 2012
Adaptive Accounts Developer Guide
Supported Formats, URLs and HTTP Request Headers
HTTP Request Headers
Header
Description
X-PAYPAL-DEVICE-ID
Client’s device ID, such as a mobile device’s IMEI number.
This field is required for mobile application and is not used
for web application.
X-PAYPAL-MERCHANT-REFERRAL-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.
N O TE :
Adaptive Accounts Developer Guide
2
PayPal recommends not specifying a version unless
it is absolutely required.
May 2012
25
2
26
Supported Formats, URLs and HTTP Request Headers
HTTP Request Headers
May 2012
Adaptive Accounts Developer Guide
3
CreateAccount API Operation
The CreateAccount API operation enables you to create a PayPal account on behalf of a
third party.
CreateAccount Request
The CreateAccountRequest contains the information required to create a PayPal account
for a business customer.
Adaptive Accounts Developer Guide
May 2012
27
3
28
CreateAccount API Operation
CreateAccount Request
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
Adaptive Accounts Developer Guide
May 2012
3
29
3
CreateAccount API Operation
CreateAccount Request
CreateAccount Request Fields
30
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.
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
Field
Description
mobilePhoneNumber
xs:string
(Optional) Mobile phone number to be associated with the account. You must
specify a value to invoke the mobile confirmation option.
createAccountWebOptions
aa:CreateAccountWebOptionsType
(Required) The URL to which the business redirects the PayPal user for
PayPal account setup completion; also used for various other. configuration
settings for the web flow.
currencyCode
xs:string
(Required) The three letter code for the currency to be associated with the
account.
dateOfBirth
xs:date
The date of birth of the person for whom the PayPal account is created.
Required for Czech Republic, Japan, New Zealand, Israel, Switzerland,
Sweden, Denmark, and Australia; otherwise optional. Use YYYY-MM-DDZ
format; for example 1970-01-01Z.
emailAddress
xs:string
(Required) Email address of person for whom the PayPal account is created.
name
aa:NameType
(Required) The name of the person for whom the PayPal account is created.
notificationURL
xs:string
(Optional) The URL to post instant payment notification (IPN) messages to
regarding account creation. This URL supersedes the IPN notification URL set
in the merchant profile.
Maximum string length: between 1 and 1024 characters of the pattern <[a-aZZ]+\://){1}\S+
partnerFieldn
xs: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).
N O TE :
Adaptive Accounts Developer Guide
3
This is only supported for Brazil, which uses tax ID numbers such as
the CPF and CNPJ.
May 2012
31
3
32
CreateAccount API Operation
CreateAccount Request
Field
Description
preferredLanguageCode
xs:string
(Required) The code indicating the language to be associated with the account.
What value is allowed depends on the country code passed in the
countryCode parameter for the address. Examples:
Argentina (AR) – en_US, es_XC
Australia (AU) – en_AU
Austria (AT) – de_DE, en_US
Brazil (BR) – en_US
Canada (CA) – en_US, fr_XC
China (CN) – 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.
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
3
AddressType Fields
Field
Description
line1
xs:string
(Required) The street address.
line2
xs:string
(Optional) The second line of the address.
N O TE :
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.
BusinessInfoType Fields
Field
Description
averageMonthlyVolume
xs:decimal
The average monthly transaction volume of the business for which the PayPal
account is created. Required for all countries except Japan and Australia.
I MP O R TAN T :
averagePrice
Do not specify this field for Japan or Australia.
xs:decimal
The average price per transaction. Required for all countries except Japan and
Australia.
I MP O R TAN T :
Do not specify this field for Japan or Australia.
businessAddress
aa:addressType
(Required) The address for the business for which the PayPal account is
created.
businessName
xs:string
(Required) The name of the business for which the PayPal account is created.
businessStakeholder
aa:businessStakeholderType
(Optional) The stakeholders in the business.
Adaptive Accounts Developer Guide
May 2012
33
3
CreateAccount API Operation
CreateAccount Request
Field
Description
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
N O TE :
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.
I MP O R TAN T :
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,
I MP O R TAN T :
customerServiceEmail
34
Do not specify this field for other countries.
Do not specify this field for other countries.
xs:string
(Required) The email address for the customer service department of the
business.
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
Field
Description
customerServicePhone
xs:string
The phone number for the customer service department of the business.
Required for United States business accounts; otherwise, optional.
dateOfEstablishment
xs:date
The date of establishment for the business. Optional for France business
accounts and required for business accounts in the following countries: United
States, United Kingdom, Canada, Germany, Spain, Italy, Netherlands, Czech
Republic, Sweden, and Denmark.
I MP O R TAN T :
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.
I MP O R TAN T :
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.
Adaptive Accounts Developer Guide
3
May 2012
35
3
CreateAccount API Operation
CreateAccount Request
Field
Description
salesVenue
aa:salesVenueType
The venue type for sales. Required for business accounts in all countries
except Czech Republic and Australia. Allowable values are:
WEB
EBAY
OTHER_MARKETPLACE
OTHER
I MP O R TAN T :
salesVenueDesc
xs:string
A description of the sales venue. Required if salesVenue is OTHER for all
countries except Czech Republic and Australia.
I MP O R TAN T :
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.
I MP O R TAN T :
vatId
Do not specify this field for other countries.
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.
I MP O R TAN T :
36
Do not specify this field for Czech Republic or Australia.
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.
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
3
BusinessStakeholderType 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 YYYYMM-DDZ format; for example 1970-01-01Z.
fullLegalName
xs:string
(Optional) The legal name of the stakeholder in the business for which the
PayPal account is created.
name
aa:NameType
(Optional) The name of the stakeholder in the business for which the PayPal
account is created.
role
aa:StakeholderRoleType
(Optional) The role of the stakeholder in the business for which the PayPal
account is created. Allowable values are:
CHAIRMAN
SECRETARY
TREASURER
BENEFICIAL_OWNER
PRIMARY_CONTACT
INDIVIDUAL_PARTNER
NON_INDIVIDUAL_PARTNER
PRIMARY_INDIVIDUAL_PARTNER
DIRECTOR
NO_BENEFICIAL_OWNER
countryCode
xs:string
The country code. For allowable values, refer to “Country Codes” on page 69.
CreateWebOptionsType Fields
Field
Description
returnUrl
xs:string
(Required) The URL to which PayPal returns the account holder after the
account is created.
returnUrlDescription
xs:string
(Optional) A description of the return URL.
Adaptive Accounts Developer Guide
May 2012
37
3
CreateAccount API Operation
CreateAccount Request
Field
Description
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.
N O TE :
useMiniBrowser
This option is only available for Australia, Canada, Spain, France,
United Kingdom, Italy, Malaysia, Singapore, and United States.
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)
N O TE :
If you specify true for useMiniBrowser, do not specify values for
returnUrl or returnUrlDescription as they are not used in the
minibrowser flow.
NameType Fields
38
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.
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Response
3
RequestEnvelope 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
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
accountId
xs:string
The ID for the PayPal account. This is only for Premier and Business accounts.
createAccountKey
xs:string
A unique key that identifies the account that was created.
Adaptive Accounts Developer Guide
May 2012
39
3
CreateAccount API Operation
CreateAccount Request Sample
Field
Description
execStatus
xs:string
The status of the payment. Allowable values:
CREATED – The account creation is complete, no redirection for approval
necessary.
COMPLETED – The account creation request was successful (user
redirection for approval required).
CREATED PENDING VERIFICATION – The account creation is complete
but verification/approval process has not been completed.
returnURL
xs:string
The URL to which you direct your customer’s browser to create the account.
responseEnvelope
common:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
ResponseEnvelope Fields
Field
Description
ack
common:AckCode
Acknowledgment code. Possible values are:
Success – Operation completed successfully
Failure – Operation failed
Warning – warning
SuccessWithWarning – Operation completed successfully; however,
there is a warning message
FailureWithWarning – Operation failed with a warning message
build
Build number; used only by Developer Technical Support.
correlationId
Correlation ID; used only by Developer Technical Support.
timestamp
The date on which the response was sent. The time is not supported.
CreateAccount Request Sample
SOAP request
To create an account, the SOAP request specifies the name, address, and other identifying
information about the account holder for whom you want to create an account. You can
specify additional information to associate with the account in the partner information fields.
40
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request Sample
3
en_US
PERSONAL
testing-2039039@paypal.com
John
Smith
1968-01-01Z
1968 Ape Way
Apt 123
Austin
TX
78750
US
888-555-1212
USD
US
en_US
http://...
WEB
http://www.myhome.com
SOAP response
The response contains the PayPal URL to which you redirect the person’s browser. The
current status of the request is COMPLETED until the customer logs into PayPal and confirms
that he or she wants to create the account. The returned account key can be used to retrieve the
end user license agreement (EULA) associated with the account.
Adaptive Accounts Developer Guide
May 2012
41
3
CreateAccount API Operation
CreateAccount Errors
2009-09-03T15:19:12.281-07:00
Success
15bdd53cd4264
1033575
AA-6H279897NK391145S
COMPLETED
https://...?cmd=_hosteduaflow&encrypted_second_auth_code=AwBJzCt4b8SLUn2KMiPrYa08vABRRSnCo61W3uM
lletaKWCP9XWs3WcXvnEzSlDHVa4&encrypted_id=U4HE2K5TWLXQN&return_url=
http://www.myhome.com
CreateAccount Errors
42
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 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
May 2012
Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Errors
Code
Message
580022
Invalid request parameter:
accountType
address
averageMonthlyVolume
averagePrice
city
countryCode
line1
line2
state
postalCode
state
businessStakeholder
businessSubtype
businessType
category
citizenshipCountryCode
city
commercialRegistrationLocation
companyId
contactPhoneNumber
currencyCode
customerServiceEmail
customerServicePhone
dateOfBirth
dateOfEstablishment
Account already exists for the specified email address
emailAddress
establishmentCountryCode
establishmentState
firstName
Interest Tax Id already exists
ipAddress
lastName
percentageRevenueFromOnline
preferredLanguageCode
returnUrl
salesVenue
salutation
sandboxEmailAddress
role
subCategory
vatId
website
workPhone
Adaptive Accounts Developer Guide
3
Additional Information
May 2012
43
3
44
CreateAccount API Operation
CreateAccount Errors
Code
Message
Additional Information
580023
The argument is inconsistent with the rest of the request
580027
The parameter is not supported
580029
A required parameter is missing from the request:
postalCode
state
businessStakeholder
city
countryCode
firstName
incorporationId
lastName
line1
postalCode
salesVenueDesc
state
mobilePhoneNumber
May 2012
Adaptive Accounts Developer Guide
4
AddBankAccount API Operation
The AddBankAccount API operation lets your application set up bank accounts as funding
sources for PayPal accounts.
AddBankAccount Request
Adaptive Accounts Developer Guide
May 2012
45
4
AddBankAccount API Operation
AddBankAccount Request
AddBankAccount Request Fields
46
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.
May 2012
Adaptive Accounts Developer Guide
AddBankAccount API Operation
AddBankAccount Request
Field
Description
confirmationType
aa:ConfirmationType
(Required) Whether PayPal account holders are redirected to PayPal.com to
confirm the payment card addition. When you pass NONE for this element, the
addition is made without the account holder’s explicit confirmation. If you pass
WEB, a URL is returned.
Allowable string values are:
WEB
NONE
NOTE:
ConfirmationType NONE requires advanced permission levels. You
must pass the createAccount key.
controlDigit
xs:string
(Optional) The control digits for the bank.
emailAddress
xs:string
(Optional) The email address for the PayPal account. You must specify either
the accountId or emailAddress for this request.
iban
xs:string
(Optional) The IBAN for the bank.
institionNumber
xs:string
(Optional) The institution number for the bank.
partnerInfo
xs:string
(Optional) The partner information for the bank.
requestEnvelope
common:RequestEnvelope
(Required) Information common to each API operation, such as the language in
which an error message is returned.
ribkey
xs:string
(Optional) The RIB key for the bank.
routingNumber
xs:string
(Optional) The bank’s routing number.
sortCode
xs:string
(Optional) The branch sort code.
taxIdType
xs:string
(Optional) Tax id type of CNPJ or CPF, only supported for Brazil.
taxIdNumber
xs:string
(Optional) Tax id number for Brazil.
webOptionsType
aa:WebOptionsType
(Optional) Additional structure to define the URLs for the cancellation and
return web flows.
Adaptive Accounts Developer Guide
4
May 2012
47
4
AddBankAccount API Operation
AddBankAccount Response
WebOptionsType Fields
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.
RequestEnvelope 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
AddBankAccount Response
48
May 2012
Adaptive Accounts Developer Guide
AddBankAccount API Operation
AddBankAccount Response
4
AddBankAccount Response Fields
Field
Definition
execStatus
xs:string
Execution status for the request. Possible values are:
COMPLETED
CREATED
CREATED PENDING VERIFICATION
fundingSourceKey
xs:string
The key for the funding source to use in subsequent Adaptive Accounts API
request messages.
redirectURL
xs:string
The URL to direct the PayPal account holder to redirection after the Add Bank
Account web flow is completed.
responseEnvelope
common:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
ResponseEnvelope Fields
Field
Description
ack
common:AckCode
Acknowledgment code. Possible values are:
Success – Operation completed successfully
Failure – Operation failed
Warning – warning
SuccessWithWarning – Operation completed successfully; however,
there is a warning message
FailureWithWarning – Operation failed with a warning message
build
Build number; used only by Developer Technical Support.
correlationId
Correlation ID; used only by Developer Technical Support.
timestamp
The date on which the response was sent. The time is not supported.
Adaptive Accounts Developer Guide
May 2012
49
4
AddBankAccount API Operation
AddBankAccount Errors
AddBankAccount Errors
50
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 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.
May 2012
Adaptive Accounts Developer Guide
5
AddPaymentCard API Operation
The AddPaymentCard API operation lets your application set up credit cards as funding
sources for PayPal accounts.
AddPaymentCard Request
Adaptive Accounts Developer Guide
May 2012
51
5
AddPaymentCard API Operation
AddPaymentCard Request
AddPaymentCard Request Fields
Field
Description
accountId
xs:string
(Optional) The identification number of the PayPal account for which a
payment card is added. You must specify either the accountId or
emailAddress for this request.
billingAddress
aa:AddressType
(Optional) The element AddressType. See “AddressType Fields” on page 33.
cardNumber
xs:string
(Required) The credit card number.
cardOwnerDateOfBirth
xs:date
(Optional) The date of birth of the card holder.
cardType
aa:CardTypeType
(Required) The type of card to be added. Allowable values are:
Visa
MasterCard
AmericanExpress
Discover
SwitchMaestro
Solo
CarteAurore
CarteBleue
Cofinoga
4etoiles
CarteAura
TarjetaAurora
JCB
cardVerificationNumber
xs:string
The verification code for the card. This parameter is generally required for calls
where confirmationType is set to NONE. With the appropriate account
review, this parameter can be optional.
confirmationType
aa:ConfirmationType
(Required) Whether PayPal account holders are redirected to PayPal.com to
confirm the payment card addition. When you pass NONE for this element, the
addition is made without the account holder’s explicit confirmation. If you pass
WEB, a URL is returned.
Allowable string values are:
WEB
NONE
NOTE:
52
ConfirmationType NONE requires advanced permission levels. You
must pass the createAccount key and the cardVerificationNumber.
May 2012
Adaptive Accounts Developer Guide
AddPaymentCard API Operation
AddPaymentCard Request
Field
Description
createAccountKey
xs:string
The createaccount key returned in the CreateAccount response. This
parameter is required for calls where the confirmationType is set to NONE.
emailAddress
xs:string
(Optional) The email address for the PayPal account. You must specify either
the accountId or emailAddress for this request.
expirationDate
aa:CardDateType
(Optional) The element containing the expiration date for the payment card.
issueNumber
xs:string
(Optional) The 2-digit issue number for Switch, Maestro, and Solo cards.
nameOnCard
aa:Nametype
(Required) The element containing the name of the card holder.
requestEnvelope
common:RequestEnvelope
(Required) Information common to each API operation, such as the language in
which an error message is returned.
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.
5
AddressType Fields
Field
Description
line1
xs:string
(Required) The street address.
line2
xs:string
(Optional) The second line of the address.
N O TE :
This field is required for Brazilian addresses.
city
xs:string
(Required) The city.
state
xs:string
(Optional) The state code.
postalCode
xs:string
(Optional) The zip or postal code.
Adaptive Accounts Developer Guide
May 2012
53
5
AddPaymentCard API Operation
AddPaymentCard Request
Field
Description
countryCode
xs:string
(Required) The country code. For allowable values, refer to “Country Codes”
on page 69.
NameType Fields
Field
Description
salutation
xs:string
(Optional) A salutation for the account or payment card holder.
firstName
xs:string
(Required) First name of the account or payment card holder.
middleName
xs:string
(Optional) Middle name of the account or payment card holder.
lastName
xs:string
(Required) Last name of the account or payment card holder.
suffix
xs:string
(Optional) A suffix for the account or payment card holder.
CardDateType Fields
Field
Description
month
xs:integer
(Optional) The month of expiration.
year
xs:integer
(Required) The year of expiration.
RequestEnvelope Fields
54
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)
May 2012
Adaptive Accounts Developer Guide
AddPaymentCard API Operation
AddPaymentCard Response
Field
Description
errorLanguage
xs:string
(Required) The RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported
5
AddPaymentCard Response
AddPaymentCard Response Fields
Field
Definition
execStatus
xs:string
Execution status for the request. Possible values are:
COMPLETED
CREATED
CREATED PENDING VERIFICATION
fundingSourceKey
xs:string
The funding source key returned by the AddBankAccount response.
redirectURL
xs:string
The URL to send the PayPal account holder to after the AddPaymentCard web
flow is completed.
responseEnvelope
common:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status. See “ResponseEnvelope Fields” on page 40
Adaptive Accounts Developer Guide
May 2012
55
5
AddPaymentCard API Operation
AddPaymentCard Errors
ResponseEnvelope Fields
Field
Description
ack
common:AckCode
Acknowledgment code. Possible values are:
Success – Operation completed successfully
Failure – Operation failed
Warning – warning
SuccessWithWarning – Operation completed successfully; however,
there is a warning message
FailureWithWarning – Operation failed with a warning message
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.
AddPaymentCard Errors
56
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 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
May 2012
Adaptive Accounts Developer Guide
AddPaymentCard API Operation
AddPaymentCard Errors
Variable
Description
580022
Request parameter is invalid:
Invalid request parameter: billingAddress
Invalid request parameter: line1
Invalid request parameter: line2
Invalid request parameter: city
Invalid request parameter: state
Invalid request parameter: postalCode
Invalid request parameters: city, state, postalCode
Invalid request parameter: startDate
Invalid request parameter: cardType
Address for UPS cannot be a PO Box
Invalid request parameter: accountId
Invalid request parameter: cardOwnerDateOfBirth
Invalid request parameter: cardNumber
Invalid request parameter: expirationDate
Invalid request parameter: cardVerificationNumber
Expired createAccountKey
Invalid request parameter: PA_Replaceable_Value
Invalid request parameter: createAccountKey
Invalid request parameter: ipAddress
580023
The argument is inconsistent with the rest of the request
Country of billing address must match country of account holder address
Account associated with createAccountKey is different from the one
provided in the request
580027
The parameter is not supported
Prohibited request parameter: PA_Replaceable_Value
The parameter is not supported
580029
Required parameter is missing in the request:
Missing required request parameter: firstName
Missing required request parameter: lastName
Missing required request parameter: line1
Missing required request parameter: city
Missing required request parameter: state
Missing required request parameter: postalCode
Missing required request parameter: countryCode
Missing required request parameter: billingAddress
Missing required request parameter: line2
Missing required request parameter: cardVerificationNumber
Missing required request parameter: createAccountKey
Missing required request parameter: PA_Replaceable_Value
Adaptive Accounts Developer Guide
May 2012
5
57
5
58
AddPaymentCard API Operation
AddPaymentCard Errors
May 2012
Adaptive Accounts Developer Guide
6
SetFundingSourceConfirmed API
Operation
The SetFundingSourceConfirmed API operation allows your application to mark a
funding source as confirmed, after it is added successfully with AddPaymentCard or
AddBankAccount.
SetFundingSourceConfirmed Request
SetFundingSourceConfirmed Request Fields
Field
Description
accountId
xs:string
(Optional) The merchant account Id of the PayPal account to which the funding
source was added in the AddPaymentCard or AddBankAccount request. You
must specify either the accountId or mailAddress when making this
request, but never both in the same request.
emailAddress
xs:string
(Optional) The email address of the PayPal account to which the funding source
was added in the AddPaymentCard or AddBankAccount request. You must
specify either the accountId or mailAddress when making this request, but
never both in the same request.
fundingSourceKey
xs:string
The funding source key returned in the AddBankAccount or AddPaymentCard
response.
requestEnvelope
common:RequestEnvelope
(Required) Information common to each API operation, such as the language in
which an error message is returned.
Adaptive Accounts Developer Guide
May 2012
59
6
SetFundingSourceConfirmed API Operation
SetFundingSourceConfirmed Response
RequestEnvelope 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
SetFundingSourceConfirmed Response
ResponseEnvelope Fields
60
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.
May 2012
Adaptive Accounts Developer Guide
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 header is missing from the HTTP request.
580001
Invalid request:
PayPal account specified in the request is locked
PayPal account specified in the request is closed
Operation is not supported: PA_Replaceable_Value
Invalid request: PA_Replaceable_Value
580022
Request parameter is invalid:
Expired createAccountKey
Invalid request parameter: PA_Replaceable_Value
Invalid request parameter: createAccountKey
Invalid request parameter: ipAddress
580023
The argument is inconsistent with the rest of the request
Account cannot be confirmed with the request parameter provided
Account associated with createAccountKey is different from the one
provided in the request
580027
The parameter is not supported.
Adaptive Accounts Developer Guide
May 2012
61
6
62
SetFundingSourceConfirmed API Operation
SetFundingSourceConfirmed Errors
May 2012
Adaptive Accounts Developer Guide
7
GetVerifiedStatus 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.
Adaptive Accounts Developer Guide
May 2012
63
7
GetVerifiedStatus API Operation
GetVerifiedStatus Request
Field
Description
matchCriteria
xs:string
(Required) The criteria that must be matched in addition to emailAddress.
Currently, only NAME is supported.
Allowable string values are:
NAME
NONE
NOTE:
requestEnvelope
To use ConfirmationType NONE you must request and be granted
advanced permission levels.
common:RequestEnvelope
(Required) Information common to each API operation, such as the language in
which an error message is returned.
RequestEnvelope Fields
64
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
May 2012
Adaptive Accounts Developer Guide
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:
userInfoType
Adaptive Accounts Developer Guide
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.
aa:UserInfoType
This set of data includes unique account identifiers.
May 2012
65
7
GetVerifiedStatus API Operation
GetVerifiedStatus Response
ResponseEnvelope Fields
Field
Description
ack
common:AckCode
Acknowledgment code. Possible values are:
Success – Operation completed successfully
Failure – Operation failed
Warning – warning
SuccessWithWarning – Operation completed successfully; however,
there is a warning message
FailureWithWarning – Operation failed with a warning message
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.
UserInfoType Fields
Field
Description
accountType
xs:string
(Required) The type of account. Allowable values are:
Personal – Personal account
Premier – Premier account
Business – Business account
name
aa:NameType
(Required) The name of the person for whom the PayPal account is created.
businessName
Business name of the PayPal account holder.
accountId
Identifies the PayPal account.
N O TE :
emailAddress
xs:string
(Required)Email address associated with the PayPal account: one of the
unique identifiers for the account.
N O TE :
66
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.
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.
May 2012
Adaptive Accounts Developer Guide
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 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: .
580023
Cannot determine PayPal account status
580022
Invalid request parameter:
580023
Invalid Request.
580029
Missing required request parameter:
Adaptive Accounts Developer Guide
May 2012
67
7
68
GetVerifiedStatus API Operation
GetVerifiedStatus Errors
May 2012
Adaptive Accounts Developer Guide
A
Country Codes
Below are the country codes for Adaptive Accounts. Countries marked with an asterisk ( * ) are not
supported for PayPal Payments Pro and Virtual Terminal.
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 *
Adaptive Accounts Developer Guide
May 2012
69
A
70
Country Codes
Country or Region
Country or Region Code
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
May 2012
Adaptive Accounts Developer Guide
Country Codes
Country or Region
Country or Region Code
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
Adaptive Accounts Developer Guide
May 2012
A
71
A
72
Country Codes
Country or Region
Country or Region Code
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
May 2012
Adaptive Accounts Developer Guide
Country Codes
Country or Region
Country or Region Code
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
Adaptive Accounts Developer Guide
May 2012
A
73
A
74
Country Codes
Country or Region
Country or Region Code
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
May 2012
Adaptive Accounts Developer Guide
Country Codes
Country or Region
Country or Region Code
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
Adaptive Accounts Developer Guide
May 2012
A
75
A
76
Country Codes
May 2012
Adaptive Accounts Developer Guide
B
Business 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
Adaptive Accounts Developer Guide
May 2012
77
B
Business Categories and Subcategories
Category
Description
1024
Vehicle sales
1025
Vehicle service and accessories
Subcategories
78
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
May 2012
Adaptive Accounts Developer Guide
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
Adaptive Accounts Developer Guide
May 2012
B
79
B
80
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
May 2012
Adaptive Accounts Developer Guide
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
Adaptive Accounts Developer Guide
May 2012
B
81
B
82
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
May 2012
Adaptive Accounts Developer Guide
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
Adaptive Accounts Developer Guide
May 2012
B
83
B
84
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
May 2012
Adaptive Accounts Developer Guide
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
Adaptive Accounts Developer Guide
May 2012
B
85
B
86
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
May 2012
Adaptive Accounts Developer Guide
Business Categories and Subcategories
Subcategory
Description
Category
Merchant Category
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
Adaptive Accounts Developer Guide
May 2012
B
87
B
88
Business Categories and Subcategories
May 2012
Adaptive Accounts Developer Guide
C
Adaptive Accounts IPN Messages
PayPal sends an IPN message whenever a PayPal account is created using the
CreateAccount API operation.
Field
Description
notify_version
Message’s version number
first_name
Account holder’s first name
last_name
Account holder’s 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.
Example IPN message in response to CreateAccount request
notify_version=UNVERSIONED&first_name=Someone&verify_sign=AI.LzRiNYreJbZLZ8
BV5FbGKL8hSAupAtXf3haOHWI2NmcJ5C4VqdQrx&charset=windows1252&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=AA6N5043354R131103K¬ify_version=UNVERSIONED&charset=windows1252&email_address=abawany-2011020801%40paypal.com&event_type=%5BACCOUNT_CONFIRMED%5D&last_name=Something&veri
fy_sign=AcIPKnsgPsoX2ONJgU17uAl9h-ZIAKJMRvhEULLvD9mOzH3WjdRNfEte
Adaptive Accounts Developer Guide
May 2012
89
C
Adaptive Accounts IPN Messages
NOT E :
This message indicates that the account setup is complete.
Example IPN message in response to account login
first_name=Someone&account_key=AA6N5043354R131103K¬ify_version=UNVERSIONED&charset=windows1252&email_address=abawany-2011020801%40paypal.com&event_type=%5BLOGIN_CONFIRMED%5D&last_name=Something&verify
_sign=ANqF6tuR41eB.S.2I9dCskJuSSvrAI8Monbec4U2PZCnoKYffnv156mN
90
May 2012
Adaptive Accounts Developer Guide
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 Accounts Developer Guide
May 2012
91
Adaptive Account Changes Corresponding to PayPal Version 69.0
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
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 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.
NOT E :
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:
92
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.
May 2012
Adaptive Accounts Developer Guide
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-PAYPALMERCHANT-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 Accounts Developer Guide
May 2012
93
Adaptive Account Changes Corresponding to PayPal Version 62.2
94
May 2012
Adaptive Accounts Developer Guide
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.
Adaptive Accounts Developer Guide
May 2012
95
96
May 2012
Adaptive Accounts Developer Guide
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
Adaptive Accounts Developer Guide
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
May 2012
97
Index
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
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
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
98
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
May 2012
Adaptive Accounts Developer Guide
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
Adaptive Accounts Developer Guide
May 2012
99
Index
100
May 2012
Adaptive Accounts Developer Guide
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Author : PayPal, Inc. Create Date : 2012:04:30 17:51:52Z Modify Date : 2012:08:01 15:49:26-07:00 Has XFA : No XMP Toolkit : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26 Format : application/pdf Title : PayPal Adaptive Accounts Developer Guide Creator : PayPal, Inc. Creator Tool : FrameMaker 9.0 Metadata Date : 2012:08:01 15:49:26-07:00 Producer : Acrobat Distiller 10.1.3 (Windows) Document ID : uuid:e3a8b9e5-2bd5-4531-8f70-4894b3a30cf6 Instance ID : uuid:e5aebc21-1239-45ae-88ef-83feb2b0249e Page Mode : UseOutlines Page Count : 100EXIF Metadata provided by EXIF.tools