Accedi

Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Important: There is a new Amazon Pay Checkout version. Amazon Pay will continue to support this version but it will not be updated with new features. See release notes for changelog. Please consider migrating to the newer version for the latest checkout features if you are still using API Version 1. See Check API Version to find out what version you are using.

Set up Instant Payment Notifications

Set up Instant Payment Notifications (IPNs) to receive notifications for events related to Amazon Pay transactions. Use IPNs to update your order states and process transactions.

Note: IPNs are used to process updates from asynchronous transactions.

IPN overview
Setting up an IPN endpoint
IPN types
IPN retry logic
Best practices

IPN overview

An IPN message is an HTTPS POST request sent to a configurable endpoint. Parse the JSON object for the IPN Message.

IPN schema

{
    "merchantID": "Relevant Merchant for the notification",
    "objectType": "one of: CHARGE, REFUND",
    "objectId": "Id of relevant object",
    "chargePermissionId": "Id of relevant Charge Permission",
    "notificationType": "STATE_CHANGE",
    "notificationId": "Randomly generated Id, used for tracking only",
    "notificationVersion": "V2"
}

IPN parameters

Parameter	Description
merchantID	Identifier of the merchant associated with the IPN message
objectType	Type of object associated with the IPN message Possible values: "CHARGE" or "REFUND"
objectId	Identifier of the object associated with the IPN message
notificationType	IPN message type Possible values: "STATE_CHANGE"
notificationId	IPN message identifier. Used for tracking purposes only
notificationVersion	IPN message format version. This is not related to the Amazon Pay API version

You must make a GET API call for the transaction specified in the message to determine transaction state. See the IPN types section for more information.

Setting up an IPN endpoint

In Seller Central, the account management site for Amazon Pay merchants, you can setup IPN endpoints for both Production and Sandbox environments. Select the environment from the drop-down options located in the center of the menu at the top of the screen.

If your screen is minimized, the environment and drop-down options are replaced with this button:

After choosing the environment, follow these steps to start receiving IPN messages:

Set up endpoints in Seller Central.
1. To set up endpoints, sign 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 at the endpoint where you want to receive instant notifications. Note that you need to use HTTPS for Production, but for the Sandbox environment, HTTP is an acceptable alternative to HTTPS. However, if you specify an HTTPS endpoint, the certificate must be valid and have a certificate chain connected to a root certificate.
3. If you or your integrator need to receive the IPNs for the same event at two distinct endpoints, you can provide the URL in the Integrator URL field.
Check your endpoint and SSL certificates using a tool like https://digicert.com/help/ to make sure that they are working properly.
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, such as .htaccess rules, which require a user login.
Verify that your HTTPS uses valid SSL certificates from a trusted certificate provider. For more information, see SSL Certification.

IPN types

Charge

You will receive an IPN each time the Charge object state changes. Check Charge state using Get Charge to determine if the Charge was successful. Examples of when you will receive an IPN:

You Capture with canHandlePendingAuthorization parameter set to True
You authorize payment on a Charge, and receive a pending response in AuthorizationInitiated state
You capture payment on a Charge, and receive a pending response in CaptureInitiated state
A charge is canceled

IPN message example

{
    "Type" : "Notification", 
    "MessageId" : "a7045d68-12c9-5bc2-8447-0bb63262b8dd", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"CHARGE\",\"ObjectId\":\"S01-0539563-2966012-C016012\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"dda4e3a5-ed5f-4766-b47f-4d8eb133bb01\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-07T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "hyj+azIy4dxAf2JmB/AgNSYmW+vL09+wXUq4oiLUUhfgQY1/wvNzT5Nq3ezF1+/EjVc+5RTe0axXgyhTn3vUO93q9nmWXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

Refund

You will receive an IPN each time the Refund object state changes. Because refunds are processed asynchronously, you will receive an IPN when the refund has finished processing. Check Refund state using Get Refund to determine if the Refund was successful.

IPN message example

{
    "Type" : "Notification", 
    "MessageId" : "a7045d68-12c9-5bc2-8447-0bb63262b8dd", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"REFUND\",\"ObjectId\":\"S01-0539563-2966012-R016012\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"326100f2-eyd3-4a8b-113d-8f48cd2f8f0w\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-07T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "hyj+azIy4dxAf2JmB/AgNSYmW+vL09+wXUq4oiLUUhfgQY1/wvNzT5Nq3ezF1+/EjVc+5RTe0axXgyhTn3vUO93q9nmWXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

IPN retry logic

Amazon Pay will retry sending an IPN if:

Your endpoint responds with HTTP status codes 100 to 101 and 500 to 599 (inclusive)
The request times out (15 seconds). Note that if a request timeout occurs, the next retry will occur every hour for the next 3 hours.
There is a connection error such as connection timeout, endpoint unreachable, bad SSL certificate, etc.

Best practices

Test in Sandbox

The Sandbox environment enables you to test your Amazon Pay integration before going live. We recommend always setting up and testing IPN functionality in the Sandbox environment first. Be sure to add your Production endpoint before going live.

See the Amazon Pay IPN blog post for tips on how to test your IPN integration.

Handle duplicate notifications

You might occasionally receive duplicate notifications. Make sure your code for processing IPNs is idempotent. A potential solution is to log notifications you’ve already processed and skip duplicates notifications with the same notification ID.