CreateAccount API Operation

Creates a PayPal account on behalf of the specified third party. The account can be a personal account, premier account, or business account.

CreateAccount Request

The CreateAccount request supplies all the information the Adaptive Accounts service needs to create a PayPal account on behalf of a third party.

CreateAccount Request Fields

Field Description
accountType xs:string
(Required) The type of account to create. Allowed values:
  • Personal - Personal account
  • Premier - Premier account
  • Business - Business account
address aa:AddressType
(Required) A structure containing the address of the holder of the new PayPal account. See AddressType Fields for details.
businessInfo aa:BusinessInfoType
(Required if creating a business account) A structure containing information needed to create a business account. See BusinessInfoType Fields for details.
citizenshipCountryCode xs:string
(Required) Code identifying the country of citizenship of the holder of the new account. See Country Codes for allowed values.
clientDetails Do not use this field.
contactPhoneNumber xs:string
(Required) Contact phone number of the holder of the new account.
governmentId aa:GovernmentIDPair
(Optional) Account holder's ID for a unique value, such as SSN, TIN, SIN, TaxID, or other ID of this kind. Generally, this value is issued by a government. Currently, only SIN, for Canada, is supported. This value is specified as an aa:GovernmentIDPair type.
homePhoneNumber xs:string
(Optional) Home phone number of the holder of the new account.
mobilePhoneNumber xs:string
(Optional) Mobile phone number of the holder of the new account.
Note: You must pass a value for this parameter in order to use the "mobile confirmation" option.
createAccountWebOptions aa:CreateAccountWebOptionsType
(Required) A structure containing web options that pertain to account creation. See CreateAccountWebOptionsType Fields for details.
currencyCode xs:string
(Required) Three-letter code identifying the currency to assign to the new account.
dateOfBirth xs:date
(Required for Brazil, Japan, New Zealand, Israel, Switzerland, and Australia; optional for other countries) Date of birth of the holder of the new PayPal account. Use YYYY-MM-DDZ format, e.g., 1970-01-01Z.
emailAddress xs:string
(Required) Email address of the holder of the new PayPal account.
functionalArea xs:string
(Optional) Account holder's functional area, meaning the account holder's department. For business accounts only. Values: Finance, Operations, Technology, Sales, Marketing, Other.
legalAgreement LegalAgreementType
(Optional) Indicates whether or not account holder has agreed to a particular agreement.
name aa:NameType
(Required) Name of the holder of the new PayPal account. See NameType Fields for details.
notificationURL xs:string
(Optional) The URL to which to post instant payment notification (IPN) messages pertaining to account creation. This URL overrides the IPN notification URL in a merchant's profile.
Maximum string length: Between 1 and 1024 characters of the pattern <[a-aZ-Z]+\://){1}\S+
occupation xs:string
(Optional) Account holder's occupation. In this case, occupation means level within a profession. For business accounts only. Values: Executive, President, Vice President, Director, Manager, Staff, Other.
partnerFieldn xs:string
(Optional) A maximum of five fields for your own use, where n is a digit between 1 and 5, inclusive.
performExtraVettingOnthisAccount xs:boolean
(Optional) Determines whether PayPal subjects the new account to extra vetting before allowing it to be used.
  • true - PayPal will perform extra vetting
  • false - PayPal will not perform extra vetting
