1 of 18

Paypal Checkout SDK

Introduction

This Package is a PHP SDK wrapper around version 2 of the PayPal rest API. It provides a simple, fluent API to create and capture orders with both sandbox and production environments supported.

Here are some quick code examples of what you can do:

Create an Order

// Create a purchase unit with the total amount
$purchase_unit = new PurchaseUnit(AmountBreakdown::of('100.00'));

// Create & add item to purchase unit
$purchase_unit->addItem(Item::make('Item 1', '100.00', 'USD', 1));

// Create a new order with intent to capture a payment
$order = (new Order())->addPurchaseUnit($purchase_unit);

// Send request to PayPal
$response = $client->send(new OrderCreateRequest($order));

Show an Order

// Create an order show http request
$request = new OrderShowRequest($order_id);

// Send request to PayPal
$response = $client->send($request);

// Get results
$result = json_decode($response->getBody()->getContents());

Capture an Order

// Create an order capture http request
$request = new OrderCaptureRequest($order_id);

// Send request to PayPal
$response = $client->send($request);

// Get results
$result = json_decode($response->getBody()->getContents());

We have badges

Requirements

PHP Requirements

paypal-checkout-sdk Package requires PHP 7.4 or higher. If you are using an older version of php this package may not function correctly.

Older versions

If you do not meet the requirements, you can opt to use an older version of the package. We only actively maintain the latest version.

Installation

The supported way of installing paypal-checkout-sdk package is via Composer.

composer require phpjuice/paypal-checkout-sdk

Setup Credentials

Get client ID and client secret by going to https://developer.paypal.com/developer/applications and generating a REST API app. Get Client ID and Secret from there.

Setup a Paypal Client

In order to communicate with PayPal platform we need to set up a client first :

Create a client with sandbox environment

// import namespace
use PayPal\Http\Environment\SandboxEnvironment;
use PayPal\Http\PayPalClient;

// client id and client secret retrieved from PayPal
$clientId = "<<PAYPAL-CLIENT-ID>>";
$clientSecret = "<<PAYPAL-CLIENT-SECRET>>";

// create a new sandbox environment
$environment = new SandboxEnvironment($clientId, $clientSecret);

// create a new client
$client = new PayPalClient($environment);

Create a client with production environment

// import namespace
use PayPal\Http\Environment\ProductionEnvironment;
use PayPal\Http\PayPalClient;

// client id and client secret retrieved from PayPal
$clientId = "<<PAYPAL-CLIENT-ID>>";
$clientSecret = "<<PAYPAL-CLIENT-SECRET>>";

// create a new sandbox environment
$environment = new ProductionEnvironment($clientId, $clientSecret);

// create a new client
$client = new PayPalClient($environment);

Upgrading

UPGRADING FROM V2 TO V3

There are few changes needed for upgrading from v2 to v3. but the bulk of changes can be done by leveraging the power of find and replace on your editor.

Change ^2.xx (xx can vary) to ^3.0 in your composer.json
Runcomposer update. Of course, your app must meet the minimum requirements as well.
Change PayPalClient namespace from PayPal\Checkout\Http\PayPalClient to PayPal\Http\PayPalClient.
Change environments namespace:
- PayPal\Checkout\Environment\Environment to PayPal\Http\Environment\Environment.
- PayPal\Checkout\Environment\ProductionEnvironment to PayPal\Http\Environment\ProductionEnvironment.
- PayPal\Checkout\Environment\SandboxEnvironment to PayPal\Http\Environment\SandboxEnvironment.
Change requests namespace:
- PayPal\Checkout\Http\OrderCreateRequest to PayPal\Checkout\Requests\OrderCreateRequest.
- PayPal\Checkout\Http\OrderCaptureRequest to PayPal\Checkout\Requests\OrderCaptureRequest.
- PayPal\Checkout\Http\OrderAuthorizeRequest to PayPal\Checkout\Requests\OrderAuthorizeRequest.
- PayPal\Checkout\Http\OrderShowRequest to PayPal\Checkout\Requests\OrderShowRequest.
- PayPal\Checkout\Http\PaypalRequest to PayPal\Http\PaypalRequest

