Updating sample comments

2013-08-26 12:21:29 +05:30
parent b1f1887cec
commit 05a4aef55e
18 changed files with 180 additions and 121 deletions
--- a/sample/payments/AuthorizationCapture.php
+++ b/sample/payments/AuthorizationCapture.php
@@ -1,6 +1,7 @@
 <?php
 // # AuthorizationCapture
-// This sample code demonstrate how you can capture the authorized payment
+// This sample code demonstrates how you can capture 
+// a previously authorized payment.
 // API used: /v1/payments/payment

 require __DIR__ . '/../bootstrap.php';
@@ -14,7 +15,7 @@ use PayPal\Api\Authorization;
 // by invoking the $authorization->capture method
 // with a valid ApiContext (See bootstrap.php for more on `ApiContext`)
 try {
-	// create payment to get authorization Id
+	// Create a new authorization to get authorization Id
 	// createAuthorization defined in common.php
 	$authId = createAuthorization($apiContext);

@@ -27,9 +28,10 @@ try {
 	$capture->setId($authId)
 		->setAmount($amt);

-	// Get the authorization
+	// Lookup the authorization.
 	$authorization = Authorization::get($authId, $apiContext);

+	// Perform a capture
 	$getCapture = $authorization->capture($capture, $apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
@@ -38,14 +40,15 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Capturing an authorization</title>
+</head>
 <body>
 	<div>
 		Captured payment <?php echo $getCapture->getParentPayment(); ?>. Capture Id:
 		<?php echo $getCapture->getId();?>
 	</div>
-	<pre>
-		<?php var_dump($getCapture->toArray());?>
-	</pre>
+	<pre><?php var_dump($getCapture->toArray());?></pre>
 	<a href='../index.html'>Back</a>
 </body>
 </html>
--- a/sample/payments/CreatePayment.php
+++ b/sample/payments/CreatePayment.php
@@ -1,8 +1,11 @@
 <?php

 // # CreatePaymentSample
+//
 // This sample code demonstrate how you can process
-// a payment with a credit card.
+// a direct credit card payment. Please note that direct 
+// credit card payment and related features using the 
+// REST API is restricted in some countries.
 // API used: /v1/payments/payment

 require __DIR__ . '/../bootstrap.php';
@@ -15,8 +18,7 @@ use PayPal\Api\FundingInstrument;
 use PayPal\Api\Transaction;

 // ### Address
-// Base Address object used as shipping or billing
-// address in a payment. [Optional]
+// [Optional] Billing address associated with card.
 $addr = new Address();
 $addr->setLine1("3909 Witmer Road")
 	->setLine2("Niagara Falls")
@@ -41,23 +43,23 @@ $card->setType("visa")

 // ### FundingInstrument
 // A resource representing a Payer's funding instrument.
-// Use a Payer ID (A unique identifier of the payer generated
-// and provided by the facilitator. This is required when
-// creating or using a tokenized funding instrument)
-// and the `CreditCardDetails`
+// For direct credit card payments, set the CreditCard
+// field on this object.
 $fi = new FundingInstrument();
 $fi->setCreditCard($card);

 // ### Payer
 // A resource representing a Payer that funds a payment
-// Use the List of `FundingInstrument` and the Payment Method
-// as 'credit_card'
+// For direct credit card payments, set payment method
+// to 'credit_card' and add an array of funding instruments.
 $payer = new Payer();
 $payer->setPaymentMethod("credit_card")
 	->setFundingInstruments(array($fi));

 // ### Amount
-// Let's you specify a payment amount.
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
 $amount = new Amount();
 $amount->setCurrency("USD")
 	->setTotal("1.00");
@@ -65,15 +67,14 @@ $amount->setCurrency("USD")
 // ### Transaction
 // A transaction defines the contract of a
 // payment - what is the payment for and who
-// is fulfilling it. Transaction is created with
-// a `Payee` and `Amount` types
+// is fulfilling it. 
 $transaction = new Transaction();
 $transaction->setAmount($amount)
-	->setDescription("This is the payment description.");
+	->setDescription("Payment description");

 // ### Payment
 // A Payment Resource; create one using
-// the above types and intent as 'sale'
+// the above types and intent set to sale 'sale'
 $payment = new Payment();
 $payment->setIntent("sale")
 	->setPayer($payer)
@@ -82,7 +83,7 @@ $payment->setIntent("sale")
 // ### Create Payment
 // Create a payment by posting to the APIService
 // using a valid ApiContext (See bootstrap.php for more on `ApiContext`)
-// The return object contains the status;
+// The return object contains the state.
 try {
 	$payment->create($apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
@@ -92,6 +93,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Direct Credit card payments</title>
+</head>
 <body>
 	<div>
 		Created payment:
--- a/sample/payments/CreatePaymentUsingPayPal.php
+++ b/sample/payments/CreatePaymentUsingPayPal.php
@@ -6,24 +6,24 @@
 // API used: /v1/payments/payment

 require __DIR__ . '/../bootstrap.php';
-use PayPal\Api\Address;
 use PayPal\Api\Amount;
 use PayPal\Api\Payer;
 use PayPal\Api\Payment;
-use PayPal\Api\FundingInstrument;
 use PayPal\Api\RedirectUrls;
 use PayPal\Api\Transaction;
 session_start();

 // ### Payer
 // A resource representing a Payer that funds a payment
-// Use the List of `FundingInstrument` and the Payment Method
-// as 'credit_card'
+// For paypal account payments, set payment method
+// to 'paypal'.
 $payer = new Payer();
 $payer->setPaymentMethod("paypal");

 // ### Amount
-// Let's you specify a payment amount.
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
 $amount = new Amount();
 $amount->setCurrency("USD")
 	->setTotal("1.00");
@@ -31,11 +31,10 @@ $amount->setCurrency("USD")
 // ### Transaction
 // A transaction defines the contract of a
 // payment - what is the payment for and who
-// is fulfilling it. Transaction is created with
-// a `Payee` and `Amount` types
+// is fulfilling it. 
 $transaction = new Transaction();
 $transaction->setAmount($amount)
-	->setDescription("This is the payment description.");
+	->setDescription("Payment description");

 // ### Redirect urls
 // Set the urls that the buyer must be redirected to after 
@@ -47,7 +46,7 @@ $redirectUrls->setReturnUrl("$baseUrl/ExecutePayment.php?success=true")

 // ### Payment
 // A Payment Resource; create one using
-// the above types and intent as 'sale'
+// the above types and intent set to 'sale'
 $payment = new Payment();
 $payment->setIntent("sale")
 	->setPayer($payer)
@@ -55,10 +54,10 @@ $payment->setIntent("sale")
 	->setTransactions(array($transaction));

 // ### Create Payment
-// Create a payment by posting to the APIService
-// using a valid apiContext.
+// Create a payment by calling the 'create' method
+// passing it a valid apiContext.
 // (See bootstrap.php for more on `ApiContext`)
-// The return object contains the status and the
+// The return object contains the state and the
 // url to which the buyer must be redirected to
 // for payment approval
 try {
@@ -69,16 +68,25 @@ try {
 	exit(1);
 }

-// ### Redirect buyer to paypal
-// Retrieve buyer approval url from the `payment` object.
+// ### Get redirect url
+// The API response provides the url that you must redirect
+// the buyer to. Retrieve the url from the $payment->getLinks()
+// method
 foreach($payment->getLinks() as $link) {
 	if($link->getRel() == 'approval_url') {
 		$redirectUrl = $link->getHref();
+		break;
 	}
 }
+
+// ### Redirect buyer to PayPal website
+// Save payment id so that you can 'complete' the payment
+// once the buyer approves the payment and is redirected
+// bacl to your website.
+//
 // It is not really a great idea to store the payment id
-// in the session. In a real world app, please store the
-// payment id in a database.
+// in the session. In a real world app, you may want to 
+// store the payment id in a database.
 $_SESSION['paymentId'] = $payment->getId();
 if(isset($redirectUrl)) {
 	header("Location: $redirectUrl");
--- a/sample/payments/CreatePaymentUsingSavedCard.php
+++ b/sample/payments/CreatePaymentUsingSavedCard.php
@@ -2,47 +2,42 @@

 // # Create payment using a saved credit card
 // This sample code demonstrates how you can process a 
-// Payment using a previously saved credit card.
+// Payment using a previously stored credit card token.
 // API used: /v1/payments/payment

 require __DIR__ . '/../bootstrap.php';
-use PayPal\Api\Address;
 use PayPal\Api\Amount;
-use PayPal\Api\CreditCard;
 use PayPal\Api\CreditCardToken;
 use PayPal\Api\Payer;
 use PayPal\Api\Payment;
 use PayPal\Api\FundingInstrument;
-use PayPal\Api\RedirectUrls;
 use PayPal\Api\Transaction;
-use PayPal\Auth\OAuthTokenCredential;

 // ### Credit card token
 // Saved credit card id from a previous call to
 // CreateCreditCard.php
-$creditCardId = 'CARD-5BT058015C739554AKE2GCEI';
 $creditCardToken = new CreditCardToken();
-$creditCardToken->setCreditCardId($creditCardId);
+$creditCardToken->setCreditCardId('CARD-29H07236G1554552FKINPBHQ');

 // ### FundingInstrument
 // A resource representing a Payer's funding instrument.
-// Use a Payer ID (A unique identifier of the payer generated
-// and provided by the facilitator. This is required when
-// creating or using a tokenized funding instrument)
-// and the `CreditCardDetails`
+// For stored credit card payments, set the CreditCardToken
+// field on this object.
 $fi = new FundingInstrument();
 $fi->setCreditCardToken($creditCardToken);

 // ### Payer
 // A resource representing a Payer that funds a payment
-// Use the List of `FundingInstrument` and the Payment Method
-// as 'credit_card'
+// For stored credit card payments, set payment method
+// to 'credit_card'.
 $payer = new Payer();
 $payer->setPaymentMethod("credit_card")
 	->setFundingInstruments(array($fi));

 // ### Amount
-// Let's you specify a payment amount.
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
 $amount = new Amount();
 $amount->setCurrency("USD")
 	->setTotal("1.00");
@@ -50,24 +45,24 @@ $amount->setCurrency("USD")
 // ### Transaction
 // A transaction defines the contract of a
 // payment - what is the payment for and who
-// is fulfilling it. Transaction is created with
-// a `Payee` and `Amount` types
+// is fulfilling it. 
 $transaction = new Transaction();
 $transaction->setAmount($amount)
-	->setDescription("This is the payment description.");
+	->setDescription("Payment description");

 // ### Payment
 // A Payment Resource; create one using
-// the above types and intent as 'sale'
+// the above types and intent set to 'sale'
 $payment = new Payment();
 $payment->setIntent("sale")
 	->setPayer($payer)
 	->setTransactions(array($transaction));

 // ###Create Payment
-// Create a payment by posting to the APIService
+// Create a payment by calling the 'create' method
+// passing it a valid apiContext.
 // (See bootstrap.php for more on `ApiContext`)
-// The return object contains the status;
+// The return object contains the state.
 try {
 	$payment->create($apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
@@ -77,6 +72,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Saved Credit card payments</title>
+</head>
 <body>
 	<div>
 		Created payment:
--- a/sample/payments/GetAuthorization.php
+++ b/sample/payments/GetAuthorization.php
@@ -1,6 +1,7 @@
 <?php
 // # GetAuthorization
-// This sample code demonstrate how you can get details of an authorized payment
+// This sample code demonstrates how you can get details 
+// of an authorized payment.
 // API used: /v1/payments/authorization/<$authorizationId>

 require __DIR__ . '/../bootstrap.php';
@@ -28,6 +29,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Lookup an authorization</title>
+</head>
 <body>
 	<div>
 		Retrieved Authorization:
--- a/sample/payments/GetCapture.php
+++ b/sample/payments/GetCapture.php
@@ -1,6 +1,7 @@
 <?php
 // # GetCapture
-// This sample code demonstrate how you can get the details of Captured Payment
+// This sample code demonstrates how you can lookup the details 
+// of a captured payment.
 // API used: /v1/payments/capture/<$captureId>

 require __DIR__ . '/../bootstrap.php';
@@ -12,22 +13,25 @@ use PayPal\Api\Authorization;

 // ### Create a mock Capture
 try {
-	// create payment to get authorization Id
+	// create a mock authorization to get authorization Id
+	// createAuthorization is defined in common.php
 	$authId = createAuthorization($apiContext);
+
+	// Lookup the authorization
+	$authorization = Authorization::get($authId, $apiContext);
+
+	### Capture
+	
 	$amt = new Amount();
 	$amt->setCurrency("USD")
 		->setTotal("1.00");
-
-	### Capture
-	$captur = new Capture();
-	$captur->setId($authId)
+	
+	// Create a capture
+	$captureInfo = new Capture();
+	$captureInfo->setId($authId)
 		->setAmount($amt);

-	// get the authorization
-	$authorization = Authorization::get($authId, $apiContext);
-
-	// Create a capture
-	$capt = $authorization->capture($captur, $apiContext);
+	$capture = $authorization->capture($captureInfo, $apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
 	var_dump($ex->getData());
@@ -38,7 +42,7 @@ try {
 // You can look up a capture by invoking the Capture::get method 
 // with a valid ApiContext (See bootstrap.php for more on `ApiContext`)
 try {
-	$capture = Capture::get($capt->getId(), $apiContext);
+	$capture = Capture::get($capture->getId(), $apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
 	var_dump($ex->getData());
@@ -46,6 +50,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Lookup a capture</title>
+</head>
 <body>
 	<div>
 		Capture Id:
--- a/sample/payments/GetPayment.php
+++ b/sample/payments/GetPayment.php
@@ -28,6 +28,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Lookup a payment</title>
+</head>
 <body>
 	<div>Retrieving Payment ID: <?php echo $paymentId;?></div>
 	<pre><?php var_dump($payment->toArray());?></pre>
--- a/sample/payments/ListPayments.php
+++ b/sample/payments/ListPayments.php
@@ -29,6 +29,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Lookup payment history</title>
+</head>
 <body>
 	<div>Got <?php echo $payments->getCount(); ?> matching payments </div>
 	<pre><?php var_dump($payments->toArray());?></pre>
--- a/sample/payments/Reauthorization.php
+++ b/sample/payments/Reauthorization.php
@@ -1,6 +1,7 @@
 <?php
 // ##Reauthorization Sample
-// Sample showing how to do a reauthorization
+// This sample code demonstrates how you can reauthorize a PayPal
+// account payment.
 // API used: v1/payments/authorization/{authorization_id}/reauthorize

 require __DIR__ . '/../bootstrap.php';
@@ -17,7 +18,7 @@ use PayPal\Api\Amount;

 try {
 	
-	// ### Retrieve a authorization using the authorization id
+	// ### Lookup authorization using the authorization id
 	$authorization = Authorization::get('7GH53639GA425732B', $apiContext);

 	$amount = new Amount();
@@ -34,6 +35,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Reauthorize a payment</title>
+</head>
 <body>
 	<div>
 		Reauthorization Id:
--- a/sample/payments/RefundCapture.php
+++ b/sample/payments/RefundCapture.php
@@ -1,9 +1,9 @@
 <?php
 // # Refund Capture Sample
-// This sample code demonstrate how you can
-// process a refund on a Captured transaction created
-// using the Capture API.
+// This sample code demonstrates how you can
+// process a refund on a Captured transaction.
 // API used: /v1/payments/capture/{<captureID>}/refund
+
 require __DIR__ . '/../bootstrap.php';

 use PayPal\Api\Authorization;
@@ -13,24 +13,25 @@ use PayPal\Api\Amount;
 use PayPal\Rest\ApiContext;


-// ### Create a mock capture
 try {
-	// create payment to get authorization Id
+	// Create a mock authorization to get authorization Id
 	$authId = createAuthorization($apiContext);

-	$amt = new Amount();
-	$amt->setCurrency("USD")
-		->setTotal("1.00");
-
-	### Capture
-	$captur = new Capture();
-	$captur->setAmount($amt);
-
 	// Get the authorization
 	$authorization = Authorization::get($authId, $apiContext);
 	
+	
+	// ### Capture
+	
+	$amt = new Amount();
+	$amt->setCurrency("USD")
+		->setTotal("1.00");
+	
 	// Create a capture
-	$capt = $authorization->capture($captur, $apiContext);
+	$captureInfo = new Capture();
+	$captureInfo->setAmount($amt);
+
+	$capture = $authorization->capture($captureInfo, $apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
 	var_dump($ex->getData());
@@ -48,7 +49,8 @@ try {
 	// Create a new apiContext object so we send a new
 	// PayPal-Request-Id (idempotency) header for this resource
 	$apiContext = new ApiContext($apiContext->getCredential());
-	$captureRefund = $capt->refund($refund, $apiContext);
+
+	$captureRefund = $capture->refund($refund, $apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
 	var_dump($ex->getData());
@@ -57,6 +59,9 @@ try {
 ?>

 <html>
+<head>
+	<title>Refund a captured payment</title>
+</head>
 <body>
 	<div>Refund Capture:</div>
 	<pre><?php var_dump($captureRefund);?></pre>
--- a/sample/payments/VoidAuthorization.php
+++ b/sample/payments/VoidAuthorization.php
@@ -1,6 +1,7 @@
 <?php
 // # VoidAuthorization
-// This sample code demonstrate how you can void an authorized payment
+// This sample code demonstrates how you can 
+// void an authorized payment.
 // API used: /v1/payments/authorization/<{authorizationid}>/void"

 require __DIR__ . '/../bootstrap.php';
@@ -13,11 +14,14 @@ use PayPal\Api\Authorization;
 // by invoking the $authorization->void method
 // with a valid ApiContext (See bootstrap.php for more on `ApiContext`)
 try {
-	// create payment to get authorization Id
+	// create an authorization to get authorization Id
 	// createAuthorization is defined in common.php
 	$authId = createAuthorization($apiContext);
-	
+
+	// Lookup the authorization
 	$authorization = Authorization::get($authId, $apiContext);
+
+	// Void the authorization 
 	$voidedAuth = $authorization->void($apiContext);
 } catch (PayPal\Exception\PPConnectionException $ex) {
 	echo "Exception: " . $ex->getMessage() . PHP_EOL;
@@ -26,6 +30,9 @@ try {
 }
 ?>
 <html>
+<head>
+	<title>Void an authorization</title>
+</head>
 <body>
 	<div>
 		Voided authorization