Amazon Pay and Login with Amazon integration guide

Sandbox simulations

You can use the Amazon Pay and Login with Amazon Sandbox to simulate specific payment scenarios. These simulations let you generate responses that you can use to test your business processes. The tables below outline how certain responses and state transitions can be simulated.
In addition to the simulations described in the table, you can also trigger certain behaviors by selecting one of the payment methods in the wallet widget marked with a * during the checkout as shown in figure 1. When you select one these payment methods, you will see the simulation scenario it will invoke. By means of that, you can trigger:

  • OrderReferenceObject Constraint PaymentMethodNotAllowed
  • Authorization Declined with ReasonCode InvalidPaymentMethod
  • Authorization Declined with ReasonCode AmazonRejected
  • Authorization Declined with ReasonCode TransactionTimedOut

Figure 1: Wallet widget with payment methods triggering sandbox simulations


For more information about the states and reason codes, see the States and reason codes section of the Amazon Pay API reference guide.

Note: For states and reason codes that can be used with a simulation string, you must specify the desired State and ReasonCode in a call to an Amazon Pay API section operation. Invalid combinations will result in an InvalidSandboxSimulationSpecified error.

To simulate various object states and reason codes:

Order Reference Object

State: Draft
Reason code Simulation string How to simulate in Sandbox
  N/A Click the Amazon Pay Sandbox button, and then sign in using your test buyer account credentials to create an Order Reference object in the Draft state
Constraint Simulation string How to simulate in Sandbox
PaymentMethodNotAllowed {"SandboxSimulation":{"Constraint":"PaymentMethodNotAllowed"}} Pass this simulation string in the field SellerNote with the SetOrderReferenceDetails API call in order to simulate a PaymentMethodNotAllowed constraint.
In order to remove the constraint again, you must explicitly overwrite the simulation string in the SellerNote by means of an additional SetOrderReferenceDetails API call.
State: Open
Reason code Simulation string How to simulate in Sandbox
  N/A Confirm a Draft Order Reference object by calling the ConfirmOrderReference operation.
State: Suspended
Reason code Simulation string How to simulate in Sandbox
InvalidPaymentMethod N/A The Order Reference object moves to the Suspended state after you simulate the Authorization object moving to the Declined state with reason code InvalidPaymentMethod.
State: Cancelled
Reason code Simulation string How to simulate in Sandbox
SellerCanceled N/A Cancel an Open or Suspended Order Reference object by calling the CancelOrderReference operation.
Stale N/A Do not confirm a Draft Order Reference object within three hours of its creation. The Order Reference object then moves to the Stale state.
AmazonCanceled N/A Cannot be simulated.
State: Closed
Reason code Simulation string How to simulate in Sandbox
Expired N/A Do not close or cancel an Order Reference object. An Open or Suspended Order Reference object is closed by Amazon with this reason code 180 days after its creation.
MaxAmountCharged N/A Capture 15% or €75 (whichever is less) above the Order Reference object amount by calling the Capture operation.
MaxAuthorizationsCaptured N/A Fully or partially capture 10 authorizations against an Open Order Reference object.
AmazonClosed {"SandboxSimulation": {"State":"Closed", "ReasonCode":"AmazonClosed"}} Specify this value in the ClosureReason request parameter of the CloseOrderReference operation for an Open Order Reference object.
SellerClosed N/A Close an Open Order Reference object by calling the CloseOrderReference operation without specifying the simulation string for the AmazonClosed reason code.

Authorization Object

State: Pending
Reason code Simulation string How to simulate in Sandbox
  N/A Request an authorisation by calling the Authorize operation in asynchronous mode. All Authorization objects are in the Pending state for 30 seconds after you submit the Authorize request. This cannot be simulated in synchronous mode.
State: Open
Reason code Simulation string How to simulate in Sandbox
  N/A Request an authorisation by calling the Authorize operation. In asynchronous mode, the Authorization object moves to the Open state after remaining in the Pending state for 30 seconds. In synchronous mode, the Authorize object immediately moves to the Open state.
State: Declined
Reason code Simulation string How to simulate in Sandbox
InvalidPaymentMethod {"SandboxSimulation": {"State":"Declined", "ReasonCode":"InvalidPaymentMethod", "PaymentMethodUpdateTimeInMins":5, "SoftDecline":"false"}}

-OR-

{"SandboxSimulation": {"State":"Declined", "ReasonCode":"InvalidPaymentMethod", "SoftDecline":"false"}}
Specify this value in the SellerAuthorizationNote request parameter of the Authorize operation.
The declined authorization with this ReasonCode will cause the OrderReferenceObject to move from the Open state to the Suspended state. You can use the PaymentMethod UpdateTimeInMins parameter to specify the time (between 1-240 minutes) after which the Order Reference object should move from the Suspended state back to the Open state. This simulates the buyer updating an invalid payment method and the Order Reference object moving back to the Open state.
Not passing the parameter UpdateTimeInMins will prevent this state transition of the OrderReferenceObject and it will stay remain Suspended.

