Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.
 Synchronizing your systems with Amazon Pay | Amazon Pay

Synchronizing your systems with Amazon Pay

Payment Object State transitions

The Amazon Pay and Login with Amazon objects (Billing Agreement object, Order Reference object, Authorization object, Capture object, and Refund object) transition to various states as a part of the payment process. These state transitions can take place as a result of certain operations performed by your system or by internal Amazon business rules.

For example, an Authorization object requested in asynchronous mode first goes to the Pending state while it is being processed. After the processing is complete, it moves to the Open state, which indicates that it is ready for capturing funds. After the Authorization object is captured, it moves to the Closed state, which indicates that no funds can be captured against that authorization. Alternatively, if you do not capture an authorization within 30 days, Amazon marks it as Closed. You should synchronize your system with the current state of a payment object in Amazon's system to prevent integration errors.

For detailed information about payment object state transitions, see "States and reason codes" found in the Amazon Pay API reference guide.

Additionally, Amazon allows a buyer to update or change their payment method after a purchase is complete, which might result in an update to the Billing Agreement. You might want to know about such changes to support your customer service and business processes.

Initial responses to API calls

The immediate, or synchronous, response to an operation depends on the type of operation and when the initial request is made.

  • AuthorizeOnBillingAgreement -- Amazon Pay doesn't process asynchronous AuthorizeOnBillingAgreement requests in real time. The asynchronous response to this call always returns the state as Pending. Synchronous AuthorizeOnBillingAgreement requests return a response of Open or Declined.
  • Capture -- A capture is processed in real time if it is requested within seven days of authorization. During this period, the synchronous response of the Capture request returns the state as Completed or Declined. If a capture is requested more than seven days after the authorization, the Capture operation returns the Pending state. These objects remain in the Pending state until Amazon processes the request.
  • Refund -- Refund requests are not processed in real time. The synchronous response to a refund request is always Pending.

The following table shows the initial response to API calls for the AuthorizeOnBillingAgreement, Capture, and Refund API calls.

API call Initial response to the API calls
AuthorizeOnBillingAgreement Synchronous Mode: Either Open or Declined
Async Mode: Always Pending
Capture Either Completed, Pending, or Declined
Refund Always Pending

Receiving asynchronous updates about status changes

After processing is complete, Amazon sends an asynchronous Instant Payment Notification (IPN) to inform you of the processing result. You can then query the status and details of these payment objects using the Off-Amazon Payments API section operations described below. For information about setting up to receive IPN messages, see Handling Instant Payment Notification (IPN) messages.

Best practices for handling Instant Payment Notification messages

Perform a get API call

Amazon sends you an asynchronous Instant Payment Notification (IPN) message when the state of any of the payment objects, the Billing Agreement object, or the Order Reference object changes. These notifications are always sent without any action required on your part and can be used to update any internal tracking or fulfillment systems you might be using to manage the order.

After you receive an IPN, a best practice is to perform a get operation for the respective object for which you have received the notification. You can use the response of the get operation to update your systems.

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.

Monitoring Payment Object state transitions

You can use Instant Payment Notifications (IPNs) to monitor the state transition of payment objects. IPNs will automatically inform you of a change in state of a payment object. After you have received an Instant Payment Notification, you can poll the service using the GetBillingAgreementDetails, GetAuthorizationDetails, GetCaptureDetails, or GetRefundDetails operations to get full details about a payment object.

Instant Notifications example

Amazon sends you a notification when the state of any of the payment objects or the Billing Agreement object changes. These notifications are always sent without any action required on your part and can be used to update any internal tracking or fulfillment systems that you might be using to manage the order or subscription.

You can set up your Notification endpoints in Seller Central by going to the Integration Settings page in Settings.

For example, you might get a notification from Amazon indicating that an Authorization object has transitioned from the Pending state to the Open state. This transition indicates that the AuthorizeOnBillingAgreement operation call was successful and that you can now proceed with the order fulfillment process, knowing that the payment was successfully authorized.

With each notification that you receive, configure your endpoint to send Amazon a "200 OK" response immediately after receipt. If you do not send this response, Amazon SNS performs retries every hour for 14 days. If your server is down when the SNS message is sent (a 4xx error code is returned), there will be no retries from Amazon SNS.

