On this page
No Headings
Last updated: June 4, 2026
Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, we recommend our latest solutions.
Shows information about an agreement between you and a sender for making payments on the sender's behalf.
The PreapprovalDetailsRequest message specifies the key of the
preapproval agreement whose details you want to obtain.
| Field | Description |
|---|---|
getBillingAddress | xsU+003Aboolean(Optional) An option that lets you retrieve a list of billing addresses for the sender.
NoteU+003A This field is available only to API callers with advanced permission levels. For information, refer to the section Adaptive Payments Service Permissions. |
preapprovalKey | xsU+003Astring(Required) A preapproval key that identifies the preapproval for which you want to retrieve details. The preapproval key is returned in the PreapprovalResponse message. |
requestEnvelope | commonU+003ArequestEnvelope(Required) Information common to each API operation, such as the language in which an error message is returned. |
| Field | Description |
|---|---|
detailLevel | commonU+003ADetailLevelCode(Optional) Level of detail required by the client application for components. Value isU+003A
|
errorLanguage | xsU+003Astring(Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported. |
The PreapprovalDetailsResponse message provides details about the
requested preapproval.
| Field | Description |
|---|---|
addresslist | apU+003AAddressListReturns a list of billing addresses. |
approved | Whether the preapproval request was approved. Value isU+003A
|
cancelUrl | The URL to which the sender's browser is redirected if the sender decides to cancel the preapproval as requested. Use the preapproval key to identify the preapproval as followsU+003A preapprovalKeyU+003DU+0024U+007BpreapprovalKeyU+007D. |
curPayments | The current number of payments by the sender for this preapproval. |
curPaymentsAmount | The current total of payments by the sender for this preapproval. |
curPeriodAttempts | The current number of payments by the sender this period for this preapproval. |
curPeriodEndingDate | Ending date for the current period. Time is currently not supported. |
currencyCode | The currency code represented by the following valuesU+003A
|
dateOfMonth | The day of the month on which a monthly payment is to be made. A number between 1 and 31 indicates the day of the month. 0 indicates that the payment can be made on any day. |
dayOfWeek | The day of the week that a weekly payment is to be made. Value isU+003A
|
endingDate | Last date for which the preapproval is valid. Time is currently not supported. NoteU+003A You must specify a value unless you have specific permission from PayPal to omit this value. |
ipnNotificationUrl | The URL to which all IPN messages for this preapproval are sent. |
maxAmountPerPayment | The preapproved maximum amount per payment. |
maxNumberOfPayments | The preapproved maximum number of payments. This field is only returned if provided. |
maxNumberOfPaymentsPerPeriod | The preapproved maximum number of payments per period. |
maxTotalAmountOfAllPayments | The preapproved maximum total amount of all payments. NoteU+003A You must specify a value unless you have specific permission from PayPal to omit this value. |
memo | A note about the preapproval. |
paymentPeriod | The payment period. Value isU+003A
|
pinType | Whether a personal identification number (PIN) is required. Value isU+003A
|
responseEnvelope | Common response information, including a timestamp and the acknowledgment status. |
returnUrl | The URL to which the sender's browser is redirected after the sender approves the preapproval on paypal.com. Use the preapproval key to identify the preapproval as followsU+003A preapprovalKeyU+003DU+0024U+007BpreapprovalKeyU+007D. |
senderEmail | Sender's email address. If not specified, the email address of the sender who logs in to approve the request becomes the email address associated with the preapproval key. |
sender.accountId | Account ID value (which is the same as the Payer ID value used in the Express Checkout API). The account ID value is an encrypted PayPal account ID. |
startingDate | First date for which the preapproval is valid. |
status | Whether this preapproval is active, represented by the following valuesU+003A
|
displayMaxTotalAmount | xsU+003AbooleanWhether to display the maximum total amount of this preapproval. Value isU+003A
|
feesPayer | xsU+003AstringThe payer of PayPal fees. Allowable values areU+003A
|
| Field | Description |
|---|---|
AddressList | apU+003AAddressReturns a billing address. |
| Field | Description |
|---|---|
addresseeName | xsU+003AstringThe name associated with the address. |
baseAddress | commonU+003ABaseAddressStreet address. |
addressId | xsU+003AstringThe ID associated with the address. |
| Field | Description |
|---|---|
city | xsU+003AstringThe city of the address. |
countryCode | xsU+003AstringThe country code of the address. |
line1 | xsU+003AstringThe first line of the address. |
line2 | xsU+003AstringAn second line of the street address. |
postalCode | xsU+003AstringThe postal code of the address. |
state | xsU+003AstringThe state for the address |
type | xsU+003Astring.The type of address. |
| Field | Description |
|---|---|
ack | commonU+003AAckCodeAcknowledgment code. Value isU+003A
|
build | xsU+003AstringBuild number. It is used only by PayPal Merchant Technical Support. |
correlationId | xsU+003AstringCorrelation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. NoteU+003A You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
timestamp | xsU+003AdatetimeDate on which the response was sent, for exampleU+003A 2012-04-02T22U+003A33U+003A35.774-07U+003A00 NoteU+003A You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
The PPFaultMessage returns ErrorData and the
ResponseEnvelope information to your application if an error
occurs.
| Field | Description |
|---|---|
error | commonU+003AErrorDataDetailed error information. |
responseEnvelope | commonU+003AResponseEnvelopeCommon response information, including a timestamp and the response acknowledgment status. |
| Field | Description |
|---|---|
category | commonU+003AErrorCategoryThe location where the error occurred. Value isU+003A
|
domain | xsU+003AstringThe domain to which this service belongs. |
errorId | xsU+003AlongA 6-digit number that uniquely identifies a particular error. |
exceptionID | This field is not used. |
message | xsU+003AstringA description of the error. |
parameter | commonU+003AErrorParameterRepresents contextual information about the error. |
severity | commonU+003AErrorSeverityThe severity of the error encountered. Value isU+003A
|
subdomain | This field is not used. |
| Field | Description |
|---|---|
ack | commonU+003AAckCodeAcknowledgment code. Value isU+003A
|
build | xsU+003AstringBuild number. It is used only by PayPal Merchant Technical Support. |
correlationId | xsU+003AstringCorrelation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. NoteU+003A You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
timestamp | xsU+003AdatetimeDate on which the response was sent, for exampleU+003A 2012-04-02T22U+003A33U+003A35.774-07U+003A00 NoteU+003A You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
These examples all use NVP for the data binding and CURL to deliver the HTTP request to the PayPal sandbox endpoint. Line breaks are provided for ease of reading; each CURL command is a single line and each request and response is a string without line breaks or extra whitespace.
In this example, the caller of the
PreapprovalDetails API operation specifies a
preapproval key. The result shows whether or not the status has been approved,
which in this case is false because the person making the
approval has not completed the process on PayPal.
Not: The sample code below uses the
insecure setting to work around the certificate for testing in
a sandbox environment. For actual implementations, you must specify the
location of the certificate.
curl https://svcs.sandbox.paypal.com/AdaptivePayments/PreapprovalDetails \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: " \ -H "X-PAYPAL-SECURITY-PASSWORD: " \ -H "X-PAYPAL-SECURITY-SIGNATURE: " \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID: " \ -d preapprovalKey=PA-9JR04288NR0519129 \ -d requestEnvelope.errorLanguage=en_USresponseEnvelope.timestamp=2009-07-13T13%3A50%3A40.496-07%3A00 &responseEnvelope.ack=Success &responseEnvelope.correlationId=16dbc35f1aea7 &responseEnvelope.build=DEV &approved=false &cancelUrl=&curPayments=0 &curPaymentsAmount=0.00 &curPeriodAttempts=0 ¤cyCode=USD &dateOfMonth=0 &dayOfWeek=NO_DAY_SPECIFIED &endingDate=2009-12-13T13%3A40%3A37.0-08%3A00&maxAmountPerPayment=200.00 &maxNumberOfPayments=30 &maxTotalAmountOfAllPayments=1500.00 &paymentPeriod=NO_PERIOD_SPECIFIED &pinType=NOT_REQUIRED &returnUrl=&startingDate=2009-07-13T13%3A40%3A37.0-07%3A00 &status=ACTIVE| Code | Message | Additional Information |
|---|---|---|
| 500000 | There is a system error | |
| 520002 | Internal error | |
| 520003 | User name/password is incorrect | |
| 520003 | Authentication failed. API credentials are incorrect. | Since 1.6.0 |
| 520006 | This call is not defined in the database | |
| 540031 | You do not have permission to get these preapproval details | Since 1.6.0 |
| 550001 | User is not allowed to perform this action | |
| 580001 | Invalid request | |
| 580001 | Invalid requestU+003A <value> | Since 1.6.0 |
| 589019 | The preapproval key is invalid | |
| 589019 | The preapproval key <value> is invalid | Since 1.6.0 |