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

use GuzzleHttp\Exception\RequestException;

try {
    $id = '8F783829JA718493L';
    $response = $client->send(new OrderCaptureRequest($id));
    $result = json_decode($response->getBody()->getContents());
} catch (RequestException $e) {
    $errors = json_decode($e->getResponse()->getBody()->getContents());
}

Errors :

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "issue": "ORDER_NOT_APPROVED",
            "description": "Payer has not yet approved the Order for payment. Please redirect the payer to the 'rel':'approve' url returned as part of the HATEOAS links within the Create Order call or provide a valid payment_source in the request."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "80cb04a5dbea7",
    "links": [
        {
            "href": "https://developer.paypal.com/docs/api/orders/v2/#error-ORDER_NOT_APPROVED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

Api

Amount

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

Methods

Amount::__construct()

Creates an amount object using constructor.

Signature

public function __construct(string $value, string $currency_code = 'USD');

Example

$amount = new Amount('100.00', 'USD');

Amount::of()

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

Signature

public static function of(string $value, string $currency_code = 'USD'): Amount;

Example

$amount = Amount::of('100.00', 'USD');

Amount::getCurrencyCode()

Gets an amount currency code.

Signature

public function getCurrencyCode(): string;

Example

$amount = Amount::of('100.00', 'USD');
$currency = $amount->getCurrencyCode(); // USD

Amount::getValue()

Gets an amount value.

Signature

public function getValue(): string;

Example

$amount = Amount::of('100.00', 'USD');
$value = $amount->getValue(); // '100.00'

Amount::toArray()

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

Signature

public function toArray(): array;

Example

$amount = Amount::of('100.00', 'USD');
$array = $amount->toArray(); 
// result
[   
    'value' => '100.00', 
    'currency_code' => 'USD'
];

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

public function __construct(string $value, string $currency_code = 'USD');

Example

$amount = new AmountBreakdown('100.00', 'USD');

AmountBreakdown::of()

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

Signature

public static function of(string $value, string $currency_code = 'USD'): AmountBreakdown;

Example

$amount = AmountBreakdown::of('100.00', 'USD');

AmountBreakdown::getCurrencyCode()

Gets an amount currency code.

Signature

public function getCurrencyCode(): string;

Example

$amount = AmountBreakdown::of('100.00', 'USD');
$currency = $amount->getCurrencyCode(); // USD

AmountBreakdown::getValue()

Gets an amount value.

Signature

public function getValue(): string;

Example

$amount = AmountBreakdown::of('100.00', 'USD');
$value = $amount->getValue(); // '100.00'

AmountBreakdown::toArray()

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

Signature

public function toArray(): array;

Example

$amount = AmountBreakdown::of('100.00', 'USD');
$array = $amount->toArray(); 
// result
[   
    'value' => '100.00', 
    'currency_code' => 'USD'
];

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.

Signature

public function getLocale(): string;

Example

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

ApplicationContext::setLocale()

Sets a locale on an application context.

Signature

public function setLocale($locale): self;

Example

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

ApplicationContext::getShippingPreference()

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

Signature

public function getShippingPreference(): string;

Example

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

ApplicationContext::setShippingPreference()

Sets a shipping preference value on an application context.

Signature

public function setShippingPreference($shipping_preference): self;

Available shipping preference options

const GET_FROM_FILE = 'GET_FROM_FILE';
const NO_SHIPPING = 'NO_SHIPPING';
const SET_PROVIDED_ADDRESS = 'SET_PROVIDED_ADDRESS';

Example

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

ApplicationContext::getLandingPage()

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

Signature

public function getLandingPage(): string;

Example

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

ApplicationContext::setLandingPage()

Sets a landing page value on an application context.

Signature

public function setLandingPage($landing_page): self;

Available landing page options

const LOGIN = 'LOGIN';
const BILLING = 'BILLING';
const NO_PREFERENCE = 'NO_PREFERENCE';

Example

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

ApplicationContext::getUserAction()

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

Signature

public function getUserAction(): string;

Example

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

ApplicationContext::setUserAction()

Sets a user action value on an application context.

Signature

public function setUserAction($user_action): self;

Available user action options

const ACTION_CONTINUE = 'CONTINUE';
const ACTION_PAY_NOW = 'PAY_NOW';

Example

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

ApplicationContext::getReturnUrl()

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

Signature

public function getReturnUrl(): string;

Example

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

ApplicationContext::setReturnUrl()

Sets a return url value on an application context.

Signature

public function setReturnUrl($return_url): self;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->setReturnUrl('https://phpjuice.org/success');
$application_context->getReturnUrl(); // https://phpjuice.org/success

ApplicationContext::getCancelUrl()

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

Signature

public function getCancelUrl(): string;

Example

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

ApplicationContext::setCancelUrl()

Sets a cancel url value on an application context.

Signature

public function setCancelUrl($cancel_url): self;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->setCancelUrl('https://phpjuice.org/cancel');
$application_context->getCancelUrl(); // https://phpjuice.org/cancel

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

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');

Order::getIntent()

Gets an order intent.

Signature

public function getIntent(): string;

Example

$order = new Order('CAPTURE');
$intent = $order->getIntent() // CAPTURE;

Order::getId()

Gets an order id.

Signature

public function getId(): string;

Example

$order = new Order('CAPTURE');
$id = $order->getId() // 8F783829JA718493L;

Order::getStatus()

Gets an order status.

Signature

public function getStatus(): string;

Example

$order = new Order('CAPTURE');
$status = $order->getStatus() // COMPLETED;

Order::getPayee()

Gets an order payee.

Signature

public function getPayee(): ?Payee;

Example

$order = new Order('CAPTURE');
$payee = $order->getPayee() // Payee::class;

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();

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.

Signature

public function getLocale(): string;

Example

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

ApplicationContext::setLocale()

Sets a locale on an application context.

Signature

public function setLocale($locale): self;

Example

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

ApplicationContext::getShippingPreference()

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

Signature

public function getShippingPreference(): string;

Example

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

ApplicationContext::setShippingPreference()

Sets a shipping preference value on an application context.

Signature

public function setShippingPreference($shipping_preference): self;

Available shipping preference options

const GET_FROM_FILE = 'GET_FROM_FILE';
const NO_SHIPPING = 'NO_SHIPPING';
const SET_PROVIDED_ADDRESS = 'SET_PROVIDED_ADDRESS';

Example

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

ApplicationContext::getLandingPage()

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

Signature

public function getLandingPage(): string;

Example

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

ApplicationContext::setLandingPage()

Sets a landing page value on an application context.

Signature

public function setLandingPage($landing_page): self;

Available landing page options

const LOGIN = 'LOGIN';
const BILLING = 'BILLING';
const NO_PREFERENCE = 'NO_PREFERENCE';

Example

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

ApplicationContext::getUserAction()

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

Signature

public function getUserAction(): string;

Example

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

ApplicationContext::setUserAction()

Sets a user action value on an application context.

Signature

public function setUserAction($user_action): self;

Available user action options

const ACTION_CONTINUE = 'CONTINUE';
const ACTION_PAY_NOW = 'PAY_NOW';

Example

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

ApplicationContext::getReturnUrl()

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

Signature

public function getReturnUrl(): string;

Example

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

ApplicationContext::setReturnUrl()

Sets a return url value on an application context.

Signature

public function setReturnUrl($return_url): self;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->setReturnUrl('https://phpjuice.org/success');
$application_context->getReturnUrl(); // https://phpjuice.org/success

ApplicationContext::getCancelUrl()

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

Signature

public function getCancelUrl(): string;

Example

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

ApplicationContext::setCancelUrl()

Sets a cancel url value on an application context.

Signature

public function setCancelUrl($cancel_url): self;

Example

$application_context = ApplicationContext::create('PHPJuice', 'en-US');
$application_context->setCancelUrl('https://phpjuice.org/cancel');
$application_context->getCancelUrl(); // https://phpjuice.org/cancel

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