Ipn

Last Updated: 1.02.2003

Table of Contents Table of Contents...................................................................................................1 Introduction to Instant Payment Notification (IPN) ...................................................2 IPN in Action ..........................................................................................................3 Using IPN .............................................................................................................11 Using IPN with Subscriptions ................................................................................13 Testing IPN...........................................................................................................16 Using IPN with Multiple Currencies .......................................................................17 IPN Frequently Asked Questions............................................................................21

The PayPal Instant Payment Notification (IPN) Manual

2

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 back-end operations. It provides immediate notification and confirmation of PayPal payments you receive, allowing you to: • • • •

Customize your website's response to customer purchases in real-time Track customers through the notification's "pass through" variables Automate your fulfillment operations Store transaction information in your own database

Once you activate IPN, you will receive an IPN when a payment is first sent, which will state the status of the payment (Completed or Pending). If the payment was ‘Pending,’ you will receive another IPN when the payment clears, fails, or is denied. IPN can be seamlessly integrated with each of the PayPal website payment solutions (Single Item Purchases, Shopping Cart, Donations, and Subscriptions), as well as with regular PayPal “Send Money” payments, and lets you focus on selling, not trying to manually track your orders. Get the most out of your online business today: start using IPN!

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

3

IPN in Action How IPN Notifications 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.

Step 3: At the time the payment is made, PayPal will post a notification to your server at a URL you specified. All of your customer's payment information and a piece of encrypted code will be included in this notification.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual 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 and send your server a "VERIFIED" or "INVALID" response.

Step 5: When you receive a VERIFIED response, you need to perform several checks before fulfilling the order (an INVALID response should be treated as suspicious and investigated).

Step 6: After successfully completing the checks, you can update your database process the purchase.

©2002 PayPal. All Rights Reserved

4

5

The PayPal Instant Payment Notification (IPN) 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.

How It Works To activate Instant

Payment When a customer makes a payment to you, PayPal will post Notification, you will need to enter a notification to your server at a URL you specify. Included in the URL at which this notification will be all of your customer's payment you would like to receive the information (e.g. customer name, amount) as well as a piece notification posts of encrypted code. When your server receives a notification, from your Profile. See page 9 for more it will then post the information, including the encrypted information. code, back to a secure PayPal URL. PayPal will authenticate the transaction and send confirmation of its validity back to your server.

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 below.

IPN Variables The variables below work for all Send Money, Single Item Purchase, PayPal Donations, and PayPal Shopping Cart IPNs. If you are using IPN to receive Subscription payment notifications, you will need to support additional variables, which are listed on page 11. Please note that the IPN variables are case-sensitive. Most values are all lower-case, but payment status is non-standard with the first letter capitalized (e.g., “Completed). Are there any restrictions on field lengths and data types included in an IPN post? IPN posts should contain only alphanumeric characters. The maximum field length for each returned field is 127 characters, with the exception of the "custom" field, which has a maximum length of 255 characters. The unique PayPal Transaction ID will always be 17 characters in length.

©2002 PayPal. All Rights Reserved

6

The PayPal Instant Payment Notification (IPN) Manual

Variable

Value

business

Transaction Specific

receiver_email

Transaction specific

item_name

Transaction specific

item_number

Transaction specific

quantity

Transaction specific

invoice

Transaction specific

custom

Transaction specific

memo

Transaction specific

tax option_name1 option_selection1

Transaction specific Transaction specific Transaction specific

option_name2 option_selection2

Transaction specific Transaction specific

num_cart_items

Shopping Cart transaction specific "Completed"

payment_status

Description Email address or account ID of the payment recipient (i.e., the merchant). Equivalent to "receiver_email" if payment sent to primary account. 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 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 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 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 number as passed by you, the merchant. Your customer is not able to view or edit this. It must be unique per transaction Custom value as passed by you, the merchant. This is a pass-through variable that is never presented to your customer Memo as entered by your customer in web accept note field Amount of tax charged on payment Option 1 Name as requested by you Option 1 Choice as entered by your customer Option 2 Name as requested by you Option 2 Choice as entered by your customer If this is a shopping cart transaction, number of items in cart The payment has been completed and the funds are successfully in your account balance

©2002 PayPal. All Rights Reserved

7

The PayPal Instant Payment Notification (IPN) Manual

Variable

Value "Pending"

"Failed"

"Denied"

pending_reason

"echeck"

"multi_currency"

"intl"

"verify"

"address"

"upgrade"

"unilateral"

"other"

