Preapproval API Operation
Last updated: Aug 15th, 7:44am
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:
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 thePreapproval
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
andendingDate
can be in either Zulu or GMT offset formats. as in the following respective examples:12010-09-10Z22010-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:
|
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:
|
endingDate |
xs:dateTime (Optional) Last date for which the
preapproval is valid. It cannot be later than one year from the starting
date.
|
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.
|
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:
|
pinType |
xs:string (Optional) Whether a personal
identification number (PIN) is required. Value is:
|
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:
|
feesPayer |
xs:string (Optional) The payer of PayPal fees.
Allowable values are:
|
requireInstantFundingSource |
xs:boolean (Optional) Whether the PayPal user
account must have an instant funding source for preapproval to be
available. Allowable values are:
|
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 acknowledgment status.
|
ResponseEnvelope Fields
Field | Description |
---|---|
ack |
common:AckCode Acknowledgment code. Value is:
|
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.
|
timestamp |
xs:datetime Date on which the response was sent, for
example: 2012-04-02T22:33:35.774-07:00
|
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 acknowledgment status.
|
ErrorData Fields
Field | Description |
---|---|
category |
common:ErrorCategory The location where the error occurred.
Value is:
|
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:
|
subdomain |
This field is not used. |
ResponseEnvelope Fields
Field | Description |
---|---|
ack |
common:AckCode Acknowledgment code. Value is:
|
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.
|
timestamp |
xs:datetime Date on which the response was sent, for
example: 2012-04-02T22:33:35.774-07:00
|
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.
Request
1curl https://svcs.sandbox.paypal.com/AdaptivePayments/Preapproval \2 -s \3 --insecure \4 -H "X-PAYPAL-SECURITY-USERID: [api_username]" \5 -H "X-PAYPAL-SECURITY-PASSWORD: [api_password]" \6 -H "X-PAYPAL-SECURITY-SIGNATURE: [api_signature]" \7 -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \8 -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \9 -H "X-PAYPAL-APPLICATION-ID: [app_id]" \10 -d cancelUrl=https://example.com \11 -d currencyCode=USD \12 -d endingDate=2009-12-13T08%3A00%3A00.000Z \13 -d maxAmountPerPayment=200.00 \14 -d maxNumberOfPayments=30 \15 -d maxTotalAmountOfAllPayments=1500.00 \16 -d pinType=NOT_REQUIRED \17 -d requestEnvelope.errorLanguage=en_US \18 -d returnUrl=https://example.com \19 -d startingDate=2009-07-13T07%3A00%3A00.000Z \20 -d senderEmail=[sender@domain]
Response
1responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A002&responseEnvelope.ack=Success3&responseEnvelope.correlationId=7967b2d03745a4&responseEnvelope.build=DEV5&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 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 |