About this Library

Prerequisites

Important:

Amazon Simple Pay sends you outbound notifications in the form of GET and POST on your ReturnURL and IPN endpoint respectively. When you handle these notifications, we recommend you to validate the Signature to ensure that the notification actually originated from us. Signature V2 provides two ways to validate this signature.

  1. Server-side validation using VerifySignature FPS Action: Send the entire URL including the HTTP parameters received to VerifySignature Action and it will return a Boolean that indicates whether the signature was validated or not. This method is the one we recommend for Amazon Simple Pay as it helps you to quickly integrate with our service. Samples for this method is packaged in the folder FPSAPIs/src/Amazon/Fps/Samples. The section "Using VerifySignature API" below describes the steps.
  2. Client-side validation using PKI based algorithm: This package includes files that implement this algorithm. If you are not willing to make an API call to verify the signature, you can follow the steps under "Using PKI algorithm" to implement signature verification on your end.

Contents of this package:

This package contains the following files to help you validate IPN and Return URL notifications using signature version 2 programmatically on your end. If you would like to use Verify Signature Action, the samples are packaged under "IPNAndReturnURLValidation/src".

  1. SignatureUtilsForOutbound.php - This class contains the following helper functions for verifying signature.
  2. IPNVerificationSampleCode.php - Verifies a sample IPN request for signature version 2
  3. ReturnUrlVerificationSampleCode.php - Verifies a sample return url redirected request for signature version 2

Using VerifySignature API

Steps to validate Return URL notifications using VerifySignature API

Steps to validate IPN posts using VerifySignature API call

Summary of the steps to use VerifySignature action for Return URL and IPN:

1

Capture the notification on on your IPN endpoint

2

Construct VerifySignature request by specifying either your Return URL or IPN endpoint as “UrlEndpoint” and the concatenated string of HTTP parameters as “HttpParameters” [‘=’ used as delimiter between URL encoded name, URL encoded value and ‘&’ used as delimiter between each name, value pair.]

3

Invoke VerifySignature request against Sandbox or Production endpoint as applicable

4

Capture the XML response and decide whether to process the IPN notification or discard it based on the value of “VerificationStatus” boolean.

Using PKI Algorithm

Steps to validate Return URL notifications using PKI algorithm (client-side)

  1. Open ReturnUrlVerificationSampleCode.php
  2. Replace/add the parameters you received at your return url and also update urlEndPoint to your return url end point. 
    //Parameters present in return url.
$params["transactionId"] = "14GPH3CZ83RPQ1ZH6J2G85NL1IO3KO8641R";
$params["transactionDate"] = "1254987247";
$params["status"] = "PS";
$params["signatureMethod"] = "RSA-SHA1";
$params["signatureVersion"] = "2";
$params["buyerEmail"] = "test-sender@amazon.com";
$params["recipientEmail"] = "test-recipient@amazon.com";
$params["operation"] = "pay";
$params["transactionAmount"] = "USD 1.1";
$params["referenceId"] = "test-reference123";
$params["buyerName"] = "test sender";
$params["recipientName"] = "Test Business";
$params["paymentMethod"] = "Credit Card";
$params["paymentReason"] = "Test Widget";
$params["certificateUrl"] = "https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem";
$params["signature"] = "VirmnCtqA/A+s+H+SE7Oj8Ku7Lfay6OKkJgP/Q0hyQeaR6evI8Usokg698utW6xzJsiUudXm0K"
. "pmqiWM33o1aby3AOxZqWUC//aMZPO9vdw1NWR5fOJ++8AR9BAfcUtTHWc2QOHa1UyJalqeMsHuQj2IqQCMmOAUHPFkHhwAZ"
. "MS9Ifkkxjqczg4S0vK9FoO39rFYkReYdL9SvuFyj6byAnqd3D7i/lgw+6jXjAlM9MqYiisMLyCGk0IQsrux5VbiQgI9LiGqU"
. "ThGh7o2XkEFWvmPlKFmdQVnLxN9RNOK4pwrktbjgrBfVKZu1BBBXjfwwy9xzin0Kw5uNlCD2ReoZA==";
 