Description 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" The payment has failed. This will only happen if the payment was made from your customer's bank account You, the merchant, denied the payment. This will only happen if the payment was previously pending due to one of the "pending reasons" below The payment is pending because it was made by an eCheck, which has not yet cleared 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 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 The payment is pending because you, the merchant, are not yet verified. You must verify your account before you can accept this payment 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" 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 The payment is pending because it was made to an email address that is not yet registered or confirmed The payment is pending for an "other" reason. For more information, contact customer service

©2002 PayPal. All Rights Reserved

8

The PayPal Instant Payment Notification (IPN) Manual

Variable

Value

payment_date

Transaction specific

mc_gross

Transaction specific for Multiple Currencies

mc_fee

Transaction specific for Multiple Currencies

mc_currency

"USD" "GBP" "EUR" "CAD" "JPY"

settle_amount

Transaction specific

settle_currency exchange_rate txn_id

Transaction specific Transaction specific for Multiple Currencies Transaction specific

txn_type

"web_accept"

"cart" "send_money" for_auction

“true”

first_name last_name

Transaction specific Transaction specific

Description Time/Date stamp generated by PayPal system [format: "18:30:30 Jan 1, 2000 PST"] Full amount of the customer's payment, before transaction fee is subtracted. Equivalent to "payment_gross" for USD payments. 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. The currency of the payment is U.S. Dollars (payment IPNs only) The currency of the payment is British Pounds Sterling (payment IPNs only) The currency of the payment is Euros (payment IPNs only) The currency of the payment is Canadian Dollars (payment IPNs only) The currency of the payment is Yen (payment IPNs only) 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 Currency of settle_amount Exchange rate used if a currency conversion occurred A unique transaction ID generated by the PayPal system The payment was sent by your customer via Single Item Purchases, Donations, or Auction Smart Logos This payment was sent by your customer via the Shopping Cart feature This payment was sent by your customer from the PayPal website, using the "Send Money" tab This is an auction payment. (Payments made using AuctionFinder or Smart Logos, as well as Send Money/Money Request payments with the type "GoodsAuction") Customer's first name Customer's last name

©2002 PayPal. All Rights Reserved

9

The PayPal Instant Payment Notification (IPN) Manual

Variable

Value

address_name

Transaction specific

address_street address_city address_state address_zip address_country address_status

Transaction specific Transaction specific Transaction specific Transaction specific Transaction specific "confirmed" "unconfirmed"

payer_email

Transaction specific

payer_id payer_status

Transaction specific "verified" "unverified" "intl_verified"

payment_type

"echeck" "instant"

notify_version

"1.4"

verify_sign

Transaction specific

payment_gross

Transaction specific

payment_fee

Transaction specific

Description Name used with address (Included when the customer provides a Gift Address) Customer's street address City of customer's address State of customer's address Zip code of customer's address Country of customer's address Customer provided a Confirmed Address Customer provided an Unconfirmed Address Customer's primary email address. Use this email to provide any credits Unique customer ID Customer has a Verified U.S. PayPal account Customer has an Unverified U.S. PayPal account Customer has a Verified International PayPal account This payment was funded with an eCheck This payment was funded with PayPal balance, credit card, or Instant Transfer The version of the Instant Payment Notification you are using An encrypted string used to validate the authenticity of the transaction (page 9 ) 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" 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"

Specifying Your Notification URL If you only need to receive your IPNs at a single URL, you can enter that URL in the “Preferences” section of your Profile. If you would like to receive payment notifications for different payments at different URLS (i.e. if you need to keep payments made to different websites you run separate), you can manually pass the IPN URL with each payment by including it in that payment’s HTML code. Use the notify_url field to pass this information.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

10

The notify_url for a specific payment will be saved, and any subsequent updates to that payment (e.g. cleared echeck) will be sent to that notify_url. When you pass a notify_url in your HTML code, it will override any preferences you set in your Profile.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

11

Using IPN Getting set-up to use IPN and validate notifications

Setting up IPN To set up IPN: 1 1. Log in to your Business or Premier PayPal account 2. Go to the `Profile’ subtab 3. Click on the `Instant Payment Notification Preferences’ link in the `Selling Preferences’ column 4. Click Edit 5. Check the box and enter the URL at which you would like to receive your IPN Notifications 6. Click Save

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 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). To be 100% certain of the authenticity of this transaction, your code should verify PayPal's certificate using Verisign's public key. If you would like more information about the verification process, it can be found at http://www.verisign.com/ You can also review this useful FAQ on digital certificates at http://digitalid.verisign.com/server/about/aboutFAQ.htm 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 "_notifyvalidate" (e.g. cmd=_notify-validate) to the POST string.

1

If you have a Personal PayPal account you cannot set-up IPN from your Profile. Instead, Log in to your account and go to the `Sell’ tab. Click on the `Technical Overview’ link in the left-hand menu. On the Technical Overview page, click on the `Start using IPN’ link. You will be taken to your Profile IPN page and may then follow steps 4-6 above.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

