Instant Payment Notification

Instant Payment Notification (IPN) is a notification mechanism that uses HTTP POST to provide updates on transactions. IPN is a simple way to process updates from FPS, and has benefits not found in other notification mechanisms:

Simple message structure
Robust delivery mechanism
Easily accomodates changes to the message parameters

Although you cannot use polling and web service notifications concurrently, you can use IPN in conjunction with polling or web service notifications.

	Tip
	If you have signed up for IPN and do not receive notifications, verify the URL you provided in your account settings. IPN will try for a day to deliver a notification before it gives up. You must poll for the results using GetResults if your server is not able to receive the IPN notification.

The IPN is sent to indicate the final status of asynchronous transactions (CC, ACH). To be consistent, IPN is sent wherever GetReults and web service notifications are sent.

If you decide to use IPN, sign in to your Amazon Payments account, and enter the URL for your web server. Once you sign up for IPN, notifications are sent to your server.

To specify the URL in account settings

Log in to the Amazon Payments web site at http://payments.amazon.com.
Point to Edit My Account Settings.
On the Manage Developer and Seller Preferences page, enter a URL for Instant Payment Notifications.
You can specify an optional port number in the URL if you want to use a specific port number.

The following parameters are sent in an IPN notification.

Parameter Description

transactionId

The Amazon FPS transaction ID.

callerReference

Caller reference passed in transactional APIs.

operation

The payment operation for this transaction.

paymentReason

The caller description passed in the transaction API call.

transactionAmount

The amount of this transaction, for example, USD 10.00.

transactionDate

The date when this transaction occurred, specified in seconds since January 1, 1970.

status

The status of the transaction as returned in GetTransaction.

paymentMethod

The payment method used by the buyer.

parentTransactionId

The transaction ID used in case of refunds.

errorCode

The error returned for failures.

recipientName

The name of the recipient.

buyerName

The name of the buyer.

recipientEmail

The e-mail address of the recipient.

buyerEmail

The e-mail address of the buyer.

	Note
	The `buyerEmail` parameter is not returned for transactions where recipient != caller (marketplace applications).

signature

Signature is the encoded string the caller uses to verify the authenticity of the IPN using his secret key.

	Important
	The signature parameter will not be sent if you are using the SOAP protocol to call FPS API actions. We recommend that you set up an HTTPS endpoint using a standard Certifying Authority to receive IPN if you are using SOAP.

Amazon FPS currently supports all the SUN JDK 1.5 CAs (cacerts file). In addition, we also support the standard CAs listed on http://www.mozilla.org/projects/security/certs/included/. Supported ports include 8080, 80 [http] ,8443, and 443 [https].

You must ensure that the IPN was indeed sent by Amazon Payments by verifying the signature sent by the IPN. If you are a Java developer, you can use the sample code for verifying the return signature from Amazon Payments. This sample code is available in the Amazon FPS Developer Resource Center.

To Verify the Return Signature from Amazon FPS

Gather all of the POST parameters from the HTTP notification.
Sort the remaining parameters alphabetically by parameter name.
Do not include the signature parameter.
Concatenate the name value pairs from the previous step in the sorted order to create a single string of the form name1value1name2value2.
Calculate the RFC 2104-compliant signature (see the Generate a Signature for Your Button topic in the Amazon Simple Pay Implementation Guide for the API code snippet) from the string computed in step 3.
Compare the value of the signature supplied in the HTTP POST with the signature you computed in step 4.
The signatures must be equal.

For more information, see GetResults and Web Service Notifications. Also, see the Amazon Simple Pay Implementation Guide.