PreapprovalDetails API Operation

Important: Adaptive Payments is now a limited release product. It is restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

Shows information about an agreement between you and a sender for making payments on the sender's behalf.

PreapprovalDetailsRequest Message

The PreapprovalDetailsRequest message specifies the key of the preapproval agreement whose details you want to obtain.

PreapprovalDetailsRequest Fields

Field Description

getBillingAddress

xs:boolean

(Optional) An option that lets you retrieve a list of billing addresses for the sender.

  • true – Includes the billing address in the response

  • false – Omits the billing address from the response (default)

Note: This field is available only to API callers with advanced permission levels. For information, refer to the section Adaptive Payments Service Permissions.

preapprovalKey

xs:string

(Required) A preapproval key that identifies the preapproval for which you want to retrieve details. The preapproval key is returned in the PreapprovalResponse message.

requestEnvelope

common:requestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

RequestEnvelope Fields

Field Description

detailLevel

common:DetailLevelCode

(Optional) Level of detail required by the client application for components. Value is:

  • ReturnAll – This value provides the maximum level of detail (default).

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.

PreapprovalDetailsResponse Message

The PreapprovalDetailsResponse message provides details about the requested preapproval.

PreapprovalDetailsResponse Fields

Field Description

addresslist

ap:AddressList

Returns a list of billing addresses.

approved

Whether the preapproval request was approved. Value is:

  • true – The request was approved

  • false – The request was denied

cancelUrl

The URL to which the sender’s browser is redirected if the sender decides to cancel the preapproval as requested. Use the preapproval key to identify the preapproval as follows: preapprovalKey=${preapprovalKey}.

curPayments

The current number of payments by the sender for this preapproval.

curPaymentsAmount

The current total of payments by the sender for this preapproval.

curPeriodAttempts

The current number of payments by the sender this period for this preapproval.

curPeriodEndingDate

Ending date for the current period. Time is currently not supported.

currencyCode

The currency code represented by the following values:

  • 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

  • U.S. Dollar – USD

dateOfMonth

The day of the month on which a monthly payment is to be made. A number between 1 and 31 indicates the day of the month. 0 indicates that the payment can be made on any day.

dayOfWeek

The day of the week that a weekly payment is to be made. Value is:

  • NO_DAY_SPECIFIED

  • SUNDAY

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

endingDate

Last date for which the preapproval is valid. Time is currently not supported.

Note: You must specify a value unless you have specific permission from PayPal to omit this value.

ipnNotificationUrl

The URL to which all IPN messages for this preapproval are sent.

maxAmountPerPayment

The preapproved maximum amount per payment.

maxNumberOfPayments

The preapproved maximum number of payments. This field is only returned if provided.

maxNumberOfPaymentsPerPeriod

The preapproved maximum number of payments per period.

maxTotalAmountOfAllPayments

The preapproved maximum total amount of all payments.

Note: You must specify a value unless you have specific permission from PayPal to omit this value.

memo

A note about the preapproval.

paymentPeriod

The payment period. Value is:

  • NO_PERIOD_SPECIFIED

  • DAILY

  • WEEKLY

  • BIWEEKLY

  • SEMIMONTHLY

  • MONTHLY

  • ANNUALLY

pinType

Whether a personal identification number (PIN) is required. Value is:

  • NOT_REQUIRED – A PIN is not required

  • REQUIRED – A PIN is required

responseEnvelope

Common response information, including a timestamp and the acknowledgment status.

returnUrl

The URL to which the sender’s browser is redirected after the sender approves the preapproval on paypal.com. Use the preapproval key to identify the preapproval as follows: preapprovalKey=${preapprovalKey}.

senderEmail

Sender’s email address. 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.

sender.accountId

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

First date for which the preapproval is valid.

status

Whether this preapproval is active, represented by the following values:

  • ACTIVE – The preapproval is active

  • CANCELED – The preapproval was explicitly canceled by the sender or by PayPal

  • DEACTIVATED – The preapproval is not active; you can reactivate it by resetting the personal identification number (PIN) or by contacting PayPal

displayMaxTotalAmount

xs:boolean

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

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)

AddressList Fields

Field Description

AddressList

ap:Address

Returns a billing address.

Address Fields

Field Description

addresseeName

xs:string

The name associated with the address.

baseAddress

common:BaseAddress

Street address.

addressId

xs:string

The ID associated with the address.

BaseAddress Fields

Field Description

city

xs:string

The city of the address.

countryCode

xs:string

The country code of the address.

line1

xs:string

The first line of the address.

line2

xs:string

An second line of the street address.

postalCode

xs:string

The postal code of the address.

state

xs:string

The state for the address

type

xs:string.

The type of address.

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

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.

PreapprovalDetails 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.

Obtaining information about a preapproval

In this example, the caller of the PreapprovalDetails API operation specifies a preapproval key. The result shows whether or not the status has been approved, which in this case is false because the person making the approval has not completed the process on PayPal.

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/PreapprovalDetails \
  -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 preapprovalKey=PA-9JR04288NR0519129 \
  -d requestEnvelope.errorLanguage=en_US

Response

responseEnvelope.timestamp=2009-07-13T13%3A50%3A40.496-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=16dbc35f1aea7
&responseEnvelope.build=DEV
&approved=false
&cancelUrl=your_cancel_url
&curPayments=0
&curPaymentsAmount=0.00
&curPeriodAttempts=0
&currencyCode=USD
&dateOfMonth=0
&dayOfWeek=NO_DAY_SPECIFIED
&endingDate=2009-12-13T13%3A40%3A37.0-08%3A00&maxAmountPerPayment=200.00
&maxNumberOfPayments=30
&maxTotalAmountOfAllPayments=1500.00
&paymentPeriod=NO_PERIOD_SPECIFIED
&pinType=NOT_REQUIRED
&returnUrl=your_cancel_url
&startingDate=2009-07-13T13%3A40%3A37.0-07%3A00
&status=ACTIVE

Preapproval Details Errors

Code Message Additional Information
500000 There is a system error  
520002 Internal error  
520003 User name/password is incorrect  

520003

Authentication failed. API credentials are incorrect.

Since 1.6.0

520006 This call is not defined in the database  

540031

You do not have permission to get these preapproval details

Since 1.6.0

550001

User is not allowed to perform this action

580001 Invalid request  
580001 Invalid request: <value>

Since 1.6.0

589019 The preapproval key is invalid  
589019 The preapproval key <value> is invalid

Since 1.6.0