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.

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

Create a client with production 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
Change requests namespace:
- PayPal\Checkout\Http\OrderCreateRequest to PayPal\Checkout\Requests\OrderCreateRequest.
- PayPal\Checkout\Http\OrderCaptureRequest

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 , 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

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.

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.

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 Create Order response.

use PayPal\Checkout\Requests\OrderCaptureRequest;

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

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

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

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

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.

{
    "id": "8F783829JA718493L",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "purchase_units": [
        {
            "reference_id": "default",
            "amount": {
                "currency_code": "CAD",
                "value": "200.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "CAD",
                        "value": "200.00"
                    },
                    "shipping": {
                        "currency_code": "CAD",
                        "value": "0.00"
                    },
                    "handling": {
                        "currency_code": "CAD",
                        "value": "0.00"
                    },
                    "insurance": {
                        "currency_code": "CAD",
                        "value": "0.00"
                    },
                    "shipping_discount": {
                        "currency_code": "CAD",
                        "value": "0.00"
                    }
                }
            },
            "payee": {
                "email_address": "merchant@phpjuice.com",
                "merchant_id": "ZCM7386XH4H6Q"
            },
            "description": "My item description",
            "items": [
                {
                    "name": "Item",
                    "unit_amount": {
                        "currency_code": "CAD",
                        "value": "100.00"
                    },
                    "tax": {
                        "currency_code": "CAD",
                        "value": "0.00"
                    },
                    "quantity": "2"
                }
            ],
            "payments": {
                "captures": [
                    {
                        "id": "6SW93058HS0959910",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "CAD",
                            "value": "200.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "ELIGIBLE",
                            "dispute_categories": [
                                "ITEM_NOT_RECEIVED",
                                "UNAUTHORIZED_TRANSACTION"
                            ]
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "CAD",
                                "value": "200.00"
                            },
                            "paypal_fee": {
                                "currency_code": "CAD",
                                "value": "6.10"
                            },
                            "net_amount": {
                                "currency_code": "CAD",
                                "value": "193.90"
                            }
                        },
                        "links": [
                            {
                                "href": "https:\/\/api.sandbox.paypal.com\/v2\/payments\/captures\/6SW93058HS0959910",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https:\/\/api.sandbox.paypal.com\/v2\/payments\/captures\/6SW93058HS0959910\/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https:\/\/api.sandbox.paypal.com\/v2\/checkout\/orders\/8F783829JA718493L",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2021-10-04T16:19:27Z",
                        "update_time": "2021-10-04T16:19:27Z"
                    }
                ]
            }
        }
    ],
    "payer": {
        "name": {
            "given_name": "John",
            "surname": "Doe"
        },
        "email_address": "buyer@phpjuice.com",
        "payer_id": "DCTWHLD9BMMMC",
        "address": {
            "country_code": "CA"
        }
    },
    "create_time": "2021-10-04T13:21:27Z",
    "update_time": "2021-10-04T16:19:27Z",
    "links": [
        {
            "href": "https:\/\/api.sandbox.paypal.com\/v2\/checkout\/orders\/8F783829JA718493L",
            "rel": "self",
            "method": "GET"
        }
    ]
}

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

public function __construct(
    ?string $brand_name = null,
    ?string $locale = 'en-US',
    ?string $landing_page = NO_PREFERENCE,
    ?string $shipping_preference = NO_SHIPPING,
    ?string $return_url = null,
    ?string $cancel_url = null
);

Example

$application_context = new ApplicationContext('PHPJuice', 'en-US');

ApplicationContext::create()

Helper method to create an ApplicationContext statically.

Signature

public static function create(
    ?string $brand_name = null,
    ?string $locale = 'en-US',
    ?string $landing_page = NO_PREFERENCE,
    ?string $shipping_preference = NO_SHIPPING,
    ?string $return_url = null,
    ?string $cancel_url = null
): ApplicationContext;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');

ApplicationContext::getBrandName()

Returns the brand name value from the application context.

Signature

public function getBrandName(): ?string;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->getBrandName() // PHPJuice

ApplicationContext::setBrandName()

Sets the brand name value on an application context.

Signature

public function setBrandName($brand_name): self;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->setBrandName('PHPJuice Inc');
$application_context->getBrandName(); // PHPJuice Inc

ApplicationContext::getLocale()

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

Sets a locale on an application context.

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

Sets a shipping preference value on an application context.

Available shipping preference options

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

Sets a landing page value on an application context.

Available landing page options

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

Sets a user action value on an application context.

Available user action options

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

Sets a return url value on an application context.

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

Sets a cancel url value on an application context.

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.

Sets an item name.

Returns an item description. defaults to null

Sets an item description.

Returns an item quantity. defaults to 1

Sets an item quantity.

Returns an item quantity. defaults to DIGITAL_GOODS

Sets an item category.

Available category options

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

Order

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

Methods

Order::__construct()

Creates an order object using constructor.

Signature

public function __construct(string $intent = CAPTURE);

Example

$order = new Order('CAPTURE');

Order::addPurchaseUnit()

Adds a new purchase unit item into purchase_units array.

Signature

public function addPurchaseUnit(PurchaseUnit $purchase_unit): self;

Example

$order = new Order('CAPTURE');
$order->addPurchaseUnit($purchase_unit);

Order::getPurchaseUnits()

Gets an array for purchase units from an order.

Signature

public function getPurchaseUnits(): array;

Example

$purchase_units = $order->getPurchaseUnits($purchase_unit);

Order::setApplicationContext()

Sets the application context of an order.

Signature

public function setApplicationContext(ApplicationContext $application_context): self;

Example

$order = new Order('CAPTURE');
$order->setApplicationContext($application_context);

Order::getApplicationContext()

Gets an order application context.

Signature

public function getApplicationContext(): ?ApplicationContext;

Example

$application_context = $order->getApplicationContext() // ApplicationContext::class ;

Order::setIntent()

Sets an order intent.

Signature

public function setIntent(string $intent): self;

Example

$order = new Order('CAPTURE');
$order->setIntent('AUTHORIZE');