# PreapprovalDetails API Operation (/archive/adaptive-payments/api/preapproval-details)
> **Note:** **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](https://www.paypal.com/us/business/accept-payments).
Shows information about an agreement between you and a sender for making
payments on the sender's behalf.
## PreapprovalDetailsRequest Message [#preapprovaldetailsrequest-message]
The `PreapprovalDetailsRequest` message specifies the key of the
preapproval agreement whose details you want to obtain.
### PreapprovalDetailsRequest Fields [#preapprovaldetailsrequest-fields]
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getBillingAddress`
| `xsU+003Aboolean`
`true` – Includes the billing address in the response
`false` – Omits the billing address from the response (default)
> **Note:** **NoteU+003A** This field is available only to API callers with advanced permission levels. For information, refer to the section [Adaptive Payments Service Permissions](/archive/adaptive-payments/integration-guide/APIntro#adaptive-payments-service-permissions). |
| `preapprovalKey`
| `xsU+003Astring`
|
| `requestEnvelope`
| `commonU+003ArequestEnvelope`
|
### RequestEnvelope Fields [#requestenvelope-fields]
| Field | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detailLevel`
| `commonU+003ADetailLevelCode`
`ReturnAll` – This value provides the maximum level of detail (default).
|
| `errorLanguage`
| `xsU+003Astring`
|
## PreapprovalDetailsResponse Message [#preapprovaldetailsresponse-message]
The `PreapprovalDetailsResponse` message provides details about the
requested preapproval.
### PreapprovalDetailsResponse Fields [#preapprovaldetailsresponse-fields]
| Field | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `addresslist`
| `apU+003AAddressList`
Returns a list of billing addresses.
|
| `approved`
| Whether the preapproval request was approved. Value isU+003A
`true` – The request was approved
`false` – The request was denied
|
| `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
Australian Dollar – `AUD`
Brazilian Real – `BRL`
> **Note:** **NoteU+003A** This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.Canadian Dollar – `CAD`
Czech Koruna – `CZK`
Danish Krone – `DKK`
Euro – `EUR`
Hong Kong Dollar – `HKD`
Hungarian Forint – `HUF`
Israeli New Shekel – `ILS`
Japanese Yen – `JPY`
Malaysian Ringgit – `MYR`
> **Note:** **NoteU+003A** The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.Mexican Peso – `MXN`
Norwegian Krone – `NOK`
New Zealand Dollar `– NZD`
Philippine Peso – `PHP`
Polish Zloty – `PLN`
Pound Sterling `– GBP`
Singapore Dollar – `SGD`
Swedish Krona `– SEK`
Swiss Franc – `CHF`
Taiwan New Dollar – `TWD`
Thai Baht `– THB`
U.S. Dollar – `USD`
|
| `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
`NO_DAY_SPECIFIED`
`SUNDAY`
`MONDAY`
`TUESDAY`
`WEDNESDAY`
`THURSDAY`
`FRIDAY`
`SATURDAY`
|
| `endingDate`
| Last date for which the preapproval is valid. Time is currently not supported.
> **Note:** **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.
> **Note:** **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
`NO_PERIOD_SPECIFIED`
`DAILY`
`WEEKLY`
`BIWEEKLY`
`SEMIMONTHLY`
`MONTHLY`
`ANNUALLY`
|
| `pinType`
| Whether a personal identification number (PIN) is required. Value isU+003A
`NOT_REQUIRED` – A PIN is not required
`REQUIRED` – A PIN is required
|
| `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
`ACTIVE` – The preapproval is active
`CANCELED` – The preapproval was explicitly canceled by the sender or by PayPal
`DEACTIVATED` – The preapproval is not active; you can reactivate it by resetting the personal identification number (PIN) or by contacting PayPal
|
| `displayMaxTotalAmount`
| `xsU+003Aboolean`
Whether to display the maximum total amount of this preapproval. Value isU+003A
`TRUE` – Display the amount
`FALSE` – Do not display the amount (default)
|
| `feesPayer`
| `xsU+003Astring`
The payer of PayPal fees. Allowable values areU+003A
`SENDER` – Sender pays all fees (for personal, implicit simple/parallel payments; do not use for chained or unilateral payments)
`PRIMARYRECEIVER` – Primary receiver pays all fees (chained payments only)
`EACHRECEIVER` – Each receiver pays their own fee (default, personal and unilateral payments)
`SECONDARYONLY` – Secondary receivers pay all fees (use only for chained payments with one secondary receiver)
|
### AddressList Fields [#addresslist-fields]
| Field | Description |
| ------------------- | ----------------------------------------------------------------- |
| `AddressList`
| `apU+003AAddress`
Returns a billing address.
|
### Address Fields [#address-fields]
| Field | Description |
| --------------------- | --------------------------------------------------------------------------- |
| `addresseeName`
| `xsU+003Astring`
The name associated with the address.
|
| `baseAddress`
| `commonU+003ABaseAddress`
Street address.
|
| `addressId`
| `xsU+003Astring`
The ID associated with the address.
|
### BaseAddress Fields [#baseaddress-fields]
| Field | Description |
| ------------------- | --------------------------------------------------------------------------- |
| `city`
| `xsU+003Astring`
The city of the address.
|
| `countryCode`
| `xsU+003Astring`
The country code of the address.
|
| `line1`
| `xsU+003Astring`
The first line of the address.
|
| `line2`
| `xsU+003Astring`
An second line of the street address.
|
| `postalCode`
| `xsU+003Astring`
The postal code of the address.
|
| `state`
| `xsU+003Astring`
The state for the address
|
| `type`
| `xsU+003Astring`.
The type of address.
|
### ResponseEnvelope Fields [#responseenvelope-fields]
| Field | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`
| `commonU+003AAckCode`
Acknowledgment code. Value isU+003A
`Success` – The operation completed successfully.
`Failure` – The operation failed.
`SuccessWithWarning` – The operation completed successfully; however, there is a warning message.
`FailureWithWarning` – The operation failed with a warning message.
|
| `build`
| `xsU+003Astring`
Build number. It is used only by PayPal Merchant Technical Support.
|
| `correlationId`
| `xsU+003Astring`
Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support.
> **Note:** **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+003Adatetime`
Date on which the response was sent, for exampleU+003A
`2012-04-02T22U+003A33U+003A35.774-07U+003A00`
> **Note:** **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. |
## PPFault Message [#ppfault-message]
The `PPFaultMessage` returns `ErrorData` and the
`ResponseEnvelope` information to your application if an error
occurs.
### FaultMessage Fields [#faultmessage-fields]
| Field | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`
| `commonU+003AErrorData`
Detailed error information.
|
| `responseEnvelope`
| `commonU+003AResponseEnvelope`
Common response information, including a timestamp and the response acknowledgment status.
|
### ErrorData Fields [#errordata-fields]
| Field | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`
| `commonU+003AErrorCategory`
The location where the error occurred.
Value isU+003A
`System` – The system encountered errors; try again
`Application` – The application encountered errors; try again
`Request` – The request was incorrect
|
| `domain`
| `xsU+003Astring`
The domain to which this service belongs.
|
| `errorId`
| `xsU+003Along`
A 6-digit number that uniquely identifies a particular error.
|
| `exceptionID`
| This field is not used.
|
| `message`
| `xsU+003Astring`
A description of the error.
|
| `parameter`
| `commonU+003AErrorParameter`
Represents contextual information about the error.
|
| `severity`
| `commonU+003AErrorSeverity`
The severity of the error encountered.
Value isU+003A
`Error` – Processing of the request was interrupted
`Warning` – Processing of the request was completed
|
| `subdomain`
| This field is not used.
|
### ResponseEnvelope Fields [#responseenvelope-fields-1]
| Field | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`
| `commonU+003AAckCode`
Acknowledgment code. Value isU+003A
`Success` – The operation completed successfully.
`Failure` – The operation failed.
`SuccessWithWarning` – The operation completed successfully; however, there is a warning message.
`FailureWithWarning` – The operation failed with a warning message.
|
| `build`
| `xsU+003Astring`
Build number. It is used only by PayPal Merchant Technical Support.
|
| `correlationId`
| `xsU+003Astring`
Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support.
> **Note:** **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+003Adatetime`
Date on which the response was sent, for exampleU+003A
`2012-04-02T22U+003A33U+003A35.774-07U+003A00`
> **Note:** **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. |
## PreapprovalDetails Examples Using NVP and CURL [#preapprovaldetails-examples-using-nvp-and-curl]
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.
### Obtaining information about a preapproval [#obtaining-information-about-a-preapproval]
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.
> **Note:** **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.
### Request [#request]
```text lineNumbers
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_US
```
### Response [#response]
```text lineNumbers
responseEnvelope.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
```
## Preapproval Details Errors [#preapproval-details-errors]
| 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 \ | Since 1.6.0
|
| 589019 | The preapproval key is invalid | |
| 589019 | The preapproval key \ is invalid | Since 1.6.0
|