purposeOfAccount xs:string
(Optional) Specifies how the account is used. The eexpected value is one of the following values: 0, 1, 2, 3, 4, or 5, each of which represents an expected account purpose, as follows:
0 - "Send payments for goods and/or services to domestic merchants"
1 - "Send payments for goods and/or services to cross-border merchants"
2 - "Send payments for goods and/or services to domestic and cross-border merchants"
3 - "Receive payments for goods and/or services from domestic buyers"
4 - "Receive payments for goods and/or services from cross-border buyers"
5 - "Receive payments for goods and/or service from domestic/cross-border buyers"
profession xs:string
(Optional) Account holder's profession. Example values: Accountant, Actuary, Advocate, Architect, Business Owner, Doctor, Dentist, Engineer, Financial Analyst, Lawyer, Librarian, Nurse, Pilot, Pharmacist, Physician, Physicial Therapist, Professor, Psychologist, Scientist, Teacher, Webmaster, Writer, Student, Other
taxId xs:string
(Optional) Tax Id (Equivalent to SSN in the US.)
Note: This field is required only if creating a Premier Brazilian account, because Brazil uses tax ID numbers, such as the CPF.
preferredLanguageCode xs:string
(Required) Code identifying the preferred language to assign to the new account. The particular value allowed depends on the country code passed for the countryCode parameter in the address structure. See Locale Codes for full list of allowed values. Example values:
  • Argentina (AR) - es_XC
  • Australia (AU) - en_AU
  • Austria (AT) - de_DE
  • Brazil (BR) - pt_BR
  • Canada (CA) - en_US
  • China (CN) - en_US
  • Czech Republic (CZ) - en_US
  • Denmark (DK) - en_US
  • France (FR) - fr_FR
  • Germany (DE) - de_DE
  • Israel (IL) - 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) - ru_RU
  • Spain (ES) - es_ES
  • Switzerland (CH) - de_DE
  • Sweden (SE) - sv_SE
  • United Kingdom (GB) - en_GB
  • United States (US) - en_US
registrationType

xs:string
(Required) Defines the type of account registration flow to use to complete account set up.

Allowed values:

  • Web - Return a redirect URL to use to initiate the web account registration flow.
    Your application redirects the account holder's browser to this URL, so he or she can finish setting up the new account.
  • Mobile - Return an account creation key to use to initiate the mobile device account registration flow.
    This key uniquely identifies the account just created. Your application passes this key to other Adaptive Accounts APIs that let the account holder finish setting up the account from a mobile device.
    Note: A create account key expires after 60 minutes. If you pass an expired key to an Adaptive Accounts API, an error is returned.
requestEnvelope common:RequestEnvelope
(Required) Information common to all API operations, such as the language in which an error message is returned. See RequestEnvelope Fields for details.
suppressWelcomeEmail xs:boolean
(Optional) Defines whether the PayPal welcome email is suppressed or sent.
  • true - Suppress the PayPal welcome email
  • false - Send the PayPal welcome email

AddressType Fields

Field Description
line1 xs:string
(Required) Street address.
line2 xs:string
(Optional) Second line of the address. Required for Brazilian accounts.
city xs:string
(Required) City name.
state xs:string
(Optional) State code. Required for some countries, including Brazil.
postalCode xs:string
(Optional) Zip or postal code. Required for some countries, including Brazil.
countryCode xs:string
(Required) Country code. See Country Codes for allowed values.

BusinessInfoType Fields

Field Description
averageMonthlyVolume xs:decimal
The average monthly transaction volume of the business for which the PayPal account is created. Required for all countries except Japan and Australia.
Important: Do not specify this field for Japan or Australia.
averagePrice xs:decimal
The average price per transaction. Required for all countries except Japan and Australia.
Important: Do not specify this field for Japan or Australia.
businessAddress aa:addressType
(Required) The address for the business for which the PayPal account is created.
businessEntityForThirdParty aa:BusinessEntityForThirdPartyType
(Optional) Use this container for a third party.
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. See BusinessStakeholderType Fields for details.
businessSubtype aa:businessSubtypeType
(Optional) The sub type of the business for which the PayPal account is created. Allowable values are:
  • ENTITY
  • EMANATION
  • ESTD_COMMONWEALTH
  • ESTD_UNDER_STATE_TERRITORY
  • ESTD_UNDER_FOREIGH_COUNTY
  • INCORPORATED
  • NON_INCORPORATED
businessType aa:businessType
(Required) The type of the business for which the PayPal account is created. Allowable values are:
  • CORPORATION
  • GOVERNMENT
  • INDIVIDUAL
  • NONPROFIT
  • PARTNERSHIP
  • PROPRIETORSHIP
Note: The WSDL lists additional business types, but the types above are the only ones currently supported.
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's Association Merchant Category Code documentation for a list of codes.
commercialRegistrationLocation xs:string
Official commercial registration location for the business for which the PayPal account is created. Required for Germany.
Important: Do not specify this field for other countries.
companyId xs:string
The identification number of the business for which the PayPal account is created. Equivalent to the tax ID in the United States.

Optional for business accounts in the United States, United Kingdom, France, Spain, Italy, Netherlands, Sweden, and Denmark. Required for business accounts in Canada and Brazil (for CNPJ information), and for some accounts in Australia, and Germany.

