******************************************************************************
Pay with Amazon PHP Library
Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); 
******************************************************************************
  
******************************************************************************
  INTRODUCTION
******************************************************************************
 
 Please understand that by using the Pay with Amazon sample code, 
 you are agreeing to understand and abide by the terms of the license, 
 as written in NOTICE.txt & LICENSE.txt accompanying this archive. 
 This sample code has been tested with PHP 5.3.8 and Curl 7.18.1
  
******************************************************************************
  INCLUDED FILES
******************************************************************************
 
 * src/                          * PHP files required to execute the code
 * LICENSE.txt                   * The Apache License this code is licensed under
 * NOTICE.txt                    * Notice file.
 * README.txt                    * This file.
 * CHANGES.txt                   * List of changes to the SDK.

******************************************************************************
  PREREQUISITES
******************************************************************************
In US, if you have registered with Amazon Payments API Integration prior to
October 7th, 2013, you will need to register with Login with Amazon (LWA) and
get a Login with Amazon (LWA) Client ID.  To register with LWA visit
https://login.amazon.com/ and click on "Sign Up" button. Once registered for
LWA to get your LWA Client ID, click on "Register Your Application" button on
LWA Seller Central page. For additional information, please see the following
step by step guide to get your Login with Amazon Client ID: https://amazon
payments.s3.amazonaws.com/documents/Get_Your_Login_with_Amazon_Client_ID.pdf
   
******************************************************************************
  USAGE INSTRUCTIONS
******************************************************************************
Note: The following steps are for a UNIX based operating environment (and can
be easily modified to suite other operating systems)

This SDK includes two sets of samples - a command line based example that
requires a minimal setup in order to run, and a webserver based sample that
demonstrates notification processing.

To run the command line based examples:

  (1) Open the src/OffAmazonPaymentsService/OffAmazonPaymentsService.config
  .inc.php file and fill out the merchant Id, access key and secret key fields.
  Please also fill out LWA client Id field if Login with Amazon service is
  available in your region. Also make sure that the environment and region
  keys are configured to the right values for your test.
  	    
  (2) Navigate to the src/OffAmazonPaymentsService/Samples directory, and run
  the selected PHP sample in the console. An Amazon Order Reference Id is
  required for the examples. If Automatic Payments service is available in your
  region, an Amazon Billing Agreement Id is required for the example
  AutomaticPaymentsSimpleCheckoutExampleCLI.php

    (a) An Amazon Order Reference Id/Amazon Billing Agreement Id can be
    generated by using the OffAmazonPayments wallet widget. There are sample
    html pages titled signin.php, address.php and wallet.php that contain
    widgets ready to host on a php webserver. Please see 
    src/OffAmazonPaymentsNotifications/Samples directory for the sample pages.

    (b) For the RefundExample.php sample, you will also need to provide the
    Amazon Capture Id as a second argument which can be obtained from an earlier
    service call.

  (3) The result of the operation can be viewed by looking at the console output
  from the script.

To run the notification based examples:

  (1) Open the src/OffAmazonPaymentsService/OffAmazonPaymentsService.config
  .inc.php file and fill out the merchant Id, access key and secret key fields.
  Please also fill out LWA client Id field if Login with Amazon service is
  available in your region. Also make sure that the environment and region
  keys are configured to the right values for your test.

  (2) Open the src/OffAmazonPaymentsNotifciations/Samples/OffAmazonPaymentsNotifications
  .config.inc.php file and fill out a directory to log notification information to. 
  This folder must be a directory to which the webserver user has write permissions.

  (3) Deploy the SDK src folder to your webserver environment, and modify your
  webserver php include path to include this src directory in your default
  include path.

  (4) Login to seller central and setup the Instant Notification merchant URL on
  the Integration Settings page.  For the samples, the notification url will
  be http://<YOURHOSTNAME>(optional /<DIRECTORY>)/IpnHandler.php and this needs
  to be accessible to the internet for notification delivery to function.

  (5) In your browser, navigate to the Samples.html file in the
  src/OffAmazonPaymentsNotifications/Samples directory to execute the samples.

Using the client API:

To make service calls from your scripts:

  (1) Include the src/OffAmazonPaymentsService/Client.php file

  (2) Create a new instance of the OffAmazonPaymentsService_Client class - by
  default this will use the values defined in the
  src/OffAmazonPaymentsService/OffAmazonPaymentsService.config.inc.php file,
  which you can optionally override in the constructor call.

To handle notifications from your scripts:

  (1) Configure your webserver to accept incoming connections over HTTPS - the
  webserver based samples make use of notification processing which requires
  a HTTPS connection, and requires a server certificate that is signed by a
  trusted CA authority.  The listed of trusted CA authorities can be found at
  http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.https.ca.html

  (2) Include the src/OffAmazonPaymentsNotifications/Client.php file

  (3) Create a new instance of the OffAmazonPaymentsNotifications_Client class

  (4) Read in the http headers and body in your script and invoke the method on
  the client class

  (5) If the client throws an NotificationsException, return a http status code
  of 500 to indicate that the notification cannot be processed.  Otherwise
  return a http 200 code.

Note: If the status code is not returned within 15 seconds of the notification
being transmitted, it will be treated as a failed delivery.

Note that these samples use the cURL library to make calls to remote servers,
and on some may systems requires additional configuration in order to
sucessfully verify the remote server.  If you are encountering SSL connection
errors then follow these steps:    

  (1) Follow the instruction on http://curl.haxx.se/docs/sslcerts.html to obtain
  a bundled ca cert file, and ensure that it includes the signing cert for
  "VeriSign Class 3 Secure Server CA - G3"

  (2) Save the file to the following path:          
    - Windows - C:\certs\caCertFile.crt          
    - Unix - /etc/conf/certs/caCertFile.crt

  (3) Uncomment the $caBundleFile line in the
  OffAmazonPaymentsService.config.php property file and restart the service

If you save to a different path then change the value of the $caBundleFile
property to point to this directory.

Note: When deploying the SDK packages to production systems, make sure that
the Samples directories are not deployed as they are not mandatory in order to
use the client code.

******************************************************************************
  SUPPORT & PROJECT HOME
******************************************************************************
The latest documentation on the Pay with Amazon can be found at the LINKS
section below:

Amazon Seller Central: https://sellercentral.amazon.com  

  1. Login to the site and navigate to the integration central tab to view
  available resources.