UPGRADING FROM V1 TO V2

There are no special requirements for upgrading from v1 to v2, other than changing ^1.xx (xx can vary) to ^2.0 in your composer. json and running composer update. Of course, your app must meet the minimum requirements as well.

Questions and issues

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving the package? Feel free to create an issue on GitHub, we'll try to address it as soon as possible.

If you discover any security related issues, please email us at phpjuice@gmail.com instead of using the issue tracker.

Changelog

All notable changes to paypal-checkout-sdk are documented on GitHub

Basic Usage

Create an Order

An order represents a payment between two or more parties. and inorder to create a new order we must send an OrderCreateRequest to PayPal API.

use PayPal\Checkout\Requests\OrderCreateRequest;
use PayPal\Checkout\Orders\AmountBreakdown;
use PayPal\Checkout\Orders\Item;
use PayPal\Checkout\Orders\Order;
use PayPal\Checkout\Orders\PurchaseUnit;

// Create a purchase unit with the total amount
$purchase_unit = new PurchaseUnit(AmountBreakdown::of('200.00', 'USD'));

// Create & add item to purchase unit
$purchase_unit->addItem(Item::make('Item 1', '100.00', 'USD', 1));
$purchase_unit->addItem(Item::make('Item 2', '100.00', 'USD', 1));

// Create a new order with intent to capture a payment
$order = (new Order())->addPurchaseUnit($purchase_unit);

// Send request to PayPal
$response = $client->send(new OrderCreateRequest($order));

// Get results
$result = json_decode($response->getBody()->getContents());

A successful request returns the HTTP 201 Created status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links.

{
    "id": "8F783829JA718493L",
    "status": "CREATED",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://www.sandbox.paypal.com/checkoutnow?token=8F783829JA718493L",
            "rel": "approve",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L",
            "rel": "update",
            "method": "PATCH"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L/capture",
            "rel": "capture",
            "method": "POST"
        }
    ]
}

Show an Order

Inorder to show an order we must send an OrderShowRequest to PayPal API with order_id in question.

use PayPal\Checkout\Requests\OrderShowRequest;

// Get order id from database or request
$order_id = '8F783829JA718493L';

// Create an order show http request
$request = new OrderShowRequest($order_id);

// Send request to PayPal
$response = $client->send($request);

// Get results
$result = json_decode($response->getBody()->getContents());

A successful request returns the HTTP 200 status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links.

{
    "id": "8F783829JA718493L",
    "intent": "CAPTURE",
    "status": "CREATED",
    "purchase_units": [
        {
            "reference_id": "default",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            },
            "payee": {
                "email_address": "merchant@phpjuice.com",
                "merchant_id": "ZCM7386XH4H6Q"
            },
            "items": [
                {
                    "name": "Item 1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "quantity": "1",
                    "description": "My item description",
                    "category": "DIGITAL_GOODS"
                }
            ]
        }
    ],
    "create_time": "2021-10-04T13:21:27Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://www.sandbox.paypal.com/checkoutnow?token=8F783829JA718493L",
            "rel": "approve",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L",
            "rel": "update",
            "method": "PATCH"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/8F783829JA718493L/capture",
            "rel": "capture",
            "method": "POST"
        }
    ]
}

Capture 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. A buyer can approve the order upon being redirected to the rel: approve URL that was provided the HATEOAS links in the response.

A successful response to a non-idempotent request returns the HTTP 201 Created status code with a JSON response body that shows captured payment details. If a duplicate response is retried, returns the HTTP 200 OK status code. By default, the response is minimal.

Catching Errors

If a payment is not yet approved by the buyer, An error response with status code 422 is returned with a JSON response body that shows errors.

Inorder to catch validation errors from PayPal, you can add the following:

Errors :

Api

Amount

See https://developer.paypal.com/docs/api/orders/v2/#definition-Amount_breakdown.

Methods

Amount::__construct()

Creates an amount object using constructor.

Signature

Example

Amount::of()

Creates an amount from a value and an optional currency code.

Signature

Example

Amount::getCurrencyCode()

Gets an amount currency code.

Signature

Example

Amount::getValue()

Gets an amount value.

Signature

