How to Sell Downloadable Products with Paypal IPN

I’ve been experimenting with Paypal IPN for some time now and I’ve had in the back of my mind that I wanted to put all the different tutorials I’d written together into one big explanation of what you need to do to sell downloadable products. When I tried this I realised there is just too much information for one tutorial.
So I’ve created a series. And despite my frog like voice I have decided to give video tutorials a go.

I’m not going to explain how to write your own code from scratch. It’s just too difficult. Commercially available scripts have mostly been around long enough to iron out the bugs, to add on new features and create spin off scripts that do other related tasks. They also have established support systems to help with any problems you might encounter.

The one I recommend is Linklok from Vibralogix. (This is an affiliate link so I gain financially if you purchase after following this link)

Vibralogix provide an excellent user guide and there is plenty of help available on their support site but despite this I found it all a bit overwhelming so hopefully you will find my video tutorials helpful. They cover all the other things you need to do as well such as setting up your Paypal account, creating Paypal Buy Now buttons and so on.

This first tutorial covers the basics. The next ones will be more advanced. e.g. using a database to store products and log orders, high security, generating serial numbers, invoices, product specific emails, complex products and so on.

The next 3 tutorials will be free to use but you will need to register to receive them.

====================CLICK HERE TO REGISTER====================

Tutorial #2: How to Customise the Download Page

Tutorial #3: Using a Database or External Product File

Coming Soon: Many more Linklok Tutorials.

One of the commonest methods of accepting Web Payment is to use Paypal but there are others such as 2Checkout.

Unless you have some programming skills or your application is very simple I would recommend you buy one of the programs that do everything for you.
One of the best companies is Vibralogix (This is an affiliate link. I am paid for this recommendation.) They do all the hard work for you and have a number of different products for handling memberships systems, digital downloads and the rest.

But if you would rather work it all out yourself there are plenty of tutorials on the site.

• How to receive Web Payments with Paypal
• Paypal IPN
• Adding a simple Buy Now button
• Adding a more complex Buy Now button
• Adding an advanced Buy Now button

Buy Now buttons

Website Payments Standard uses a normal HTML Form to get information from your website. When you use their Create a Button wizard the HTML created is basically an HTML Form containing hidden HTML input variables that contain all the relevant details of the purchase.

1. Saved Buttons

Buttons created and saved on the Paypal website will have much of the information associated with them stored on the Paypal site. Consequently the HTML form on your website will be much simpler than one that is not stored on Paypal’s site. A saved button will have a variable with button id such as

<input type=”hidden” name=”hosted_button_id” value=”10954267″>

You should not edit this or try to generate your own hosted button ids but you can enhance the HTML form by adding extra value as custom variables. These should be added to a Paypal hosted button in Step 3 (Customise Advanced Features)

If you try to mix a hosted button with a manually created button you can get unexpected results. Paypal may ignore your manual additions. So I would recommend you go for one or the other.

2. The Form tag

The form tag will look like this. You should leave this alone.

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>

3. Input variables

The input variables don’t need to be seen by the purchaser so they are marked as hidden. They will take the following format.

<input type=”hidden” name=”variableName” value=”variableValue”>

4. cmd variable

The “cmd” variable is always required in the Form. It always takes the value “_s-xclick” or “_xclick” for a “Buy Now” button. Don’t alter this.

<input type=”hidden” name=”cmd” value=”_s-xclick”>

5. Passthru variables.

Paypal lets you set variables and it will pass them on unaltered. Their use is optional and will depend on your situation. The following are passthru variables.

<input type=”hidden” name=”item_number” value=”test1″> (up to 127 chars)
<input type=”hidden” name=”custom” value=”anythingyouwant”> (up to 256 chars)
<input type=”hidden” name=”invoice” value=”123456″> (up to 127 chars. Intended for use as invoice number)

6. Character Set and Currency code

You can specify which character set you wish to use. e.g. to use UTF-8

<input type=”hidden” name=”charset” value=”utf-8″>

and currency code (USD is assumed if not present) Codes accepted can be found here Currency Codes

<input type=”hidden” name=”currency_code” value=”CurrencyCode”>

7. Return URL for specific transactions.

