AWS Documentation » Amazon Flexible Payments Service » Basic Quick Start » Programming Guide » Setting Up Instant Payment Notification	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Setting Up Instant Payment Notification

When the sender uses ABT (Amazon Payments Balance Transfer) to pay for a purchase, the purchase is approved or denied synchronously, which means that processing stops until the Pay call returns, and this happens relatively quickly. When the sender uses ACH (bank account withdrawal) or a credit card, the purchase is asynchronous, which means that it can take much longer to succeed or fail.

Since you cannot easily determine when asynchronous transactions complete, Amazon FPS has created a notification service called Instant Payment Notification (IPN) that uses HTTP POST to notify you when the following asynchronous transactions occur:

A payment or reserve succeeds
A payment or reserve fails
A payment or reserve goes into a pending state
A reserved payment is settled successfully
A reserved payment is not settled successfully
A refund succeeds
A refund fails
A refund goes into a pending state
A payment is canceled
A reserve is canceled
A token is canceled successfully

Note

IPN must be configured in order to operate. If you do not configure IPN, only email notifications will be sent.

IPN is a simple way to process updates from Amazon FPS and has the following benefits compared to other notification mechanisms:

Easy implementation (compared to polling for updates)
Robust delivery mechanism
Robust to changes in message parameters
Simple message structure

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.

Setting Up IPN Preferences

To receive IPN notifications, you need to set up a web service that receives IPN notifications from Amazon FPS and register the URL of that web service in your Amazon FPS developer account on http://payments.amazon.com.

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

To configure your developer account so that you receive IPN messages

Log in to the Amazon Payments website at http://payments.amazon.com.
Click Edit My Account Settings.
The Edit My Account Settings page displays.
Click Manage Developer and Seller Preferences.
The Manage Developer and Seller Preferences page appears.
Enter the URL for your IPN server in the URL for Instant Payment Notification text box.

Receiving IPN Notifications

Amazon FPS uses HTTP POST to send IPN notifications to the URL registered in your Amazon Payments developer account. Use the following process to create a script that handles IPN notifications.

Tip

If your IPN receiving service is down for some time, it is possible that our retry mechanism will deliver the IPNs out of order. If you receive an IPN for TransactionStatus (IPN), as SUCCESS or FAILURE or RESERVED, then after that time ignore any IPN that gives the PENDING status for the transaction.

Setup Process for a Script to Receive IPN

1	Set up your web server to receive the HTTP POST IPN notifications on one of the following ports: 8080, 80 [http], 8443, or 443 [https].
2	Write a program that parses the IPN elements (for a list of the elements, see Common IPN Response Elements).
3	Write your program so that it verifies the `signature` value sent in the IPN to make sure Amazon FPS sent the IPN. For more information, see Verifying the ReturnURL and IPN Notifications, below.
4	Write your program to use the returned elements to notify you of the IPN-related transactions.

Important

The signature parameter won't 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 Certificate 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/.

How To Verify the IPN Signature

You must ensure that the IPN indeed came from Amazon Payments. You can do this by verifying the value of the signature parameter contained in the response. IPN responses contain the components you need to validate with server-side signature verification. For more information, see Verifying the ReturnURL and IPN Notifications.

You can use the IPNAndRuturnURLValidation sample to assist creating your own IPN validation page. For more information, see Understanding the IPNAndReturnURLValidation Sample

Common IPN Response Elements

These IPN response elements are common to most types of transactions. For a list of IPN response elements for marketplace transactions, see IPN Responses for Marketplace Transactions.

