GetUserAgreement API Operation

Gets the user agreement for the customer to approve the new PayPal account.

User agreement management

PayPal requires account holders to agree to its User Agreement when they sign up for an account. You can use the GetUserAgreement API operation to obtain the agreement before or after the account has been created. For example, you might want to enable a potential account holder to view the agreement before you redirect them to PayPal to confirm account creation, or you might want to enable an existing PayPal account holder to view the user agreement without logging in to PayPal. The terms of the user agreement depend on the country associated with the account, which is specified when the account is created. The user agreement is typically available in the most common languages used within a country. You can specify the contents and language of the user agreement by specifying one of the following sets of information in the request of the GetUserAgreement API operation:

  • The account key returned in the response to the CreateAccount API operation
  • The country and language of the account

The response to the GetUserAgreement API operation contains the text of the user agreement as a text string. If an account key is specified in the request, the user agreement is appropriate for the country and language of the account; otherwise, the user agreement is for the specified country and language.Typically, you use country and language to display an agreement before the account has been created and use the account key after the account has been created. You can format the text to match the presentation characteristics of your site.

GetUserAgreement request

The GetUserAgreement request functions to request the PayPal's user agreement for the user to approve during account creation. The type of user agreement that is presented depends on the country and the language selected. For example, the PayPal account user may be a native Spanish speaker in the United States. In this case, the GetUserAgreement method presents a version of the agreement tailored for the United States in Spanish.

GetUserAgreement fields

The following table lists the required and optional fields for the GetUserAgreement request. The user agreement is tailored to the PayPal user's language and country code settings. You can either pass the country code and language code, or you can simply pass the createAccountKey that was returned in the CreateAccountResponse message.

Field Description
countryCode xs:string(Optional) The code for the country in which the user account is located. You do not need to provide this country code if you are passing the createAccount key. Allowable values are:
  • Australia - AU
  • Canada - CA
  • Czech Republic - CZ
  • France - FR
  • Germany - DE
  • Greece - GR
  • Israel - IL
  • Italy - IT
  • Japan - JP
  • Netherlands - NL
  • Poland - PL
  • Spain - ES
  • United Kingdom - GB
  • United States - US
createAccountKey xs:string(Optional) The key returned for this account in the CreateAccountResponse message in the createAccountKey field. If you specify this key, do not pass a country code or language code. Doing so will result in an error.
languageCode xs:string(Optional) The code indicating the language to be used for the agreement.
requestEnvelope common:RequestEnvelope(Required) Information common to each API operation, such as the language in which an error message is returned.

RequestEnvelope fields

Field Description
detailLevel common:DetailLevelCode(Optional) The level of detail required by the client application for component such as Item, Transaction. Value is:
  • ReturnAll - This value provides the maximum level of detail (default)
errorLanguage xs:string(Required) The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

GetUserAgreement response

The GetUserAgreement response includes the string with the text of the user agreement in the language requested for the country in which the account is located.

GetUserAgreement Response Fields

Field Definition
agreement xs:string This is the text of the actual PayPal user agreement.
responseEnvelope common:ResponseEnvelope Common response information, including a time stamp and the response acknowledgment status.

ResponseEnvelope fields

Field Description
ack common:AckCode Acknowledgment code. Value is:
  • Success - Operation completed successfully
  • Failure - Operation failed
  • Warning - warning
  • SuccessWithWarning - Operation completed successfully; however, there is a warning message
  • FailureWithWarning - Operation failed with a warning message
build Build number; used only by Developer Technical Support.
correlationId Correlation ID; used only by Developer Technical Support.
timestamp The date when the response was sent. The time is not supported.

SOAP GetUserAgreement example

This example shows how to set up a request to obtain the user agreement associated with a specific country and language. The response contains the agreement itself.

SOAP request

In this example, the country is US and the language is en_US.

Note: You must also include credentials. They are not shown in this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns2:GetUserAgreementRequest xmlns:ns2="http://svcs.paypal.com/services">
<requestEnvelope>
<errorLanguage>en_US</errorLanguage>
</requestEnvelope>
<countryCode>US</countryCode>
<languageCode>en_US</languageCode>
<agreementType>Personal</agreementType>
</ns2:GetUserAgreementRequest>
</soapenv:Body>
</soapenv:Envelope>

SOAP response

The response contains the actual agreement, which you typically format before presenting to the user.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header />
<soapenv:Body>
<ns2:GetUserAgreementResponse xmlns:ns2="http://svcs.paypal.com/types/aa">
<responseEnvelope>
<timestamp>2009-09-03T15:09:25.101-07:00</timestamp>
<ack>Success</ack>
<correlationId>860b4b0d476df</correlationId>
<build>1033575</build>
</responseEnvelope>
<agreement>

This User Agreement ("Agreement") is a contract between you and PayPal and applies to your use of PayPal's Services. You must read, agree with and accept all of the terms and conditions contained in this Agreement. In addition, you must read, agree with and accept any applicable agreements on the Legal Agreements page.
...
"Viewable Online Signature Confirmation" means documentation that can be viewed online at the Approved Shipper's website and includes the signature of the person who received the package.
"User," "you," or "your" means you and any other person or entity using the Service.
</agreement>
</ns2:GetUserAgreementResponse>
</soapenv:Body>
</soapenv:Envelope>

GetUserAgreement errors

Variable Description
520002 Internal error
520003 Username/Password is incorrect
550005 The application ID does not exist
550006 The application is not authorized for the app caller
580022 Request parameter is invalid:
  • line1 cannot be null
  • city cannot be null
  • countryCode cannot be null
  • firstName cannot be null
  • lastName cannot be null
  • Invalid request: address
For invalid requests regarding address, the postal code is required for the country, or the city is missing from the address.
580029 Required parameter is missing in the request:
  • Invalid request: emailAddress
  • Invalid request: sandboxEmailAddress
580001 Invalid request:
  • accountType does not match the pattern Personal/Premier/ Business
  • citizenshipCountryCode
  • countryCode
  • currencyCode
  • dateofBirth
  • firstName is not between 1 and 192 characters long
  • ipAddress
  • preferredLanguageCode
  • line1 is not between 1 and 300 characters long
  • notificationUrl is not between 1 and 1024 characters long
  • notificationUrl does not match the pattern <[a-aZ-Z]+\://){1}\S+
  • state is not between 0 and 120 characters long
580022 Account already exists Since 1.3.0
580029 Required parameter is missing in the request:
  • Invalid request: emailAddress
  • Invalid request: sandboxEmailAddress