PayPal Adaptive Accounts - 2012 Developer's Guide
Adaptive Accounts
Developer Guide
Last updated: May 2012
PayPal Adaptive Accounts Developer Guide
Document Number: 10109.en_US-201205
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
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
Introducing Adaptive Accounts
1
The Adaptive Accounts API lets you build applications that create PayPal accounts and handle
account management.
Adaptive Accounts Scenarios
The Adaptive Accounts API enables your application to create and verify PayPal accounts.
You can also add bank accounts to link to PayPal accounts as funding sources.
Consider the following examples. You might create a PayPal account using the Adaptive
Accounts APIs as part of the set up for a:
marketplace. You can offer PayPal as a payment option and create PayPal accounts for
your users that do not already have them. Your users can include buyers and suppliers or
clients and services providers as senders and receivers in various countries.
social networking application, such as one that “pays for lunch” or sends a payment for any
reason. Your application may not be directly involved in the payment; however, you can
enable the payment by ensuring that the user has the opportunity to create a PayPal
account.
enterprise application, such as a payroll application for small-to-medium sized businesses.
You can create PayPal accounts for each employee that does not have one and pay all
employees using PayPal’s Mass Pay or Adaptive Payments capabilities.
store checkout flow. You might provide PayPal account creation for your customers or you
might provide account creation for someone else’s customers as part of a shopping cart
service.
Creating an Account
PayPal account holders traditionally create their PayPal accounts by going directly to
PayPal.com or signing up during a checkout flow. The Adaptive Accounts CreateAccount
method offers a new way: Creating accounts within your application or website, outside the
checkout flow.
Your application sends a request using the CreateAccount method with information
gathered from your website, and PayPal creates the account. At this point, the new PayPal
account holder is briefly redirected to PayPal.com to enter private information, such as a
password, and to accept the PayPal User Agreement. PayPal then returns the new account
Adaptive Accounts Developer Guide May 2012 11
Introducing Adaptive Accounts
1
Adding Bank Accounts as Funding Sources
holder to your website. This greatly reduces the chances of losing customers during the
account creation flow.
That brings us to the key benefit of Adaptive Accounts: A streamlined account creation and
completion process. Research shows that removing barriers from account creation and
payment experience increases conversion and improves customer satisfaction.
Imagine the possibilities: With the CreateA ccount method, shopping cart application could
create PayPal Business accounts for its merchants directly from the shopping cart site.
Adding Bank Accounts as Funding Sources
In addition to creating and verifying PayPal accounts, Adaptive Accounts lets your application
link bank accounts to PayPal accounts as funding sources. Traditionally, PayPal account
holders do this manually at PayPal.com. With the AddBankAccount method, you can now
offer your customers the benefit of a smooth, uninterrupted process where PayPal account
creation includes adding a funding source for the account, all in one fell swoop. If you are a
financial institution, you can offer customers who are also PayPal account holders an easy way
to link the bank account with your institution as a funding source for their PayPal accounts.
How does it work? Your application sends an AddBankAccount request, passing the relevant
bank account information, such as the account number and routing number. The PayPal
account holder is redirected briefly to PayPal.com to confirm the information, then returns to
your customer’s website.
Adding Payment Cards as Funding Sources
Adaptive Accounts lets your application link the created PayPal account to a credit card or
payment card. This card can then be used as a funding source (payment method) for the PayPal
account. To use this feature, you use the createAccount key from the CreateAccount
response and pass it with the AddPaymentCard method together with pertinent payment card
information.
For standard permissions, the AddPaymentCard method requires the PayPal account user to
confirm the payment card addition on paypal.com. Developers with advanced permissions can
pass the AddPaymentCard with the confirmedType element (set to NONE) to add payment
cards without redirecting to paypal.com.
Supported payment cards are:
Visa
MasterCard
American Express
Discover
Maestro
12 May 2012 Adaptive Accounts Developer Guide
Set Funding Sources to Confirmed Status
Solo
Carte Aurore
Carte Bleue
Cofinoga
4 étoiles
Carte Aura
Tarjeta Aurora
JCB
Set Funding Sources to Confirmed Status
If you call the AddBankAccount or AddPaymentCard methods, you can use the
SetFundingSourceConfirmed method to set the created funding source to “confirmed”. In
certain instances, this will cause the PayPal account status to be set to Verified.
Introducing Adaptive Accounts
1
Verifying the Status of a PayPal Account
A huge challenge that merchants face today is fraud. The GetVerifiedStatus method is a
great way to help PayPal merchants reduce the loss of profits due to fraud.
It works like this: Before a PayPal merchant engages in a transaction, the application sends a
GetVerifiedStatus request. This request contains specific criteria you want to match, such
as the PayPal account holder’s email address. The Adaptive Accounts web service responds
with a message that indicates if the match was verified. This provides an effective method of
reducing fraud. With the GetVerifiedStatus method, merchants have the security of
knowing that consumers’ PayPal accounts are verified before completing a transaction.
Account Creation Flow
For account creation on the web, call CreateAccount and use the redirect URL to direct the
person’s browser to PayPal. After the person creates an account, the browser is redirected to
the return URL you specified in the CreateAccount request.
The following diagram shows the basic flow of control for account creation on the web:
Adaptive Accounts Developer Guide May 2012 13
Introducing Adaptive Accounts
1
Account Creation Flow
The following items correspond to the circled numbers in the diagram:
1. Your site or device sends a CreateAccount request to PayPal on behalf of a potential
account holder.
2. PayPal responds with a key and a URL, named the redirectURL, that you use when you
direct the person to PayPal.
3. You include the key and redirect your person’s browser to PayPal using the
redirectURL.
After the person logs on to PayPal and completes the account setup, the person is prompted to
return to the URL.
Account Creation Using a Minibrowser
PayPal can enable your customer to create an account using a minibrowser flow. Set
CreateAccountRequest.CreateAccountWebOptio nsType.useMinibrowser to
true in the CreateAccount request message to specify this flow.
NOTE: You must use Version 1.0.1 or higher of the Adaptive Accounts WSDL to implement
this flow.
When you redirect your customer’s browser to the URL in the CreateAccount response
message, PayPal responds with the following:
14 May 2012 Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
1
Your customer enters the password twice and clicks Agree and Continue to create the
account.
NOTE: By default, redirecting the browser to the returned URL opens the page in a default
browser window. You must provide JavaScripts to pop-up the window in a
minibrowser or to display it in a lightbox within your browser window.
Adding a Credit Card in the Minibrowser Account Creation Flow
PayPal can require your customer to add a credit card using a minibrowser flow. Set
CreateAccountRequest.CreateAccountWebOptio nsType.showAddCreditCard to
true in the CreateAccount request message to add a credit card during this flow.
After the customer specifies the password and agrees to create the account, PayPal responds
with the following page in a minibrowser:
Adaptive Accounts Developer Guide May 2012 15
Introducing Adaptive Accounts
1
Account Creation Flow
Your customer enters debit or credit card information and clicks Add Card and Continue.
NOTE: Your customer can enter a phone number and associate a billing address, or add a new
address from the Billing address drop-down menu:
16 May 2012 Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
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.CreateAccountWebOptio nsType.showMobileConfirm to
true in the CreateAccount request message to enable account creation using a mobile
phone during this flow.
After adding a debit or credit card, PayPal responds with the following page in a minibrowser:
Adaptive Accounts Developer Guide May 2012 17
Introducing Adaptive Accounts
1
Account Creation Flow
Your customer requests a confirmation code by clicking Send SMS, and then clicks Confirm
Phone after entering the code in the SMS message.
NOTE: The phone number to confirm is the number associated with a debit or credit card for
the account, which you set on the Link a debit or credit card page. You cannot
change the phone number.
Default Account Creation From the Web
To enable your customer to create a PayPal account, you call the CreateAccout API
operation and use the returned URL to redirect your customer’s browser to PayPal. Your
customer then signs up and agrees to the terms of the account.
18 May 2012 Adaptive Accounts Developer Guide
Introducing Adaptive Accounts
Account Creation Flow
By default, when you redirect your customer’s browser to the URL in the CreateAccount
response message, PayPal responds with the following sequence of pages:
1. The Welcome page identifies the information that will be needed to create an account:
1
2. The Cr eate PayPal account login screen requests your customer to submit a password and
security questions, with answers:
Adaptive Accounts Developer Guide May 2012 19
Introducing Adaptive Accounts
1
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
1
NOTE: The account holder can add a credit or debit card now or click Cancel to continue
without adding a card.
4. After the person logs on to PayPal and completes the account setup, the person is prompted
to return to the URL.
Adaptive Accounts Developer Guide May 2012 21
Introducing Adaptive Accounts
1
Account Creation Flow
22 May 2012 Adaptive Accounts Developer Guide
Supported Formats, URLs and
2
HTTP Request Headers
Adaptive Accounts Methods
Adaptive Accounts provides the following methods:
API Operation Description
CreateAccount Creates PayPal accounts.
AddBankAccount Link bank accounts to PayPal accounts as funding sources.
AddPaymentCard Link payment cards to PayPal accounts as funding sources
SetFundingSourceConfirmed Set the funding source to confirmed; they may set the account to PayPal
Verified status.
GetVerifiedStatus Verify PayPal accounts by matching account holder criteria such as the
account holder’s email address.
Adaptive Accounts URLs
The endpoint is determined by the method and the environment in which you want to execute
the API operation. For example, if you want to send a CreateAccount request to the
sandbox, specify the following URL:
https://svcs.sandbox.paypal.co m/AdaptiveAccounts /CreateAccount
You can specify the following URLs:
Environment Endpoint
Production
https://svcs.paypal.com/AdaptiveAccounts/API_operation
Sandbox
https://svcs.sandbox.paypal.com/AdaptiveAccounts/API_operation
Adaptive Accounts Developer Guide May 2012 23
Supported Formats, URLs and HTTP Request Headers
2
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
JSO N – JavaScript object notation
X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSO N – JavaScript object notation
Optional HTTP Request Headers
Header Description
X-PAYPAL-SANDBOX-EMAIL-ADDRESS The email address that the API caller uses to log into the
sandbox or beta sandbox; not required outside of the
sandbox.
24 May 2012 Adaptive Accounts Developer Guide
Supported Formats, URLs and HTTP Request Headers
HTTP Request Headers
Header Description
X-PAYPAL-DEVICE-ID Client’s device ID, such as a mobile device’s IMEI number.
This field is required for mobile application and is not used
for web application.
X-PAYPAL-MERCHANT-REFERRAL-BONU S-ID When creating a Business or Premier account, this header
enables the Merchant Referral Bonus invitation.
X-PAYPAL-SERVICE-VERSION The version of an API operation to use. By default, PayPal
executes a request with the current version of an API
operation.
NOTE: PayPal recommends not specifying a version unless
it is absolutely required.
2
Adaptive Accounts Developer Guide May 2012 25
Supported Formats, URLs and HTTP Request Headers
2
HTTP Request Headers
26 May 2012 Adaptive Accounts Developer Guide
CreateAccount API Operation
3
The CreateAccount API operation enables you to create a PayPal account on behalf of a
third party.
CreateAccount Request
The CreateAccountRequest contains the information required to create a PayPal account
for a business customer.
Adaptive Accounts Developer Guide May 2012 27
CreateAccount API Operation
3
CreateAccount Request
28 May 2012 Adaptive Accounts Developer Guide
CreateAccount API Operation
CreateAccount Request
3
Adaptive Accounts Developer Guide May 2012 29
CreateAccount API Operation
3
CreateAccount Request
CreateAccount Request Fields
Field Description
accountType xs:string
(Required) The type of account to be created. Allowable values are:
Pe rsonal – Personal account
Pr emier – Premier account
Bu siness – Business account
address aa:Ad dressType
(Required) The address to be associated with the PayPal account.
businessInfo aa:BusinessInfoTyp e
This field is required for business account creation.
citizenshipCountryCode xs:string
(Required) The code of the country to be associated with the account. For
allowable values, refer to “Country Codes” on page 69.
clientDetails Do not use this field.
contactPhoneNumber xs:string
(Required) Phone number to be associated with the account.
homePhoneNumber xs:string
(Optional) Home phone number to be associated with the account.
30 May 2012 Adaptive Accounts Developer Guide
Loading...