Order API Support

- Added Order API Support
- Updated Sample Code to demonstrate
- Updated Sample Docs
- Fixes #237

sample/payments/ExecutePayment.php

@@ -33,16 +33,21 @@ if (isset($_GET['success']) && $_GET['success'] == 'true') {
     $execution = new PaymentExecution();
     $execution->setPayerId($_GET['PayerID']);
 
-    // Execute the payment
-    // (See bootstrap.php for more on `ApiContext`)
-    $result = $payment->execute($execution, $apiContext);
-
-    ResultPrinter::printResult("Executed Payment", "Payment", $payment->getId(), $execution, $result);
-
     try {
-        $payment = Payment::get($paymentId, $apiContext);
+        // Execute the payment
+        // (See bootstrap.php for more on `ApiContext`)
+        $result = $payment->execute($execution, $apiContext);
+
+        ResultPrinter::printResult("Executed Payment", "Payment", $payment->getId(), $execution, $result);
+
+        try {
+            $payment = Payment::get($paymentId, $apiContext);
+        } catch (Exception $ex) {
+            ResultPrinter::printError("Get Payment", "Payment", null, null, $ex);
+            exit(1);
+        }
     } catch (Exception $ex) {
-        ResultPrinter::printError("Get Payment", "Payment", null, null, $ex);
+        ResultPrinter::printError("Executed Payment", "Payment", null, null, $ex);
         exit(1);
     }
 
@@ -53,4 +58,5 @@ if (isset($_GET['success']) && $_GET['success'] == 'true') {
 
 } else {
     ResultPrinter::printResult("User Cancelled the Approval", null);
+    exit;
 }

sample/payments/OrderAuthorize.php

@@ -0,0 +1,51 @@
+<?php
+// #Authorize Order Sample
+// To authorize an order payment, pass the orderId in the URI of a POST call. This begins the process of confirming that funds are available until it is time to complete the payment transaction.
+// API used: POST /v1/payments/orders/<Order-Id>/authorize
+
+/** @var \PayPal\Api\Payment $payment */
+$payment = require __DIR__ . '/ExecutePayment.php';
+
+use PayPal\Api\Order;
+use PayPal\Api\Amount;
+use PayPal\Api\Authorization;
+
+// ### Approval Status
+// Determine if the user approved the payment or not
+if (isset($_GET['success']) && $_GET['success'] == 'true') {
+
+    // ### Retrieve the order
+    // OrderId could be retrieved by parsing the object inside related_resources.
+    $transactions = $payment->getTransactions();
+    $transaction = $transactions[0];
+    $relatedResources = $transaction->getRelatedResources();
+    $relatedResource = $relatedResources[0];
+    $order = $relatedResource->getOrder();
+
+    // ### Create Authorization Object
+    // with Amount in it
+    $authorization = new Authorization();
+    $authorization->setAmount(new Amount(
+        '{
+            "total": "2.00",
+            "currency": "USD"
+        }'
+    ));
+
+    try {
+        // ### Authorize Order
+        // Authorize the order by passing authorization object we created.
+        // We will get a new authorization object back.
+        $result = $order->authorize($authorization, $apiContext);
+        ResultPrinter::printResult("Authorized Order", "Authorization", $result->getId(), $authorization, $result);
+    } catch (Exception $ex) {
+        ResultPrinter::printError("Authorized Order", "Authorization", null, $authorization, $ex);
+        exit(1);
+    }
+
+    return $result;
+
+} else {
+    ResultPrinter::printResult("User Cancelled the Approval", null);
+    exit;
+}

sample/payments/OrderCapture.php

@@ -0,0 +1,51 @@
+<?php
+// #Capture Order Sample
+// To authorize an order payment, pass the orderId in the URI of a POST call. This begins the process of confirming that funds are available until it is time to complete the payment transaction.
+// API used: POST /v1/payments/orders/<Order-Id>/authorize
+
+/** @var \PayPal\Api\Payment $payment */
+$payment = require __DIR__ . '/ExecutePayment.php';
+
+use PayPal\Api\Capture;
+use PayPal\Api\Amount;
+
+// ### Approval Status
+// Determine if the user approved the payment or not
+if (isset($_GET['success']) && $_GET['success'] == 'true') {
+
+    // ### Retrieve the order
+    // OrderId could be retrieved by parsing the object inside related_resources.
+    $transactions = $payment->getTransactions();
+    $transaction = $transactions[0];
+    $relatedResources = $transaction->getRelatedResources();
+    $relatedResource = $relatedResources[0];
+    $order = $relatedResource->getOrder();
+
+    // ### Create Capture Object
+    // with Amount in it
+    $capture = new Capture();
+    $capture->setIsFinalCapture(true);
+    $capture->setAmount(new Amount(
+        '{
+            "total": "2.00",
+            "currency": "USD"
+        }'
+    ));
+
+    try {
+        // ### Capture Order
+        // Capture the order by passing capture object we created.
+        // We will get a new capture object back.
+        $result = $order->capture($capture, $apiContext);
+        ResultPrinter::printResult("Captured Order", "Capture", $result->getId(), $capture, $result);
+    } catch (Exception $ex) {
+        ResultPrinter::printError("Captured Order", "Capture", null, $capture, $ex);
+        exit(1);
+    }
+
+    return $result;
+
+} else {
+    ResultPrinter::printResult("User Cancelled the Approval", null);
+    exit;
+}

