Lives On Board

/ My MetaSphere /

Wed Dec 3, 2003

Flash MX Hosting
Web Hosting
Web Tools
Help FAQ
Marketing
Portfolio
Contact
Site Chat
Web Search
Asheville NC
NEW!!Boards
Network Log
Got Flash?
Web Links

Need Help?
We are online if image is green.
We are online if this image is green. Click here to chat live with metasphere.net.

In Memory of the passing of one of America's greatest photographers, Jorge Otero. Jaophoto.com

Flash Hosting with MetaSphere

Today in History:
1818: Illinois entered the Union as the 21st state.

Metasphere.net
Asheville, NC
Help/FAQ Index / Search
Help/FAQ
Previous Page in Help/FAQ Tour Next Page in Help/FAQ Tour
Return to Main Page in 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:
  1. Perform the "Notification Validation" below
  2. Confirm that "payment_status" is "Completed"
  3. Check "txn_id" against prior transactions to prevent duplicate processing
  4. 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.

 




Refresh / Add Page to favorites/bookmarks.