Name	Description
`addressFullName`	Full name of the buyer/sender. Type: String
`addressLine1`	Sender's address (first line). For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`addressLine2`	Sender's address (second line). For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`addressState`	Sender's state. For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`addressZip`	Sender's post code. For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`addressCountry`	Sender's country. For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`addressPhone`	Sender's phone number. For IPN, this element is returned only if the value has been updated with Amazon. Type: String
`buyerEmail`	Sender's email address. Note The `buyerEmail` element is not returned when the recipient is not the caller (i.e., marketplace transactions). Type: String Size: 65 bytes
`buyerName`	Sender's name. Type: String Size: 128 bytes
`certificateUrl`	A url specifying the location of the certificate used for signing the response. Type: String Max Size: 1024 bytes
`customerEmail`	Customer's email address. Type: String Size: 65 bytes
`customerName`	Buyer/Sender Full Name. Type: String Size: 128 bytes
`dateInstalled`	If the `notificationType` element (below) is `TokenCancellation`, this element contains the date the token was installed. Type: String Size: 30 bytes
`isShippingAddressProvided`	If the IPN results include address updates, this element contains TRUE. Otherwise this element is not present in the response. Type: String
`operation`	The name of the payment action, also called an operation, used for this transaction. For example, PAY for the action Pay. Type: String Max Size: 20 bytes
`notificationType`	Notification type may be either `TokenCancellation` or `TransactionStatus` Type: String Size: 20 bytes
`paymentMethod`	The payment method used by the sender. For more information, see the IPN values in PaymentMethod. Type: String Size: 20 bytes
`paymentReason`	Reason for payment. Type: String
`recipientEmail`	Recipient's email address. Note As a security precaution, you should always check that the recipient email is the same as the one in your original request. Type: String Size: 65 bytes
`recipientName`	Recipient's name. Type: String Size: 128 bytes
`signature`	The encoded string the caller uses to verify the IPN. Amazon Payments calculates the signature using the elements in the returnURL. The merchant must have manually signed the request. For more information, see Handling the Receipt of IPN Notifications. We recommend that you always verify the signature using the method in How to Verify the IPN Signature. Type: String Size: 512 bytes
`signatureVersion`	A value that specifies the `Signature` format. Type: Integer Valid Values: 2
`signatureMethod`	A value that specifies the signing method. Type: String Valid Values: HmacSHA256 (preferred) and HmacSHA1.
`tokenId`	If `notificationType` is `TokenCancellation`, this element contains the ID of the cancelled token. Type: String Size: 65 bytes
`tokenType`	If `notificationType` is `TokenCancellation`, this element contains the type of the canceled token. Type: String Size: 20 bytes
`transactionAmount`	Specifies the amount payable in this transaction; for example, USD 10.00. Type: String Size: 30 bytes
`transactionDate`	The date when this transaction occurred, specified in seconds since the start of the epoch. Type: Long Size: 40 bytes
`transactionId`	Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String Size: 35 bytes
`transactionStatus`	Specifies the status of the transaction. For more information, see TransactionStatus (IPN). Type: String

IPN Responses for Marketplace Transactions

The following IPN response elements are returned only for marketplace transactions.

IPN Marketplace Transaction Elements

Name	Description
`buyerName`	Sender's name. Type: String
`operation`	The name of the payment action, also called an operation, used for this transaction. For example, PAY for the action Pay. Type: String Max Size: 20 bytes
`paymentMethod`	The payment method used by the sender. For more information, see the IPN values in PaymentMethod. Type: String
`paymentReason`	Reason for payment. Type: String
`recipientEmail`	Recipient's email address. Type: String
`recipientName`	Recipient's name. Type: String
`referenceId`	If you specified a referenceId in the button creation form, Amazon Payments returns the referenceId to you. Type: String
`signature`	The encoded string the caller uses to verify the IPN. Amazon Payments calculates the signature using the elements in the returnURL. The merchant must have manually signed the request. For more information, see Handling the Receipt of IPN Notifications. We recommend that you always verify the signature using the method in How to Verify the IPN Signature. Type: String
`status`	Specifies the status of the transaction. For more information, see TransactionStatus (IPN). Type: String
`transactionAmount`	Specifies the amount payable in this transaction; for example, USD 10.00. This element is not being returned in the current version. Type: Double
`transactionDate`	The date when this transaction occurred, specified in seconds since the beginning of the epoch. Type: Long
`transactionId`	Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...