AlertPay-Instant Payment Notification Guide

Overview

IPN stands for Instant Payment Notification. It is a notification message that contains all the payment details data as well as your customer’s information. You would use the given information for any post-payment operations, such as updating your inventory or database, issuing a receipt and fulfilling orders.

What is IPN?

AlertPay notifies you as soon as a transaction has been made successfully and posts all the payment details on your website at a URL that you must provide. IPN messages are sent when payments are made on your website through our checkout page or when you have successfully paid someone through AlertPay’s MassPay API.
To capture and process the data contained in the IPN, you will have a script written in the web programming language(s) of your choice which will wait for and handle any incoming messages. The program or script is often called the IPN Handler or Listener and it should be located at the Alert URL you have provided in your AlertPay account. The Alert URL is a specific URL where your IPN messages will be sent.
Depending on the needs of your website, your IPN Handler may perform different actions with the IPN messages. Here are few examples:

• Update an inventory
• Update and fulfill a customer’s order
• Automatically make a payout upon receipt of a payment using our SendMoney API

AlertPay also notifies you by email when a payment is made to your account. Our IPN messages allow you to simply automate the processing of the information you receive.

Alert URL

The Alert URL is where your IPN Handler is located and where AlertPay posts the IPN messages for a particular business profile in your account. For security reasons, we take specific measures to ensure that your Alert URL remains confidential. Your Alert URL should not be included in the HTML form created for your payment buttons. It is not necessary to submit the Alert URL since AlertPay has it listed in your account profile.
Please note that the Alert URL cannot be the same as the Return URL.
To set up your Alert URL, just follow these steps:

1. Login to your AlertPay account.
2. Click on "Business Tools".
3. Under "Instant Payment Notification - IPN", click on "IPN Setup".
4. Enter your Transaction PIN and click on "Access".
5. Click on the "Edit" icon for the respective business profile. **This is for Business accounts only. Ignore this step if you only have one business profile on your account**
6. Enter the information:
   1. For IPN Status, select "Enabled".
   2. For Alert URL, enter the URL of the location of your IPN Handler.
7. Click on "Update" button.

How IPN works?

AlertPay will send an IPN message back to your IPN Handler for a payment made through our checkout page or for a MassPay transaction made through our API.

IPN messages for Payment Buttons

When a customer clicks on a payment button, such as a "Buy Now" or "Subscribe Now" button, they are sent to AlertPay’s checkout page to complete their payment. Upon a successful payment, an IPN will be sent to your IPN Handler for any post-purchase processing such as updating an inventory, upgrading a membership, fulfilling an order and more.
The following diagram shows AlertPay’s response to a successful payment made through our checkout page:

1. The customer shops on your website.
2. When the customer is ready to pay, they click on a "Buy Now" button and are taken to AlertPay's checkout page to complete the payment.
3. AlertPay sends the payment confirmation data to the URL of the location of your IPN Handler which will process the variables. The data consists of information about the completed purchase and the details about the buyer. You can take this captured information for post-purchase processing and authenticate the purchase by checking the following:
   • The IPN Security Code you receive matches the one generated in your AlertPay account — so you know that AlertPay sent the data.
   • The amount paid was the expected amount.
   • The amount paid was for the correct item.
   • The currency is correct.
   • ...

When AlertPay sends IPN messages it will make sure that your web server receives it. If AlertPay does not receive an acknowledgement that your server received our IPN post, then it will try again up to 9 times until your web server successfully receives the post. The attempts will occur as follows:

• The first 3 attempts will occur every 15 minutes
• If the previous attempts fail, the next 3 will occur every hour
• Lastly, 3 final attempts will be made every 8 hours

The intervals between the attempts will give you enough time to correct anything on your server that is preventing you from receiving the IPN posts.
If all of the 9 attempts fail, then the IPN notification will be lost for that transaction. You may contact AlertPay’s Integration/Technical Support Team to manually re-send a lost IPN.

IPN Security Code

Your IPN Security Code provides a way of authenticating that AlertPay sent the data. You generate your IPN Security Code from your AlertPay account so only you know its value. Your IPN Security Code will not change unless you re-generate a new one. You can make this change at any time, by going to IPN Setup.
This IPN Security Code will be sent by AlertPay with all IPN posts to your Alert URL. You may then compare the code sent with the one that you have generated from your account to ensure that the information captured was sent by AlertPay.
To setup your IPN Security Code:

