Preapproval API Operation

API

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:

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

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:

      12010-09-10Z
      22010-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
    • 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
    • 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.
    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:
    • 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
    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:
    • 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.
    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:
    • 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
    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.
    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%3A00
        2&responseEnvelope.ack=Success
        3&responseEnvelope.correlationId=7967b2d03745a
        4&responseEnvelope.build=DEV
        5&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

        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