To simulate the soft decline retry behavior, use "SoftDecline":"true" in the simulation string. You can call the ConfirmOrderReference operation on the Order Reference object in state Suspended to change its state to Open again. This simulates the merchant confirming on the Suspended Order Reference object and moving it back to the Open state to retry the Authorize operation.
AmazonRejected {"SandboxSimulation": {"State":"Declined", "ReasonCode":"AmazonRejected"}} Specify this value in the SellerAuthorizationNote request parameter of the Authorize operation.
ProcessingFailure N/A Cannot be simulated.
TransactionTimedOut {"SandboxSimulation": {"State":"Declined", "ReasonCode":"TransactionTimedOut"}} Specify this value in the SellerAuthorizationNote request parameter of the Authorize operation.
State: Closed
Reason code Simulation string How to simulate in Sandbox
ExpiredUnused {"SandboxSimulation": {"State":"Closed", "ReasonCode":"ExpiredUnused", "ExpirationTimeInMins":1}} Specify this value in the SellerAuthorizationNote request parameter of the Authorize operation. You can use the ExpirationTimeInMins parameter to specify the time after which the Authorization object should be closed (from 1 to 60 minutes).
MaxCapturesProcessed N/A Capture an Open Authorization object by calling the Capture operation.
AmazonClosed {"SandboxSimulation": {"State":"Closed", "ReasonCode":"AmazonClosed"}} Specify this value in the SellerAuthorizationNote request parameter of the Authorize operation.
OrderReferenceCanceled N/A Cancel the Order Reference object associated with the Authorization object by calling the CancelOrderReference operation.
SellerClosed N/A Close an Open Authorization object by calling the CloseAuthorization operation.

Capture Object

State: Pending
Reason code Simulation string How to simulate in Sandbox
  {"SandboxSimulation": {"State":"Pending"}} Specify this value in the SellerCaptureNote request parameter of the Capture operation. The Capture object then remains in the Pending state for 30 seconds.
State: Declined
Reason code Simulation string How to simulate in Sandbox
AmazonRejected {"SandboxSimulation": {"State":"Declined", "ReasonCode":"AmazonRejected"}} Specify this value in the SellerCaptureNote request parameter of the Capture operation.
ProcessingFailure N/A Cannot be simulated.
State: Completed
Reason code Simulation string How to simulate in Sandbox
  N/A Capture funds against an Open Authorization object by calling the Capture operation.
State: Closed
Reason code Simulation string How to simulate in Sandbox
MaxAmountRefunded N/A Refund 15% or €75 (whichever is less) above the captured amount by calling the Refund operation.
MaxRefundsProcessed N/A Issue 10 refunds by calling the Refund operation against the corresponding Completed Capture object.
AmazonClosed {"SandboxSimulation": {"State":"Closed", "ReasonCode":"AmazonClosed"}} Specify this value in the SellerCaptureNote request parameter of the Capture operation.

Refund Object

State: Pending
Reason code Simulation string How to simulate in Sandbox
  N/A Request a Refund by calling the Refund operation. All Refund objects will be in the Pending state for 30 seconds after you submit the Refund request.
State: Declined
Reason code Simulation string How to simulate in Sandbox
AmazonRejected {"SandboxSimulation": {"State":"Declined", "ReasonCode":"AmazonRejected"}} Specify this value in the SellerRefundNote request parameter of the Refund operation.
ProcessingFailure N/A Cannot be simulated.
State: Completed
Reason code Simulation string How to simulate in Sandbox
  N/A Refund funds against a Completed Capture object by calling the Refund operation.

Most likely, you will submit the simulation strings introduced above by means of just applying them for the corresponding request parameter in the methods of the Amazon Pay SDK. Only in rare cases, you will to the compose the REST request yourself, as in the following example. It demonstrates how you can simulate the Authorization Declined state with reason code InvalidPaymentMethod using the SellerAuthorizationNote request parameter:

https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=Authorize
&AmazonOrderReferenceId=S23-1234567-1234567
&AuthorizationAmount.Amount=50
&AuthorizationAmount.CurrencyCode=EUR
&AuthorizationReferenceId=test_authorize_1
&SellerAuthorizationNote=
%7B%22SandboxSimulation%22%3A%7B%22State%22%3A%22Declined%22%2C
%22ReasonCode%22%3A%22InvalidPaymentMethod%22%7D%7D
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-10-03T19%3A01%3A11Z
&TransactionTimeout=1440
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

Copyright © 2009-2017 Amazon.com, Inc. or its affiliates. Amazon and Amazon.com are registered trademarks of Amazon.com, Inc. or its affiliates. All other trademarks are the property of their respective owners.