There is the option to set a global return URL in your Paypal account which will apply in all cases for Paypal buttons you create. You may however want to override this for specific buttons or you may want to include session related information in the return url. How to use session information is beyond the scope of this tutorial.

<input type=”hidden” name=”return” value=”URLspecificToThisTransaction”>

“cancel_ return” is a URL to which the payer’s browser is redirected if payment is cancelled; for example, a URL on your website that displays a “Payment Canceled” page.

“rm” specifies the Return method. The FORM METHOD used to send data to the URL specified by the return variable after payment completion. Allowable values:

0 – all shopping cart transactions use the GET method
1 – the payer’s browser is redirected to the return URL by the GET method, and no transaction variables are sent
2 – the payer’s browser is redirected to the return URL by the POST method, and all transaction variables are also posted

The default is 0.
Note: The rm variable takes effect only if the return variable is also set.

“cbt” sets the text for the Return to Merchant button on the PayPal Payment Complete page. For Business accounts, the return button displays your business name in place of the word “Merchant” by default. For Donate buttons, the text reads “Return to donations coordinator” by default.
Note: The return variable must also be set.

8. Pre filling the form to make things easier for your customer.

If you already know the answer to some of the questions Paypal will need to know such as the Buyers Billings Address you can pre populate the form. This feature is not available in all countries. It is available in the US and UK.

Keep in mind that regardless of the address you fill in, when address_override=1 is passed a member’s confirmed address on file will be used as the shipping address and will be uneditable. When a non-PayPal account holder pays, their billing address and shipping address will need to match.

<input type=”hidden” name=”first_name” value=”John”>
<input type=”hidden” name=”last_name” value=”Doe”>
<input type=”hidden” name=”address1″ value=”9 Elm Street”>
<input type=”hidden” name=”address2″ value=”Apt 5″>
<input type=”hidden” name=”city” value=”Berwyn”>
<input type=”hidden” name=”state” value=”PA”> (or as appropriate for non US)
<input type=”hidden” name=”country” value=”US”>
<input type=”hidden” name=”zip” value=”19312″>
<input type=”hidden” name=”night_phone_a” value=”610″> (Buyers home phone. Area code for US. Country code for non US. 3 digit max)
<input type=”hidden” name=”night_phone_b” value=”555″> (Buyers home phone. 3 digit prefix for US. Entire phone number for non US. 16 char max)
<input type=”hidden” name=”night_phone_c” value=”1234″> (Buyers home phone. 4 digit phone number for US.)
<input type=”hidden” name=”email” value=”jdoe@zyzzyu.com”>
<input type=”hidden” name=”lc” value=”US”> (payers language for the billing info/log in page only. Default is US. Use UK for United Kingdom)
<input type=”hidden” name=”charset” value=”utf-8″>

9. Product Options

Specify product options such as size on a dropdown box or text box. You can specify up to 7 options on a single button (Up to 5 dropdown and 2 text)
You can either use the create button wizrd to do this or specify the code manually.

for example

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>

<input type=”hidden” name=”business” value=”herschelgomez@xyzzyu.com”>

<input type=”hidden” name=”cmd” value=”_xclick”>

<input type=”hidden” name=”item_name” value=”Hot Sauce-12 oz. Bottle”>
<input type=”hidden” name=”amount” value=”5.95″>
<input type=”hidden” name=”currency_code” value=”USD”>

<input type=”hidden” name=”on0″ value=”Type”>Type of sauce

<select name=”os0″>
<option value=”Select a type”>– Select a type –
<option value=”Red”>Red sauce
<option value=”Green”>Green sauce
</select>

<input type=”image” name=”submit” border=”0″ src=”https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif” alt=”PayPal – The safer, easier way to pay online”>
<img alt=”" border=”0″ width=”1″ height=”1″ src=”https://www.paypal.com/en_US/i/scr/pixel.gif” >

</form>

10. Product Quantity.

The default is 1 item but you can use the button wizard to change this. Or use this example code.

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>

<input type=”hidden” name=”business” value=”herschelgomez@xyzzyu.com”>

<input type=”hidden” name=”cmd” value=”_xclick”>