sample/payments/OrderCreateForAuthorization.php

@@ -0,0 +1,112 @@
+<?php
+
+// # Order Create Using PayPal
+// In a call to the /payment resource, provide the payment details. In the intent field, specify order, and set the payment_method to paypal. Creating an order is similar to creating a payment.
+// API used: /v1/payments/payment
+
+require __DIR__ . '/../bootstrap.php';
+use PayPal\Api\Amount;
+use PayPal\Api\Details;
+use PayPal\Api\Item;
+use PayPal\Api\ItemList;
+use PayPal\Api\Payer;
+use PayPal\Api\Payment;
+use PayPal\Api\RedirectUrls;
+use PayPal\Api\Transaction;
+
+// ### Payer
+// A resource representing a Payer that funds a payment
+// For paypal account payments, set payment method
+// to 'paypal'.
+$payer = new Payer();
+$payer->setPaymentMethod("paypal");
+
+// ### Itemized information
+// (Optional) Lets you specify item wise
+// information
+$item1 = new Item();
+$item1->setName('Ground Coffee 40 oz')
+    ->setCurrency('USD')
+    ->setQuantity(1)
+    ->setPrice(7.5);
+$item2 = new Item();
+$item2->setName('Granola bars')
+    ->setCurrency('USD')
+    ->setQuantity(5)
+    ->setPrice(2);
+
+$itemList = new ItemList();
+$itemList->setItems(array($item1, $item2));
+
+// ### Additional payment details
+// Use this optional field to set additional
+// payment information such as tax, shipping
+// charges etc.
+$details = new Details();
+$details->setShipping(1.2)
+    ->setTax(1.3)
+    ->setSubtotal(17.50);
+
+// ### Amount
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
+$amount = new Amount();
+$amount->setCurrency("USD")
+    ->setTotal(20)
+    ->setDetails($details);
+
+// ### Transaction
+// A transaction defines the contract of a
+// payment - what is the payment for and who
+// is fulfilling it. 
+$transaction = new Transaction();
+$transaction->setAmount($amount)
+    ->setItemList($itemList)
+    ->setDescription("Payment description")
+    ->setInvoiceNumber(uniqid());
+
+// ### Redirect urls
+// Set the urls that the buyer must be redirected to after 
+// payment approval/ cancellation.
+$baseUrl = getBaseUrl();
+$redirectUrls = new RedirectUrls();
+$redirectUrls->setReturnUrl("$baseUrl/OrderAuthorize.php?success=true")
+    ->setCancelUrl("$baseUrl/OrderAuthorize.php?success=false");
+
+// ### Payment
+// A Payment Resource; create one using
+// the above types and intent set to 'order'
+$payment = new Payment();
+$payment->setIntent("order")
+    ->setPayer($payer)
+    ->setRedirectUrls($redirectUrls)
+    ->setTransactions(array($transaction));
+
+
+// For Sample Purposes Only.
+$request = clone $payment;
+
+// ### Create Payment
+// 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 state and the
+// url to which the buyer must be redirected to
+// for payment approval
+try {
+    $payment->create($apiContext);
+} catch (Exception $ex) {
+    ResultPrinter::printError("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", null, $request, $ex);
+    exit(1);
+}
+
+// ### Get redirect url
+// The API response provides the url that you must redirect
+// the buyer to. Retrieve the url from the $payment->getApprovalLink()
+// method
+$approvalUrl = $payment->getApprovalLink();
+
+ResultPrinter::printResult("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", "<a href='$approvalUrl' >$approvalUrl</a>", $request, $payment);
+
+return $payment;

sample/payments/OrderCreateForCapture.php

