IPN Messages

PayPal sends an IPN message in response to a payment, a refund, creation of a preapproval, and cancellation of a preapproval. Your IPN message handler must be set up in the way described in the Instant Payment Notification Guide.

Specifically, it must guard against spoofing and it must be able to handle duplicate messages, which can occur, for example, if your application is both the caller of the Pay API and a receiver of the payment.

The IPN messages listed here do not use the IPN message handler that you can specify in the Profile. IPN messages are only sent to the notification URL specified in the Adaptive Payment API operation's request.

Important: IPN variable names, such as transaction[0].status, are strings and you must manipulate them as strings. Some languages, such as PHP and others, may attempt to interpret the non-alphanumeric characters found in the variable name. To avoid misinterpretation of these strings, you should always to use the raw HTTP request string and process it yourself rather than rely on the support provided by the language to obtain request parameters.

Pay Message Variables

PayPal generates an IPN message that contains information about the pay request or payment in response to the Adaptive Payments Pay and ExecutePayment API operations.

Variable Description
transaction_type The type of transaction. Possible values are:
  • Adaptive Payment PAY This notification occurs when is a payment is made due to a PayRequest. The variables for the Adaptive Payment Pay notification are similar to the PaymentDetailsResponse fields.
  • Adjustment This can be for a chargeback, reversal, or refund; check the reason_code to see which it is.
status The status of the payment. Possible values are:
  • CANCELED – The Preapproval agreement was cancelled
  • CREATED – The payment request was received; funds will be transferred once the payment is approved
  • COMPLETED – The payment was successful
  • INCOMPLETE – Some transfers succeeded and some failed for a parallel payment or, for a delayed chained payment, secondary receivers have not been paid
  • ERROR – The payment failed and all attempted transfers failed or all completed transfers were successfully reversed
  • REVERSALERROR – One or more transfers failed when attempting to reverse a payment
  • PROCESSING – The payment is in progress
  • PENDING – The payment is awaiting processing
sender_email Sender's email address.
action_type Whether the Pay API is used with or without the SetPaymentOptions and ExecutePayment API operations. Possible values are:
  • PAY – If you are not using the SetPaymentOptions and ExecutePayment API operations
  • CREATE – If you are using the SetPaymentOptions and ExecutePayment API operations
payment_request_date The date on which the payment request was initiated.
reverse_all_parallel_payments_on_error Whether the payment request specified to reverse parallel payments if an error occurs. Possible values are:
  • true – Each parallel payment is reversed if an error occurs
  • false – Only incomplete payments are reversed (default)
transaction[n].id The transaction ID, where [n] is a number from 0 to 5. For simple, single receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
transaction[n].status The transaction status, where [n] is a number from 0 to 5. For simple single-receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments. Possible values are:
  • Completed
  • Pending
  • Refunded
transaction[n].id_for_sender The transaction ID for the sender, where [n] is a number from 0 to 5. For simple, single receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
transaction[n].status_for _sender_txn The transaction status, where [n] is a number from 0 to 5. For simple single-receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments. Possible values are:
  • COMPLETED – The sender's transaction has completed
  • PENDING – The transaction is awaiting further processing
  • CREATED – The payment request was received; funds will be transferred once approval is received
  • PARTIALLY_REFUNDED– Transaction was partially refunded
  • DENIED – The transaction was rejected by the receiver
  • PROCESSING – The transaction is in progress
  • REVERSED – The payment was returned to the sender
  • REFUNDED – The payment was refunded
  • FAILED – The payment failed
transaction[n].refund_id The identification number for the refund
transaction[n].refund_amount The amount that was refunded.
transaction[n].refund_account_charged The email address of the debit account of the refund.
transaction[n].receiver The receiver's email address for the transaction
transaction[n].invoiceId The invoice number for this transaction
transaction[n].amount The payment amount of the transaction
transaction[n].is_primary_receiver Whether there is a primary receiver for this transaction, which indicates whether the transaction is a chained payment. Possible values are:
  • true – There is a primary receiver (chained payment)
  • false – There is no primary receiver (simple or parallel payment)
return_url The URL to which the sender's browser is redirected after approving a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
cancel_url The URL to which the sender's browser is redirected if the sender cancels the approval for a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
ipn_notification_url The URL to which all IPN messages for this payment are sent.
pay_key The pay key that identifies this payment. This is a token that is assigned by the Pay API after a PayRequest message is received and can be used in other Adaptive Payments APIs as well as the cancelURL and returnURL to identify this payment. The pay key is valid for 3 hours.
memo A note associated with the payment.
fees_payer The payer of PayPal fees. Possible 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)
trackingId The tracking ID that was specified for this payment in the PaymentDetailsRequest message.
preapproval_key The preapproval key returned after a PreapprovalRequest, or the preapproval key that identifies the preapproval key sent with a PayRequest.
reason_code Whether this transaction is a chargeback, partial, or reversal. Possible values are:
  • Chargeback Settlement – Transaction is a chargeback
  • Admin reversal – Transaction was reversed by PayPal administrators
  • Refund – Transaction was partially or fully refunded

Preapproval Message Variables

PayPal generates an IPN message that contains information about a preapproval in response to the Adaptive Payments Preapproval API operation.

Variable Description
transaction_type The type of transaction. For a preapproval, this variable returns Adaptive Payment Preapproval.

Note: If this variable is set to Adaptive Payment Pay or Adjustment, refer to the Pay Message Variable section.

preapproval_key The preapproval key returned after a PreapprovalRequest.
approved Whether the preapproval request was approved. Possible values are:
  • true – The preapproval was approved
  • false – The preapproval was denied
cancel_url 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 payment as follows: preapprovalKey=${preapprovalKey}
current_number_of_payments The current number of payments made for this preapproval.
current_total_amount_of_all_payments The current total of payments made for this preapproval.
current_period_attempts The current number of attempts this period for this preapproval.
currencyCode The currency code. Possible 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
date_of_month 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. A value of 0 indicates that the payment can be made on any day.
day_of_week The day of the week that a weekly payment is to be made. Possible values are:
  • NO_DAY_SPECIFIED
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
starting_date First date for which the preapproval is valid.
ending_date Last date for which the preapproval is valid. Time is currently not supported.
max_total_amount_of_all_payments The preapproved maximum total amount of all payments.
max_amount_per_payment The preapproved maximum amount of all payments.
max_number_of_payments The maximum number of payments that is preapproved.
payment_period The payment period. Possible values are:
  • NO_PERIOD_SPECIFIED
  • DAILY
  • WEEKLY
  • BIWEEKLY
  • SEMIMONTHLY
  • MONTHLY
  • ANNUALLY
pin_type Whether a personal identification number (PIN) is required. It is one of the following values:
  • NOT_REQUIRED – A PIN is not required
  • REQUIRED – A PIN is required
sender_email The sender's email address.