Important: Do not specify this field for other countries.
customerServiceEmail xs:string
(Required) The email address for the customer service department of the business.
customerServicePhone xs:string
The phone number for the customer service department of the business. Required for United States business accounts; otherwise, optional.
dateOfEstablishment xs:date
The date of establishment for the business. Optional for France business accounts and required for business accounts in the following countries: United States, United Kingdom, Canada, Germany, Spain, Italy, Netherlands, Czech Republic, Sweden, and Denmark.
Important: Do not specify this field for other countries.
disputeEmail xs:string
(Optional) The email address to contact to dispute charges.
doingBusinessAs xs:string
(Optional) The business name being used if it is not the actual name of the business.
establishmentCountryCode xs:string
(Optional) The code of the country where the business was established. See Country Codes for allowed values.
establishmentState xs:string
(Optional) The state in which the business was established.
hasBeneficialOwners aa:YesNoType
(Optional) Specify YES if the business has beneficial owners, otherwise NO.
hasDirectors aa:YesNoType
(Optional) Specify YES if the business has directors, otherwise NO.
hasThirdPartyAssociates aa:YesNoType
(Optional) Specify YES if the business has third party associates, otherwise NO.
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.
percentageRevenueFromOnline xs:integer
The percentage of online sales for the business from 0 through 100. Required for business accounts in the following countries: United States, Canada, United Kingdom, France, Czech Republic, New Zealand, Switzerland, and Israel.
Important: Do not specify this field for other countries.
principalPlaceOfBusinessAddress aa:AddressType
(Optional) The principle business address.
registeredOfficeAddress aa:AddressType
(Optional) The business address for the business registration.
salesVenue aa:salesVenueType
The venue type for sales. Required for business accounts in all countries except Czech Republic and Australia. Allowable values are:
  • WEB
  • EBAY
  • OTHER_MARKETPLACE
  • OTHER
  • Important: Do not specify this field for Czech Republic or Australia.
salesVenueDesc xs:string
A description of the sales venue. Required if salesVenue is OTHER for all countries except Czech Republic and Australia.
Important: Do not specify this field for Czech Republic or Australia.
subcategory xs:integer
The subcategory describing the business for which the PayPal account is created. Required unless you specify merchantCategoryCode. PayPal uses the industry standard Merchant Category Codes. Refer to the business' Association Merchant Category Code documentation for a list of codes.
vatCountryCode xs:string
The country for the VAT. Optional for business accounts in the following countries: United Kingdom, France, Germany, Spain, Italy, Netherlands, Switzerland, Sweden, and Denmark. See Country Codes for allowed values.
Important: Do not specify this field for other countries.
vatId xs:string
The VAT identification number of the business. Optional for business accounts in the following countries: United Kingdom, France, Germany, Spain, Italy, Netherlands, Switzerland, Sweden, and Denmark.
Important: Do not specify this field for other countries.
webSite xs:string
The URL for the website of the business in the following format: https://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.

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 YYYY-MM-DDZ format; for example 1970-01-01Z.
fullLegalName xs:string
(Optional) The legal name of the stakeholder in the business for which the PayPal account is created.
name aa:NameType
(Optional) The name of the stakeholder in the business for which the PayPal account is created. See NameType for details.
occupation xs:string
(Optional) Occupation, meaning profession, of a business stakeholder. Specify a value such as one of the following: Accountant, Actuary, Advocate, Architect, Business Owner, Doctor, Dentist, Engineer, Financial Analyst, Lawyer, Librarian, Nurse, Pilot, Pharmacist, Physician, Physicial Therapist, Professor, Psychologist, Scientist, Teacher, Webmaster, Writer, Student, Other.
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
Code identifying the country of the stakeholder. See Country Codes for allowed values.

BusinessEntityForThirdPartyType Fields