Note: Most of the time each notification is delivered to your application exactly once but because of the distributed nature of Amazon SNS and transient network conditions, a duplicate message is occasionally possible. Be sure to design your application so that if multiple IPN messages are received your payment workflow doesn't break.

For more information about the format of the Instant Notification, see HTTP/HTTPS Notification JSON Format in the Amazon SNS Getting Started Guide, which is available in the Amazon AWS Documentation portal.

The contents of the NotificationData member that is returned in the Instant Notification are described by the following publicly available XSD: https://amazonpayments.s3.amazonaws.com/documents/payments_ipn.xsd.

All Instant Notifications received from Amazon are signed. For more information about how to verify the signature, see Verifying the Signatures of Amazon SNS Messages in the Amazon SNS Getting Started Guide, which is available in the Amazon AWS Documentation portal.

The following is a list of notifications available from Amazon:

  • BillingAgreementNotification
  • OrderReferenceNotification
  • AuthorizationNotification
  • CaptureNotification
  • RefundNotification

These IPNs are triggered when the status of the payment object is updated. In addition, you also receive an IPN when the buyer updates the payment method or address associated with the Billing Agreement. The BillingAgreementNotification contains an EventType parameter that explains the reason that the notification was sent. The EventType parameter has four possible values:

  • BillingAgreementStatusUpdated
  • PaymentMethodUpdated
  • AddressUpdated
  • AddressAndPaymentMethodUpdated

Note: Address refers to shipping address. For billing address updates after receiving StatusUpdated IPN, use GetBillingAgreementDetails.

The following example shows the BillingAgreementNotification:

 
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 432f33bf-9f84-5004-815f-7a6cfEXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
  "Type" : "Notification",
  "MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
  "TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
  "Message" :
    "{"NotificationReferenceId":"48305092-c8ae-424c-a886-
    09d3aa48888e","MarketplaceID":"165580",
    "NotificationType":"BillingAgreementNotification",
    "SellerId":" YOUR_SELLER_ID_HERE 
    ","ReleaseEnvironment":"Sandbox","EventType":"PaymentMethodUpdated",
    "Version":"2013-01-01",
    "NotificationData":"\n    
    \n        
    
      C01-9478069-example
    <\/AmazonBillingAgreementId>\n        
    \n            
       YOUR_SELLER_ID<\/SellerId>\n        
    <\/SellerBillingAgreementAttributes>\n        
    \n          
      Open<\/State>\n            
      2014-01-07T07:28:06.582Z
      <\/LastUpdateTimestamp>\n        
    <\/BillingAgreementStatus>\n        
    
      2014-01-07T07:26:16.775Z
    <\/CreationTimestamp>\n        
    \n        
    \n
    500.0<\/Amount>\n                
    USD<\/CurrencyCode>\n            
    <\/AmountLimitPerTimePeriod>\n            
    
      2014-01-01T00:00:00.000Z
    <\/TimePeriodStartDate>\n            
    
      2014-02-01T00:00:00.000Z
    <\/TimePeriodEndDate>\n            
    \n                
    500.0<\/Amount>\n                
    USD<\/CurrencyCode>\n            
    <\/CurrentRemainingBalance>\n        
    <\/BillingAgreementLimits>\n        
    
      true
    <\/BillingAgreementConsent>\n    
    <\/BillingAgreement>\n
    <\/BillingAgreementNotification>","Timestamp":"2014-01-11T01:44:42Z"}
    ",
  "Timestamp" : "2013-04-22T06:00:15.108Z",
  "SignatureVersion" : "1",
  "Signature" : "deako5R0...CVmPQOI=",
  "SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
  SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",
  "UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
  ?Action=Unsubscribe
  &SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}
    