12

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: 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. Once you have completed the above checks, you may update your database based on the information provided. If you receive an INVALID response, it should be treated as suspicious and investigated.

©2002 PayPal. All Rights Reserved

13

The PayPal Instant Payment Notification (IPN) Manual

Using IPN with Subscriptions Additional information if you receive PayPal Subscriptions payments

Subscriptions Variables In addition to the variables listed on page 5, these variables are included in Subscriptions IPNs: Variable txn_type

Value "subscr_signup" "subscr_cancel" "subscr_failed"

subscr_date

"subscr_payment" "subscr_eot" “subscr_modify” Transaction specific

subscr_effective

Transaction specific

period1

Transaction specific

period2

Transaction specific

period3

Transaction specific

amount1

Transaction specific

amount2

Transaction specific

amount3

Transaction specific

mc_amount1

Transaction specific

mc_amount2

Transaction specific

mc_amount3

Transaction specific

mc_currency

“USD” “GBP” “EUR” “CAD”

Description This IPN is for a subscription sign-up This IPN is for a subscription cancellation This IPN is for a subscription payment failure This IPN is for a subscription payment This IPN is for a subscription's end of term This IPN is for a subscription modification Start date or cancellation date depending on whether transaction is "subscr_signup" or "subscr_cancel" Date when the subscription modification will be effective (only for txn_type = subscr_modify) (optional) Trial subscription interval in days, weeks, months, years (example: a 4 day interval is "period1: 4 D") (optional) Trial subscription interval in days, weeks, months, years Regular subscription interval in days, weeks, months, years Amount of payment for trial period 1 for USD payments; otherwise blank (optional) Amount of payment for trial period 2 for USD payments; otherwise blank (optional) Amount of payment for trial period 3 for USD payments; otherwise blank Amount of payment for trial period 1, regardless of currency (optional) Amount of payment for trial period 2, regardless of currency (optional) Amount of payment for trial period 3, regardless of currency The currency of the subscription is U.S. Dollars (non-payment IPNs only)” The currency of the subscription is British Pounds Sterling (non-payment IPNs only)” The currency of the subscription is Euros (non-payment IPNs only)” The currency of the subscription is Canadian Dollars (non-payment IPNs only)”

©2002 PayPal. All Rights Reserved

14

The PayPal Instant Payment Notification (IPN) Manual

Variable

Value

Description

“JPY” recurring

Transaction specific

reattempt

Transaction specific

retry_at

Transaction specific

recur_times

Transaction specific

username

The currency of the subscription is Yen (non-payment IPNs only)” Indicates whether regular rate recurs (1 is yes, left blank is no) Indicates whether reattempts should occur upon payment failures (1 is yes, left blank is no) Date we will retry failed subscription payment How many payment installments will occur at the regular rate (optional) Username generated by PayPal and given to subscriber to access the subscription (optional) Password generated by PayPal and given to subscriber to access the subscription (password will be hashed). ID generated by PayPal for the subscriber

Transaction specific

password

Transaction specific

subscr_id

Transaction specific

Variables for each Subscription Type The table below shows which variables are associated with and may be included with each transaction type (the IPN will only contain variables for which it has information): Subscription Transaction Type Variable

receiver_email business item_name item_number quantity invoice custom option_name1 option_selection1 option_name2 option_selection2 num_cart_items payment_status pending_reason mc_gross mc_fee mc_currency settle_amount settle_currency exchange_rate payment_date

Signup

Cancel

Modify

Payment (USD)

Payment (MC)

Failed

EOT

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X

X X X X X X X X X

X X X X X X X X X

X

X

X

X

©2002 PayPal. All Rights Reserved

15

The PayPal Instant Payment Notification (IPN) Manual txn_id txn_type first_name last_name address_name address_street address_city address_state address_zip address_country address_status payer_email payer_id payer_status payment_type notify_version verify_sign payment_gross payment_fee subscr_date subscr_effective period1 period2 period3 amount1 amount2 amount3 mc_amount1 mc_amount2 mc_amount3 recurring reattempt retry_at recur_times username password subscr_id

X subscr_ signup X X X X X X X X X X X X

