CreateAccount API Operation

API

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

FieldDescription
accountTypexs:string
(Required) The type of account to create. Allowed values:
  • Personal - (Deprecated) Personal account
  • Premier - (Deprecated) Premier account
  • Business - Business account
addressaa:AddressType
(Required) A structure containing the address of the holder of the new PayPal account. See AddressType Fields for details.
businessInfoaa:BusinessInfoType
(Required if creating a business account) A structure containing information needed to create a business account. See BusinessInfoType Fields for details.
citizenshipCountryCodexs:string
(Required) Code identifying the country of citizenship of the holder of the new account. See Country Codes for allowed values.
clientDetailsDo not use this field.
contactPhoneNumberxs:string
(Required) Contact phone number of the holder of the new account.
governmentIdaa: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.
homePhoneNumberxs:string
(Optional) Home phone number of the holder of the new account.
mobilePhoneNumberxs:string
(Optional) Mobile phone number of the holder of the new account.
createAccountWebOptionsaa:CreateAccountWebOptionsType
(Required) A structure containing web options that pertain to account creation. See CreateAccountWebOptionsType Fields for details.
currencyCodexs:string
(Required) Three-letter code identifying the currency to assign to the new account.
dateOfBirthxs: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.
emailAddressxs:string
(Required) Email address of the holder of the new PayPal account.
functionalAreaxs:string
(Optional) Account holder's functional area, meaning the account holder's department. For business accounts only. Values: Finance, Operations, Technology, Sales, Marketing, Other.
legalAgreementLegalAgreementType
(Optional) Indicates whether or not account holder has agreed to a particular agreement.
nameaa:NameType
(Required) Name of the holder of the new PayPal account. See NameType Fields for details.
notificationURLxs: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+
occupationxs: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.
partnerFieldnxs:string
(Optional) A maximum of five fields for your own use, where n is a digit between 1 and 5, inclusive.
performExtraVettingOnthisAccountxs: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
purposeOfAccountxs: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"
professionxs: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
taxIdxs:string
(Optional) Tax Id (Equivalent to SSN in the US.)
preferredLanguageCodexs: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.
requestEnvelopecommon:RequestEnvelope
(Required) Information common to all API operations, such as the language in which an error message is returned. See RequestEnvelope Fields for details.
suppressWelcomeEmailxs: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

FieldDescription
line1xs:string
(Required) Street address.
line2xs:string
(Optional) Second line of the address. Required for Brazilian accounts.
cityxs:string
(Required) City name.
statexs:string
(Optional) State code. Required for some countries, including Brazil.
postalCodexs:string
(Optional) Zip or postal code. Required for some countries, including Brazil.
countryCodexs:string
(Required) Country code. See Country Codes for allowed values.

BusinessInfoType Fields

FieldDescription
averageMonthlyVolumexs:decimal
The average monthly transaction volume of the business for which the PayPal account is created. Required for all countries except Japan and Australia.
averagePricexs:decimal
The average price per transaction. Required for all countries except Japan and Australia.
businessAddressaa:addressType
(Required) The address for the business for which the PayPal account is created.
businessEntityForThirdPartyaa:BusinessEntityForThirdPartyType
(Optional) Use this container for a third party.
businessNamexs:string
(Required) The name of the business for which the PayPal account is created.
businessStakeholderaa:BusinessStakeholderType
(Optional) The stakeholders in the business. See BusinessStakeholderType Fields for details.
businessSubtypeaa: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
businessTypeaa:businessType
(Required) The type of the business for which the PayPal account is created. Allowable values are:
  • CORPORATION
  • GOVERNMENT
  • INDIVIDUAL
  • NONPROFIT
  • PARTNERSHIP
  • PROPRIETORSHIP
categoryxs: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.
commercialRegistrationLocationxs:string
Official commercial registration location for the business for which the PayPal account is created. Required for Germany.
companyIdxs: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.
customerServiceEmailxs:string
(Required) The email address for the customer service department of the business.
customerServicePhonexs:string
The phone number for the customer service department of the business. Required for United States business accounts; otherwise, optional.
dateOfEstablishmentxs: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.
disputeEmailxs:string
(Optional) The email address to contact to dispute charges.
doingBusinessAsxs:string
(Optional) The business name being used if it is not the actual name of the business.
establishmentCountryCodexs:string
(Optional) The code of the country where the business was established. See Country Codes for allowed values.
establishmentStatexs:string
(Optional) The state in which the business was established.
hasBeneficialOwnersaa:YesNoType
(Optional) Specify YES if the business has beneficial owners, otherwise NO.
hasDirectorsaa:YesNoType
(Optional) Specify YES if the business has directors, otherwise NO.
hasThirdPartyAssociatesaa:YesNoType
(Optional) Specify YES if the business has third party associates, otherwise NO.
incorporationIdxs:string
(Optional) The incorporation identification number for the business.
merchantCategoryCodexs: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.
percentageRevenueFromOnlinexs: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.
principalPlaceOfBusinessAddressaa:AddressType
(Optional) The principle business address.
registeredOfficeAddressaa:AddressType
(Optional) The business address for the business registration.
salesVenueaa: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
salesVenueDescxs:string
A description of the sales venue. Required if salesVenue is OTHER for all countries except Czech Republic and Australia.
subcategoryxs: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.
vatCountryCodexs: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.
vatIdxs: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.
webSitexs: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.
workPhonexs:string
(Required)* The phone number for the business. Not required for businesses in Mexico.

