# Northstar Server SDK for PHP

[TOC]

## Description

This SDK acts as library to interact with the PayPal API. It will handle the heavy lifting of managing API calls, so devs can focus on their business logic rather than the low level network details.

The PayPal Orders API is a part of the Checkout workflow. An order represents a payment between two or more parties. This SDK allows user to perform all necessary actions on an order.

HTTP request | Description
------------- | -------------
**POST** /orders/{id}/authorize | Authorize payment for order
**POST** /orders/{id}/capture | Capture payment for order
**POST** /orders/{id}/confirm-payment-source | Confirm the Order
**POST** /orders | Create order
**GET** /orders/{id} | Show order details
**PATCH** /orders/{id} | Update order

## Design
### Class Diagrams

classDiagram
class Configuration {
-$_environment : string
-$_clientId : string
-$_clientSecret : string
+__construct($clientId : string, $clientSecret : string, $environment : string)
+baseUrl() string
+getClientId() string
+getClientSecret() string
} 

class Environment {
 <<External PayPalHttp interface>>
 +baseUrl() string
}

Configuration ..|> Environment : implements

class Base {
#$_config : Configuration
+__construct($config : Configuration)
#execute($request : HttpRequest) HttpResponse
}

class Order {
+authorize($id : string, OrderAuthorizeRequestJson) OrderAuthorizeResponseJson
+capture($id : string, OrderCaptureRequestJson) OrderJson
+confirm($id : string, ConfirmOrderRequestJson) OrderJson
+create(OrderRequestJson) OrderJson
+retrieve($id : string) OrderJson
+update(MerchantsCommonComponentsSpecificationV1SchemaCommonComponentsV3SchemaJsonOpenapi20PatchJson[]) int
}

Order --|> Base : extends

class PayPalClient {
-$_config Configuration
-$_order Order
+__construct($config : Configuration)
+order() Order
}

PayPalClient "1" --* "1" Configuration : has-a
PayPalClient "1" --* "1" Order : has-a

## Setup
### Requirements
PHP 7.4 and later.

### Installation
Use [Composer](https://getcomposer.org/)

## Quick Start
### Initialize SDK with Client ID and Secret
Client id and secret are required for each request to [authenticate](https://developer.paypal.com/api/rest/authentication/) the client. Login to [PayPal Developer Dashboard](https://developer.paypal.com/developer/applications) to retrieve your client id and secret.

Client sets the environment, client id, and secret prior to initial request.
The environment is sandbox or production.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use PayPalSDK\Configuration;
use PayPalSDK\PayPalClient;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);
?>

### Create New Order

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use PayPalSDK\Configuration;
use PayPalSDK\PayPalClient;
use PayPalSDK\AmountWithBreakdown;
use PayPalSDK\PurchaseUnitRequest;
use PayPalSDK\OrderRequest;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

$amount = (new AmountWithBreakdown())
  ->setCurrencyCode('USD')
  ->setValue('100.00');

$purchaseUnit = (new PurchaseUnitRequest())
  ->setAmount($amount);

$orderRequest = (new OrderRequest())
  ->setIntent('CAPTURE')
  ->setPurchaseUnits([$purchaseUnit]);

$response = $client->order()->create($orderRequest);
?>

### Get Existing Order
Shows details for an order, by ID.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

// Replace ORDER_ID with actual id.
$response = $client->order()->get(ORDER_ID);

$orderId = $response->getId();
$orderStatus = $response->getStatus();
?>

### Authorize Order
Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Token;
use PaymentSource;
use OrderAuthorizeRequest;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

// OrderAuthorizeRequestJson is optional
$token = (new Token())
    ->setId(PAYPAL_GENERATED_ID)
    ->setType('BILLING_AGREEMENT');
$paymentSource = (new PaymentSource())
    ->setToken($token);
$orderAuthorizeRequest = (new OrderAuthorizeRequest())
    ->setPaymentSource($paymentSource);

$response = $client->order()->authorize(ORDER_ID, $orderAuthorizeRequest);
?>

### Capture Order
Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Token;
use PaymentSource;
use OrderCaptureRequest;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

$token = (new Token())
    ->setId(PAYPAL_GENERATED_ID)
    ->setType('BILLING_AGREEMENT');

$paymentSource = (new PaymentSource())
    ->setPaymentSource($paymentSource);

$orderCaptureRequest = new OrderCaptureRequest();

$response = $client->order()->capture(ORDER_ID, $orderCaptureRequest);
?>

### Patch Order
Updates an order with a CREATED or APPROVED status. You cannot update an order with the COMPLETED status.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Patch;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

$patch = new Patch()
    ->setOp(...)
    ->setPath(...)
    ->setFrom(...)
    ->setValue(...);

$response = $client->order()->patch(ORDER_ID, [$patch]);
?>

### Confirm Order
Payer confirms their intent to pay for the the order with the given payment source.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

use Token;
use PaymentSource;
use ConfirmOrderRequest;

// Replace CLIENT_ID and CLIENT_SECRET with non-hard coded values.
$config = new Configuration(CLIENT_ID, CLIENT_SECRET, 'sandbox');
$client = new PayPalClient($config);

$token = (new Token())
    ->setId(PAYPAL_GENERATED_ID)
    ->setType('BILLING_AGREEMENT');

$paymentSource = (new PaymentSource())
    ->setToken($token);

$confirmOrderRequest = (new ConfirmOrderRequestJson())
    ->setPaymentSource($paymentSource);

$response = $client->order()->confirm(ORDER_ID, $confirmOrderRequest);
?>