subscr_ cancel X X X X X X X X X X X X

subscr_ modify X X X X X X X X X X X X

X X

X X

X X

X

X

X X X X X X X X X X X

X X X X X X X X X X X

X X X X X X X X X X X X X

X X X X

X X X X

X X X X

X

subscr_payment X X X X X X X X X X X X X X X X X

X X X X X X X X X X X X X X X

subscr_ failed X X

subscr_ eot X X

X X X

X X X

X X X

X X X

X X X X

©2002 PayPal. All Rights Reserved

X X X

X X X

X X X

The PayPal Instant Payment Notification (IPN) Manual

16

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 both one Personal and one Premier/Business account. Please do not set up any additional PayPal accounts, as this may result in your account access being limited.) 2. Make sure that your Business/Premier account is Verified. This is the account which uses IPN - your "seller" account. 3. Log in to your buyer account and Send Money to your seller account, as if you were making a regular payment. 4. Check the results of your IPN test. One useful testing technique is to set the "return" field to the URL of your script that processes IPNs. This lets you see error messages right in the browser window. 5. Log in to your seller account and refund the payment. (To refund a payment, go to the Transaction Details page and follow the Refund Payment link at the bottom.) The refund reverses the entire payment, including transaction fees! Remember that you only have 30 days to Refund the payment. This testing method is free of charge and lets you complete the entire process yourself. You can also have friends or trusted clients send you test payments, then refund them, if you would prefer not to open a second PayPal account. Testing tip: Set the "return" URL to point to your IPN script. This way when you click the "Continue" button you can actually see how your script reacts. When IPN is being used, the "return" URL is POSTing the exact same FORM fields.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

17

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 now include 2 information about the currency of the payment. The overview below explains how IPN will interact with Multiple Currencies. “payment_gross” and “payment_fee” These variables reflect the amount received and corresponding fee of U.S. Dollar (USD) payments. If the amount received and fee deducted are in a currency other than USD, the variables will still appear in your IPN, but will have no values in them. Note: “payment_fee” is not always present in IPNs (e.g. when a payment is pending) These values are absent for non-USD payments so IPN scripts will not process these amounts as USD. This will intentionally break IPN scripts that do not handle Multiple Currencies payments if they receive a non-USD payment. However, legacy IPN scripts will continue to work as before as long as the merchant only receives USD payments. New variables for IPNs IPNs that use the “payment_gross” variable will have the following new variables added. The variables “mc_gross” and “mc_fee” will not be added to IPNs with txn_type: subscr_signup, subscr_cancel, subscr_modify, subscr_failed, or subscr_eot. “mc_gross” Full amount of payment received, before transaction fee. Note if payment is in USD, the “payment_gross” value will equal “mc_gross.” “mc_fee” Transaction fee associated with the payment. Variable should function like “payment_fee” variable (variable does not appear when payment pending, etc). Note if payment is in USD, the “payment_fee” value will equal “mc_fee.”

2

If you are using one of PayPal’s Website Payment solutions (e.g. PayPal Shopping Cart), and would like to be paid in a currency other than U.S. Dollars, you will need to set up your buttons for your currency of choice. For additional information, please see the PayPal website or the manual for your PayPal Website Payment Solution.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

18

“mc_currency” Currency of “mc_gross”, “mc_fee”, and “payment_gross” and “payment_fee” amounts. The values are (note the capitalization): -

USD EUR GBP CAD JPY

For non-payment subscription IPNs (e.g. signup, cancel, modify, failed, eot), mc_currency will refer to the currency of the subscription, rather than the currency of the payment. For payment subscription IPNs, mc_currency will refer to the currency of the payment. Examples 1 & 2 below refer to subscr_payment IPNs. If a user with a USD balance receives a 100 USD payment, these variables will be used for the payment (mc_gross = payment_gross and mc_fee = payment_fee): Example 1: USD Payment (subscr_payment IPN) payment_status = Completed payment_gross = 100 payment_fee = 3.00 mc_gross = 100 mc_fee = 3.00 mc_currency = USD

