Preapproval API operation

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.

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

To set up a preapproval request, you must specify values for the following fields:

Table 1. Required preapproval fields

Field, Description
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

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

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.
The startingDate and endingDate can be in either Zulu or GMT offset formats. as in the following respective examples:
```
2010-09-10Z
2010-09-10T17:24:03.874-07:00
```

PreapprovalRequest message

The PreapprovalRequest message contains the fields to set up a preapproval agreement between yourself and a sender.

PreapprovalRequest fields

Field, Description
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: 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: 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: 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: 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

Field, Description
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

Field, Description
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

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

Field, Description
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

Field, Description
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: 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: 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

The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs.

FaultMessage fields

Field, Description
Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

ErrorData fields

Field, Description
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

Field, Description
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: 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: 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

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

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: 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

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

responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=7967b2d03745a
&responseEnvelope.build=DEV
&preapprovalKey=PA-9JR04288NR0519129

Preapproval errors

Code, Message, Additional Information
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

Sets up an agreement between yourself and a sender for making payments on the sender's behalf.

Preapproval overview

To set up a preapproval request, you must specify values for the following fields:

Table 1. Required preapproval fields

Field, Description
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

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

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.
The startingDate and endingDate can be in either Zulu or GMT offset formats. as in the following respective examples:
```
2010-09-10Z
2010-09-10T17:24:03.874-07:00
```

PreapprovalRequest message

The PreapprovalRequest message contains the fields to set up a preapproval agreement between yourself and a sender.

PreapprovalRequest fields

Field, Description
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: 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: 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: 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: 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

Field, Description
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

Field, Description
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 fields

Field, Description
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

Field, Description
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: 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: 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

The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs.

FaultMessage fields

Field, Description
Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

ErrorData fields

Field, Description
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

Field, Description
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: 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: 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

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.

Request

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

responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=7967b2d03745a
&responseEnvelope.build=DEV
&preapprovalKey=PA-9JR04288NR0519129

Preapproval errors

Code, Message, Additional Information
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

Preapproval API operation

On this page

On this page

On this page

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

Preapproval API operation

On this page

On this page