CreateAccount API Operation
Last updated: Aug 15th, 8:08am
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:
|
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. |
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.
|
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.) |
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:
|
registrationType |
Allowed values:
|
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.
|
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. |
averagePrice | xs:decimal The average price per transaction. Required for all countries except Japan and 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:
|
businessType | aa:businessType (Required) The type of the business for which the PayPal account is created. Allowable values are:
|
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. |
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. |
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. |
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:
|
salesVenueDesc | xs:string A description of the sales venue. Required if salesVenue is OTHER for all countries except Czech Republic and 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. |
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. |
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:
|
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.
|
showMobileConfirm | xs:boolean (Optional) Defines whether the "mobile confirmation" option is included in the PayPal account registration flow.
|
usemini-browser | xs:boolean (Optional) Defines whether to use the mini-browser account registration flow or the traditional account registration flow.
|
reminderEmailFrequency |
Allowed values:
|
confirmEmail |
Allowed values:
|
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 |
Allowed values:
|
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:
|
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:
|
build | Build number. Used by Merchant Technical Support only. |
correlationId | Correlation ID. Used by Merchant 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.
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">2<soapenv:Body>3<ns2:CreateAccountRequest xmlns:ns2="https://svcs.paypal.com/services">4<requestEnvelope>5<errorLanguage>en_US</errorLanguage>6</requestEnvelope>7<accountType>PERSONAL</accountType>8<emailAddress>testing-2039039@paypal.com</emailAddress>9<name>10<firstName>John</firstName>11<lastName>Smith</lastName>12</name>13<dateOfBirth>1968-01-01Z</dateOfBirth>14<address>15<line1>1968 Ape Way</line1>16<line2>Apt 123</line2>17<city>Austin</city>18<state>TX</state>19<postalCode>78750</postalCode>20<countryCode>US</countryCode>21</address>22<contactPhoneNumber>888-555-1212</contactPhoneNumber>23<currencyCode>USD</currencyCode>24<citizenshipCountryCode>US</citizenshipCountryCode>25<preferredLanguageCode>en_US</preferredLanguageCode>26<notificationURL>https://...</notificationURL>27<registrationType>WEB</registrationType>28<createAccountWebOptions>29<returnUrl>https://example.com</returnUrl>30</createAccountWebOptions>31</ns2:CreateAccountRequest>32</soapenv:Body>33</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.
1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">2<soapenv:Header />3<soapenv:Body>4<ns2:CreateAccountResponse xmlns:ns2="https://svcs.paypal.com/types/aa">5<responseEnvelope>6<timestamp>2009-09-03T15:19:12.281-07:00</timestamp>7<ack>Success</ack>8<correlationId>15bdd53cd4264</correlationId>9<build>1033575</build>10</responseEnvelope>11<createAccountKey>AA-6H279897NK391145S</createAccountKey>12<execStatus>COMPLETED</execStatus>13<redirectURL>https://...?cmd=_hostedua-flow&encrypted_second_auth_code=AwBJzCt4b8SLUn2KMiPrYa08vABRRSnCo61W3uMlletaKWCP9XWs3WcXvnEzSlDHVa4&encrypted_id=U4HE2K5TWLXQN&return_url=https://example.com</redirectURL>14</ns2:CreateAccountResponse>15</soapenv:Body>16</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:
| |
580022 | Invalid request parameter:
| |
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:
|