@@ -0,0 +1,112 @@
+<?php
+
+// # Order Create Using PayPal
+// In a call to the /payment resource, provide the payment details. In the intent field, specify order, and set the payment_method to paypal. Creating an order is similar to creating a payment.
+// API used: /v1/payments/payment
+
+require __DIR__ . '/../bootstrap.php';
+use PayPal\Api\Amount;
+use PayPal\Api\Details;
+use PayPal\Api\Item;
+use PayPal\Api\ItemList;
+use PayPal\Api\Payer;
+use PayPal\Api\Payment;
+use PayPal\Api\RedirectUrls;
+use PayPal\Api\Transaction;
+
+// ### Payer
+// A resource representing a Payer that funds a payment
+// For paypal account payments, set payment method
+// to 'paypal'.
+$payer = new Payer();
+$payer->setPaymentMethod("paypal");
+
+// ### Itemized information
+// (Optional) Lets you specify item wise
+// information
+$item1 = new Item();
+$item1->setName('Ground Coffee 40 oz')
+    ->setCurrency('USD')
+    ->setQuantity(1)
+    ->setPrice(7.5);
+$item2 = new Item();
+$item2->setName('Granola bars')
+    ->setCurrency('USD')
+    ->setQuantity(5)
+    ->setPrice(2);
+
+$itemList = new ItemList();
+$itemList->setItems(array($item1, $item2));
+
+// ### Additional payment details
+// Use this optional field to set additional
+// payment information such as tax, shipping
+// charges etc.
+$details = new Details();
+$details->setShipping(1.2)
+    ->setTax(1.3)
+    ->setSubtotal(17.50);
+
+// ### Amount
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
+$amount = new Amount();
+$amount->setCurrency("USD")
+    ->setTotal(20)
+    ->setDetails($details);
+
+// ### Transaction
+// A transaction defines the contract of a
+// payment - what is the payment for and who
+// is fulfilling it. 
+$transaction = new Transaction();
+$transaction->setAmount($amount)
+    ->setItemList($itemList)
+    ->setDescription("Payment description")
+    ->setInvoiceNumber(uniqid());
+
+// ### Redirect urls
+// Set the urls that the buyer must be redirected to after 
+// payment approval/ cancellation.
+$baseUrl = getBaseUrl();
+$redirectUrls = new RedirectUrls();
+$redirectUrls->setReturnUrl("$baseUrl/OrderCapture.php?success=true")
+    ->setCancelUrl("$baseUrl/OrderCapture.php?success=false");
+
+// ### Payment
+// A Payment Resource; create one using
+// the above types and intent set to 'order'
+$payment = new Payment();
+$payment->setIntent("order")
+    ->setPayer($payer)
+    ->setRedirectUrls($redirectUrls)
+    ->setTransactions(array($transaction));
+
+
+// For Sample Purposes Only.
+$request = clone $payment;
+
+// ### Create Payment
+// 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 state and the
+// url to which the buyer must be redirected to
+// for payment approval
+try {
+    $payment->create($apiContext);
+} catch (Exception $ex) {
+    ResultPrinter::printError("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", null, $request, $ex);
+    exit(1);
+}
+
+// ### Get redirect url
+// The API response provides the url that you must redirect
+// the buyer to. Retrieve the url from the $payment->getApprovalLink()
+// method
+$approvalUrl = $payment->getApprovalLink();
+
+ResultPrinter::printResult("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", "<a href='$approvalUrl' >$approvalUrl</a>", $request, $payment);
+
+return $payment;

sample/payments/OrderCreateForVoid.php