If a user with a CAD balance receives a 100 CAD payment, these variables will be used for the payment (mc_gross and mc_fee have values but 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.00 mc_currency = CAD

Additional variables for payments converted into another currency

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

19

IPNs for payments which are converted into the Primary Currency of the account (either manually or automatically) will include three new variables with information on the conversion. settle_amount Amount that is deposited into the user’s primary balance after the conversion occurs settle_currency Currency of “settle_amount” exchange_rate Exchange rate used if a conversion transaction occurs. pending_reason In addition, payments that are ”pending“ because the balance needs to be manually accepted (either because the account does not currently have a balance in that currency or because automatic conversion is not turned on) will have a new IPN “pending_reason”: pending_reason = multi_currency If the account is set to automatically convert payments, a user with a USD balance who receives a payment of 100 GBP, these variables will be used to show the conversion 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.5

If a payment received is pending due to “pending_reason = multi_currency”, the first IPN received would not have the “settle_amount”, “settle_currency”, or “exchange_rate”. Example 4: Pending Payment

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

20

payment_status = Pending pending_reason = multi_currency payment_gross = mc_gross = 100 mc_currency = GBP

The second IPN would contain information about settling the payment. If the payment is accepted into the account’s Primary Currency (here, USD): Example 4: 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.5

If the payment is accepted into a balance of the same currency: Example 4: Pending – Accept to currency balance payment_status = Completed payment_status = Completed payment_gross = payment_fee = mc_gross = 100 mc_fee = 3.00 mc_currency = GBP

If the payment is denied: Example 4:Pending - Deny payment_status = Denied payment_gross = mc_gross = 100 mc_currency = GBP

The logic described above applies to all IPNs sent for pending payments. 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.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

21

IPN Frequently Asked Questions 1. Are there any restrictions on field lengths and data types included in an IPN post? 2. Why is my script being continuously called for the same transaction? 3. If my site is down, will PayPal resend the IPN post? 4. I receive the final post from PayPal with a 'Verified' response, but my script still isn't performing correctly. Why? 5. Why does my successful payment URL generate a standard PayPal webpage? 6. Why do my buyers receive an error message when they click 'Continue' after making a payment? 7. Why do I always receive an 'Invalid' response from PayPal? 8. Why does my Perl script produce an 'Internal Server Error'? 1. Are there any restrictions on field lengths and data types included in an IPN post? IPN posts should contain only alphanumeric characters. The maximum field length for each returned field is 127 characters, with the exception of the "custom" field, which has a maximum length of 255 characters. The unique PayPal Transaction ID will always be 17 characters in length. 2. Why is my script being continuously called for the same transaction? PayPal's IPN system re-posts to your script after 1 second, then 2 seconds, 4 seconds, 8 seconds, etc., (up to a 4 hour duration), until we receive a basic HTTP "200 OK" response from your web server or 1.5 days have passed since the initial post. 3. If my site is down, will PayPal resend the IPN post? PayPal's IPN system re-posts to your script after 1 second, then 2 seconds, 4 seconds, 8 seconds, etc., (up to a 4 hour duration), until we receive a basic HTTP "200 OK" response from your web server or 1.5 days have passed since the initial post. 4. I receive the final post from PayPal with a 'Verified' response, but my script still isn't performing correctly. Why? This generally means that the communication between PayPal and your IPN script is working correctly, but the customized portion of your script is not performing the final step(s) to complete your process. To fix this, debug the custom portion of your script and double-check your database connection, file paths, syntax, etc.

©2002 PayPal. All Rights Reserved

The PayPal Instant Payment Notification (IPN) Manual

22

5. Why does my successful payment URL generate a standard PayPal webpage? The post within your IPN script is probably incorrect. Make sure that the following line is present in the script and that it appears exactly as follows: str

=

str & "&cmd = _notify-validate"

6. Why do my buyers receive an error message when they click 'Continue' after making a payment? If you are using the IPN feature and have specified a successful payment url, there is a hidden form containing all of the transaction variables that posts to your designated page. Your page must be able to accept this post. Please check the file extension of the web page producing the error - if it is ".htm" or ".html", it may need to be renamed with the default extension for the server model specified. If you have already renamed the script to include a .cgi extension and are still receiving the same error message, you may need to contact your ISP about permissions. 7. Why do I always receive an 'Invalid' response from PayPal? If your script is receiving the final post from PayPal but it is always 'Invalid' or you are receiving an error message, then you are posting back to us, but there is a problem with the information we are receiving. You must post all of the form variables exactly as you received them. If you are receiving a specific error message, please contact us with the exact error message so we may assist you.

8. Why does my Perl script produce an 'Internal Server Error'? There are several configuration problems that can cause an internal server error when you access your Perl script. To find the cause, please check the following: Ensure that your script has been uploaded in ASCII mode (not binary mode or automatic) and that the permissions on your script are correct Check the Perl path within the top line of your script. You may need to contact your web host or consult its documentation if you are unsure Check your server's error/access logs and look for any clues as to why the script is failing.

©2002 PayPal. All Rights Reserved