1. Login to your AlertPay account.
2. Click on "Business Tools".
3. Under "Instant Payment Notification - IPN", click on "IPN Setup".
4. Enter your Transaction PIN and click on "Access".
5. Click on the "Edit" icon for the respective business profile. **This is for Business accounts only. Ignore this step if you only have one business profile on your account**
6. Enter the information:
   1. For IPN Status, select "Enabled".
   2. Generate a security code if necessary and record it.
7. Click on "Update".

Sample IPN message

AlertPay’s IPN message will contain variables on a transaction, containing information about you, the buyer and related transaction details. The following is a sample IPN message that is sent to your IPN Handler for a purchase of $42.40 USD for an "item-goods".

ap_merchant%3Downer%40example.com%26ap_securitycode%3DHdhiox4S5cdOhh5p%26ap_custfirstname%3DJohn%26ap_custlastname%3DSmith%26ap_custaddress%3D5200+De+La+Savane%26ap_custcity%3DMontreal%26ap_custstate%3DQC%26ap_custcountry%3DCAN%26ap_custzip%3DH0H0H0%26ap_custemailaddress%3Djohnsmith%40example.com%26apc_1%3Dred%26apc_2%3D%26apc_3%3D%26apc_4%3D%26apc_5%3D%26apc_6%3D%26ap_test%3D0%26ap_purchasetype%3Ditem-goods%26ap_referencenumber%3D13AD5-2WD40-5UE7B%26ap_amount%3D40.00%26ap_quantity%3D1%26ap_currency%3DUSD%26ap_description%3DLorem+Ipsum%26ap_itemcode%3DSU1%26ap_itemname%3DShoes%26ap_shippingcharges%3D2.40%26ap_additionalcharges%3D0.00%26ap_taxamount%3D0.00%26ap_discountamount%3D0.00%26ap_totalamount%3D42.40%26ap_feeamount%3D1.25%26ap_netamount%3D41.15%26ap_status%3DSuccess

You will notice that our IPN message is URL-encoded. After receiving the IPN, you must URL-decode it before using its values. Further details on URL-decoding are given in the following section. After a URL-decode, the IPN message will look like the following:

ap_merchant=owner@example.com&ap_securitycode=Hdhiox4S5cdOhh5p&ap_custfirstname=John&ap_custlastname=Smith&ap_custaddress=5200 De La Savane&ap_custcity=Montreal&=QC&ap_custcountry=CAN&ap_custzip=H0H0H0&ap_custemailaddress=johnsmith@example.com&apc_1=red&apc_2=&apc_3=&apc_4=&apc_5=&apc_6=&ap_test=0&ap_purchasetype=item-goods&ap_referencenumber=13AD5-2WD40-5UE7B&ap_amount=40.00&ap_quantity=1&ap_currency=USD&ap_description=Lorem Ipsum&ap_itemcode=SU1&ap_itemname=Shoes&ap_shippingcharges=2.40&ap_additionalcharges=0.00&ap_taxamount=0.00&ap_discountamount=0.00&ap_totalamount=42.40&ap_feeamount=1.25&ap_netamount=41.15&ap_status=Success

Before using the information in the IPN, you must first verify that the message was for your account and that it was sent by AlertPay. You must make the proper validation for ap_merchant & ap_securitycode. You will need to check that ap_merchant matches the email that you have in your business profile and that the ap_securitycode matches the one that was generated in your AlertPay account. You may validate other variables depending on the needs of your business. Further details on the common variables to check are discussed in section Implementing an IPN Handler.

URL-Decode

In order to transmit special characters, characters that are not allowed in a URL and characters that have special meaning in a URL properly across the internet, URL-encoding is performed prior to sending any data. AlertPay’s IPN messages are URL-encodes all of its messages, therefore you must make sure that you URL-decode our IPN within your handler script before using the data for any processes.
For example, the following URL-encoded string, ap_custfirstname%3DJohn%26ap_custlastname%3DSmith%26ap_custaddress%3D5200+De+La+Savane, will display the following after a URL-decoded string: ap_custfirstname=John&ap_custlastname=Smith&ap_custaddress=5200 De La Savane
Here are the methods to perform URL-decoding for various web programming languages:

URL-Decoding Methods

Language	URL-Decode Method
ASP.NET	System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default)
Classic ASP	No built-in function.
ColdFusion	URLDecodeurlEncodedString[, charset])
Java	java.net.URLDecoder.decode
JavaScript	unescape(String)
Perl	uri_unescape
PHP	urldecode(string)

Implementing an IPN Handler

