Originally published on January 20, 2020
Have you ever been in the situation where you were following a sports game on your phone and you constantly refreshed the game stats to see if your team scored? After constant refreshes, you keep seeing the same score. Wouldn’t it be better if the app just notified you when there was a change in score? This concept is similar to the Instant Payment Notifications experience with Amazon Pay, but instead of sports scores, it provides you with most up to date order/transaction information.
What are Instant Payment Notifications?
Amazon Pay Instant Payment Notifications, or IPNs, are notifications that are securely sent whenever a transaction is created or when the transaction state changes. You can take advantage of these notifications to automate back-end processes when certain payment events occur. Some examples of when an IPN would be sent are:
- A pending authorisation is approved
- A refund is processed
- A pending capture is declined
A full list of notifications and samples for each kind can be found here.
What are IPNs used for?
A developer can leverage IPNs to keep backend systems in sync with orders and transactions through Amazon Pay. Code can be written to update systems with transaction data from Amazon Pay. Examples of systems that are typically integrated with Amazon Pay are:
- Accounting software
- Shipping/fulfillment services
- Order and inventory management
- Email services
How to enable IPNs
Enabling Amazon Pay IPNs is simple. All you need to do is log into Seller Central and enter your merchant URL in your integration IPN settings. A full guide for setting up IPNs can be found here. From now on you will receive IPNs to this provided merchant URL.
Tips for testing your IPN integration
Viewing IPNs without setting up any code
When first testing your workflow to receive IPNs, it’s helpful to create a temporary web listener that inspects what kind of notifications are sent. There are many web tools available that quickly and effortlessly setup a temporary web listener — these tools generate a URL for you to enter within your Seller Central configuration, and once you do that you can observe all the incoming notifications in the web listener site. Here are a few examples of these sites:
NOTE: Only use these tools to test transactions in sandbox mode. Your production IPN settings should always point to a secure web listener that you own — the example temporary web listener sites are meant for testing purposes only.
Sending IPNs to your local machine while developing
Amazon Pay IPNs are only sent to HTTPS endpoints, therefore you may be wondering how to test your local code with real examples of IPNs. Localhost tunnelling tools expose your local web listener publicly during development and testing. These tools generate an HTTPS endpoint for listening to IPNs, and by running the tools on your local machine, IPNs that are sent to the generated HTTPS endpoint are automatically forwarded to your local machine, allowing you to easily receive IPNs and debug in your development environment. Otherwise, if your machine is running a local web listener with the http://localhost URL, there would be no way for Amazon Pay to send IPNs to your machine. Some examples of tools you can use for localhost tunnelling are:
Tools for changing transaction states in order to trigger IPN notifications
Amazon Pay has useful tools to help create and change the status of test orders. These tools expedite your testing and allow you to simulate actions in order to trigger a notification being sent. Some of the tools you can use for testing are:
MWS Scratchpad, for quickly generating API requests to AmazonPay and simulating state changes
Note: You will need to choose “Off-Amazon Payments Sandbox” from the API Section drop-down selector to make requests in the sandbox environment
Amazon Pay SDKs, for parsing IPNs and making requests to the Amazon Pay API
Future updates to Instant Payment Notifications
Looking towards the future, Amazon Pay will be releasing a new and improved system for IPNs. The biggest change in the new IPN system will be the concept of lean IPNs. Currently when an IPN is sent, the contents include the same details that are received when programmatically requesting them. With the lean IPN concept, only the identifier of the object is sent. The web listener code will then be required to make an API call to Amazon Pay in order to get the full details of the updated object. This improves the speed of delivery for the IPN, and reduces the amount of data the incoming IPN listener is required to process.
Can I sync my systems without IPNs?
IPNs aren’t the only way to get Amazon Pay data synced with your systems. Another technique is called polling, where you have code that runs periodically and requests the latest transaction data. This is just like the example of refreshing the sports score to see if there was an update. Polling can be setup to run at any time interval, or even in a manner called exponential backoff, where the time between requests increases each time there is no update. Developers may want to setup polling if they don’t want to manage the overhead of hosting and setting up a web listener. Polling is also useful as a backup to using IPNs — if there was ever an issue with the IPN web listener, having a process periodically checking to see if there were updates would make sure the update was received during the period of web listener down time.
Easy to setup, real time updates
Amazon Pay Instant Payment Notifications are a great way to keep your systems in sync with the latest transactional data for all your Amazon Pay orders. They are easy to setup and provide near real time updates to ensure your systems are up to date. Look out for future updates and enhancements to our IPN system, and happy coding!