<input type=”hidden” name=”item_name” value=”Hot Sauce-12 oz. Bottle”>
<input type=”hidden” name=”amount” value=”5.95″>
<input type=”hidden” name=”currency_code” value=”USD”>

<input type=”hidden” name=”undefined_quantity” value=”1″>

<input type=”image” name=”submit” border=”0″ src=”https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif” alt=”PayPal – The safer, easier way to pay online”>
<img alt=”" border=”0″ width=”1″ height=”1″ src=”https://www.paypal.com/en_US/i/scr/pixel.gif” >

</form>

11. Offering a discount.

Paypal allows you to offer a discount.
- “Discount_amount” must be less than “amount”.
- If you don’t specify “discount_amount2″ then “discount_amount” will apply to all items not just the first.
- To use “discount_amount2″ you must specify “discount” as greater than or equal to 0.

You can specify “discount_rate” and “discount_rate2″ as an alternative to “discount_amount” and “discount_amount2″. This applies a percentage from 0 to 100.
Unlike “discount_amount” if you don’t specify “discount_rate2″ then “discount_rate” only applies to the first item.

Use “discount_num” to specify an upper limit on the number of items to which “discount_amount2″ or “discount_rate2″ applies.

Use the button creation tool wizard or this example code that provides a $0.15 discount on the first item ordered and a $0.20 discount on the next four items.
<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>

<input type=”hidden” name=”business” value=”herschelgomez@xyzzyu.com”>

<input type=”hidden” name=”cmd” value=”_xclick”>

<input type=”hidden” name=”item_name” value=”Hot Sauce-12 oz. Bottle”>
<input type=”hidden” name=”amount” value=”5.95″>
<input type=”hidden” name=”currency_code” value=”USD”>

<input type=”hidden” name=”discount_amount” value=”0.15″>
<input type=”hidden” name=”discount_amount2″ value=”0.20″>
<input type=”hidden” name=”discount_num” value=”4″>

<input type=”hidden” name=”undefined_quantity” value=”1″>

<input type=”image” name=”submit” border=”0″ src=”https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif” alt=”PayPal – The safer, easier way to pay online”>
<img alt=”" border=”0″ width=”1″ height=”1″ src=”https://www.paypal.com/en_US/i/scr/pixel.gif” >

</form>

12. Shipping and Handling charges

“shipping” and “shipping2″ specify the cost of shipping an item and subsequent items.
“handling” applies regardless of number of items.

13. Tax

Use “tax” and “tax_rate” to apply a transaction based tax amount or tax rate irrespective of customers location.
“tax_rate” can be 0.001 to 100

14. Weight

“weight” and “weight_unit” (lbs or kgs)

15. How the Paypal Checkout Looks

“page_style” can be set to “paypal” to use the Paypal page style
“page_style” can be set to “primary” to use page style you defined as primary in your account
“page_style” can also be set to any custon style you created in your account profile.

“image_url” specifies where the 150×50 pixel image is that will be used as your logo. If you don’t specifiy this then your business name will be used if you have a business acccount otheriwise your email address.

“cpp_header_image” specifies the image at the top left of the checkout page. maximum size is 750×90 pixels. PayPal recommends that you provide an image that is stored only on a secure (https) server.

“cpp_headerback_color” specifies the background color for the header of the checkout page. Valid value is case-insensitive six-character HTML hexadecimal color code in ASCII.

“cpp_headerborder_color”specifies the border color around the header of the checkout page. The border is a 2-pixel perimeter around the header space, which has a maximum size of 750 pixels wide by 90 pixels high. Valid value is case-insensitive six-character HTML hexadecimal color code in ASCII.

“cpp_payflow_color” specifies the background color for the checkout page below the header. Valid value is case-insensitive six-character HTML hexadecimal color code in ASCII. Note: Background colors that conflict with PayPal’s error messages are not allowed; in these cases, the default color is white.

“cs” specifies the background color of the checkout page. Allowable values:

0 – background color is white
1 – background color is black

The default is 0.

“lc” specifies the language of the login or sign-up page that subscribers see when they click the Subscribe button. If unspecified, the language is determined by a PayPal cookie in the subscriber’s browser. If there is no PayPal cookie, the default language is U.S. English.

