Real life handling of the ExpressCheckout

docs/ExpressCheckout.md

@@ -1,32 +1,44 @@
+PayPal Express Checkout provides a very easy and user friendly way for users to make payment. All transactions happen in an overlayer modal box, users will not need to leave your site during the whole process unlike other methods, where users will be redirected to PayPal official site to make payment.
+
 ExpressCheckout does not use any other configurations than those for authentication.
 
-The order has three required fields:
- - `total_price`
- - `items_price`
- - `shipping_price`
+The order is an array of items with three required fields:
+ - `name`
+ - `price`
+ - `quantity`
 
 **Example**:
 
-``` php
+```php
+$items = array();
+$items[] = array('name' => 'Item Name #1', 'price' => 3, 'quantity' => 1);
+$items[] = array('name' => 'Item Name #2', 'price' => 5, 'quantity' => 3);
+
 $express_checkout = Payment::instance('ExpressCheckout')
-  ->order(array(
-    'items_price' => 50,
-    'shipping_price' => 10,
-    'total_price' => 60
-  ))
+  ->order($items)
   ->return_url('example.com/success')
-  ->cancel_url('example.com/cancelled')
-  ->notify_url('example.com/ipn');
+  ->cancel_url('example.com/cancelled');
 
 $response = $express_checkout
   ->set_express_checkout();
 
-// Redirecting the user to confirm the payment using $response['TOKEN']
+
+```
+
+Now you need to redirect user to Paypal page ('www.paypal.com/incontext?token=') using $response['TOKEN']
+
+Upon success you need to finaly confirm the payment:
+```php
+$params['TOKEN']   = $_REQUEST['token'];
+$params['PAYERID'] = $_REQUEST['PayerID'];
+
+$express_checkout = Payment::instance('ExpressCheckout')
+    ->order($items); //the same $items as before
 
 $express_checkout
-  ->do_express_checkout_payment($response['TOKEN'], $response['PAYERID']);
+  ->do_express_checkout_payment($params['TOKEN'], $params['PAYERID']);
 ```
 
 **Notes**:
 
-You should store the token or the whole response in a permanent or a session storage. They will be needed after the user has confirmed the payment on paypal.com.
+You should store the token or the whole response in a permanent or a session storage. They will be needed after the user has confirmed the payment on paypal.com.

docs/configuration.md

@@ -14,6 +14,11 @@ Credentials consist of the following:
 
 Different PayPal APIs use different authentication mechanisms. Consult with the PayPal developer documentation which to use.
 
+In order to run in a sandbox mode use:
+```php
+Payment::environment(Payment::ENVIRONMENT_SANDBOX);
+```
+
 Instance configuration
 ----------------------
 

src/OpenBuildings/PayPal/Payment/ExpressCheckout.php

@@ -26,62 +26,54 @@ public function get_express_checkout_details(array $params)
 	 */
 	public function set_express_checkout(array $params = array())
 	{
+        $startParams = array(
+            'RETURNURL' => $this->return_url(),
+            'CANCELURL' => $this->cancel_url()
+        );
+        $params = array_merge($startParams, $params);
+
 		return $this->_request('SetExpressCheckout', $this->_set_params($params));
 	}
 
 	public function do_express_checkout_payment($token, $payer_id)
 	{
-		$order = $this->order();
-
-		return $this->_request('DoExpressCheckoutPayment', array(
-			'TOKEN'                          => $token,
-			'PAYERID'                        => $payer_id,
-
-			// Total amount of the order
-			'PAYMENTREQUEST_0_AMT'           => number_format($order['total_price'], 2, '.', ''),
-
-			// Price of the items being sold
-			'PAYMENTREQUEST_0_ITEMAMT'       => number_format($order['items_price'], 2, '.', ''),
+        $params = array(
+            'TOKEN'                          => $token,
+            'PAYERID'                        => $payer_id
+        );
 
-			// Shipping costs for the whole transaction
-			'PAYMENTREQUEST_0_SHIPPINGAMT'   => number_format($order['shipping_price'], 2, '.', ''),
-
-			'PAYMENTREQUEST_0_CURRENCYCODE'  => $this->config('currency'),
-
-			'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale'
-		));
+        return $this->_request('DoExpressCheckoutPayment', $this->_set_params($params));
 	}
 
 	protected function _set_params(array $params = array())
 	{
-		$order = $this->order();
-
-		$defaultParams = array(
-			// Total amount for the transaction
-			'PAYMENTREQUEST_0_AMT' => number_format($order['total_price'], 2, '.', ''),
+        $defaultParams = array(
+            'PAYMENTREQUEST_0_CURRENCYCODE' => $this->config('currency'),
 
-			// Price of the items being sold
-			'PAYMENTREQUEST_0_ITEMAMT' => number_format($order['items_price'], 2, '.', ''),
+            'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale',
 
-			// Shipping costs for the whole transaction
-			'PAYMENTREQUEST_0_SHIPPINGAMT' => number_format($order['shipping_price'], 2, '.', ''),
+            'useraction' => 'commit',
 
-			'PAYMENTREQUEST_0_CURRENCYCODE' => $this->config('currency'),
+            // PayPal won't display shipping fields to the customer
+            // For digital goods this field is required and it must be set to 1.
+            'NOSHIPPING' => 1,
 
-			'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale',
-
-			'RETURNURL' => $this->return_url(),
+            'REQCONFIRMSHIPPING' => 0,
 
-			'CANCELURL' => $this->cancel_url(),
+            'ADDROVERRIDE' => 0,
+        );
 
-			'useraction' => 'commit',
+        $totalPrice = 0;
+        foreach($this->order() as $index => $item) {
+            $defaultParams['L_PAYMENTREQUEST_0_NAME' . $index] = $item["name"];
+            $defaultParams['L_PAYMENTREQUEST_0_AMT' . $index]  = $item["price"];
+            $defaultParams['L_PAYMENTREQUEST_0_QTY' . $index]  = $item["quantity"];
+            $defaultParams['L_PAYMENTREQUEST_0_ITEMCATEGORY' . $index] = "Digital";
 
-			// PayPal won't display shipping fields to the customer
-			// For digital goods this field is required and it must be set to 1.
-			'NOSHIPPING' => 1,
+            $totalPrice += $item["price"] * $item["quantity"];
+        }
+        $params['PAYMENTREQUEST_0_AMT'] = number_format($totalPrice, 2, '.', '');
 
-			'ADDROVERRIDE' => 0,
-		);
 		$params = array_merge($defaultParams, $params);
 
 		if ($this->notify_url())