Instant Payment Notification Guide Last updated: July 10, 2012
IPN Guide Document Number: 10087.en_US-20120710 © 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Chapter 1 Introducing IPN . . . . . . . . . . . . . . . . . . . . . . . 7 IPN Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 IPN Protocol and Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 IPN Messages Generated by PayPal Payments Standard . . .
Contents Chapter 6 Using Fraud Management Filters With IPN . . . . . . . . . 37 Chapter 7 IPN Variable Reference . . . . . . . . . . . . . . . . . . . 41 IPN Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Transaction and Notification-Related Variables . . . . . . . . . . . . . . . . . . . . . . . 42 Buyer Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Payment Information Variables . . . . . . . . . . . . . . . . .
Preface This document describes the Instant Payment Notification (IPN) message service. Documentation Feedback Help us improve this guide by sending feedback to: documentationfeedback@paypal.
Documentation Feedback 6 July 10, 2012 IPN Guide
1 Introducing IPN Instant Payment Notification (IPN) is a message service that notifies you of events related to PayPal transactions. You can use it to automate back-office and administrative functions, such as fulfilling orders, tracking customers, and providing status and other information related to a transaction.
Introducing IPN IPN Overview Trigger order fulfillment or enable media downloads when a check clears or a payment is made Update your list of customers Update accounting records Create specialized “to do” lists based on the kind of event You are typically notified of events by email as well, but the IPN message service enables you to automate your response to events.
Introducing IPN IPN Protocol and Architecture The diagram shows requests and responses, which are the result of processing button clicks or API operations on PayPal. PayPal sends an IPN message when it sends a response to a request. The IPN message is not actually part of the response sent to your website. Rather, the IPN message is sent to the your listener, which allows you to take actions that are not directly tied to the operation of your website.
Introducing IPN IPN Protocol and Architecture 2. Your listener sends the complete unaltered message back to PayPal; the message must contain the same fields in the same order and be encoded in the same way as the original message 3. PayPal sends a single word back, which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent Your listener must respond to each message, whether or not you intend to do anything with it.
Introducing IPN IPN Protocol and Architecture IPN Messages Generated by PayPal Payments Standard PayPal generates an IPN message when your customer clicks a PayPal Payments Standard (previously known as Website Payments Standard) payment button, such as a Buy Now button, and completes the transaction on PayPal. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.
Introducing IPN IPN Protocol and Architecture IPN Messages Generated by APIs PayPal generates an IPN message when you invoke an API operation, such as DoExpressCheckoutPayment of DoDirectPayment during checkout or an Adaptive Payments Pay, Preapproval, or ExecutePayment API operation. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.
Introducing IPN IPN Protocol and Architecture IPN Messages Generated by a Back-Office Procedure PayPal generates an IPN message when you perform actions that invoke the PayPal API, regardless of whether it is from your website or from a back-office or administrative procedure. You can use this notification to trigger an email to your customer, store information in a CRM or accounting system, and so on.
Introducing IPN A Sample IPN Message and Response PayPal-Initiated IPN Messages Some IPN messages generated by PayPal are not directly associated with a web flow. PayPal generates an IPN message when external events arise that might affect a transaction, such as disputes, chargebacks, echeck clearing, and various recurring payment and subscription events. In this case, events that trigger IPN messages are not directly related to actions on your website.
Introducing IPN A Sample IPN Message and Response mc_gross=19.95&protection_eligibility=Eligible&address_status=confirmed&pay er_id=LPLWNMTBWMFAY&tax=0.00&address_street=1+Main+St&payment_date=20%3A12% 3A59+Jan+13%2C+2009+PST&payment_status=Completed&charset=windows1252&address_zip=95131&first_name=Test&mc_fee=0.88&address_country_code=US& address_name=Test+User¬ify_version=2.
Introducing IPN A Sample IPN Message and Response Variable Notes address_street = 1 Main St address_zip = 95131 Information about the payment: custom = Your custom field handling_amount = 0.00 item_name = item_number = mc_currency = USD mc_fee = 0.88 mc_gross = 19.95 payment_date = 20:12:59 Jan 13, 2009 PST payment_fee = 0.88 payment_gross = 19.
Introducing IPN Non-IPN Notification Mechanisms PayPal will then send one single-word message, VERIFIED, if the message is valid; otherwise, it will send another single-word message, INVALID. IM PORT AN T : After you receive the VERIFIED message, there are several important checks you must perform before you can assume that the message is legitimate and not already processed: Non-IPN Notification Mechanisms You can use IPN with other notification mechanisms.
Introducing IPN Non-IPN Notification Mechanisms 18 July 10, 2012 IPN Guide
2 Implementing an IPN Listener You write your IPN listener in the scripting or programming language of your choice and host it on your web server. You can use sample code provided by PayPal as a starting point. The PayPal SDKs for PayPal Payments Standard contain sample code in various programming languages that you can modify to create your own listener.
Implementing an IPN Listener 20 July 10, 2012 IPN Guide
3 Identifying Your IPN Listener to PayPal After you implement and test your IPN listener, you make your listener known to PayPal by specifying the listener’s URL in your account’s profile. Optionally, you can override the URL to specify another listener for specific payments.
Identifying Your IPN Listener to PayPal Setting Up IPN Notifications on PayPal 4. Specify the URL for your listener in the Notification URL field. 5. Click Receive IPN messages (Enabled) to enable your listener. 6. Click Save. The following screen appears: 7. Click Back to Profile Summary to return to the Profile after activating your listener. You also can click Edit settings to modify your notification URL or disable your listener. You can click Turn Off IPN to reset your IPN preferences.
Identifying Your IPN Listener to PayPal Dynamically Setting the Notification URL Dynamically Setting the Notification URL You can specify an IPN listener for a specific payment; this is the only way to receive IPNs associated with Adaptive Payments. In this case, PayPal sends the IPN message to the listener specified in the notification URL for a specific button or API operation instead of the listener specified in your Profile. To specify a notification URL For a/an ...
Identifying Your IPN Listener to PayPal Dynamically Setting the Notification URL 24 July 10, 2012 IPN Guide
4 IPN Testing After you implement your listener and start it running on your web server, you can use the IPN simulator in the Sandbox to send IPN messages to the URL at which your listener is running. This tool allows you to verify that you are receiving IPN messages correctly. Testing Your Listener IPN Troubleshooting Tips Testing Your Listener The first level of testing is to ensure that your IPN listener receives messages and handles them appropriately.
IPN Testing Testing Your Listener 3. Keep or modify the values of fields that you want to include in the IPN. By default, only populated fields are displayed. You can check the Show all fields box to view all fields. The simulator does not check the validity of fields that you change.
IPN Testing IPN Troubleshooting Tips 4. Click Send IPN. The IPN message is sent to the specified URL and the results of the operation are displayed at the top of the page. After Completing This Task: If your IPN listener receives a message, you know that it is properly installed on your web server. The default messages sent by the IPN simulator are valid, thus, if your listener responds correctly to the message, it should receive a VERIFIED message.
IPN Testing IPN Troubleshooting Tips Ensure that you are encoding your response string and are using the same character encoding as the original message. NOT E : 28 If you receive multiple IPN messages for the same transaction or if messages appear to be out of order, this is not necessarily an indication that your listener is malfunctioning. For example, if you do not respond in time, PayPal resends the message.
5 IPN Operations on PayPal The IPN History page on PayPal provides additional information to help you troubleshoot IPN messages. You can use the IPN History page to determine the status of IPN messages and to resend them, if necessary. Using the IPN History Resending IPN Messages Using the IPN History Use the IPN History page on PayPal to view IPN messages sent to you from PayPal and request that messages be resent.
IPN Operations on PayPal Using the IPN History The search results contain the following information: The date and time that PayPal created the IPN message Whether this IPN message was the original message or whether it was resent, which is indicated in the Date/time created column The IPN message ID assigned by PayPal The current status, which is one of the following values: – Sent indicates that PayPal sent the message to your IPN listener – Failed indicates that PayPal did not receive an a
IPN Operations on PayPal Using the IPN History – Queued indicates that PayPal is ready to send the message – Retrying indicates that message was resent between 1 and 15 times and PayPal continues to be resend the message – Disabled indicates that the message will not be resent because the merchant’s account has been disabled NOT E : If you have requested that PayPal resend the IPN message and the status has not been updated for the attempt, resending is appended to the status, e.g. Failed - resending.
IPN Operations on PayPal Using the IPN History In addition to the information on the IPN History page, the details contain the following information: 32 Whether this IPN message was the original message or whether it was resent The last time the message was resent The URL on which your listener was running when the message was sent The number of retries before the message was successfully acknowledged The type of IPN message July 10, 2012 IPN Guide
IPN Operations on PayPal Resending IPN Messages Resending IPN Messages You can use the IPN History page to request that PayPal resend one or more IPN messages. You can search the IPN message history for the messages that may need to be resent and then select them. To make a request that PayPal resend IPN messages, mark one or more messages for PayPal to resend and click the Resend selected button to make the request: If you check the box for To send an IPN again to a profile URL...
IPN Operations on PayPal Resending IPN Messages not check this option, PayPal sends the message to the same URL to which the original message was sent, which is not necessarily the current profile URL. You may receive a confirmation notice alerting you to the possibility that you will receive duplicate messages. Click Confirm to resend; otherwise click Cancel: After you make the request, PayPal notifies you that the messages have been resent and updates the status.
IPN Operations on PayPal Resending IPN Messages When the message has been sent, your server’s response to the HTTP POST is used to update the HTTP response code field. A value of 200 indicates that your server successfully received the IPN message. Other values typically indicate a server configuration error for the server that hosts your IPN listener. For more information about these codes, see RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1.
IPN Operations on PayPal Resending IPN Messages 36 July 10, 2012 IPN Guide
6 Using Fraud Management Filters With IPN Fraud Management Filter actions are reported in IPN payment messages only when a filter causes the payment to be pended awaiting your review or a when you accept or deny a filterpended payment. Filter actions are not reported when filters flag payments for review, allow payments to be accepted, or cause them to be denied.
Using Fraud Management Filters With IPN txn_type = virtual_terminal payment_date = 17:11:42 Jul 15, 2008 PDT last_name = receipt_id = 3075-7371-4622-1677 residence_country = US pending_reason = address item_name = payment_gross = 3.33 mc_currency = USD business = acqrte_1215804264_biz@gmail.com payment_type = instant verify_sign = APYUGJhXGkUmvFnZf4I5co6CedKKAowZjfT4T7GXWJMDnZ0uFLkcq.oH payer_status = unverified test_ipn = 1 fraud_management_pending_filters_1 = Maximum Transaction Amount tax = 0.
Using Fraud Management Filters With IPN txn_type = virtual_terminal payment_date = 17:11:42 Jul 15, 2008 PDT last_name = receipt_id = 3075-7371-4622-1677 residence_country = US item_name = payment_gross = 3.33 mc_currency = USD business = acqrte_1215804264_biz@gmail.com payment_type = instant verify_sign = AFcWxV21C7fd0v3bYYYRCpSSRl31AjcbYkD.VCCBmpD4lZq.yYTxBKkr payer_status = unverified test_ipn = 1 fraud_management_pending_filters_1 = Maximum Transaction Amount tax = 0.
Using Fraud Management Filters With IPN txn_type = virtual_terminal payment_date = 17:09:40 Jul 15, 2008 PDT last_name = receipt_id = 0739-3836-3393-2098 residence_country = US item_name = payment_gross = 2.11 mc_currency = USD business = acqrte_1215804264_biz@gmail.com payment_type = instant verify_sign = AFcWxV21C7fd0v3bYYYRCpSSRl31ASrKFBPwac7aQm47p8CMLrdParSt payer_status = unverified test_ipn = 1 fraud_management_pending_filters_1 = Maximum Transaction Amount tax = 0.
7 IPN Variable Reference PayPal returns related variables for each kind of IPN message. Not all variables are returned for each type of transaction.
IPN Variable Reference Transaction and Notification-Related Variables Transaction Type (txn_type) Description new_case A new dispute was filed recurring_payment Recurring payment received recurring_payment _expired Recurring payment expired recurring_payment _profile_created Recurring payment profile created recurring_payment _skipped Recurring payment skipped; it will be retried up to a total of 3 times, 5 days apart send_money Payment received; source is the Send Money tab on the PayPal webs
IPN Variable Reference Buyer Information Variables Variable Name Description ipn_track_id Internal; only for use by MTS and DTS notify_version Message’s version number parent_txn_id In the case of a refund, reversal, or canceled reversal, this variable contains the txn_id of the original transaction, while txn_id contains a new ID for the new transaction. Length: 19 characters receipt_id Unique ID generated during guest checkout (payment by credit card without logging in).
IPN Variable Reference Payment Information Variables Variable Name Description address_city City of customer’s address Length: 40 characters address_country_code ISO 3166 country code associated with customer’s address Length: 2 characters address_name Name used with address (included when the customer provides a Gift Address) Length: 128 characters address_state State of customer’s address Length: 40 characters address_status Whether the customer provided a confirmed address.
IPN Variable Reference Payment Information Variables Variable Name Description auth_exp Authorization expiration date and time, in the following format: HH:MM:SS DD Mmm YY, YYYY PST Length: 28 characters auth_id Authorization identification number Length: 19 characters auth_status Status of authorization echeck_time_processed The time an eCheck was processed; for example, when the status changes to Success or Completed. The format is as follows: hh:mm:ss MM DD, YYYY ZONE, e.g.
IPN Variable Reference Payment Information Variables 46 Variable Name Description mc_gross Full amount of the customer's payment, before transaction fee is subtracted. Equivalent to payment_gross for USD payments. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction. mc_gross_x The amount is in the currency of mc_currency, where x is the shopping cart detail item number.
IPN Variable Reference Payment Information Variables Variable Name Description payment_date Time/Date stamp generated by PayPal, in the following format: HH:MM:SS Mmm DD, YYYY PDT Length: 28 characters payment_fee USD transaction fee associated with the payment. payment_gross minus payment_fee equals the amount deposited into the receiver email account. Is empty for non-USD payments.
IPN Variable Reference Payment Information Variables 48 Variable Name Description payment_status The status of the payment: Canceled_Reversal: A reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. Completed: The payment has been completed, and the funds have been added successfully to your account balance. Created: A German ELV payment is made using Express Checkout. Denied: You denied the payment.
IPN Variable Reference Payment Information Variables Variable Name Description pending_reason This variable is set only if payment_status = Pending. address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set yo allow you to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.
IPN Variable Reference Auction Variables Variable Name Description reason_code This variable is set if payment_status =Reversed, Refunded, or Canceled_Reversal. adjustment_reversal: Reversal of an adjustment buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. chargeback: A reversal has occurred on this transaction due to a chargeback by your customer.
IPN Variable Reference Mass Pay Variables Variable Name Description auction_buyer_id The customer’s auction ID. Length: 64 characters auction_closing_date The auction’s close date, in the following format: HH:MM:SS DD Mmm YY, YYYY PST Length: 28 characters auction_multi_item The number of items purchased in multi-item auction payments.
IPN Variable Reference Recurring Payments Variables Variable Name Description payment_status Completed: For Mass Payments, this means that all of your payments have been claimed, or after a period of 30 days, unclaimed payments have been returned to you. Denied: For Mass Payments, this means that your funds were not sent and the Mass Payment was not initiated. This may have been caused by lack of funds. Processed: Your Mass Payment has been processed and all payments have been sent.
IPN Variable Reference Recurring Payments Variables Variable Name Description outstanding_balance Outstanding balance for recurring payments payment_cycle Payment cycle for recurring payments period_type Kind of period for a recurring payment product_name Product name associated with a recurring payment product_type Product name associated with a recurring payment profile_status Profile status for a recurring payment recurring_payment_id Recurring payment ID rp_invoice_id The merchant’s ow
IPN Variable Reference Recurring Payments Variables Summary of recurring payment variables Variables Profile created message Recurring payment message Basic Information X business receiver_email X X X receiver_id Transaction Information payment_status X payment_type X payment_date X txn_id X initial_payment_status X X initail_payment_txn_id txn_type recurring_payment_profile_ created recurring_payment Currency and Exchange mc_gross X mc_fee X mc_currency X payment_gross X curren
IPN Variable Reference Subscription Variables Variables Profile created message Recurring payment message payer_id X X payer_status X X residence_country X X address_country_code X address_status X Recurring Payment recurring_payment_id X X rp_invoice_id X X product_name X X product_type X X period_type X X payment_cycle X X outstanding_balance X X amount_per_cycle X X initial_payment_amount X X profile_status X X amount X X time_created X X next_payment_
IPN Variable Reference Subscription Variables 56 Variable Name Description amount2 Amount of payment for trial period 2 for USD payments; otherwise blank (optional). amount3 Amount of payment for regular subscription period for USD payments; otherwise blank. mc_amount1 Amount of payment for trial period 1, regardless of currency (optional). mc_amount2 Amount of payment for trial period 2, regardless of currency (optional).
IPN Variable Reference Subscription Variables Summary of subscription variables Signup Cancel Modify USD Payment business X X X X receiver_email X X X Variable MultiCurrency Payment Refund Failed EOT X X X X X X X X X Basic Information receiver_id item_name X X X X X X X item_number X X X X X X X Advanced and Custom Information invoice X X X X X X X custom X X X X X X X option_name1 X X X X X X X option_selecti on1 X X X X X X X o
IPN Variable Reference Subscription Variables Variable Signup Cancel Modify USD Payment payment_gross X payment_fee X MultiCurrency Payment Refund Failed EOT X X Buyer Information first_name X X X X X X X last_name X X X X X X X payer_business _name X X X X X X address_name X X X X X X address_street X X X X X X address_city X X X X X X address_state X X X X X X address_zip X X X X X X address_ country X X X X X X payer_email
IPN Variable Reference Dispute Resolution Variables Variable Signup Cancel Modify recurring X X X reattempt X X X USD Payment MultiCurrency Payment Refund Failed EOT X retry_at recur_times X X X username X X X X X X X password X X X X X X X subscr_id X X X X X X X Dispute Resolution Variables Dispute resolution information identifies the case ID and status associated with a dispute.
IPN Variable Reference Pay Message Variables Variable Name Description reason_code Reason for the case. Values for case_type set to complaint: non_receipt: Buyer claims that he did not receive goods or service. not_as_described: Buyer claims that the goods or service received differ from merchant’s description of the goods or service. Values for case_type set to chargeback: unauthorized adjustment_reimburse: A case that has been resolved and close requires a reimbursement.
IPN Variable Reference Pay Message Variables Variable Description status The status of the payment.
IPN Variable Reference Pay Message Variables 62 Variable Description transaction[n].status_fo r _sender_txn The transaction status, where [n] is a number from 0 to 5. For simple singlereceiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
IPN Variable Reference Preapproval Message Variables Variable Description fees_payer The payer of PayPal fees.
IPN Variable Reference Preapproval Message Variables 64 Variable Description 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.
IPN Variable Reference Preapproval Message Variables Variable Description currencyCode The currency code.
IPN Variable Reference Adaptive Accounts IPN Messages Variable Description 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.
IPN Variable Reference Adaptive Accounts IPN Messages Field Description notify_version Message’s version number first_name Account holder’s first name last_name Account holder’s last name verify_sign Encrypted string used to validate the authenticity of the transaction charset Character set account_key Account key returned by the CreateAccount API operation confirmation_code Confirmation code event_type The kind of event: ACCOUNT_CONFIRMED indicates that the account holder has set a pass
IPN Variable Reference Payment Review Using Notifications Payment Review Using Notifications If PayPal places a payment under review, PayPal sends messages containing the payment_status and pending_reason variables. In addition, it sends a protection_eligibility variable that identifies the kind of protection in force for the transaction. The initial IPN or PDT message indicates that the payment is under review: The payment_status variable is set to Pending.
Revision History Revision history for PayPal Instant Payment Notification Guide. Date Published Description 07/10/12 Maintenance release. 05/22/12 Maintenance release. 05/02/12 Maintenance release. 04/03/12 Updated references to Website Payments Standard and Website Payments Pro to PayPal Payments Standard and PayPal Payments Pro, respectively. 02/14/12 Maintenance release. 07/26/11 Added additional IPN variables and transaction types; echeck_time_processed is new for revision 78.0.
July 10, 2012 IPN Guide