Field Description
thirdPartyType xs:string
(Optional) Either Individual or Business must be specified.
name aa:NameType
(Optional) If the third party is an individual, specify the name of the individual. If the third party is a business, specify the name of the business contact person.
dateOfBirth xs:date
(Optional) If the third party is an individual, specify the date of birth.
address aa:AddressType
(Optional) Address of the third party.
profession xs:string
(Optional) If the third party is an individual, the profession.
relationshipWithThirdParty xs:string
(Optional) The individual's or business's relationship with the third party.
natureOfBusiness xs:string
(Optional) If the third party is a business, the nature of the business.
nameOfBusiness xs:string
(Optional) If the third party is a business, the name of the business.
businessType xs:string
(Optional) If the third party is a business, specify one of these values: Corporation, Private Company, Public Company, Partnership, Government Entity, or Non-Profit Organization.
incorporationId xs:string
(Optional) If the third party is a business, specify the incorporation ID.
incorporationCountry xs:string
(Optional) If the third party is a business, specify the country of incorporation.
incorporationState xs:string
(Optional) If the third party is a business, specify the state of incorporation.

CreateAccountWebOptionsType Fields

Field Description
returnUrl xs:string
(Required) The URL to which you want the account holder to return when he or she finishes account registration. This URL appears as a link on the final page of the PayPal account registration flow. The text of this link is the text passed in the returnUrlDescription request parameter (below).
returnUrlDescription xs:string
(Optional) A description of the return URL.
showAddCreditCard xs:boolean
(Optional) Defines whether the "add credit card" option is included in the PayPal account registration flow.
  • true - Show the option (default)
  • false - Do not show the option
showMobileConfirm xs:boolean
(Optional) Defines whether the "mobile confirmation" option is included in the PayPal account registration flow.
  • true - Show the option
  • false - Do not show the option (default)
Note: The mobile confirmation option appears in the account registration flow only if you also passed a mobilePhoneNumber in the CreateAccount request.

Note: The mobile confirmation option is available in only these countries: Australia, Canada, Spain, France, United Kingdom, Italy, Malaysia, Singapore, and the United States.
usemini-browser xs:boolean
(Optional) Defines whether to use the mini-browser account registration flow or the traditional account registration flow.
  • true - Use the mini-browser flow
  • false - Use the traditional flow (default)
Note: If you pass true for usemini-browser, do not pass values for returnUrl or returnUrlDescription since the mini-browser flow does not use them.
reminderEmailFrequency

xs:string
(Optional) Defines whether the Adaptive Accounts-specific emails (its initial email, as well as its 30/60/90 day reminder emails) are sent once the account has been created.

Allowed values:

  • DEFAULT - Send the initial redirect email, as well as the 30/60/90 day reminder emails.
    Note that the same behavior results if this parameter is not passed.
  • NONE - Do not send either the initial redirect email or the 30/60/90 day reminder emails.
Note: Suppressing the Adaptive Account email messages works only if registrationType is Web.
Note: This field affects only email messages that Adaptive Accounts sends to get new account holders to set up their accounts. This flag does not affect other PayPal email messages.
confirmEmail

xs:string
(Optional) Defines whether the account holder's email address is automatically confirmed during the create account flow.

Allowed values:

  • true - Automatically confirm the account holder's email address during the create account flow.
    In this case, you should suppress the standard PayPal welcome email, since it requests email address confirmation, which has already been done. To suppress this message, pass true for suppressWelcomeEmail. Note that it's not an error, if an account holder re-confirms an email address.
  • false - Do not automatically confirm the account holder's email address confirmation during the create account flow (default).
    In this case, the account holder must manually confirm his or her email address via the PayPal welcome message or by logging into the new account.
Note: Automatic email address confirmation works only if registrationType is Web.
Note: Currently, the redirect URL in the initial Adaptive Accounts email to the account holder includes the email confirmation token, but the redirect URL in the subsequent reminder emails does not.
Note: Only select partners have permission to use the confirmEmail field.

GovernmentIDPair Fields

Field Description
value xs:string
(Optional) The actual value of the government ID.
type aa:GovernmentIDTypes
(Optional) The kind of government ID, e.g. SIN.

LegalAgreementType Fields

Field Description
accepted xs:string
(Optional) Whether the legal agreement has been accepted.
type aa:LegalAgreementTypes
(Optional) The kind of legal agreement, e.g. FINANCIAL_BINDING_AUTHORITY which indicates an agreement in which the account holder has the financial authority to bind the business to the agreement.

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.

RequestEnvelope Fields

Field Description
detailLevel