Example

Amount::toArray()

Casts the Amount an array representation, used when serializing an amount into http request.

Signature

Example

Amount Breakdown

See https://developer.paypal.com/docs/api/orders/v2/#definition-Amount_breakdown.

Methods

AmountBreakdown::__construct()

Creates an amount breakdown object using constructor.

Signature

Example

AmountBreakdown::of()

Creates an amount from a value and an optional currency code.

Signature

Example

AmountBreakdown::getCurrencyCode()

Gets an amount currency code.

Signature

Example

AmountBreakdown::getValue()

Gets an amount value.

Signature

Example

AmountBreakdown::toArray()

Casts the AmountBreakdown an array representation, used when serializing an amount into http request.

Signature

Example

Application Context

See https://developer.paypal.com/docs/api/orders/v2/#definition-order_application_context

Methods

ApplicationContext::__construct()

Creates an application context object using constructor.

Signature

Example

ApplicationContext::create()

Helper method to create an ApplicationContext statically.

Signature

Example

ApplicationContext::getBrandName()

Returns the brand name value from the application context.

Signature

Example

ApplicationContext::setBrandName()

Sets the brand name value on an application context.

Signature

Example

ApplicationContext::getLocale()

Returns the locale value from the application context, default to en-US.

Signature

Example

ApplicationContext::setLocale()

Sets a locale on an application context.

Signature

Example

ApplicationContext::getShippingPreference()

Returns the shipping preference value from an application context, default to NO_SHIPPING.

Signature

Example

ApplicationContext::setShippingPreference()

Sets a shipping preference value on an application context.

Signature

Available shipping preference options

Example

ApplicationContext::getLandingPage()

Returns the landing page value from an application context, default to NO_PREFERENCE.

Signature

Example

ApplicationContext::setLandingPage()

Sets a landing page value on an application context.

Signature

Available landing page options

Example

ApplicationContext::getUserAction()

Returns the user action value from an application context, default to CONTINUE.

Signature

Example

ApplicationContext::setUserAction()

Sets a user action value on an application context.

Signature

Available user action options

Example

ApplicationContext::getReturnUrl()

Returns the return url value from an application context, default to null.

Signature

Example

ApplicationContext::setReturnUrl()

Sets a return url value on an application context.

Signature

Example

ApplicationContext::getCancelUrl()

Returns the cancel url value from an application context, default to null.

Signature

Example

ApplicationContext::setCancelUrl()

Sets a cancel url value on an application context.

Signature

Example

Item

See https://developer.paypal.com/docs/api/orders/v2/#definition-item.

Methods

Item::__construct()

Creates an item object using constructor.

Signature

public function __construct(string $name, AmountContract $amount, int $quantity = 1);

Example

$amount = Amount::of('100', 'USD');
$item = new Item('Item name', $amount, 2);

Item::create()

A static helper method to create a new item.

Signature

public static function create(string $name, string $value, string $currency_code = 'USD', int $quantity = 1): Item;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);

Item::setUnitAmount()

A method to override a unit amount on an item.

Signature

public function setUnitAmount(AmountContract $unit_amount): self;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$new_amount = Amount::of('200.00', 'USD');
$item->setUnitAmount($new_amount);

Item::getSku()

Returns a sku value assigned to an Item, default to uniqid().

Signature

public function getSku(): string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getSku() // random ex:5819f3ad1c0ce

Item::setSku()

Sets an sku value on an item.

Signature

public function setSku(string $sku): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setSku('item_5819f3ad1c0ce');
$item->getSku(); // item_5819f3ad1c0ce

Item::getName()

Returns an item name.

Signature

