Introduction:

Amazon FPS sends you outbound notifications in the form of GET and POST on your ReturnURL and IPN endpoints respectively. When you handle these notifications, we recommend you to validate the signature to ensure that the notification actually originated from us. You can validate the signature using signature version 2 with a server-side call to the VerifySignature API. In this call, you send the entire URL including the HTTP parameters received to FPS VerifySignature API and it will return a Boolean that indicates whether the signature was validated. Samples using this API to validate the signature are included in the src/com/amazonaws/ipnreturnurlvalidation folder. Their usage is described below.

Package Content

Directory Overview
src/Amazon/FPS All sources including code samples that demonstrate making FPS calls.
src/Amazon/IpnReturnUrlValidation All sources including code samples that demonstrate validation of ipn and return url notifications.

Verifying Incoming Signatures

Steps to validate Return URL

  1. Go to src/Amazon/IpnReturnUrlValidation/Samples directory and open ReturnUrlVerificationSampleCode.php
  2. In function test, replace/add the parameters you received at your return url and also update urlEndPoint to your return url end point.
            $utils = new Amazon_FPS_SignatureUtilsForOutbound();
            
            //Parameters present in return url.
            $params["expiry"] = "10/2013";
            $params["tokenID"] = "Q5IG5ETFCEBU8KBLTI4JHINQVL6VAJVHICBRR49AKLPIEZH1KB1S8C7VHAJJMLJ3";
            $params["status"] = "SC";
            $params["callerReference"] = "1253247023946cMcrTRrjtLjNrZGNKchWfDtUEIGuJfiOBAAJYPjbytBV";
            $params["signatureMethod"] = "RSA-SHA1";
            $params["signatureVersion"] = "2";
            $params["certificateUrl"] = "https://fps.amazonaws.com/certs/090909/PKICert.pem";
            $params["signature"] = "H4NTAsp3YwAEiyQ86j5B53lksv2hwwEaEFxtdWFpy9xX764AZy/Dm0RLEykUUyPVLgqCOlMopay5"
              . "Qxr/VDwhdYAzgQzA8VCV8x9Mn0caKsJT2HCU6tSLNa6bLwzg/ildCm2lHDho1Xt2yaBHMt+/Cn4q"
              . "I5B+6PDrb8csuAWxW/mbUhk7AzazZMfQciJNjS5k+INlcvOOtQqoA/gVeBLsXK5jNsTh09cNa7pb"
              . "gAvey+0DEjYnIRX+beJV6EMCPZxnXDGo0fA1PENLWXIHtAoIJAfLYEkVbT2lva2tZ0KBBWENnSjf"
              . "26lMZVokypIo4huoGaZMp1IVkImFi3qC6ipCrw==";
            
            $urlEndPoint = "http://www.mysite.com/call_pay.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 and make sure the signature is valid.

Steps to validate IPN posts

  1. Go to src/Amazon/IpnReturnUrlValidation/Samples directory and open IpnVerificationSampleCode.php
  2. In function test, replace/add the parameters that you got in your IPN post. Also, set the urlEndPoint to your IPN end point.
            $utils = new Amazon_FPS_SignatureUtilsForOutbound();
            
            //Parameters present in ipn.
            $params["transactionId"] = "14DRG2JGR7LK4J54P544DKKNDLQFFZLE323";
            $params["transactionDate"] = "1251832057";
            $params["status"] = "INITIATED";
            $params["notificationType"] = "TransactionStatus";
            $params["callerReference"] = "callerReference=ReferenceStringJYI1251832057319108";
            $params["operation"] = "PAY";
            $params["transactionAmount"] = "USD 1.00";
            $params["buyerName"] = "BuyerName-SsUo3oDjHx";
            $params["paymentMethod"] = "CC";
            $params["paymentReason"] = "DescriptionString-1251832057319108";
            $params["recipientEmail"] = "recipientemail@amazon.com";
            $params["signatureMethod"] = "RSA-SHA1";
            $params["signatureVersion"] = "2";
            $params["certificateUrl"] = "https://fps.amazonaws.com/certs/090909/PKICert.pem";
            $params["signature"] = "vKXXCbtxvSkRR+Zn8YNW6DNGpbi474h2iM4L+xaOi16kYKdYpuGbvKyXQ36uTZTVHdUGAAcvpXFL"
                    . "wDfnTcqcckr2IUElrVJKQeT0WeWR+IqmABwSRGo+YqjzPNISSNXNzg6LFhouhUvmmwY15X3YgXfc"
                    . "ERN5IhPwv04YkyCLPCA9P0/QgD8Jum/hc9jj0HYjj3s3MuuQ3yoIhf2x+2CBZRm5lslRqnoF/8OJ"
                    . "1ZHmAHt9VvQSZ+QC3fwJgeqzJPAvtuOm930BP6hPYZVhXE5w7ByLt0qLk1ZFE/vzQ4io4vOyie6W"
                    . "bhp5+AuNyAs+QrGMYO8VZruZJfkZO4b6QOgV2A==";
    
            $urlEndPoint = "http://www.mysite.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 make sure the signature is valid.

Summary of the steps to use Server side validation for Return URL and IPN:

1

Capture the notification on your IPN endpoint

2

Pass all the parameters to the validateRequest method of SignatureUtilsForOutbound

3

Capture the boolean returned by the validateRequest method and process the IPN or discard based on its value