# Preapproval API operation (/archive/adaptive-payments/api/preapproval)
> **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/business/accept-payments).
Sets up an agreement between yourself and a sender for making payments on the
sender's behalf.
You set up a preapprovals for a specific maximum amount over a specific period
of time and, optionally, by any of the following constraints: the number of
payments, a maximum per-payment amount, a specific day of the week or the
month, and whether or not a PIN is required for each payment request.
## Preapproval overview [#preapproval-overview]
To set up a preapproval request, you must specify values for the following
fields:
**Table 1. Required preapproval fields**
| Field | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `endingDate` | Last date for which the preapproval is valid. It cannot be later than one year from the starting date. Contact PayPal if you do not want to specify an ending date. |
| `startingDate` | First date for which the preapproval is valid. It cannot be before today's date or after the ending date. |
| `maxTotalAmountOfAllPayments` | The preapproved maximum total amount of all payments. It cannot exceed U+00242,000 USD or its equivalent in other currencies. |
| `currencyCode` | The code for the currency in which the payment is made; you can specify only one currency, regardless of the number of receivers |
| `cancelUrl` | URL to redirect the sender's browser to after canceling the preapproval |
| `returnUrl` | URL to redirect the sender's browser to after the sender has logged into PayPal and confirmed the preapproval |
| `requestEnvelope.errorLanguage` | The code for the language in which errors are returned, which must be `en_US`. |
### Preapproval notifications [#preapproval-notifications]
Notifications are sent after preapproval is complete:
* PayPal sends an email to the sender that confirmed the approval.
* PayPal sends an IPN message to the URL specified in the `ipnNotificationUrl` field of the `Preapproval` request.
### Additional notes about the PreApproval API operation [#additional-notes-about-the-preapproval-api-operation]
1. Preapproval constraints are additive; thus, for example, if you specify a preapproval that allows payments only on Fridays and on the 13th day of the month, the preapproval would be valid only on Friday the 13th of months within the specified time period.
2. The `startingDate` and `endingDate` can be in either Zulu or GMT offset formats. as in the following respective examples:
```text lineNumbers
2010-09-10Z
2010-09-10T17:24:03.874-07:00
```
## PreapprovalRequest message [#preapprovalrequest-message]
The `PreapprovalRequest` message contains the fields to set up a
preapproval agreement between yourself and a sender.
### PreapprovalRequest fields [#preapprovalrequest-fields]
| Field | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancelUrl` | `xs:string` *(Required)* The URL to which the sender's browser is redirected after the sender cancels the preapproval at paypal.com. Maximum length: 1024 characters |
| `clientDetails` | `common:ClientDetailsType` *(Required)* Information about the sender. |
| `currencyCode` | `xs:string` *(Required)* The currency code. Allowable values are: Australian Dollar — `AUD`Brazilian Real — `BRL` > **Note:** **Note:** 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:** **Note:** 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` | `xs:int` *(Optional)* The day of the month on which a monthly payment is to be made. Allowable values are numbers between 0 and 31. A number between 1 and 31 indicates the date of the month. Specifying 0 indicates that payment can be made on any day of the month. |
| `dayOfWeek` | `common:DayOfWeek` *(Optional)* The day of the week that a weekly payment is to be made. Allowable values are: `NO_DAY_SPECIFIED``SUNDAY``MONDAY``TUESDAY``WEDNESDAY``THURSDAY``FRIDAY``SATURDAY` |
| `endingDate` | `xs:dateTime` *(Optional)* Last date for which the preapproval is valid. It cannot be later than one year from the starting date. > **Note:** **Note:** You must specify a value unless you have specific permission from PayPal to omit this value. |
| `ipnNotificationUrl` | `xs:string` *(Optional)* The URL to which you want all IPN messages for this preapproval to be sent. This URL supersedes the IPN notification URL in your profile. Maximum length: 1024 characters |
| `maxAmountPerPayment` | `xs:decimal` *(Optional)* The preapproved maximum amount per payment. It cannot exceed the preapproved maximum total amount of all payments. |
| `maxNumberOfPayments` | `xs:int` *(Optional)* The preapproved maximum number of payments. It cannot exceed the preapproved maximum total number of all payments. |
| `maxNumberOfPaymentsPerPeriod` | `xs:int` *(Optional)* The preapproved maximum number of all payments per period. You must specify a value unless you have specific permission from PayPal. |
| `maxTotalAmountOfAllPayments` | `xs:decimal` *(Optional)* The preapproved maximum total amount of all payments. It cannot exceed U+00242,000 USD or its equivalent in other currencies. > **Note:** **Note:** You must specify a value unless you have specific permission from PayPal to omit this value. |
| `memo` | `xs:string` *(Optional)* A note about the preapproval. Maximum length: 1000 characters, including newline characters |
| `paymentPeriod` | `xs:string` *(Optional)* The payment period. Value is: `NO_PERIOD_SPECIFIED``DAILY` — Each day`WEEKLY` — Each week`BIWEEKLY` — Every other week`SEMIMONTHLY` — Twice a month`MONTHLY` — Each month`ANNUALLY` — Each year |
| `pinType` | `xs:string` *(Optional)* Whether a personal identification number (PIN) is required. Value is: `NOT_REQUIRED` — A PIN is not required (default)`REQUIRED` — A PIN is required; the sender must specify a PIN when setting up the preapproval on PayPal |
| `requestEnvelope` | `common:RequestEnvelope` *(Required)* Information common to each API operation, such as the language in which an error message is returned. |
| `returnUrl` | `xs:string` *(Required)* The URL to which the sender's browser is redirected after the sender approves the preapproval on paypal.com. Maximum length: 1024 characters |
| `senderEmail` | `xs:string` *(Optional)* Sender's email address. You can specify a value for `senderEmail` or for `sender.accountId`. 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. Maximum length: 127 characters |
| `sender.accountId` | `xs:string` *(Optional)* 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` | `xs:dateTime` *(Required)* First date for which the preapproval is valid. It cannot be before today's date or after the ending date. |
| `displayMaxTotalAmount` | `xs:boolean` *(Optional)* Whether to display the maximum total amount of this preapproval. Value is: `TRUE` — Display the amount`FALSE` — Do not display the amount (default) |
| `feesPayer` | `xs:string` *(Optional)* The payer of PayPal fees. Allowable values are: `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) |
| `requireInstantFundingSource` | `xs:boolean` *(Optional)* Whether the PayPal user account must have an instant funding source for preapproval to be available. Allowable values are: `TRUE` — Require an instant funding source in the PayPal user account`FALSE` — Allow a non-instant funding source such as eCheck for preapproval (default) |
### ClientDetails fields [#clientdetails-fields]
| Field | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicationId` | `xs:string` *(Optional)* Your application's identification, such as the name of your application |
| `customerId` | `xs:string` *(Optional)* Your ID for this sender Maximum length: 127 characters |
| `customerType` | `xs:string` *(Optional)* Your identification of the type of customer Maximum length: 127 characters |
| `deviceId` | `xs:string` *(Optional)* Sender's device ID, such as a mobile device's IMEI number or a web browser cookie. If a device ID was passed with the `PayRequest`, use the same ID here. Maximum length: 127 characters |
| `geoLocation` | `xs:string` *(Optional)* Sender's geographic location Maximum length: 127 characters |
| `ipAddress` | `xs:string` *(Optional)* Sender's IP address. If an IP addressed was passed with the `PayRequest`, use the same ID here. |
| `model` | `xs:string` *(Optional)* A sub-identification of the application Maximum length: 127 characters |
| `partnerName` | `xs:string` *(Optional)* Your organization's name or ID Maximum length: 127 characters |
### RequestEnvelope fields [#requestenvelope-fields]
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `detailLevel` | `common:DetailLevelCode` *(Optional)* Level of detail required by the client application pertaining to a particular data component. The detail level is specified as a detail level code, which has all the enumerated values of the detail level for the component. By default, the detail level code is `ReturnAll`, which provides the maximum level of detail. |
| `errorLanguage` | `xs:string` *(Required)* RFC 3066 language in which error messages are returned; by default it is `en_US`, which is the only language currently supported. |
## PreapprovalResponse message [#preapprovalresponse-message]
The `PreapprovalResponse` message contains a preapproval key. This
key uniquely identifies the preapproval for this request, and can be used in
other Adaptive Payment APIs to identify this specific preapproval.
### PreapprovalResponse fields [#preapprovalresponse-fields]
| Field | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preapprovalKey` | `xs:string` A preapproval key that identifies the preapproval requested. You can use this key in other Adaptive Payment requests to identify this preapproval. |
| `responseEnvelope` | `common:ResponseEnvelope` Common response information, including a timestamp and the acknowledgment status. |
### ResponseEnvelope fields [#responseenvelope-fields]
| Field | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack` | `common:AckCode` Acknowledgment code. Value is: `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` | `xs:string` Build number. It is used only by PayPal Merchant Technical Support. |
| `correlationId` | `xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. > **Note:** **Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| `timestamp` | `xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` > **Note:** **Note:** 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` | `common:ErrorData` Detailed error information. |
| `responseEnvelope` | `common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status. |
### ErrorData fields [#errordata-fields]
| Field | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | `common:ErrorCategory` The location where the error occurred. Value is: `System` — The system encountered errors; try again`Application` — The application encountered errors; try again`Request` — The request was incorrect |
| `domain` | `xs:string` The domain to which this service belongs. |
| `errorId` | `xs:long` A 6-digit number that uniquely identifies a particular error. |
| `exceptionID` | This field is not used. |
| `message` | `xs:string` A description of the error. |
| `parameter` | `common:ErrorParameter` Represents contextual information about the error. |
| `severity` | `common:ErrorSeverity` The severity of the error encountered. Value is: `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` | `common:AckCode` Acknowledgment code. Value is: `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` | `xs:string` Build number. It is used only by PayPal Merchant Technical Support. |
| `correlationId` | `xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. > **Note:** **Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| `timestamp` | `xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` > **Note:** **Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
## Preapproval examples using NVP and CURL [#preapproval-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.
### Setting up a preapproval [#setting-up-a-preapproval]
In this example, the caller of the `Preapproval` API sets up a
preapproval that is valid from July 17, 2009 through December 12, 2009
.
The maximum amount of the preapproval is $1,500, of which a maximum of 30
payments are authorized with the largest payment not to exceed $200
.
The sender need not include a PIN. The response contains the preapproval key
that the caller can use in the `Pay` API operation.
> **Note:** **Note:** 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/Preapproval \
-s \
--insecure \
-H "X-PAYPAL-SECURITY-USERID: [api_username]" \
-H "X-PAYPAL-SECURITY-PASSWORD: [api_password]" \
-H "X-PAYPAL-SECURITY-SIGNATURE: [api_signature]" \
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
-H "X-PAYPAL-APPLICATION-ID: [app_id]" \
-d cancelUrl=https://example.com \
-d currencyCode=USD \
-d endingDate=2009-12-13T08%3A00%3A00.000Z \
-d maxAmountPerPayment=200.00 \
-d maxNumberOfPayments=30 \
-d maxTotalAmountOfAllPayments=1500.00 \
-d pinType=NOT_REQUIRED \
-d requestEnvelope.errorLanguage=en_US \
-d returnUrl=https://example.com \
-d startingDate=2009-07-13T07%3A00%3A00.000Z \
-d senderEmail=[sender@domain]
```
#### Response [#response]
```text lineNumbers
responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=7967b2d03745a
&responseEnvelope.build=DEV
&preapprovalKey=PA-9JR04288NR0519129
```
## Preapproval errors [#preapproval-errors]
| Code | Message | Additional Information |
| ------ | ------------------------------------------------------------------------------------------------- | ---------------------- |
| 500000 | There is a system error | |
| 520002 | Internal error | |
| 520003 | User name/password is incorrect | |
| 520006 | This call is not defined in the database | |
| 569016 | Preapproval PIN functionality is not enabled | |
| 569018 | Preapproved payments have been disabled | |
| 570026 | The starting date is too far in the future | |
| 579038 | The date range between the start date and the end date is too wide | |
| 579055 | The limit for total amount of all payments is above PayPal's limit | |
| 580001 | Invalid request | |
| 580022 | Account already exists | Since 1.3.0 |
| 580024 | The start date must be in the future | |
| 580025 | The start date must be earlier than the end date | |
| 580027 | The argument is unsupported | |
| 580028 | The URL 0x3Cvalue0x3E is malformed | |
| 589023 | If a fractional amount is rounded due to currency conversion, funds could be lost | |
| 589039 | The email address is invalid. It may not be registered in PayPal's system yet | |