“no_note” specifies to not prompt payers to include a note with their payments. Allowable values:
0 – provide a text box and prompt for the note
1 – hide the text box and the prompt

The default is 0.

“cn” is a label that appears above the note field. This value is not saved and will not appear in any of your notifications. If omitted, the default label above the note field is “Add special instructions to merchant.” The cn variable is not valid with Subscribe buttons or if you include no_note=”1″.

“no_shipping” specifies to not prompt payers for shipping address. Allowable values:

0 – prompt for an address, but do not require one
1 – do not prompt for an address
2 – prompt for an address, and require one

The default is 0.

A Basic Non hosted Buy Now button sample code

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>

<input type=”hidden” name=”business” value=”herschelgomez@xyzzyu.com”>

<input type=”hidden” name=”cmd” value=”_xclick”>

<input type=”hidden” name=”item_name” value=”Hot Sauce-12 oz. Bottle”>
<input type=”hidden” name=”amount” value=”5.95″>
<input type=”hidden” name=”currency_code” value=”USD”>

<input type=”image” name=”submit” border=”0″ src=”https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif” alt=”PayPal – The safer, easier way to pay online”>
<img alt=”" border=”0″ width=”1″ height=”1″ src=”https://www.paypal.com/en_US/i/scr/pixel.gif” >

</form>

A Basic hosted Buy Now button sample code

<form action=”https://www.paypal.com/cgi-bin/webscr” method=”post”>
<input type=”hidden” name=”cmd” value=”_s-xclick”>
<input type=”hidden” name=”hosted_button_id” value=”10954267″>
<input type=”image” src=”https://www.paypal.com/en_US/GB/i/btn/btn_buynowCC_LG.gif” border=”0″ name=”submit” alt=”PayPal – The safer, easier way to pay online.”>
<img alt=”" border=”0″ src=”https://www.paypal.com/en_GB/i/scr/pixel.gif” width=”1″ height=”1″>
</form>

Have you seen the other Paypal tutorials on DesignerTuts?

Adding a More Complex Buy Now Button
Adding a Really Simple Buy Now Button
Paypal IPN
Paypal IPN Receiving Instant Payments

1. Inventory Tracking.

If you know how many of a product you have in stock you can let Paypal keep track of how many you are selling and they will warn you by email when stock is getting low. To set this up edit your existing button or make a new button as described in simple paypal buy now button tutorial but when you have finished Step 1 click on Step 2 where it says “Track Inventory” and then check the “Track Inventory” checkbox.

You can then enter your existing stock level and the level at which you want to receive an email warning.
You can also decide whether to allow customers to make a purchase when an item is sold out and specify a page to send them to when they click “Continue Shopping” after a sold out situation.

The following are all setup in Step 3 of the button creation process.

2. Let customer change order quantities.

3. Let customer add special instructions in a message to you

The default is to allow this so if you want this you don’t need to do anything.

4. Don’t ask for customers postal address

If you don’t need the customers postal address don’t ask for it.

5. Specify which page the customer goes to if they cancel e.g. https://www.mystore.com/cancel

6. Specify which page the customer goes to if they complete the purchase e.g. https://www.mystore.com/thanks

Here is the finished article

The “top of the range” in terms of extra things you can do with a “Buy Now” button is to specify your own advanced variables. I will be covering this in my next Paypal Button tutorial.

Answer: Use Paypal Website Payments Standard. Its very easy to set up. The customer clicks a “Buy Now” button. They are taken to Paypal’s site where they enter their card details or pay from their paypal account if they have one. The money then appears in your paypal account.

Question: What does it cost.

Answer: There are no setup charges, fees or cancellation charges for Website Payments Standard. There are charges on each transaction though. The amount depends on sales volume. You will need a Paypal account.

Question: So how do I do it.
Answer:

1. Get a Paypal account

Go to the paypal website and click Sign Up. Then choose the Paypal Business account.

2. Make a button.

Log in to your paypal account and click to go to your “Profile”. Under “Selling Preferences” click the “Create New Button” (or “My Saved Buttons”) link.

On the question about selling multiple items change the checkbox to “No” so that it creates a “Buy Now” button.

Fill in the name of the item and its price.

Click Customize Appearance and you can change a few basic features.

