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 Handling Signatures in Responses, 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/.

Common IPN Response Elements

These response elements are common to all button 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

buyerName

Sender's name.

Type: String

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

customerName

Buyer/Sender Full Name.

Type: String

dateInstalled

If the notificationType element (below) is TokenCancellation, this element contains the date the token was installed.

Type: String

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

operation

The payment operation for this transaction.

Type: String

notificationType

Notification type may be either TokenCancellation or TransactionStatus

Type: String

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

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

tokenId

If notificationType is TokenCancellation, this element contains the ID of the cancelled token.

Type: String

tokenType

If notificationType is TokenCancellation, this element contains the type of the cancelled token.

Type: String

transactionAmount

Specifies the amount payable in this transaction; for example, USD 10.00.

Type: String

transactionDate

The date when this transaction occurred, specified in seconds since the start 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

IPN Response Elements for Subscriptions

The following IPN response elements are returned for successful creation of subscriptions.

Name Description

addressLine1

Sender's address (first line). This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

addressLine2

Sender's address (second line). This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

addressName

Sender's name. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

buyerEmail

Sender's e-mail address.

	Note
	The `buyerEmail` element is not returned for transactions where the recipient is not the caller (i.e., marketplace transactions).

Type: String

buyerName

Sender's name.

Type: String

city

Sender's address - city. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

country

Sender's address - country. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

noOfPromotionTransactions

Number of transactions for this promotion. This element is only returned if there was a trial period with a special promotional rate.

Type: Integer

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

phoneNumber

Sender's telephone number. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

promotionAmount

Amount charged for this promotion. This element is only returned if there was a trial period with a special promotional rate.

Type: String

recipientEmail

Recipient's e-mail address.

Type: String

recipientName

Recipient's name.

Type: String

recurringFrequency

Tells how often the subscription fee will be charged.

Type: String

referenceId

If you specified a referenceId in the button creation form, Amazon Payments returns the referenceId to you.

Type: String

signature

Type: String

startValidityDate

Date the subscription begins. This is expressed as the timestamp value from the epoch in seconds.

Type: String

state

Sender's address - state. This element is returned only if the collectshippingaddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

status

For a successful creation, the status code returned is SubscriptionSuccessful.

Type: String

subscriptionId

A unique value identifying the subscription that is generated by Amazon Payments.

Type: String

subsciptionPeriod

Total time period to charge for the subscription.

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: String

transactionSerialNumber

For Subscriptions, a unique value identifying the subscription that is generated by Amazon Payments. This element is returned only for subscription transactions.

Type: Integer

zip

Sender's zip code. This element is returned only if the collectshippingaddress parameter was passed as true in the Amazon Simple Pay HTML form.

Type: String

The following IPN response elements are returned for successful cancellation of subscriptions.

Name Description

Name	Description
`subscriptionId`	A unique value identifying the subscription that is generated by Amazon Payments. Type: String
`status`	For a successful cancellation, the status code sent is `SubscriptionCanceled`. Type: String
`statusReason`	Reason for this status. Type: String

subscriptionId

A unique value identifying the subscription that is generated by Amazon Payments.

Type: String

status

For a successful cancellation, the status code sent is SubscriptionCanceled.

Type: String

statusReason

Reason for this status.

Type: String

The following IPN elements are returned for successful completion of subscriptions.

Name Description

Name	Description
`subscriptionId`	A unique value identifying the subscription that is generated by Amazon Payments. Type: String
`status`	For a successful completion, the status code sent is `SubscriptionCompleted`. Type: String

subscriptionId

A unique value identifying the subscription that is generated by Amazon Payments.

Type: String

status

For a successful completion, the status code sent is SubscriptionCompleted.

Type: String

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
`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`	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`	Type: String