登录
登录
感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

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

An IPN message is an HTTPS POST request sent to a configurable endpoint. The request content-type header is text/plain. Parse the JSON object for the IPN Message.

IPN schema

{
    "MerchantID": "Relevant Merchant for the notification",
    "ObjectType": "one of: CHARGE_PERMISSION, CHARGE, REFUND, CHARGEBACK", 
    "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_PERMISSION", CHARGE", "REFUND", "CHARGEBACK"
objectId
Identifier of the object associated with the IPN message
chargePermissionId
Identifier of the Charge Permission associated with the IPN message
notificationType
IPN message type

Possible values: "STATE_CHANGE", "ATTRIBUTE_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:

  1. 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.
  2. Check your endpoint and SSL certificates using a tool like https://digicert.com/help/ to make sure that 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, such as .htaccess rules, which require a user login.
  4. Verify that your HTTPS uses valid SSL certificates from a trusted certificate provider. For more information, see SSL Certification.

IPN types

Charge Permission

You will receive an IPN each time a Charge Permission object state changes. Note that some IPNs are only triggered for recurring and not for one-time Charge Permissions. Examples of when you will receive an IPN:

  • A buyer updates the payment method for a Charge Permission on pay.amazon.com. This will move one-time and recurring Charge Permissions from non-chargeable to chargeable state
  • Payment decline moves a recurring Charge Permission from chargeable to a non-chargeable state
  • A buyer cancels a recurring Charge Permission on pay.amazon.com
  • Amazon Pay closes or cancels a recurring Charge Permission due to fraud
  • Amazon Pay moves a recurring Charge Permission to closed state after 13 months of inactivity

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_PERMISSION\",\"ObjectId\":\"S01-0539563-2966012\",\"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"
}

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 call Create Charge
  • 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-0000000-0000000-C000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"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-0000000-0000000-R000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"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"
}

Chargeback

You will receive an IPN each time a chargeback status changes. Look up chargeback details in Seller Central using the chargePermissionId. Examples of when you will receive an IPN:

  • A buyer has filed a chargeback
  • The chargeback case has been resolved in your favor
  • The chargeback case has been resolved in the buyer’s favor

IPN message example

{
    "Type" : "Notification", 
    "MessageId" : "b8043d28-13c9-1bc2-1883-0cc63262b8ee", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"CHARGEBACK\",\"ObjectId\":\"S01-0000000-0000000-C000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"9b4155a0-c396-46d0-83f7-db1cd2cb1568\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-10T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "utm+azIy4dxAf2JmB/YtHNYmW+vL09+wXUq4oiLIIKfgQY1/wvNzT5Nq3ezF1+/EjVc+1RTe0axXgyhTn3vUO93q9nmZXm+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.