$urlEndPoint = "http://yourwebsite.com/return.jsp"; //Your return url end point. 
print "Verifying return url signed using signature v2 ....\n";
//return url is sent as a http GET request and hence we specify GET as the http method.
//Signature verification does not require your secret key
print "Is signature correct: " . $utils->validateRequest($params, $urlEndPoint, "GET") . "\n";
  3. Run the sample.
  4. Make sure the signature is valid.

Steps to validate IPN posts using PKI algorithm (client-side)

  1. Open IPNVerificationSampleCode.php
  2. Replace/add the parameters that you got in your IPN post. Also, set the urlEndPoint to your IPN end point. 
    //Parameters present in ipn.
$params["transactionId"] = "14GPH3CZ83RPQ1ZH6J2G85NL1IO3KO8641R"; 
$params["transactionDate"] = "1254987247"; 
$params["status"] = "PS"; 
$params["signatureMethod"] = "RSA-SHA1"; 
$params["signatureVersion"] = "2"; 
$params["buyerEmail"] = "test-sender@amazon.com"; 
$params["recipientEmail"] = "test-recipient@amazon.com"; 
$params["operation"] = "pay"; 
$params["transactionAmount"] = "USD 1.100000"; 
$params["referenceId"] = "test-reference123"; 
$params["buyerName"] = "test sender"; 
$params["recipientName"] = "Test Business"; 
$params["paymentMethod"] = "CC"; 
$params["paymentReason"] = "Test Widget"; 
$params["certificateUrl"] = "https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem"; 
$params["signature"] ="g2tEn6VVu8VKsxnkWeCPn8M9HABkzkVGbYTozSSKg9Y7B5Xsvq5GSoXkDlaz+izQM56wzvgFCou"
. "79un06KI6CeE4lf0SSsonoPInqvTrKoS/XPZqBChtdfciCqSyWBpPZ2YaEbSYEZdk1YZW0W7oeezgQqgzBL/CLN9U128GyF"
. "llt3/Yxr6p+XBltBUjh0kGmdAFVuFgwYq7h7cyMwAyseIRU7vDW5qsTreAPBmae9h3v4oZly5CyNDP+4HhExyzakf2r+UBE"
. "qj9EwZtek3k9qj956dlG8Dd3QeEF9AqjLp0D+7MyZr0rupNcWNbO1wGX8aEda/FvoWMRxXB3sU9dw=="; 

$urlEndPoint = "http://yourwebsite.com/ipn.jsp"; //Your url end point receiving the ipn.
      
print "Verifying IPN signed using signature v2 ....\n";
//IPN is sent as a http POST request and hence we specify POST as the http method.
//Signature verification does not require your secret key
print "Is signature correct: " . $utils->validateRequest($params, $urlEndPoint, "POST") . "\n";
  3. Run the sample.
  4. Make sure the signature is valid.

Summary of the steps to use PKI algorithm for Return URL and IPN:

1

Decode the signature in the notification.

2

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

3

Decode and read the certificateUrl parameter from the notification.

4

Check if the certificate corresponding to the URL was already downloaded and cached.

5

If the certificate was not cached, download the same and cache it.

6

Compute the StringToSign using the V2 algorithm (same as inbound requests) – StringToSign should include all the parameters sent in the notification excluding signature.

7

Validate the signature using the StringToSign and the Certificate downloaded.
Note: Since the signature is calculated with FPS private key using PKI based cryptography, you will require the above parameter values (signature, stringToSign, certificate and signatureMethod) to validate this signature using language specific libraries. Look at our code samples for more details on the library support. Note that libraries in different languages take these inputs in different formats.

8

If the signatures match, the notification is processed. Otherwise, the notification is discarded.

Examples

Examples for ReturnUrl Signature Verification

Examples for IPN Signature Verification