@@ -0,0 +1,112 @@
+<?php
+
+// # Order Create Using PayPal
+// In a call to the /payment resource, provide the payment details. In the intent field, specify order, and set the payment_method to paypal. Creating an order is similar to creating a payment.
+// API used: /v1/payments/payment
+
+require __DIR__ . '/../bootstrap.php';
+use PayPal\Api\Amount;
+use PayPal\Api\Details;
+use PayPal\Api\Item;
+use PayPal\Api\ItemList;
+use PayPal\Api\Payer;
+use PayPal\Api\Payment;
+use PayPal\Api\RedirectUrls;
+use PayPal\Api\Transaction;
+
+// ### Payer
+// A resource representing a Payer that funds a payment
+// For paypal account payments, set payment method
+// to 'paypal'.
+$payer = new Payer();
+$payer->setPaymentMethod("paypal");
+
+// ### Itemized information
+// (Optional) Lets you specify item wise
+// information
+$item1 = new Item();
+$item1->setName('Ground Coffee 40 oz')
+    ->setCurrency('USD')
+    ->setQuantity(1)
+    ->setPrice(7.5);
+$item2 = new Item();
+$item2->setName('Granola bars')
+    ->setCurrency('USD')
+    ->setQuantity(5)
+    ->setPrice(2);
+
+$itemList = new ItemList();
+$itemList->setItems(array($item1, $item2));
+
+// ### Additional payment details
+// Use this optional field to set additional
+// payment information such as tax, shipping
+// charges etc.
+$details = new Details();
+$details->setShipping(1.2)
+    ->setTax(1.3)
+    ->setSubtotal(17.50);
+
+// ### Amount
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
+$amount = new Amount();
+$amount->setCurrency("USD")
+    ->setTotal(20)
+    ->setDetails($details);
+
+// ### Transaction
+// A transaction defines the contract of a
+// payment - what is the payment for and who
+// is fulfilling it. 
+$transaction = new Transaction();
+$transaction->setAmount($amount)
+    ->setItemList($itemList)
+    ->setDescription("Payment description")
+    ->setInvoiceNumber(uniqid());
+
+// ### Redirect urls
+// Set the urls that the buyer must be redirected to after 
+// payment approval/ cancellation.
+$baseUrl = getBaseUrl();
+$redirectUrls = new RedirectUrls();
+$redirectUrls->setReturnUrl("$baseUrl/OrderDoVoid.php?success=true")
+    ->setCancelUrl("$baseUrl/OrderDoVoid.php?success=false");
+
+// ### Payment
+// A Payment Resource; create one using
+// the above types and intent set to 'order'
+$payment = new Payment();
+$payment->setIntent("order")
+    ->setPayer($payer)
+    ->setRedirectUrls($redirectUrls)
+    ->setTransactions(array($transaction));
+
+
+// For Sample Purposes Only.
+$request = clone $payment;
+
+// ### Create Payment
+// 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 state and the
+// url to which the buyer must be redirected to
+// for payment approval
+try {
+    $payment->create($apiContext);
+} catch (Exception $ex) {
+    ResultPrinter::printError("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", null, $request, $ex);
+    exit(1);
+}
+
+// ### Get redirect url
+// The API response provides the url that you must redirect
+// the buyer to. Retrieve the url from the $payment->getApprovalLink()
+// method
+$approvalUrl = $payment->getApprovalLink();
+
+ResultPrinter::printResult("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", "<a href='$approvalUrl' >$approvalUrl</a>", $request, $payment);
+
+return $payment;

sample/payments/OrderCreateUsingPayPal.php

@@ -0,0 +1,112 @@
+<?php
+
+// # Order Create Using PayPal
+// In a call to the /payment resource, provide the payment details. In the intent field, specify order, and set the payment_method to paypal. Creating an order is similar to creating a payment.
+// API used: /v1/payments/payment
+
+require __DIR__ . '/../bootstrap.php';
+use PayPal\Api\Amount;
+use PayPal\Api\Details;
+use PayPal\Api\Item;
+use PayPal\Api\ItemList;
+use PayPal\Api\Payer;
+use PayPal\Api\Payment;
+use PayPal\Api\RedirectUrls;
+use PayPal\Api\Transaction;
+
+// ### Payer
+// A resource representing a Payer that funds a payment
+// For paypal account payments, set payment method
+// to 'paypal'.
+$payer = new Payer();
+$payer->setPaymentMethod("paypal");
+
+// ### Itemized information
+// (Optional) Lets you specify item wise
+// information
+$item1 = new Item();
+$item1->setName('Ground Coffee 40 oz')
+    ->setCurrency('USD')
+    ->setQuantity(1)
+    ->setPrice(7.5);
+$item2 = new Item();
+$item2->setName('Granola bars')
+    ->setCurrency('USD')
+    ->setQuantity(5)
+    ->setPrice(2);
+
+$itemList = new ItemList();
+$itemList->setItems(array($item1, $item2));
+
+// ### Additional payment details
+// Use this optional field to set additional
+// payment information such as tax, shipping
+// charges etc.
+$details = new Details();
+$details->setShipping(1.2)
+    ->setTax(1.3)
+    ->setSubtotal(17.50);
+
+// ### Amount
+// Lets you specify a payment amount.
+// You can also specify additional details
+// such as shipping, tax.
+$amount = new Amount();
+$amount->setCurrency("USD")
+    ->setTotal(20)
+    ->setDetails($details);
+
+// ### Transaction
+// A transaction defines the contract of a
+// payment - what is the payment for and who
+// is fulfilling it. 
+$transaction = new Transaction();
+$transaction->setAmount($amount)
+    ->setItemList($itemList)
+    ->setDescription("Payment description")
+    ->setInvoiceNumber(uniqid());
+
+// ### Redirect urls
+// Set the urls that the buyer must be redirected to after 
+// payment approval/ cancellation.
+$baseUrl = getBaseUrl();
+$redirectUrls = new RedirectUrls();
+$redirectUrls->setReturnUrl("$baseUrl/OrderGet.php?success=true")
+    ->setCancelUrl("$baseUrl/OrderGet.php?success=false");
+
+// ### Payment
+// A Payment Resource; create one using
+// the above types and intent set to 'order'
+$payment = new Payment();
+$payment->setIntent("order")
+    ->setPayer($payer)
+    ->setRedirectUrls($redirectUrls)
+    ->setTransactions(array($transaction));
+
+
+// For Sample Purposes Only.
+$request = clone $payment;
+
+// ### Create Payment
+// 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 state and the
+// url to which the buyer must be redirected to
+// for payment approval
+try {
+    $payment->create($apiContext);
+} catch (Exception $ex) {
+    ResultPrinter::printError("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", null, $request, $ex);
+    exit(1);
+}
+
+// ### Get redirect url
+// The API response provides the url that you must redirect
+// the buyer to. Retrieve the url from the $payment->getApprovalLink()
+// method
+$approvalUrl = $payment->getApprovalLink();
+
+ResultPrinter::printResult("Created Payment Order Using PayPal. Please visit the URL to Approve.", "Payment", "<a href='$approvalUrl' >$approvalUrl</a>", $request, $payment);
+
+return $payment;

