# IPN and ReturnURL Validation PHP Library

## About this Library

- Signature validation helper for IPN and Return URL notifications signed using signature version 2.
- Sample Code Version 2.0
- Release Date : 2009-11-03

## Prerequisites

- php 5.2.6

## 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.

## Contents of this package:

This package contains the following files to help you validate IPN and Return URL notifications using signature version 2. The samples are packaged under "IPNAndReturnURLValidation/src".

1. SignatureUtilsForOutbound.php - This class contains the following helper functions for verifying signature.

- validateRequest - Returns whether the signature specified in IPN or return url is correct or not. Takes a map of all the IPN/return url parameters. Takes additional parameters like httpMethod (GET or POST), url end point receiving the IPN or return url request (e.g. www.mysite.com/handle_ipn.jsp) for signature version 2.

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

## Verifying Incoming Signatures

### Steps to validate Return Url

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

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 validate the Return URL and IPN response:

1 | Capture the notification on on your IPN endpoint
2 | Pass all the parameters to the validateRequest method of SignatureUtilsForOutbound
4 | Capture the boolean returned by the validateRequest method and process the IPN or discard based on its value

### Examples

Examples for ReturnUrl Signature Verification

Examples for IPN Signature Verification