An IPN Handler can be written in any web programming or scripting languages you like. AlertPay provides you with sample IPN Handler codes in different programming languages which will help you get started. Your IPN Handler script must be hosted by your web server.
Creating an IPN Handler for AlertPay’s IPN is simple and easy to implement. Make sure that your handler script does the following:

1. It must be ready to capture the HTTP POST from AlertPay. All IPN messages are sent by HTTP POST.
2. It must URL-decode the received POST variables before using them in any processes.
3. It must verify that the IPN received was sent from AlertPay by checking the values of the following variable:
   1. ap_merchant must match with the email associated with the appropriate business profile.
   2. ap_securitycode must match with the one generated in your AlertPay account for the appropriate business profile.

Optionally, you may want to check the following variables:

1. ap_purchasetype: Check whether the purchase type was for an item or a subscription.
2. ap_status: Depending on the purchase type, check for the proper status. Please to the IPN Variables Reference for the complete listing of possible statuses.
3. ap_test: Check whether the received IPN was for a test transaction
4. ap_referencenumber: If the IPN was for a test transaction, the value of this variable will be "TEST TRANSACTION" else it will be a reference number for you to store.
5. ap_itemname: Check if it the payment was for the correct item by matching this name with the name in your inventory.
6. ap_currency: Check if the payment was made with the proper currency.
7. ap_totalamount: Check if the amount paid to you was the expected amount.

Sample IPN handler in PHP

You may use the IPN Handler located at out SDKs & Sample Code section as a blueprint for your own custom-made handler. The script handles the basic validations that should be made for any received IPN. You will need to add extra lines of code in order for it to behave as your web application requires.

Testing the IPN Handler

AlertPay provides a feature that allows you to test whether your IPN Handler is able to receive and process our IPNs properly. No real funds are transferred and no Reference Number is created during this testing phase, but you will receive an IPN message with all the information pertaining to the test transaction.
To receive test IPNs, you must enable Test Mode from within your AlertPay account by following these instructions:

1. Login to your AlertPay account.
2. Click on "Business Tools".
3. Under "Instant Payment Notification - IPN", click on "IPN Setup".
4. Enter your Transaction PIN and click on "Access".
5. Click on the "Edit" icon for the respective business account.
6. For Test Mode, select "Enabled".
7. Click on "Update".

After you have enabled Test Mode for your respective business profiles, you may go to your own website and make a payment to yourself by clicking on your payment buttons. This will take you to the AlertPay checkout page where you will see the details of the purchase. At the top of the page, you will see "Test Transaction" in red. This means that no transaction will be created since Test Mode is enabled.
You may login to your AlertPay account to continue the payment process. *When in Test Mode, you can pay yourself even if you do not have funds in your account.*
Once you are logged in, click on the "Pay" button to complete the payment. This does not create the transaction, but mimics the process and sends a confirmation email and IPN.
You may repeat this process as many times as you like until you are satisfied with the test results. Once you have finished testing and want to accept real payments, please turn off Test Mode in your AlertPay account.

Setting up IPN on your Account

To receive IPN messages, you are required to enable the IPN Status for a particular business profile in your account and to specify an Alert URL which is the location of your IPN Handler.
Please follow the instructions below to enable your IPN Status and to set up your Alert URL:

1. Login to your AlertPay account.
2. Click on "Business Tools".
3. Under "Instant Payment Notification – IPN", click on "IPN Set up".
4. Enter your Transaction PIN and click on "Access".
5. Click on the "Edit" icon for the respective business profile. **This is for Business accounts only. Ignore this step if you only have one business profile on your account**
6. Enter the information:
   1. For IPN Status, select "Enabled".
   2. For Alert URL, enter the URL of the location of your IPN Handler.
   3. Generate a security code if necessary and record it.
   4. For Test Mode, choose to enable or disable it for this business profile. (See "Test Mode" section for more information)
7. Click on "Update".

IPN Troubleshooting

The most common issue with IPNs is not being able to receive them. Here are the possible reasons why your IPN Handler is not receiving any of our IPNs.

1. Your Alert URL is incorrect and does not link to your script. Make sure that you have entered the proper URL of the location of your script.
2. Your Return URL is the same as your Alert URL. Our system does not allow these two URLs to be exactly the same. You must specify a unique URL for each one of them.
3. Your web server or host provider might be blocking incoming messages from our public IP. AlertPay sends its IPNs from one of the following servers: 174.142.185.131 or 174.142.185.132. (The following IPs are no longer in effect 67.205.87.225, 67.205.87.226 or 67.205.87.235)
4. The firewall settings on your web server that might be blocking HTTP POST from AlertPay.