Instant Payment Notification Manual A hands-on guide to understanding and using Instant Payment Notification Last Revision: February 12, 2004
PayPal Instant Payment Notification Manual Copyright © 2004 PayPal, Inc. All Rights Reserved Notice of Liability The information in this manual is distributed in an “as is” basis. All information provided in this document is provided with good will. The authors and publishers of this manual are not responsible for loss, or purported loss due to any contents of this publication.
Table of Contents Introduction to Instant Payment Notification (IPN) 1 IPN in Action 2 Instant Payment Notification How It Works 5 IPN Variables 5 Restrictions on Field Lengths and Data Types 5 Using IPN Setting up IPN 13 Notification Validation 13 Specifying Your Notification URL 14 Using IPN with Subscriptions and Recurring Payments Subscriptions Variables 15 Variables for Each Subscription Type 16 Testing IPN Using IPN with Multiple Currencies payment_gross and payment_fee 22 Multi-
Instant Payment Notification Manual Introduction to Instant Payment Notification (IPN) Automate online payments with back-end server-to-server integration PayPal’s Instant Payment Notification (IPN) allows you to integrate PayPal payments with your website’s back-end operations. IPN provides immediate notification and confirmation of PayPal payments you receive, allowing you to: • Customize your website’s response to customer purchases in real-time.
Instant Payment Notification Manual IPN in Action How IPNs are sent Step 1: Your buyer comes to your website and clicks on a PayPal Buy Now button to make a purchase. Step 2: After your buyer checks the payment details and sends the payment, he will see a confirmation page, as shown in the following diagram. Copyright 2004 PayPal, Inc.
Instant Payment Notification Manual Step 3: At the time the payment is made, PayPal will post a notification to your server at the URL you specified. All of your customer’s payment information and a piece of encrypted code will be included in this notification. Step 4: On receiving the notification, your server will send the information, including the encrypted code, back to a secure PayPal URL. PayPal will authenticate the transaction by checking the encrypted string.
Instant Payment Notification Manual Step 6: After successfully completing the checks, you can update your database with the IPN data and process the purchase. Copyright 2004 PayPal, Inc.
Instant Payment Notification Manual Instant Payment Notification Back-end server-to-server integration 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. Note: To activate Instant Payment Notification, you will need to go to your Profile to enter the URL at which you would like to receive notification posts.
Instant Payment Notification Manual Variable Value Description business Transaction-specific Email address or account ID of the payment recipient (i.e., the merchant). Equivalent to receiver_email if payment is sent to primary account, and 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).
Instant Payment Notification Manual Variable Value Description option_name2 Transaction-specific Option 2 name as requested by you. option_selection2 Transaction-specific Option 2 choice as entered by your customer. Shopping Cart Information num_cart_items Transaction-specific for PayPal Shopping Cart If this is a PayPal Shopping Cart transaction, number of items in cart.
Instant Payment Notification Manual Variable Value 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 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.
Instant Payment Notification Manual Variable Value Description reason_code This variable is only set if payment_status = "Reversed" or “Refunded”. “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. “guarantee” A reversal has occurred on this transaction due to your customer triggering a moneyback guarantee.
Instant Payment Notification Manual Variable Value Description Currency and Exchange Information mc_gross Transactionspecific for Multiple Currencies 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.
Instant Payment Notification Manual Variable Value Description payment_gross Transaction-specific for USD payments only 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. 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.
Instant Payment Notification Manual Variable Value Description address_name Transaction-specific Name used with address (Included when the customer provides a Gift Address). 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.
Instant Payment Notification Manual Using IPN Getting set up to use IPN and validate notifications Setting up IPN To set up IPN: 1. Log in to your Business or Premier PayPal account. 2. Click the Profile subtab. 3. Click on the Instant Payment Notification Preferences link in the Selling Preferences column. 4. Click Edit. 5. Click the checkbox and enter the URL at which you would like to receive your IPN Notifications. 6. Click Save.
Instant Payment Notification Manual When you receive a VERIFIED response, perform the following checks: 1. Check that the payment_status is Completed. 2. 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. 3. After you have checked the payment_status and txn_id, make sure the receiver_email is an email address registered in your PayPal account. 4.
Instant Payment Notification Manual Using IPN with Subscriptions and Recurring Payments Additional information if you receive PayPal Subscriptions payments Subscriptions Variables In addition to the variables listed in the previous table, the following variables are included in Subscriptions IPNs: Variable Value Description txn_type “subscr_signup” This IPN is for a subscription sign-up. “subscr_cancel” This IPN is for a subscription cancellation.
Instant Payment Notification Manual Variable Value Description mc_amount3 Transaction-specific Amount of payment for regular subscription period, regardless of currency. mc_currency For non-payment subscriptions IPNs (i.e., txn_type = signup, cancel, failed, eot, or modify), this is the currency of the subscription. For payment IPNs, it is the currency of the payment (i.e., txn_type = subscr_payment) “USD” The currency of the subscription is U.S. Dollars.
Instant Payment Notification Manual Signup Cancel Modify Payment (USD) Payment (MC) Failed EOT business X X X X X X X receiver_email X X X X X X X X X Variable 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_selection1 X X X X X X X option_name2 X X X X X X X option_selection2 X X X
Instant Payment Notification Manual Signup Cancel Modify Payment (USD) Payment (MC) Failed EOT first_name X X X X X X X last_name X X X X X X X X X Variable Buyer Information payer_business_ name address_name X X X X X address_street X X X X X address_city X X X X X address_state X X X X X address_zip X X X X X address_country X X X X X address_status X X X X X payer_email X X X X X X X payer_id X X X X X X X payer_status
Instant Payment Notification Manual Variable Signup Cancel Modify mc_amount3 X X X recurring X X X reattempt X X X Payment (USD) Payment (MC) 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 Copyright 2004 PayPal, Inc.
Instant Payment Notification Manual Testing IPN You should always test your IPN implementation with the live PayPal system. Here’s an easy way to do it: 1. Sign up for a Personal PayPal account if you don’t already have one, and add a credit card to the account. This will be your “buyer” account. Note: According to the PayPal User Agreement, you may have one Personal and one Premier/Business account.
Instant Payment Notification Manual Testing tip 2: In your Website Payments button HTML code, add or modify the return and rm variables as follows (replacing the URL with the URL for your website): Then, from the buyer account, click on the Website Payments button and complete the transaction.
Instant Payment Notification Manual Using IPN with Multiple Currencies With multiple currencies, you can accept payments in U.S. Dollars, Canadian Dollars, Euros, Pounds Sterling, and Yen. As a result, your IPNs will then include information about the currency of the payment. The following overview explains how IPN interacts with multiple currencies. Note: If you are using one of PayPal’s Website Payments solutions (e.g. PayPal Shopping Cart), and would like to be paid in a currency other than U.S.
Instant Payment Notification Manual Note: If payment is in USD, the payment_fee value will equal mc_fee. • mc_currency: Currency of mc_gross, mc_fee, payment_gross, and payment_ fee amounts. The values are (note the capitalization): – USD – EUR – GBP – CAD – JPY For non-payment subscription IPNs, such as signup, cancel, modify, failed, and eot, mc_currency will refer to the currency of the subscription, rather than the currency of the payment.
Instant Payment Notification Manual Example 2: If a user with a CAD balance receives a $100 CAD payment, the following variables will be used for the payment: • mc_gross and mc_fee have values • payment_gross and payment_fee are blank Example 2: CAD Payment (subscr_payment IPN) payment_status = Completed payment_gross = payment_fee = mc_gross =100 mc_fee = 3.
Instant Payment Notification Manual Example 3: If the account is set to automatically convert payments, these variables will be used to show the conversion. This example is for a user with a USD balance who receives a payment of 100 GBP: Example 3: Automatic Conversion of GBP Payment payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP settle_amount = 145.5 settle_currency = USD exchange_rate = 1.
Instant Payment Notification Manual The second IPN would contain information about settling the payment. If the payment is accepted into the account’s primary currency, which is USD in the following example: Example 5: Pending - Convert to Primary Currency payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP settle_amount = 145.5 settle_currency = USD exchange_rate = 1.
Instant Payment Notification Manual If the payment is denied: Example 7: Pending - Deny payment_status = Denied payment_gross = mc_gross = 100 mc_currency = GBP Note: If a user receives a payment into a currency balance and later converts this amount into another currency balance, the corresponding currency conversion transaction has no IPN. Copyright 2004 PayPal, Inc.
Instant Payment Notification Manual Where to Get Help with IPN PayPal Help If you need further assistance, go to http://www.paypal.com/wf/, click the Seller Tools topic, and then click Instant Payment Notification (IPN). PayPal Developer Discussion Boards You can also check the PayPal Developer Discussion Boards at http://www.paypaldev.org for help Copyright 2004 PayPal, Inc.
