Verifying the ReturnURL and IPN Notifications

Amazon Simple Pay sends you outbound notifications for both the ReturnURL and IPN notification. For the ReturnURL, it is in the form of GET data, and for IPN notification, it is POST data. When you handle these notifications, we recommend you validate the signature to ensure the notification originated from Amazon Payments. The signature version 2 security has two methods for you to verify the signature of the response:

Server-side signature verification using the VerifySignature FPS Action.
This is the method we recommend for Amazon Simple Pay . To use it, modify your returnUrl and ipnUrl pages to parse the notification. From those components, you assemble the relevant parameters for VerifySignature. The result of the call from is either Success, meaning the response is valid, or Failure, indicating the response is suspect.
For more information on VerifySignature, see VerifySignature. In addition, you can use the validation samples to assist creating your own validation pages. For more information, see Return URL Validation Sample.
Client-side signature verification using PKI.
This method is intended for applications which need to process a greater number of transactions. The notifications sent to both the returnUrl and ipnUrl endpoints contain the certificateUrl parameter. The certificateUrl value is a URL which specifies the location of the certificate used for signing the response. (For optimum performance, you can download the certificate and cache it locally. It only needs to be updated on its annual expiration date).
You then use the certificate to validate the request using PKI. For more information, see Client-side Signature Validation.

Client-side Signature Validation

	Important
	If you are using signature version 1 to validate the notifications from Amazon Payments, we strongly recommend you convert to signature version 2. For more information, see Appendix: Moving your Application to Signature Version 2

The following process describes how to verify the legitimacy of an outbound notification from Amazon Payments. You use the same process for Return URL and IPN posts. (For more information about handling responses, see Handling Return Content.)

Validating the signature in the Return URL and IPN notifications

1 Decode the signature in the notification.

2 Decode and read the signatureVersion and signatureMethod parameters from the notification. The value of signatureVersion value should be 2, and the value for signatureMethod value should be RSA-SHA1 (format is Algorithm-Digest).

3 Decode and read the certificateUrl parameter from the notification.

4 Verify that the certificate corresponding to the URL is downloaded and cached.

If the certificate is not cached, you need to verify and download it:

Verify the host and ensure the SSL certificate has been issued by a valid certificate authority (CA). This ensures that the certificate does not belong to an unauthorized CA. Using an SSL connection makes this happen, because with an SSL connection the CA is validated against the list of standard CAs. This is a required step.
Force the certificate to download without redirection. This ensures your request isn't hijacked by a invalid CA. This is a required step.
Optionally, verify that the certificate originates with Amazon. The certificate subject must be:
/C=US/ST=Washington/L=Seattle/O=Amazon.com Inc./CN=notifications.amazonpayments.com
An organization of Amazon.com Inc ensures the certificate is Amazon's certificate.

The Amazon FPS code samples shows how the first two steps are done in a language-specific way in the SignatureUtilsForOutbound.* file, in the getPublicKeyCertificateAsString method (for C# and java) or the getPublicKey method, for perl and php. For information on downloading the samples, see ..

6 Follow steps 1 and 2 as specified in How to Generate a Signature to create the string-to-sign. Include all the parameters in the notification except for the signature parameter.

Calculate the signature using the PKI based cryptography, using the string-to-sign you created in step 6 and the cached certificate in step 5..

	Note
	Because the signature in outbound notification is calculated with the Amazon Payments private key using PKI, you need the values for the following parameters: string-to-sign, `signature`, `certificate` and `signatureMethod`). Each sample library uses these values in different formats. For information on using the sample library in the language of your choice see Getting the Samples

8 Compare the calculated signature with the signature in the original notification.

If the signatures match, process the notification.

Otherwise, discard the notification.

Note

If you didn't choose the Enable Signature V2 option from the Developer and Seller Preferences page, your responses will be signed using signature version 1. To verify signature version 1 signatures, you need to use the verification process described in Appendix: Verifying Responses Signed Using Signature Version 1. For information on selecting signature version 2, see Configuring Default Button Values