Handling Instant Payment Notification (IPN) messages

Overview

Amazon processes some of your payment requests in an asynchronous manner. After Amazon processes the request, the status of the corresponding payment objects are updated. While you might check for this status page by periodically requesting it from our API, you can also set up a listener and receive notifications via Instant Payment Notification (IPN) messages.

IPN messages are sent by Amazon Pay without any action required on your part and can be used to update your internal order management system and process orders.

If any of the following occurs you need to wait for IPN messages to obtain the results:

  • You make an asynchronous Authorization API call.
  • When a Capture response comes back as Pending.
  • You make a Refund API call.
  • A customer's bank or credit card company issues a chargeback or reversal of payment.

The most common modification to an object is a state change, but other modifications trigger an IPN. For example, a customer might update their shipping address, or Amazon might decline a payment method.

For more information about payment object state transitions, see the States and reason codes section of the Amazon Pay API reference guide.

Setting up to receive IPN messages

An IPN message is an HTTPS POST request containing the XML-based notification data in its body. Before you can receive IPN messages you must do this:

  1. Set up endpoints in Seller Central.
    1. To set up endpoints, sign in in to Seller Central, click Settings, and then click Integration Settings.
    2. Under the Instant Notifications Settings section, click Edit, and then enter your Merchant URL on your endpoint where you want to receive instant notifications. Note that you need to use HTTPS for production, but for the Sandbox environment HTTP is acceptable as an alternative to HTTPS. If you specify an HTTPS endpoint, however, the certificate must be valid and have an intact certificate chain up to a root certificate.
    3. If you need to receive the IPNs for the same event on two distinct endpoints, you can provide the URL in the Integrator URL.
  2. Check your endpoint and SSL certificates to make sure they are working properly.
  3. Verify that you are running a web service that can receive HTTPS POST requests made to your endpoint and process the notifications. Remove potential access protections, like .htaccess rules requiring a user login.
  4. Verify that your HTTPS uses valid SSL certificates from a trusted certificate provider. For more information, see SSL certification.

Secure IPN processing

To prevent spoofing attacks, you must validate the IPN signature to verify the authenticity of the message. For more information, see Verifying the Signatures of Amazon SNS Messages.

If you are using an Amazon SDK, this validation is handled for you. If not, use the same validation steps as described in Verifying the Signatures of Amazon SNS Messages and as implemented in the SDKs.

See also