The following example shows the OrderReferenceNotification:

 
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 432f33bf-9f84-5004-815f-7a6cfEXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
    arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961 
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
  "Type" : "Notification",
  "MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
  "TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
  "Message" :
    "{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab2EXAMPLE\",
      \"NotificationType\":\"OrderReferenceNotification\",
      \"SellerId\":\"YOUR_SELLER_ID_HERE\",
      \"ReleaseEnvironment\":\"Sandbox\",
      \"Version\":\"2013-01-01\",
      \"NotificationData\":
      \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>
        <OrderReferenceNotification
          xmlns=\\\"https://mws.amazonservices.com/
                    ipn/OffAmazonPayments/2013-01-01\\\">\\n
        <OrderReference>\\n
        <AmazonOrderReferenceId>
          S23-1234567-1234567
        <\\/AmazonOrderReferenceId>\\n
        <OrderTotal>\\n
        <Amount>106.00<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/OrderTotal>\\n
        <OrderReferenceStatus>\\n
        <State>CLOSED<\\/State>\\n
        <ReasonCode>SellerClosed<\\/ReasonCode>\\n
        <LastUpdateTimestamp>
          2013-04-01T10:49:59.532Z
        <\\/LastUpdateTimestamp>\\n
        <\\/OrderReferenceStatus>\\n
        <CreationTimestamp>2013-03-30T09:58:51.234Z<\\/CreationTimestamp>\\n
        <ExpirationTimestamp>
          2013-04-06T09:58:51.234Z
        <\\/ExpirationTimestamp>\\n
        <\\/OrderReference>\\n
        <\\/OrderReferenceNotification>\",
      \"Timestamp\":\"2013-04-22T06:00:14Z\"}",
  "Timestamp" : "2013-04-22T06:00:15.108Z",
  "SignatureVersion" : "1",
  "Signature" : "deako5R0...CVmPQOI=",
  "SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
    SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",
  "UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
    ?Action=Unsubscribe
    &SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}

The following example shows the AuthorizationNotification:

 
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 6f7e123e-49c9-5c9d-a389-5bed0EXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961 
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
  "Type" : "Notification",
  "MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
  "TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
  "Message" :
    "{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab28909513\",
      \"NotificationType\":\"PaymentAuthorize\",
      \"SellerId\":\"YOUR_SELLER_ID_HERE\",
      \"ReleaseEnvironment\":\"Sandbox\",
      \"Version\":\"2013-01-01\",
      \"NotificationData\":
      \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>
        <AuthorizationNotification
          xmlns=\\\"https://mws.amazonservices.com/
                    ipn/OffAmazonPayments/2013-01-01\\\">\\n
        <AuthorizationDetails>\\n
        <AmazonAuthorizationId>
          S23-1234567-1234567-0000001
        <\\/AmazonAuthorizationId>\\n
        <AuthorizationReferenceId>
          9bbe88cd5ab4435b85d717fd8EXAMPLE
        <\\/AuthorizationReferenceId>\\n
        <AuthorizationAmount>\\n
        <Amount>5.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/AuthorizationAmount>\\n
        <CapturedAmount>\\n
        <Amount>0.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/CapturedAmount>\\n
        <AuthorizationFee>\\n
        <Amount>0.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/AuthorizationFee>\\n
        <IdList/>\\n
        <CreationTimestamp>2013-04-22T05:59:38.186Z<\\/CreationTimestamp>\\n
        <ExpirationTimestamp>
          2013-05-22T05:59:38.186Z
        <\\/ExpirationTimestamp>\\n
        <AuthorizationStatus>\\n
        <State>Open<\\/State>\\n
        <LastUpdateTimestamp>
          2013-04-22T06:00:11.473Z
        <\\/LastUpdateTimestamp>\\n
        <\\/AuthorizationStatus>\\n
        <OrderItemCategories/>\\n
        <CaptureNow>false<\\/CaptureNow>\\n
        <SoftDescriptor/>\\n
        <\\/AuthorizationDetails>\\n
        <\\/AuthorizationNotification>\",
      \"Timestamp\":\"2013-04-22T06:00:14Z\"}",
  "Timestamp" : "2013-04-22T06:00:15.108Z",
  "SignatureVersion" : "1",  
  "Signature" : "W/cfaDzC...5glwqJk=",
  "SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
    SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",
  "UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
    ?Action=Unsubscribe
    &SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}