BusinessStakeholderType Fields

FieldDescription
addressaa:addressType
(Optional) The address of the stakeholder in the business for which the PayPal account is created.
dateOfBirthxs:date
(Optional) The date of birth of the stakeholder in the business. Use YYYY-MM-DDZ format; for example 1970-01-01Z.
fullLegalNamexs:string
(Optional) The legal name of the stakeholder in the business for which the PayPal account is created.
nameaa:NameType
(Optional) The name of the stakeholder in the business for which the PayPal account is created. See NameType for details.
occupationxs: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.
roleaa: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
countryCodexs:string
Code identifying the country of the stakeholder. See Country Codes for allowed values.

BusinessEntityForThirdPartyType Fields

FieldDescription
thirdPartyTypexs:string
(Optional) Either Individual or Business must be specified.
nameaa: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.
dateOfBirthxs:date
(Optional) If the third party is an individual, specify the date of birth.
addressaa:AddressType
(Optional) Address of the third party.
professionxs:string
(Optional) If the third party is an individual, the profession.
relationshipWithThirdPartyxs:string
(Optional) The individual's or business's relationship with the third party.
natureOfBusinessxs:string
(Optional) If the third party is a business, the nature of the business.
nameOfBusinessxs:string
(Optional) If the third party is a business, the name of the business.
businessTypexs: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.
incorporationIdxs:string
(Optional) If the third party is a business, specify the incorporation ID.
incorporationCountryxs:string
(Optional) If the third party is a business, specify the country of incorporation.
incorporationStatexs:string
(Optional) If the third party is a business, specify the state of incorporation.

CreateAccountWebOptionsType Fields

FieldDescription
returnUrlxs: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).
returnUrlDescriptionxs:string
(Optional) A description of the return URL.
showAddCreditCardxs: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
showMobileConfirmxs: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)

usemini-browserxs: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)
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.
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.

GovernmentIDPair Fields

FieldDescription
valuexs:string
(Optional) The actual value of the government ID.
typeaa:GovernmentIDTypes
(Optional) The kind of government ID, e.g. SIN.

LegalAgreementType Fields

FieldDescription
acceptedxs:string
(Optional) Whether the legal agreement has been accepted.
typeaa: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

FieldDescription
salutationxs:string
(Optional) A salutation for the account or payment card holder.
firstNamexs:string
(Required) First name of the account or payment card holder.
middleNamexs:string
(Optional) Middle name of the account or payment card holder.
lastNamexs:string
(Required) Last name of the account or payment card holder.
suffixxs:string
(Optional) A suffix for the account or payment card holder.

RequestEnvelope Fields

FieldDescription
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)
errorLanguagexs: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

FieldDescription
accountIdxs:string
The ID of the new PayPal account. This value is returned only for Premier and Business accounts.
createAccountKeyxs: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.
execStatusxs: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.
redirectURLxs: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.
responseEnvelopecommon:ResponseEnvelope
Information common to all API responses, including a timestamp and the response acknowledgment status.

ResponseEnvelope Fields

FieldDescription
ackcommon: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
buildBuild number. Used by Merchant Technical Support only.
correlationIdCorrelation ID. Used by Merchant Technical Support only.
timestampThe 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

      CodeMessageAdditional Information
      500000Framework failure. Retry.
      520002Internal error
      520003Invalid credentials
      550001User is not allowed to perform this action
      560022Invalid header.
      560029The required &lt;name&gt; header is missing from the HTTP request
      580001Invalid request:
      • User has exceeded call limit set for the API
      • Personal account is not allowed for the country
      • Language not supported
      • <name>
      580022Invalid 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
      580023The argument is inconsistent with the rest of the request
      580027The parameter is not supported
      580029A required parameter is missing from the request:
      • postalCode
      • state
      • businessStakeholder
      • city
      • countryCode
      • firstName
      • incorporationId
      • lastName
      • line1
      • postalCode
      • salesVenueDesc
      • state
      • mobilePhoneNumber

      If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more