ExpressCheckout

docs/ExpressCheckout.md

@@ -1,32 +1,83 @@
+PayPal Express Checkout provides a very easy and user friendly way for users to make payment. All transactions happen in an overlayer modal box or popup window (it mostly depends on the user choice of "Remember Me Cookie"). It seems like users don't need to leave your site during the whole process unlike other methods, where users will be redirected to the 'full' 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']
+```
 
-$express_checkout
-  ->do_express_checkout_payment($response['TOKEN'], $response['PAYERID']);
+Now when you have ```$response['TOKEN']``` you need to open a popup with Paypal page. You can get valid URL for the form action by ```$express_checkout->ec_form_action_url($response['TOKEN'])```:
+```html
+<form action="https://www.paypal.com/incontext?token=TOKEN" method="POST">
+    <input type='image' name='paypal_submit' id='paypal_submit'
+     src='https://www.paypal.com/en_US/i/btn/btn_dg_pay_w_paypal.gif' border='0' align='top' alt='Pay with PayPal'/>
+</form>
+```
+Upon success Paypal redirects to your ```return_url``` where you need to finally complete the payment and act accordingly:
+```php
+$params['TOKEN']   = $_REQUEST['token'];
+$params['PAYERID'] = $_REQUEST['PayerID'];
+
+$express_checkout = Payment::instance('ExpressCheckout')
+    ->order($items); //the same $items as before
+
+//In $response you'd have some extra important information like transaction id or fees taken by Paypal
+$response = $express_checkout
+  ->do_express_checkout_payment($params['TOKEN'], $params['PAYERID']);
+
+$ack = strtoupper($response["ACK"]);
+if("SUCCESS" == $ack || "SUCCESSWITHWARNING" == $ack)
+{
+    /*
+    * TODO: Proceed with desired action after the payment
+    * (ex: start download, start streaming, add coins to the game, etc.)
+    */
+}
 ```
 
 **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.
+
+ - You also need to have this code before ```</body>``` on your website with the Paypal button. A good choice for ```expType``` is ```instant``` but for more options you may refer to [Paypal documentation](https://developer.paypal.com/docs/classic/express-checkout/digital-goods/IntroducingExpressCheckoutDG/).
+```html
+    <script src='https://www.paypalobjects.com/js/external/dg.js' type='text/javascript'></script>
+    <script>
+        var dg = new PAYPAL.apps.DGFlow({
+            trigger: 'paypal_submit', // ID of the form submit button
+		    expType: 'instant'
+	        });
+    </script>
+```
+
+ - Don't forget to close the popup window, you may use a code like this:
+```javascript
+window.onload = function(){
+    if(window.opener){
+         window.close();
+     }
+    else{
+         if(top.dg.isOpen() == true){
+             top.dg.closeFlow();
+             return true;
+          }
+      }
+};
+```

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

@@ -11,6 +11,16 @@ class Payment_ExpressCheckout extends Payment {
 
 	const API_VERSION = '98.0';
 
+	const EXPRESSCHECKOUT_FORM_ACTION_END = 'paypal.com/incontext?token=';
+
+	public function ec_form_action_url($token)
+	{
+		return Payment::ENDPOINT_START
+			.Payment::environment()
+			.self::EXPRESSCHECKOUT_FORM_ACTION_END
+			.$token;
+	}
+
 	public function get_express_checkout_details(array $params)
 	{
 		if ( ! isset($params['TOKEN']))
@@ -26,62 +36,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, '.', ''),
-
-			// Shipping costs for the whole transaction
-			'PAYMENTREQUEST_0_SHIPPINGAMT'   => number_format($order['shipping_price'], 2, '.', ''),
-
-			'PAYMENTREQUEST_0_CURRENCYCODE'  => $this->config('currency'),
+		$params = array(
+			'TOKEN'   => $token,
+			'PAYERID' => $payer_id
+		);
 
-			'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, '.', ''),
-
-			// Price of the items being sold
-			'PAYMENTREQUEST_0_ITEMAMT' => number_format($order['items_price'], 2, '.', ''),
-
-			// 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',
-
-			'RETURNURL' => $this->return_url(),
-
-			'CANCELURL' => $this->cancel_url(),
 
 			'useraction' => 'commit',
 
 			// 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,
 
+			'REQCONFIRMSHIPPING' => 0,
+
 			'ADDROVERRIDE' => 0,
 		);
+
+		$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";
+
+			$totalPrice += $item["price"] * $item["quantity"];
+		}
+		$params['PAYMENTREQUEST_0_AMT'] = number_format($totalPrice, 2, '.', '');
+
 		$params = array_merge($defaultParams, $params);
 
 		if ($this->notify_url())