common:DetailLevelCode
The level of detail requested by the client application for various data components (for example, Item and Transaction).

Allowed values:

  • ReturnAll - Requests the maximum level of detail (default)
errorLanguage xs:string
The RFC 3066 language in which error messages are returned. By default, this language is en_US, which is the only language currently supported

CreateAccount Response

The CreateAccount response message contains values your application needs to allow the account holder to register the account just created. The response also includes status information.

CreateAccount Response Fields

Field Description
accountId xs:string
The ID of the new PayPal account. This value is returned only for Premier and Business accounts.
createAccountKey xs:string
A key that uniquely identifies the PayPal account just created. This key is returned if the registrationType request parameter was set to Mobile. Pass this key to other Adaptive Accounts APIs to enable the account holder to complete account registration from his or her mobile device.
execStatus xs:string
The status of the payment. Allowed values:
  • CREATED - Account creation is complete. No redirection is necessary to let the account holder finish setting up the account.
  • COMPLETED - The account creation request was successful, but the account holder must be redirected to finish setting up the account.
  • CREATED PENDING VERIFICATION - Account creation is complete, but the verification/approval process is not complete.
redirectURL xs:string
The URL to which to redirect the account holder so he or she can finish setting up the account. This URL is returned if the registrationType request parameter was set to Web. Use this URL to redirect the account holder to the web form of the account registration flow.
responseEnvelope common:ResponseEnvelope
Information common to all API responses, including a timestamp and the response acknowledgment status.

ResponseEnvelope Fields

Field Description
ack common:AckCode
Acknowledgment code. Allowed 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 by Developer Technical Support only.
correlationId Correlation ID. Used by Developer Technical Support only.
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.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns2:CreateAccountRequest xmlns:ns2="http://svcs.paypal.com/services">
<requestEnvelope>
<errorLanguage>en_US</errorLanguage>
</requestEnvelope>
<accountType>PERSONAL</accountType>
<emailAddress>testing-2039039@paypal.com</emailAddress>
<name>
<firstName>John</firstName>
<lastName>Smith</lastName>
</name>
<dateOfBirth>1968-01-01Z</dateOfBirth>
<address>
<line1>1968 Ape Way</line1>
<line2>Apt 123</line2>
<city>Austin</city>
<state>TX</state>
<postalCode>78750</postalCode>
<countryCode>US</countryCode>
</address>
<contactPhoneNumber>888-555-1212</contactPhoneNumber>
<currencyCode>USD</currencyCode>
<citizenshipCountryCode>US</citizenshipCountryCode>
<preferredLanguageCode>en_US</preferredLanguageCode>
<notificationURL>https://...</notificationURL>
<registrationType>WEB</registrationType>
<createAccountWebOptions>
<returnUrl>https://example.com</returnUrl>
</createAccountWebOptions>
</ns2:CreateAccountRequest>
</soapenv:Body>
</soapenv:Envelope>

SOAP response

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header />
<soapenv:Body>
<ns2:CreateAccountResponse xmlns:ns2="http://svcs.paypal.com/types/aa">
<responseEnvelope>
<timestamp>2009-09-03T15:19:12.281-07:00</timestamp>
<ack>Success</ack>
<correlationId>15bdd53cd4264</correlationId>
<build>1033575</build>
</responseEnvelope>
<createAccountKey>AA-6H279897NK391145S</createAccountKey>
<execStatus>COMPLETED</execStatus>
<redirectURL>https://...?cmd=_hostedua-flow&amp;encrypted_second_auth_code=AwBJzCt4b8SLUn2KMiPrYa08vABRRSnCo61W3uMlletaKWCP9XWs3WcXvnEzSlDHVa4&amp;encrypted_id=U4HE2K5TWLXQN&amp;return_url=https://example.com</redirectURL>
</ns2:CreateAccountResponse>
</soapenv:Body>
</soapenv:Envelope>

CreateAccount Errors

Code Message Additional Information
500000 Framework failure. Retry.
520002 Internal error
520003 Invalid credentials
550001 User is not allowed to perform this action
560022 Invalid header.
560029 The required <name> header is missing from the HTTP request
580001 Invalid request:
  • User has exceeded call limit set for the API
  • Personal account is not allowed for the country
  • Language not supported
  • <name>
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
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