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. Because you cannot know when asynchronous transactions will 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
A refund succeeds
A refund fails
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 web site 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 displays.
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/.

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 response elements are common to all 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 e-mail 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

customData

Data passed by the customer in the Pay call is returned in this element.

Type: String

customerEmail

Customer's e-mail 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

integratorId

If present, this is the id of the solution provider assisting with the transaction.

Type: String

isShippingAddressProvided

If the IPN results include address updates, this element contains TRUE. Otherwise this element is not present in the response.

Type: String

Size: 32 Bytes (or Boolean==1?)

operation

The payment operation for this transaction.

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 e-mail address.

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: 1 | 2

signatureMethod

A value that specifies the signing method.

Type: String

Valid Values: HmacSHA256 (preferred) and HmacSHA1.

status

Shorthand code that specifies the status of the transaction..

For more information, see TransactionStatus (IPN)

Type: String

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 cancelled 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

IPN Responses for Marketplace Transactions

The following IPN response elements are returned for marketplace transactions.

IPN Marketplace Transaction Elements

Name	Description
`buyerName`	Sender's name. Type: String
`operation`	The payment operation for this transaction. 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 e-mail address. Type: String
`recipientName`	Recipient's name. Type: String
`referenceId` `Refund for`	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`	Shorthand code that 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