The following example shows the CaptureNotification:

 
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 64f5f75c-5799-53e5-b4c3-be8f1EXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961 
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
  "Type" : "Notification",
  "MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
  "TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
  "Message" :
    "{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab2EXAMPLE\",
      \"NotificationType\":\"PaymentCapture\",
      \"SellerId\":\"YOUR_SELLER_ID_HERE\",
      \"ReleaseEnvironment\":\"Sandbox\",
      \"Version\":\"2013-01-01\",
      \"NotificationData\":
      \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>
        <CaptureNotification
          xmlns=\\\"https://mws.amazonservices.com/
                   ipn/OffAmazonPayments/2013-01-01\\\">\\n
        <CaptureDetails>\\n
        <AmazonCaptureId>S23-1234567-1234567-0000002<\\/AmazonCaptureId>\\n
        <CaptureReferenceId>
          6f4d9dea0c234279a65e77994EXAMPLE
        <\\/CaptureReferenceId>\\n
        <CaptureAmount>\\n
        <Amount>5.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/CaptureAmount>\\n
        <RefundedAmount>\\n
        <Amount>0.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/RefundedAmount>\\n
        <CaptureFee>\\n
        <Amount>0.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/CaptureFee>\\n
        <IdList/>\\n
        <CreationTimestamp>2013-04-22T06:02:22.026Z<\\/CreationTimestamp>\\n
        <CaptureStatus>\\n
        <State>Completed<\\/State>\\n
        <LastUpdateTimestamp>
          2013-04-22T06:02:25.227Z
        <\\/LastUpdateTimestamp>\\n
        <\\/CaptureStatus>\\n
        <SoftDescriptor>AMZ*softdescriptor<\\/SoftDescriptor>\\n
        <\\/CaptureDetails>\\n
        <\\/CaptureNotification>\",
      \"Timestamp\":\"2013-04-22T06:00:14Z\"}",
  "Timestamp" : "2013-04-22T06:00:15.108Z",
  "SignatureVersion" : "1",
  "Signature" : "dUWd9lrs...iNGKnR4=",
  "SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
    SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",   
  "UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
    ?Action=Unsubscribe
    &SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}

The following example shows the RefundNotification:

 
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 5f43584c-1f96-5880-9c98-119f5EXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961 
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
  "Type" : "Notification",
  "MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
  "TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
  "Message" :
    "{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab2EXAMPLE\",
    \"NotificationType\":\"PaymentRefund\",
    \"SellerId\":\"YOUR_SELLER_ID_HERE\",
    \"ReleaseEnvironment\":\"Sandbox\",
    \"Version\":\"2013-01-01\",
    \"NotificationData\":
      \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>
        <RefundNotification
          xmlns=\\\"https://mws.amazonservices.com/
                    ipn/OffAmazonPayments/2013-01-01\\\">\\n
        <RefundDetails>\\n
        <AmazonRefundId>S23-1234567-1234567-0000003<\\/AmazonRefundId>\\n
        <RefundReferenceId>
          07fff0c4e05046958db7e47607e7db17
        <\\/RefundReferenceId>\\n
        <RefundType>SellerInitiated<\\/RefundType>\\n
        <RefundAmount>\\n
        <Amount>5.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/RefundAmount>\\n
        <FeeRefunded>\\n
        <Amount>0.0<\\/Amount>\\n
        <CurrencyCode>USD<\\/CurrencyCode>\\n
        <\\/FeeRefunded>\\n
        <CreationTimestamp>2013-04-22T06:07:34.617Z<\\/CreationTimestamp>\\n
        <RefundStatus>\\n
        <State>Completed<\\/State>\\n
        <LastUpdateTimestamp>
          2013-04-22T06:09:20.178Z
        <\\/LastUpdateTimestamp>\\n
        <\\/RefundStatus>\\n
        <SoftDescriptor>AMZ*softDescriptor<\\/SoftDescriptor>\\n
        <\\/RefundDetails>\\n
        <\\/RefundNotification>\",
    \"Timestamp\":\"2013-04-22T06:00:14Z\"}",
  "Timestamp" : "2013-04-22T06:00:15.108Z",
  "SignatureVersion" : "1",
  "Signature" : "kjac14DH...oQT6FbA=",
  "SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
    SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",
  "UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
    ?Action=Unsubscribe
    &SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}

Polling API example

The following example shows how to call the GetAuthorizationDetails operation to get the status of an Authorization object:

 
https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=GetAuthorizationDetails
&AmazonAuthorizationId=S23-1234567-1234567-0000001
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-12-19T19%3A01%3A11Z
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
    

For more information about the GetAuthorizationDetails operation, including the request parameters and response elements, see the GetAuthorizationDetails section in the Amazon Pay API reference guide.