There are more advanced features available but for a basic “Buy Now” button that is all you need so just click “Create Button”

Here is one I made earlier.

I will be showing some of the more advanced features in a future tutorial.

Instant Payment Notification is better known as Paypal IPN and is Paypal’s interface for handling real time confirmation of purchases.

A typical use for IPN is where you want a customer to pay for a software download but there can be more to it than that and the IPN interface provides a wealth of options some of which I will go through in this article.

See my new Video Tutorial for Linklok. Videos make things much easier to understand.

Paypal have a simple demo of the basics of a Paypal IPN purchase, plus a good explanation called Introducing IPN and I have a more in depth Paypal IPN Tutorial available on this site which includes example php code. You should view these explanations before reading on but a very simple summary goes as follows:

1. Customer clicks the buy button and makes the payment through Paypal
2. Paypal posts a notification to your server with all the payment details
3. Your server echoes back the details
4. Paypal authenticates the transaction and sends VERIFIED or INVALID response
5. When your server sees VERIFIED it makes some checks and processes the order

The best place to search for information is the Paypal Integration centre. which has guides, code and links for everything to do with integrating your website with Paypal. It covers much more than just IPN. This article will assume you have decided that IPN is right for you.

The one place you MUST visit is the Paypal IPN Forum on the developer website. As well as a constantly changing list of discussion topics about IPN, there are some good sticky posts about troubleshooting tips, IPN variables, template code etc.

Paypal Sandbox

When you are developing your website you really don’t want to be trying to get it working by experimenting on a real money system. Any early bugs in the system could leave security holes but even if you write perfect code it is best not to do your testing using real money.

Paypal provides what they call a sandbox, almost identical to the live Paypal system. You can setup fake customers with fake money and make as many test purchases as you want. The perfect system to fully test your web application.

The Sandbox sets the variable test_ipn with a value of 1 in the HTTP response back to your IPN page. You may want to check for this so you know you are dealing with the real or the sandbox system.

There is a Testing Forum on the developer network. It’s a great place for advice.

Paypal Account

Paypal provide 3 different types of account. Personal, Premier and Business. You will need Premier or Business to use IPN.

Paypal IPN Events

IPN messages are normally generated to indicate a payment has occurred but this is not the only situation and you should be prepared to handle all of the following situations.

• Instant payments, including Express Checkout and direct credit card payments
• eCheck payments and associated status, such as pending, completed, or denied
• Payments that may be pending for other reasons, such as those being reviewed for potential fraud
• Events related to recurring payments and subscriptions
• Authorizations, which indicate a sale whose payment has not yet been collected
• Chargebacks, which are initiated by a credit card processor; for example, when a customer disputes a charge
• Disputes, which are initiated by a buyer using the PayPal resolution process
• Reversals, which occur when you win a dispute or a chargeback is canceled
• Refunds, which you may choose to give

Listener

Paypal IPN messages are not synchronized with actions on your website. You detect IPN messages from Paypal with a piece of code known as a listener. Paypal provides example code and there is also an example IPN code snippet in the IPN tutorial.

You specify the URL of your listener in your Paypal account’s profile (Profile, Selling Preferences, Instant Payment Notification Preferences) but you can override this for specific transactions when you setup a button or API operation (Set the notify_url HTML form variable). You can also temporarily turn off the sending of IPN messages, useful if your site is down for maintenance. They are still generated and stored until you switch sending back on again.

Paypal expects an acknowledgement from you (within 30secs) to show you have received the IPN message ok. If you don’t send an acknowledgement Paypal will resend the IPN message at intervals for up to 4 days after the first message. So even if you don’t intend to process the message you must acknowledge it or Paypal will send it again. If you receive a re transmission from Paypal even though you sent an acknowledgement you should send another acknowledgement. There may be a timing problem or the first acknowledgement may have been lost. Your listener code must be able to cope with this retry situation without processing the transaction twice.

Paypal recommends that your checkout flow should NOT wait for an IPN message before it is allowed to complete.

Listener Processing

You must perform a number of checks on the IPN message received from Paypal.

• Check the email address to make sure it is yours
• Check that you have not already processed the transaction identified by the transaction ID
• Make sure that the transaction’s payment status is “completed”
• Verify that the payment amount actually matches what you intend to charge

