Help/FAQ Index / Search Help/FAQ

Paypal Instant Payment Notification

Instant Payment Notification (IPN) is PayPal's interface for handling real-time purchase confirmation and server-to-server communications. IPN delivers immediate notification and confirmation of PayPal payments you receive and provides status and additional data on pending, cancelled, or failed transactions. IPN can be used to manage and customize a variety of PayPal-enabled web services and communication, including: Customize your website's response to customer purchases in real-time Track customers via IPN "pass through" variables Deliver access keys for software downloads and other digital goods Automate your fulfillment operations Track affiliate sales and commissions Store transaction information in your own database

Instant Payment Notification (IPN) is PayPal's interface for handling real-time purchase confirmation and server-to-server communications. IPN delivers immediate notification and confirmation of PayPal payments you receive and provides status and additional data on pending, cancelled, or failed transactions. IPN can be used to manage and customize a variety of PayPal-enabled web services and communication, including: Customize your website's response to customer purchases in real-time Track customers via IPN "pass through" variables Deliver access keys for software downloads and other digital goods Automate your fulfillment operations Track affiliate sales and commissions Store transaction information in your own database

Instant Payment Notification allows you to integrate your PayPal payments with your website's back-end operations, so you get immediate notification and authentication of the PayPal payments you receive. Start using IPN. (you must have paypal account and be logged in to view this link) How It Works When a customer makes a payment to you, PayPal will post a notification to your server at a URL you specify. Included in this notification will be all of your customer's payment information (e.g. customer name, amount) as well as a piece of encrypted code. When your server receives a notification, it will then post the information, including the encrypted code, back to a secure PayPal URL. PayPal will authenticate the transaction and send confirmation of its validity back to your server. Note: To activate Instant Payment Notification, you will need to enter the URL at which you would like to receive the notification posts from your Profile. After you have activated Instant Payment Notification, your server will be sent a notification every time you receive a payment, this notification will be sent as a hidden "FORM POST" to the URL you specified, and will include all of the payment information. The FORM variables for the notification are listed at the bottom of this page. Using IPN Each time you receive an IPN from PayPal, you must complete these four steps: Perform the "Notification Validation" below Confirm that "payment_status" is "Completed" Check "txn_id" against prior transactions to prevent duplicate processing Confirm that "receiver_email" is an email address registered in your PayPal account View (you must have paypal account and be logged in to view this link) Notification Validation To ensure that a payment has been made into your PayPal account, you must verify that the email address used as your "receiver_email" has been registered and confirmed in your PayPal account. Once your server has received the Instant Payment Notification, you will need to confirm it by constructing an HTTP POST to PayPal. Your POST should be sent to https://www.paypal.com/cgi-bin/webscr You must post all of the form variables you received exactly as you received them. You will also need to append a variable named "cmd" with the value "_notify-validate" (e.g. cmd=_notify-validate) to the POST string. PayPal will respond to the post with a single word, "VERIFIED" or "INVALID", in the body of the response. When you receive a VERIFIED response, you need to: Check that the "payment_status" is "completed" If the "payment_status" is "completed", check the "txn_id" against the previous PayPal transaction you have processed to ensure it is not a duplicate. After you have checked the "payment_status" and "txn_id", make sure the "receiver_email" is an email address registered in your PayPal account Once you have completed the above checks, you may update your database based on the information provided. If you receive an "INVALID" notification, it should be treated as suspicious and investigated. Note: for maximum security, you may wish to include code to check for PayPal's digital certificate using the Verisign public key. When you connect to PayPal's secure server (https://www.paypal.com) it will present you with a digital certificate signed by a trusted Certificate Authority (Verisign). The certificate confirmation code will depend on the server platform and scripting language used in your implementation; we have provided an example of this confirmation in our Java IPN code sample. For more information on digital certificates and certificate verification, you may also check these sites: http://www.verisign.com/ http://digitalid.verisign.com/server/about/aboutFAQ.htm IPN Variables Variable Value Description business Transaction specific Email address or account ID of the payment recipient (i.e., the merchant). Essentially an echo of the "business" variable passed in the website payment button HTML code receiver_email Transaction specific Primary email address of the payment recipient (i.e., the merchant). If the payment is sent to a non-primary email address on your PayPal account, the receiver_email will still be your primary email item_name Transaction specific Item name as passed by you, the merchant. Or, if not passed by you, as entered by your customer. If this is a shopping cart transaction we will append the number of the item (e.g. item_name1, item_name2) item_number Transaction specific Item number as passed by you, the merchant. If this is a shopping cart transaction we will append the number of the item (e.g. item_number1, item_number2) quantity Transaction specific Quantity as entered by your customer or as passed by you, the merchant. If this is a shopping cart transaction we will append the number of the item (e.g. quantity1, quantity 2) invoice Transaction specific Invoice number as passed by you, the merchant. Your customer is not able to view or edit this. It must be unique per transaction custom Transaction specific Custom value as passed by you, the merchant. This is a pass-through variable that is never presented to your customer option_name1 Transaction specific Option 1 Name as requested by you option_selection1 Transaction specific Option 1 Choice as entered by your customer option_name2 Transaction specific Option 2 Name as requested by you option_selection2 Transaction specific Option 2 Choice as entered by your customer num_cart_items Shopping Cart transaction specific If this is a shopping cart transaction, number of items in cart payment_status "Completed" The payment has been completed and the funds are successfully in your account balance   "Pending" The payment is pending - see the "pending reason" variable below for more information. Note: You will receive another instant payment notification when the payment becomes "completed", "failed", or "denied"   "Failed" The payment has failed. This will only happen if the payment was made from your customer's bank account   "Denied" You, the merchant, denied the payment. This will only happen if the payment was previously pending due to one of the "pending reasons" below pending_reason "echeck" The payment is pending because it was made by an eCheck, which has not yet cleared   "multi_currency" You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment   "intl" The payment is pending because you, the merchant, hold an international account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview   "verify" The payment is pending because you, the merchant, are not yet verified. You must verify your account before you can accept this payment   "address" The payment is pending because your customer did not include a confirmed shipping address and you, the merchant, have your Payment Receiving Preferences set such that you want to manually accept or deny each of these payments. To change your preference, go to the "Preferences" section of your "Profile"   "upgrade" The payment is pending because it was made via credit card and you, the merchant, must upgrade your account to Business or Premier status in order to receive the funds   "unilateral" The payment is pending because it was made to an email address that is not yet registered or confirmed   "other" The payment is pending for an "other" reason. For more information, contact customer service payment_date Transaction specific Time/Date stamp generated by PayPal system [format: "18:30:30 Jan 1, 2000 PST"] settle_amount Transaction specific Amount that is deposited into the account's primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment settle_currency Transaction specific Currency of settle_amount exchange_rate Transaction specific for Multiple Currencies Exchange rate used if a currency conversion occurred mc_gross Transaction specific for Multiple Currencies Full amount of the customer's payment, before transaction fee is subtracted. Equivalent to "payment_gross" for USD payments. mc_fee Transaction specific for Multiple Currencies Transaction fee associated with the payment. "mc_gross" minus "mc_fee" will equal the amount deposited into the "receiver_email" account. Equivalent to "payment_fee" for USD payments. mc_currency "USD" The currency of the payment is U.S. Dollars (payment IPNs only)   "CAD" The currency of the payment is Canadian Dollars (payment IPNs only)   "GBP" The currency of the payment is Pounds Sterling (payment IPNs only)   "EUR" The currency of the payment is Euros (payment IPNs only)   "JPY" The currency of the payment is Yen (payment IPNs only) txn_id Transaction specific A unique transaction ID generated by the PayPal system txn_type "web_accept" The payment was sent by your customer via Single Item Purchases or Donations   "cart" This payment was sent by your customer via the Shopping Cart feature   "send_money" This payment was sent by your customer from the PayPal website, using the "Send Money" tab first_name Transaction specific Customer's first name last_name Transaction specific Customer's last name address_street Transaction specific Customer's street address address_city Transaction specific City of customer's address address_state Transaction specific State of customer's address address_zip Transaction specific Zip code of customer's address address_country Transaction specific Country of customer's address address_status "confirmed" Customer provided a Confirmed Address   "unconfirmed" Customer provided an Unconfirmed Address payer_email Transaction specific Customer's primary email address. Use this email to provide any credits payer_id Transaction specific Unique customer ID payer_status "verified" Customer has a Verified U.S. PayPal account   "unverified" Customer has an Unverified U.S. PayPal account   "intl_verified" Customer has a Verified International PayPal account   "intl_unverified" Customer has an Unverified International PayPal account payment_type "echeck" This payment was funded with an eCheck   "instant" This payment was funded with PayPal balance, credit card, or Instant Transfer notify_version "1.4" Version of Instant Payment Notification verify_sign Transaction specific An encrypted string used to validate the authenticity of the transaction (see below) payment_gross Transaction specific Full USD amount of the customer's payment, before transaction fee is subtracted. Will be empty for non-USD payments. This is a legacy field replaced by "mc_gross" payment_fee Transaction specific USD transaction fee associated with the payment. "payment_gross" minus "payment_fee" will equal the amount deposited into the "receiver_email" account. Will be empty for non-USD payments. This is a legacy field replaced by "mc_fee" These variables are either being added or changed as part of upcoming enhancements to the IPN code related to the Multiple Currencies feature -- you must have paypal account and be logged in to view this link. Please make sure your IPN integration is set up to allow additional variables to be added to the notifications.

View additional IPN variables for Subscriptions -- you must have paypal account and be logged in to view this link.