Preapproval API Operation

Use the Preapproval API operation to set 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
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 $2,000 USD or its equivalent in other currencies. Contact PayPal if you do not want to specify a maximum amount.
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

  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:
    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
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: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.

  • Canadian Dollar – CAD
  • Czech Koruna – CZK
  • Danish Krone – DKK
  • Euro – EUR
  • Hong Kong Dollar – HKD
  • Hungarian Forint – HUF
  • Israeli New Sheqel – 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
  • Turkish Lira – TRY

    Note: The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts.

  • 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 $2,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. It is one of the following values:
  • 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. It is one of the following values:
  • 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. It is one of the following values:
  • 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
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
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
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 acknowledgement status.

ResponseEnvelope Fields

Field Description
ack common:AckCode Acknowledgement code. It is one of the following values:
  • 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
error common:ErrorData Detailed error information.
responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.

ErrorData Fields

Field Description
category common:ErrorCategory The location where the error occurred. Possible values are:
  • 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. Possible values are:
  • Error – Processing of the request was interrupted
  • Warning – Processing of the request was completed
subdomain This field is not used.

ResponseEnvelope Fields

Field Description
ack common:AckCode Acknowledgement code. It is one of the following values:
  • 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 -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"
https://svcs.sandbox.paypal.com/AdaptivePayments/Preapproval  -d
"cancelUrl=http://your_cancel_url
&currencyCode=USD
&endingDate=2009-12-13T08%3A00%3A00.000Z
&maxAmountPerPayment=200.00
&maxNumberOfPayments=30
&maxTotalAmountOfAllPayments=1500.00
&pinType=NOT_REQUIRED
&requestEnvelope.errorLanguage=en_US
&returnUrl=http://your_return_url
&startingDate=2009-07-13T07%3A00%3A00.000Z
&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
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 <value> 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