Example IPN Message

A typical IPN message:

mc_gross=19.95&protection_eligibility=Eligible&address_status=confirmed&payer_id=LPLWNMTBWMFAY&tax=0.00&address_street=1+Main+St&payment_date=20%3A12%3A59+Jan+13%2C+2009+PST&payment_status=Completed&charset=windows-1252&address_zip=95131&first_name=Test&mc_fee=0.88&address_country_code=US&address_name=Test+User&notify_version=2.6&custom=&payer_status=verified&address_country=United+States&address_city=San+Jose&quantity=1&verify_sign=AtkOfCXbDm2hu0ZELryHFjY-Vb7PAUvS6nMXgysbElEn9v-1XcmSoGtf&payer_email=gpmac_1231902590_per%40paypal.com&txn_id=61E67681CH3238416&payment_type=instant&last_name=User&address_state=CA&receiver_email=gpmac_1231902686_biz%40paypal.com&payment_fee=0.88&receiver_id=S8XGHLYDW9T3S&txn_type=express_checkout&item_name=&mc_currency=USD&item_number=&residence_country=US&test_ipn=1&handling_amount=0.00&transaction_subject=&payment_gross=19.95&shipping=0.00

Testing your Listener

The Sandbox has an excellent IPN Simulator (under Test Tools) which lets you choose the transaction type, fill in all the parameter values and send a test IPN to a specified address.

Some advice on the forum about using curl/fsockopen/local testing.

When things go wrong…

If you receive nothing at all.

• check that you have specified not only the correct file name for your IPN listener but also the correct path to the file.
• Check your firewall isn’t blocking HTTP POST messages from PayPal.
• Check the webserver logs for any errors

If you receive some messages but not all.

• Make sure the listener is processing ALL messages
• Make sure account is valid and confirmed

If you receive INVALID message.

• Check you are sending your responses to the correct paypal address
• Verify that your response contains exactly the same IPN variables and values in the same order, preceded with cmd=_notify-validate.
• Ensure that you are encoding your response string and are using the same character encoding as the original message.

IPN History

Paypal provides an IPN history page under the My Account tab. Click on History to see it. It includes everything you want to know about each IPN message including the following Status 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
• Retrying: indicates that message was resent between 1 and 15 times and PayPal continues to be resend the message
• Disabled: indicates that the message will not be resent because the merchant’s account has been disabled

IPN Resending

Use the History page to resend an IPN.

Conclusion

Paypal IPN is a difficult subject but the combination of an excellent testing environment in the form of the sandbox and the good quality advice provided through the forums should make it possible for you to get your website application up and running.

Interesting External Blogs

• Process Paypal IPN Requests Through Wordpress « James Van Dyne – Process Paypal IPN Requests Through Wordpress. Introduction. Paypal is perhaps the easiest way to send/receive money online and Wordpress is perhaps the most popular blogging platform out there. Wouldn’t it be great if there was a way …

• PayPal IPN Python Code | Django Aware – PayPal has Instant Payment Notification (IPN) libraries with examples for Perl, Java, and even Ruby, but look as hard as I may none for Python. Then again I.

This paypal ipn tutorial explains how to use Paypals IPN system with a simple single item purchase. 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. The main use of IPN is where your website needs to know immediately that payment has been made. For example you might have sold something that you will then make available for the user to download.

There is a lot of information on the Paypal website which is worth looking at but the following paypal ipn example will show you in detail a real world example of how to use it.

See my Paypal Tips Section at the end of the Tutorial for the following

• Using CURL instead of fsockopen
• Paypal’s IPN Script and Docs

Jump to the Tips Section at the end of the Tutorial or continue on this page with the IPN tutorial itself.

There are 3 main parts to an IPN system.

1) A webpage that initiates a call to Paypal to make a payment
2) A php page on your webserver that Paypal calls to notify you that payment has been made
3) A webpage that confirms the above have occurred, and continues on to the next phase of you web application.

1 and 3 will be part of your website and accessible to users in the normal way. 2 however is only ever accessed by paypal.

I will first explain some of the issues that you need to understand if you want to know how to use IPN.