public function getName(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getName() // Item name

Item::setName()

Sets an item name.

Signature

public function setName(string $name): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setName('My Item');
$item->getName(); // My Item

Item::getDescription()

Returns an item description. defaults to null

Signature

public function getDescription(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getDescription() // null

Item::setDescription()

Sets an item description.

Signature

public function setDescription(string $description): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setDescription('My Item description');
$item->getDescription(); // My Item description

Item::getQuantity()

Returns an item quantity. defaults to 1

Signature

public function getQuantity(): int;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getQuantity() // 4

Item::setQuantity()

Sets an item quantity.

Signature

public function setQuantity(int $quantity): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setQuantity(3);
$item->getQuantity(); // 3

Item::getCategory()

Returns an item quantity. defaults to DIGITAL_GOODS

Signature

public function getCategory(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getCategory() // DIGITAL_GOODS

Item::setCategory()

Sets an item category.

Signature

public function setCategory(string $category): self;

Available category options

const DIGITAL_GOODS = 'DIGITAL_GOODS';
const PHYSICAL_GOODS = 'PHYSICAL_GOODS';

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setCategory(PHYSICAL_GOODS);
$item->getCategory(); // PHYSICAL_GOODS

Item::toArray()

Returns an item array representation. used when serializing an item into http request.

Signature

public function toArray(): array;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->toArray();
// result
[
    'name' => 'Item name',
    'unit_amount' => [
        'value' => '100.00',
        'currency_code' => 'USD'
    ],
    'quantity' => 4,
    'description' => null,
    'category' => 'DIGITAL_GOODS',
]

Order

See https://developer.paypal.com/docs/api/orders/v2/#definition-order.

Methods

Order::__construct()

Creates an order object using constructor.

Signature

Example

Order::addPurchaseUnit()

Adds a new purchase unit item into purchase_units array.

Signature

Example

Order::getPurchaseUnits()

Gets an array for purchase units from an order.

Signature

Example

Order::setApplicationContext()

Sets the application context of an order.

Signature

Example

Order::getApplicationContext()

Gets an order application context.

Signature

Example

Order::setIntent()

Sets an order intent.

Signature

Example

Order::getIntent()

Gets an order intent.

Signature

Example

Order::getId()

Gets an order id.

Signature

Example

Order::getStatus()

Gets an order status.

Signature

Example

Order::getPayee()

Gets an order payee.

Signature

Example

Payee

See https://developer.paypal.com/docs/api/orders/v2/#payee.

Methods

Payee::__construct()

Creates a payee object using constructor.

Signature

public function __construct(string $email_address, string $merchant_id);

Example

$payee = new Payee('payee@paypal.com', 'YP568Y95AVSDY');

Payee::create()

Creates a payee object.

Signature

public static function create(string $email_address, string $merchant_id): Payee;

Example

$payee = Payee::create('payee@paypal.com', 'YP568Y95AVSDY');

Payee::setEmailAddress()

Sets an email address on a payee object.

Signature

public function setEmailAddress(string $email_address): self

Example

$payee = Payee::create('payee@paypal.com', 'YP568Y95AVSDY');
$payee->setEmailAddress('payee2@paypal.com');

Payee::getEmailAddress()

Gets a payee email address.

Signature

public function getEmailAddress(): string;

Example

$payee = Payee::create('payee@paypal.com', 'YP568Y95AVSDY');
$payee->getEmailAddress() // payee@paypal.com;

Payee::setMerchantId()

Sets a merchant id on a payee object.

Signature

public function setMerchantId(string $merchant_id): self;

Example

$payee = Payee::create('payee@paypal.com', 'YP568Y95AVSDY');
$payee->setEmailAddress('YP568Y95AVSDY');

Payee::getMerchantId()

Gets a payee merchant id.

Signature

public function getMerchantId(): ?string

Example

$payee = Payee::create('payee@paypal.com', 'YP568Y95AVSDY');
$payee->getMerchantId() // YP568Y95AVSDY;

Purchase Unit

See https://developer.paypal.com/docs/api/orders/v2/#definition-purchase_unit.

Methods

PurchaseUnit::__construct()

Creates a new PurchaseUnit instance.

Signature

public function __construct(AmountBreakdown $amount);

Example

$amount = AmountBreakdown::of('100.00', 'CAD');
$purchase_unit = new PurchaseUnit($amount);

PurchaseUnit::addItems()

Pushes a new item or array of items into the items array of PurchaseUnit.

Signature

public function addItems(array $items): self;

Example

$amount = AmountBreakdown::of('100', 'CAD');
$purchase_unit = new PurchaseUnit($amount);

$items = array_map(function ($index) {
    return Item::create("Item $index", '100.00', 'CAD', $index);
}, [1, 2, 3]);


$purchase_unit->addItems($items);

PurchaseUnit::addItem()

Pushes a new item into the items array of PurchaseUnit.

Signature

public function addItem(Item $item): self;

Example

$amount = AmountBreakdown::of('100', 'CAD');
$purchase_unit = new PurchaseUnit($amount);

$purchase_unit->addItem(Item::create('Item 1', '100.00', 'CAD', 2));

PurchaseUnit::getItems()

Returns the items array of PurchaseUnit.

Signature

public function getItems(): array;

Example

$amount = AmountBreakdown::of('100', 'CAD');
$purchase_unit = new PurchaseUnit($amount);

$purchase_unit->addItem(Item::create('Item 1', '100.00', 'CAD', 2));
$purchase_unit->addItem(Item::create('Item 2', '100.00', 'CAD', 2));

$purchase_unit->getItems();

PurchaseUnit::getAmount()

Returns the amount breakdown of PurchaseUnit.

Signature

public function getAmount(): AmountBreakdown;

Example

$amount = AmountBreakdown::of('100', 'CAD');
$purchase_unit = new PurchaseUnit($amount);

$amount = $purchaseUnit->getAmount();

Item

See https://developer.paypal.com/docs/api/orders/v2/#definition-item.

Methods

Item::__construct()

Creates an item object using constructor.

Signature

public function __construct(string $name, AmountContract $amount, int $quantity = 1);

Example

$amount = Amount::of('100', 'USD');
$item = new Item('Item name', $amount, 2);

Item::create()

A static helper method to create a new item.

Signature

public static function create(string $name, string $value, string $currency_code = 'USD', int $quantity = 1): Item;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);

Item::setUnitAmount()

A method to override a unit amount on an item.

Signature

public function setUnitAmount(AmountContract $unit_amount): self;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$new_amount = Amount::of('200.00', 'USD');
$item->setUnitAmount($new_amount);

Item::getSku()

Returns a sku value assigned to an Item, default to uniqid().

Signature

public function getSku(): string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getSku() // random ex:5819f3ad1c0ce

Item::setSku()

Sets an sku value on an item.

Signature

public function setSku(string $sku): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setSku('item_5819f3ad1c0ce');
$item->getSku(); // item_5819f3ad1c0ce

Item::getName()

Returns an item name.

Signature

public function getName(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getName() // Item name

Item::setName()

Sets an item name.

Signature

public function setName(string $name): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setName('My Item');
$item->getName(); // My Item

Item::getDescription()

Returns an item description. defaults to null

Signature

public function getDescription(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getDescription() // null

Item::setDescription()

Sets an item description.

Signature

public function setDescription(string $description): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setDescription('My Item description');
$item->getDescription(); // My Item description

Item::getQuantity()

Returns an item quantity. defaults to 1

Signature

public function getQuantity(): int;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getQuantity() // 4

Item::setQuantity()

Sets an item quantity.

Signature

public function setQuantity(int $quantity): self;

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setQuantity(3);
$item->getQuantity(); // 3

Item::getCategory()

Returns an item quantity. defaults to DIGITAL_GOODS

Signature

public function getCategory(): ?string;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->getCategory() // DIGITAL_GOODS

Item::setCategory()

Sets an item category.

Signature

public function setCategory(string $category): self;

Available category options

const DIGITAL_GOODS = 'DIGITAL_GOODS';
const PHYSICAL_GOODS = 'PHYSICAL_GOODS';

Example

$item = Item::create('Item 1', '100.00', 'USD', 4);
$item->setCategory(PHYSICAL_GOODS);
$item->getCategory(); // PHYSICAL_GOODS

Item::toArray()

Returns an item array representation. used when serializing an item into http request.

Signature

public function toArray(): array;

Example

$item = Item::create('Item name', '100.00', 'USD', 4);
$item->toArray();
// result
[
    'name' => 'Item name',
    'unit_amount' => [
        'value' => '100.00',
        'currency_code' => 'USD'
    ],
    'quantity' => 4,
    'description' => null,
    'category' => 'DIGITAL_GOODS',
]