Step 6. Integrate return URL parameters | Amazon Pay

Step 6. Integrate return URL parameters

Whether the request was successful or failed, Amazon Pay returns a URL containing parameters that you can integrate into your order management system. For example, if the request was successful, at the conclusion of the checkout flow, the buyer is redirected back to the URL that you specified in the button request, along with parameters describing the successful transaction.

Similarly, if a buyer abandons the checkout process by clicking Cancel on one of the checkout pages, they are redirected to your website where return URL parameters can provide the reason for abandonment. This topic describes Amazon Pay return URL parameters.

There are two types of return URLs, a returnURL and a cancelReturnURL. All responses are sent to the returnURL. If you elect to use the cancelReturnURL, only successful responses are directed to the returnURL. For more informatio,n see Step 3: Specify the parameter values.

Important: Before fulfilling orders on a successful response, you should verify the signature, amount, sellerOrderId, and currencyCode parameters to ensure that the response was sent by Amazon Pay and that it has been properly processed. Alternatively, you can make backend calls via the MWS Amazon Pay API using the OrderReferenceId.

Note: Integrating return URL parameters is one way to monitor the status of transactions on your webpage, but we recommend that you also use Instant Payment Notification (IPN) to monitor transactions. IPN is a HTML POST notification that is sent when a transaction either completes successfully or fails. You can specify the default URL to handle IPN in your Amazon Pay account settings. For more information on IPN, see Monitoring Payment Object state transitions in the Amazon Pay and Login with Amazon integration guide. To see transactions in Seller Central, sign in, click Orders, and then click Manage Transactions.

Common parameters

Parameter Required Description
resultCode Yes The response indicating whether checkout was successful.

Valid values:
  • Success
  • Failure
sellerId Yes The Seller ID used for the request. A solution provider uses this parameter to identify the merchant that the call was made for.

Success parameters

Parameter Required Description
orderReferenceId Yes The ID of the order reference. The order reference is the contract that encapsulates the payment agreement between you and the buyer.
amount Yes The amount that the buyer has agreed to pay.
currencyCode Yes A code that indicates the type of currency: USD (dollars), EUR (euros), or GBP (pounds).
paymentAction Yes The specified request parameter. Valid values:
  • None
  • Authorize
  • AuthorizeAndCapture
sellerOrderId No The seller-specified ID for this order. This is returned only if it is provided as a button parameter.
accessKey Yes The Amazon MWS private key's corresponding public key used to create the response signature.
signature Yes A signature used to ensure that the Amazon Pay response parameters have not been tampered with. If you detect a signature mismatch, then ignore the response. For information about how to calculate the signature, see Step 5. Generate a signature for the payment request.

Failure parameters

Parameter Required Description
failureCode Yes The code describing the error. Examples:
  • BuyerAbandoned
  • AmazonRejected
  • RequestSignatureFailure
  • InvalidParameterValue
  • MissingParameter
  • InvalidSellerAccountStatus
  • TemporarySystemIssue

The following sample shows what the response might look like if the transaction is successful. Note that the sample includes line breaks so that it is easier to read; a real response would be returned as a single, continuous string.

 
http://www.courtandcherry.com/AmazonResponseHandler
&resultCode=Success
&orderReferenceId=S01-0912345-1234567
&sellerId=ADEMO3053M41F7TEXAMPLE
&accessKey=ARIWE420982EXAMPLE
&amount=10
&currencyCode=USD
&paymentAction=None
&sellerOrderId=A481WEIFEXAMPLE
&signature=n345ngiwasdfasdJimCJixkEuxqN0021sdf56bDdZ4EXAMPLE
    

The following sample shows what a response might look like if the buyer cancels the transaction. Note that the sample includes line breaks so that it is easier to read; a real response would be returned as a single, continuous string.

 
http://www.courtandcherry.com/AmazonResponseHandler
?resultCode=Failure
&sellerId=ADEMO3053M41F7EXAMPLE    
&failureCode=BuyerAbandoned