Paypal Account Setup

Your Paypal account must be setup correctly to use IPN. Check the following in your paypal account (under edit profile).

under “Selling Preferences” , “Instant Payment Notification Preferences”

• set IPN to “On”
• set IPN Url to the page containing the ipn code shown later in the tutorial. The name I use is “http://<yourwebsite address>/paypalipn.php” but you can use anything here.

Under “Selling Preferences”, “payment receiving preferences”

• block payments from users who pay with echeck. (This is because these will not be instant)

Under “account information” , “email”

• make a note of your primary email address. You will need to embed it in the code below. This email will be visible to users so make it a professional one. Users don’t get a good feeling about sending money to a hotmail address or to an address that doesnt match the website.

Sequence of Events

The way IPN works is a bit unusual so to explain…

You initiate IPN by sending a message to Paypal from the webpage that the user is on when they confirm a purchase.
What happens next is that 2 completely separate chains of events occur.

• The first is the obvious one where the user goes to the paypal website, makes the payment and is returned to your website where they can be told their purchase is confirmed.
• The second is initiated by Paypal and envolves Paypal calling up a predetermined webpage on your site (paypalipn.php). Paypal will send a message to this page which indicates that the payment has happened, how much was paid, who paid it, who was paid etc. On this page you need to check these details and somehow log that the payment has happened, usually by updating a database.

These two chains of events are happening at the same time (only the first is visible to the user). Although as the paypal event is more complex it will usually take longer. For this reason when you send the user to the confirmation page and it checks the database that payment has happened ok it may well find that the payment hasn’t yet been made. You will need to create some code that waits for the payment to go through and as this can take quite a few seconds you will need to inform the user with a message along the lines of “Waiting for Paypal to confirm payment…”.

So in summary

1. Customer makes a payment through your website.
2. Paypal sends an IPN to your specified ipn webpage specifying what has been bought etc
3. Your webpage validates the IPN and sends Paypal an acknowledgement.
4. Customer continues to access your website.

2 and 3 occur in parallel with what the user is doing in 4) on your website.

The purchase page

The easiest way to generate the code to use on this page is to use Paypals “Buy Now Button” function. Log in to Paypal and look under Merchant Services for “Buy It Now” button.

Fill in the information as required

You must take steps to ensure the security of the purchase.
There are various ways of doing this

• Encrypt the button on the paypal site (there is an option for this)
• Encrypt the button yourself (complex and beyond this tutorial)
• Manually check all prices before shipping. I assume this isn’t appropriate for this tutorial.
• Check all the values in the IPN processing. (Explained below in the paypalipn.php code)

If you enter an image for the button make sure it is on a secure (https) server otherwise the user will get a warning about insecure items which may scare them off continuing with the purchase.

Click to “Create Button” and copy and paste the code produced into your purchase web page.

The code will look something like this…

button code

The IPN webpage code

Paypal IPN page
Save this as paypalipn.php

Notes

There are two methods of validating the IPN sent by Paypal. Shared Secret and Postback. Paypal recommends shared secret as it is more secure but this tutorial uses Postback. Shared Secret requires that you have dedicated hosting, SSL enabled and you use Paypal Encypted website payments. Paypal recommends Postback for shared hosting applications and where you dont have SSL.
They also don’t recommend you use IPN unless you have SSL !

This is too complicated!

Hope you enjoyed the tutorial. IPN is a complicated subject. If you found it too complicated there are a few commercial products out there that will handle everything for you, such as (this is an affiliate link so I am paid for this recommendation)

Have a look at my new Video Tutorials about Paypal IPN.

• Vibralogix Linklok Paypal

Here are some useful websites to help you.

Overview

IPN Variables

Order Management Guide

Script Generator

Forum

• Using CURL

$url= ‘https://www.sandbox.paypal.com/cgi-bin/webscr’;
$curl_result=$curl_err=”;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $req);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(“Content-Type: application/x-www-form-urlencoded”, “Content-Length: ” . strlen($req)));
curl_setopt($ch, CURLOPT_HEADER , 0);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$res = @curl_exec($ch);
$curl_err = curl_error($ch);
curl_close($ch);

• Paypal’s IPN Script and Docs