sample/payments/OrderDoVoid.php

@@ -0,0 +1,40 @@
+<?php
+// #Void Order Sample
+// Use this call to void an existing order.
+// Note: An order cannot be voided if payment has already been partially or fully captured.
+// API used: POST /v1/payments/orders/<Order-Id>/do-void
+
+/** @var \PayPal\Api\Payment $payment */
+$payment = require __DIR__ . '/ExecutePayment.php';
+
+use PayPal\Api\Capture;
+use PayPal\Api\Amount;
+
+// ### Approval Status
+// Determine if the user approved the payment or not
+if (isset($_GET['success']) && $_GET['success'] == 'true') {
+
+    // ### Retrieve the order
+    // OrderId could be retrieved by parsing the object inside related_resources.
+    $transactions = $payment->getTransactions();
+    $transaction = $transactions[0];
+    $relatedResources = $transaction->getRelatedResources();
+    $relatedResource = $relatedResources[0];
+    $order = $relatedResource->getOrder();
+
+    try {
+        // ### Void Order
+        // Call void method on order object. You will get an Order Object back
+        $result = $order->void($apiContext);
+        ResultPrinter::printResult("Voided Order", "Order", $result->getId(), null, $result);
+    } catch (Exception $ex) {
+        ResultPrinter::printError("Voided Order", "Order", null, null, $ex);
+        exit(1);
+    }
+
+    return $result;
+
+} else {
+    ResultPrinter::printResult("User Cancelled the Approval", null);
+    exit;
+}

sample/payments/OrderGet.php

@@ -0,0 +1,32 @@
+<?php
+// #Get Order Sample
+// Specify an order ID to get details about an order.
+// API used: GET /v1/payments/orders/<Order-Id>
+
+/** @var \PayPal\Api\Payment $payment */
+$payment = require __DIR__ . '/ExecutePayment.php';
+
+// ### Approval Status
+// Determine if the user approved the payment or not
+if (isset($_GET['success']) && $_GET['success'] == 'true') {
+
+    $transactions = $payment->getTransactions();
+    $transaction = $transactions[0];
+    $relatedResources = $transaction->getRelatedResources();
+    $relatedResource = $relatedResources[0];
+    $order = $relatedResource->getOrder();
+
+    try {
+        $result = \PayPal\Api\Order::get($order->getId(), $apiContext);
+        ResultPrinter::printResult("Get Order", "Order", $result->getId(), null, $result);
+    } catch (Exception $ex) {
+        ResultPrinter::printError("Get Order", "Order", null, null, $ex);
+        exit(1);
+    }
+
+    return $result;
+
+} else {
+    ResultPrinter::printResult("User Cancelled the Approval", null);
+    exit;
+}