Instant Payment Notification Guide For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l’instant.
IPN Guide Document Number: 10087.en_US-20090626 © 2009 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. PayPal (Europe) Ltd.
Contents Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Chapter 1 Introducing IPN . . . . . . . . . . . . . . . . . . . . . . . 7 What is IPN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 IPN Protocol and Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Transaction and Notification-Related Variables . . . . . . . . . . . . . . . . . . . . . . . 42 Buyer Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Payment Information Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Auction Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Mass Pay Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface This document describes the Instant Payment Notification (IPN) message service. Intended Audience This document is intended for merchants implementing IPN. Revision History Revision history for Instant Payment Notification Guide. TABLE P.1 Revision History IPN Guide Date Description 06/26/09 Added information about IPN messages related to payment review. Updated the section about setting up IPN notifications on PayPal and added a note about the delivery of IPN messages to the notify URL.
Revision History 6 June, 2009 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 What is IPN? administrative processes that respond the messages. PayPal provides sample code that you can modify to implement a listener that detects IPN messages. The actions to take when your listener is notified of an event are specific to your needs.
Introducing IPN IPN Protocol and Architecture 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. NOTE: The diagram does not show the IPN authentication protocol messages that validate the IPN message. IPN is an asynchronous message service, meaning that messages are not synchronized with actions on your website.
Introducing IPN IPN Protocol and Architecture 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. If you do not respond, PayPal assumes that the message was not received and resends the message.
Introducing IPN IPN Protocol and Architecture The numbers in diagram correspond to the following steps: 1. The button action initiates a payment that completes on PayPal 2. PayPal sends your IPN listener a message that notifies you of the event 3. 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 4.
Introducing IPN IPN Protocol and Architecture The numbers in diagram correspond to the following steps: 1. The API operation initiates a payment on PayPal. 2. PayPal sends your IPN listener a message that notifies you of the event 3. 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 4.
Introducing IPN IPN Protocol and Architecture The numbers in diagram correspond to the following steps: 1. Your back-office or administrative process invokes a PayPal API operation; for example, it could invoke the RefundTransaction API operation when your employee issues a refund. 2. PayPal sends your IPN listener a message that notifies you of the event 3.
Introducing IPN A Sample IPN Message and Response The numbers in diagram correspond to the following steps, which implement the IPN message authentication protocol: 1. PayPal sends your IPN listener a message that notifies you of the event 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.
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. IMPORTANT: 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: Confirm that the payment status is Completed.
Introducing IPN Non-IPN Notification Mechanisms 18 June, 2009 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 Website Payments Standard contain sample code in various programming languages that you can modify to create your own listener.
Implementing an IPN Listener 6. If the verified response passes the checks, take action based on the value of the txn_type variable if it exists; otherwise, take action based on the value of the reason_code variable. 7. If the response is INVALID, save the message for further investigation. A sample test listener using PHP The following listener sends email to the address specified in the ipn_email variable, as in https://your_host/live_ipn_mail.php?ipn_email=email_address.
Implementing an IPN Listener $value) // Handle escape characters, which depends on setting of magic quotes { if($get_magic_quotes_exists == true && get_magic_quotes_gpc() == 1) { $value = urlencode(stripslashes($value)); } else {
Implementing an IPN Listener } mail($email, "Live-INVALID IPN", $emailtext . "\n\n" .
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. 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 ... specify your IPN Listener’s URL in the ...
Identifying Your IPN Listener to PayPal Dynamically Setting the Notification URL 26 June, 2009 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. z Testing Your Listener z 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 z Ensure that you are encoding your response string and are using the same character encoding as the original message. NOTE: 30 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. z Using the IPN History z 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 z Whether this IPN message was the original message or whether it was resent, which is indicated by the asterisk (*) in the Date/time created column z The IPN message ID assigned by PayPal z 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 acknowledgement to the message Queued indicates that PayPal is ready to send the message
IPN Operations on PayPal Resending IPN Messages In addition to the information on the IPN History page, the details contain the following information: z Whether this IPN message was the original message or whether it was resent z The last time the message was resent z The URL on which your listener is running NOTE: You cannot change the URL; if you request PayPal to resend an IPN message, it is sent to this URL.
IPN Operations on PayPal Resending IPN Messages 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: 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 June, 2009 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 send_money Payment received; source is the Send Money tab on the PayPal website subscr_cancel Subscription canceled subscr_eot Subscription expired subscr_failed Subscription signup failed subscr_modify Subscription modified subscr_payment Subscription payment received subscr_signup Subscription started virtual_terminal Payment received; source is Virtual Terminal web_accept Paym
IPN Variable Reference Buyer Information Variables Variable Name Description receiver_email Primary email address of the payment recipient (that is, the merchant). If the payment is sent to a non-primary email address on your PayPal account, the receiver_email is still your primary email. NOTE: The value of this variable is normalized to lowercase characters. Length: 127 characters receiver_id Unique account ID of the payment recipient (i.e., the merchant).
IPN Variable Reference Payment Information Variables Variable Name Description address_status Whether the customer provided a confirmed address. It is one of the following values: z confirmed – Customer provided a confirmed address. z unconfirmed – Customer provided an unconfirmed address. address_street Customer’s street address. Length: 200 characters address_zip Zip code of customer’s address. Length: 20 characters contact_phone Customer’s telephone number.
IPN Variable Reference Payment Information Variables Variable Name Description fraud_managment_pending_fil ters_x One or more filters that identify a triggering action associated with one of the following payment_status values: Pending, Completed, Denied, where x is a number starting with 1 that makes the IPN variable name unique; x is not the filter’s ID number.
IPN Variable Reference Payment Information Variables 46 Variable Name Description mc_fee Transaction fee associated with the payment. mc_gross minus mc_fee equals the amount deposited into the receiver_email account. Equivalent to payment_fee 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 fee.
IPN Variable Reference Payment Information Variables Variable Name Description option_selection2 Option 2 choice as entered by your customer. PayPal appends the number of the item where x represents the number of the shopping cart detail item (e.g., option_selection1, option_selection2). Length: 200 characters payer_status Whether the customer has a verified PayPal account. z verified – Customer has a verified PayPal account. z unverified – Customer has an unverified PayPal account.
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 Cancelled_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 currenc
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 op
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 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 Payment Review Using Notifications Variable Name Description reason_code Reason for the case. Values for case_type set to complaint: z non_receipt: Buyer claims that he did not receive goods or service. z 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: z unauthorized z adjustment_reimburse: A case that has been resolved and close requires a reimbursement.