PHPackages                             square/square - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. square/square

ActiveLibrary[API Development](/categories/api)

square/square
=============

Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.

45.0.0.20260122(2mo ago)793.4M—1.7%5520MITPHPPHP ^8.1CI passing

Since Jun 10Pushed 2mo ago17 watchersCompare

[ Source](https://github.com/square/square-php-sdk)[ Packagist](https://packagist.org/packages/square/square)[ Docs](https://squareup.com/developers)[ RSS](/packages/square-square/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (21)Versions (179)Used By (20)

Square PHP SDK
==============

[](#square-php-sdk)

[![fern shield](https://camo.githubusercontent.com/7cfaf5314e1b5d061cd50428e99e60c0cab6c3fa9b20995623b13f52f7a68778/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2546302539462538432542462d53444b25323067656e65726174656425323062792532304665726e2d627269676874677265656e)](https://github.com/fern-api/fern)[![php shield](https://camo.githubusercontent.com/c6935ea725f448fdb79c5a9a86bf2f898610c8bf44028a3192176889b47cdba6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d7061636b61676973742d70696e6b)](https://packagist.org/packages/square/square)

The Square PHP library provides convenient access to the Square API from PHP.

Requirements
------------

[](#requirements)

Use of the Square PHP SDK requires:

- PHP ^8.1

Installation
------------

[](#installation)

Use Composer to configure and install to configure and install the Square PHP SDK:

```
composer require square/square
```

Usage
-----

[](#usage)

```
use Square\SquareClient;
use Square\Payments\Requests\CreatePaymentRequest;
use Square\Types\CashPaymentDetails;
use Square\Types\Currency;
use Square\Types\Money;

$square = new SquareClient();
$response = $square->payments->create(
    request: new CreatePaymentRequest(
        [
            'idempotencyKey' => '4935a656-a929-4792-b97c-8848be85c27c',
            'sourceId' => 'CASH',
            'amountMoney' => new Money([
                'amount' => 100,
                'currency' => Currency::Usd->value
            ]),
            'tipMoney' => new Money([
                'amount' => 50,
                'currency' => Currency::Usd->value
            ]),
            'cashDetails' => new CashPaymentDetails([
                'buyerSuppliedMoney' => new Money([
                    'amount' => 200,
                    'currency' => Currency::Usd->value
                ])
            ]),
        ],
    )
);
```

Instantiation
-------------

[](#instantiation)

To get started with the Square SDK, instantiate the `SquareClient` class as follows:

```
use Square\SquareClient;

$square = new SquareClient("SQUARE_TOKEN");
```

Alternatively, you can omit the token when constructing the client. In this case, the SDK will automatically read the token from the `SQUARE_TOKEN` environment variable:

```
use Square\SquareClient;

$square = new SquareClient(); // Token is read from the SQUARE_TOKEN environment variable.
```

### Environment and Custom URLs

[](#environment-and-custom-urls)

This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL.

#### Environments

[](#environments)

```
use Square\SquareClient;
use Square\Environments;

$square = new SquareClient(options: [
  'baseUrl' => Environments::Production->value // Used by default
]);
```

#### Custom URL

[](#custom-url)

```
use Square\SquareClient;

$square = new SquareClient(options: [
  'baseUrl' => 'https://custom-staging.com'
]);
```

Enums
-----

[](#enums)

This SDK leverages PHP 8.1’s first-class enums to improve type safety and usability. In order to maintain forward compatibility with the API —- where new enum values may be introduced in the future -— we define enum properties as `string` and use `value-of` annotations to specify the corresponding enum type.

### Example Usage

[](#example-usage)

```
use Square\Types\InvoicePaymentRequest;
use Square\Types\InvoiceRequestType;

$paymentRequest = new InvoicePaymentRequest([
    'requestType' => InvoiceRequestType::Balance->value,
    ...
]);
```

### PHPDoc Annotations

[](#phpdoc-annotations)

```
/**
 * @param ?value-of $requestType Optional request type for the invoice.
 */
```

Automatic Pagination
--------------------

[](#automatic-pagination)

List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:

```
use Square\Payments\Requests\ListPaymentsRequest;

$payments = $square->payments->list(
    new ListPaymentsRequest([
        'total' => 100,
    ]),
);

foreach ($payments as $payment) {
    echo sprintf(
        "payment: ID: %s Created at: %s, Updated at: %s\n",
        $payment->getId(),
        $payment->getCreatedAt(),
        $payment->getUpdatedAt(),
    );
}
```

You can also iterate page-by-page:

```
foreach ($payments->getPages() as $page) {
    foreach ($page->getItems() as $payment) {
        echo sprintf(
            "payment: ID: %s Created at: %s, Updated at: %s\n",
            $payment->getId(),
            $payment->getCreatedAt(),
            $payment->getUpdatedAt(),
        );
    }
}
```

Timeouts
--------

[](#timeouts)

Setting a timeout for each individual request is as simple as using the `timeout` request option. Setting a one second timeout for an individual API call looks like the following:

```
$payments = $square->payments->list(
    request: new ListPaymentsRequest([
        'total' => 100,
    ]),
    options: [
        'timeout' = 1.0,
    ],
);
```

Exception Handling
------------------

[](#exception-handling)

When the API returns a non-zero status code, (`4xx` or `5xx` response), a `SquareApiException` will be thrown:

```
use Square\Exceptions\SquareApiException;
use Square\Exceptions\SquareException;

try {
    $square->payments->create(...);
} catch (SquareApiException $e) {
    echo 'Square API Exception occurred: ' . $e->getMessage() . "\n";
    echo 'Status Code: ' . $e->getCode() . "\n";
    echo 'Response Body: ' . $e->getBody() . "\n";
    // Optionally, rethrow the exception or handle accordingly.
}
```

Webhook Signature Verification
------------------------------

[](#webhook-signature-verification)

The SDK provides utility methods that allow you to verify webhook signatures and ensure that all webhook events originate from Square. The `WebhooksHelper.verifySignature` method can be used to verify the signature like so:

```
use Square\Utils\WebhooksHelper;

$isValid = WebhooksHelper.verifySignature(
    requestBody: $requestBody,
    signatureHeader: $headers['x-square-hmacsha256-signature'],
    signatureKey: 'YOUR_SIGNATURE_KEY',
    notificationUrl: 'https://example.com/webhook', // The URL where event notifications are sent.
)
```

Legacy SDK
----------

[](#legacy-sdk)

While the new SDK has a lot of improvements, we at Square understand that it takes time to upgrade when there are breaking changes. To make the migration easier, the new SDK also exports the legacy SDK as `Square\Legacy\...`. Here's an example of how you can use the legacy SDK alongside the new SDK inside a single file:

```
use Square\SquareClient;
use Square\Legacy\SquareClient as LegacySquareClient;

$square = new SquareClient();
$legacyClient = new LegacySquareClient();
```

We recommend migrating to the new SDK using the following steps:

1. Upgrade the package to `^41.0.0`
2. Search and replace all requires and imports from `Square\...` to `Square\Legacy\...`
3. Gradually move over to use the new SDK by importing it from the `Square\...` import.

Advanced
--------

[](#advanced)

### Custom HTTP Client

[](#custom-http-client)

This SDK is built to work with any HTTP client that implements Guzzle’s `ClientInterface`. By default, if no client is provided, the SDK will use Guzzle’s default HTTP client. However, you can pass your own client that adheres to `ClientInterface`:

```
use GuzzleHttp\Client;
use Square\SquareClient;

// Create a custom Guzzle client with specific configuration.
$client = new Client([
    'timeout' => 5.0,
]);

// Pass the custom client when creating an instance of the class.
$square = new SquareClient(options: [
    'client' => $client
]);
```

### Send Additional Properties

[](#send-additional-properties)

All endpoints support sending additional request body properties and query parameters that are not already supported by the SDK. This is useful whenever you need to interact with an unreleased or hidden feature.

For example, suppose that a new feature was rolled out that allowed users to list all deactivated team members. You could set the relevant query parameters like so:

```
use Square\TeamMembers\Requests\SearchTeamMembersRequest;

$teamMembers = $square->teamMembers->search(
    request: new SearchTeamMembersRequest([
        'limit' => 100,
    ]),
    options: [
        'queryParameters' = [
            'status' => 'DEACTIVATED'
        ],
    ],
);
```

### Receive Additional Properties

[](#receive-additional-properties)

Every response type includes the `getAdditionalProperties` method, which returns an `array` that contains any properties in the JSON response that were not specified in the returned class. Similar to the use case for sending additional parameters, this can be useful for API features not present in the SDK yet.

You can access the additional properties like so:

```
$payments = $square->payments->create(...);
$additionalProperties = $payments->getAdditionalProperties();
```

Contributing
------------

[](#contributing)

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!

###  Health Score

70

—

ExcellentBetter than 100% of packages

Maintenance85

Actively maintained with recent releases

Popularity59

Moderate usage in the ecosystem

Community44

Growing community involvement

Maturity83

Battle-tested with a long release history

 Bus Factor4

4 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Recently: every ~36 days

Total

77

Last Release

77d ago

Major Versions

40.0.0.20250123 → 41.0.0.202502202025-02-20

41.0.0.20250220 → 42.0.0.202503192025-03-19

42.2.0.20250521 → 43.0.0.202506182025-06-18

43.2.0.20251016 → 44.0.0.202601222026-01-22

44.0.0.20260122 → 45.0.0.202601222026-03-02

PHP version history (6 changes)5.0.0.20200528PHP >=7.1

10.0.0.20210421PHP >=7.2

17.2.0.20220216PHP >=7.2 <8.1

17.3.0.20220316PHP >=7.2 <8.2

26.0.0.20230419PHP ^7.2 || ^8.0

41.0.0.20250220PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/cb2855e537ca0333febcfae98e9a7fc6d9415a06e4505d3f49811577c078d815?d=identicon)[square-developers](/maintainers/square-developers)

![](https://www.gravatar.com/avatar/2e2c3a9a9576e1117216f11c52e51e97155b95706c1834061ea6e96e9c7f4f08?d=identicon)[jessiedlcs](/maintainers/jessiedlcs)

![](https://www.gravatar.com/avatar/e5b80bcd302b9c14f9dbc477b740d0e76fd921200e0b5a40b8af09b3c3ccc9c3?d=identicon)[lindy0820](/maintainers/lindy0820)

![](https://www.gravatar.com/avatar/57ef167d300d6819a089f1f5e495c2233cd893f644faf367145c7526d60eaad8?d=identicon)[xsquared](/maintainers/xsquared)

![](https://www.gravatar.com/avatar/2063239eb488bc2e3e460e4820d80a9f80670c5c010130939fb7d095de0f3e4f?d=identicon)[jffsquare](/maintainers/jffsquare)

---

Top Contributors

[![jessdelacruzsantos](https://avatars.githubusercontent.com/u/32309499?v=4)](https://github.com/jessdelacruzsantos "jessdelacruzsantos (26 commits)")[![fern-api[bot]](https://avatars.githubusercontent.com/in/244756?v=4)](https://github.com/fern-api[bot] "fern-api[bot] (22 commits)")[![joanc-sq](https://avatars.githubusercontent.com/u/86378073?v=4)](https://github.com/joanc-sq "joanc-sq (13 commits)")[![okenshields](https://avatars.githubusercontent.com/u/52800758?v=4)](https://github.com/okenshields "okenshields (10 commits)")[![mikekono](https://avatars.githubusercontent.com/u/2348732?v=4)](https://github.com/mikekono "mikekono (10 commits)")[![jguze](https://avatars.githubusercontent.com/u/2375555?v=4)](https://github.com/jguze "jguze (6 commits)")[![mohsin-sq](https://avatars.githubusercontent.com/u/64042325?v=4)](https://github.com/mohsin-sq "mohsin-sq (6 commits)")[![deanpapastrat](https://avatars.githubusercontent.com/u/4662240?v=4)](https://github.com/deanpapastrat "deanpapastrat (5 commits)")[![square-sdk-deployer](https://avatars.githubusercontent.com/u/33105396?v=4)](https://github.com/square-sdk-deployer "square-sdk-deployer (5 commits)")[![daphnechiu](https://avatars.githubusercontent.com/u/44045645?v=4)](https://github.com/daphnechiu "daphnechiu (5 commits)")[![Barry-Zou](https://avatars.githubusercontent.com/u/89813505?v=4)](https://github.com/Barry-Zou "Barry-Zou (4 commits)")[![eyw520](https://avatars.githubusercontent.com/u/64514273?v=4)](https://github.com/eyw520 "eyw520 (3 commits)")[![fern-support](https://avatars.githubusercontent.com/u/126544928?v=4)](https://github.com/fern-support "fern-support (3 commits)")[![zenmasterjobo](https://avatars.githubusercontent.com/u/16927748?v=4)](https://github.com/zenmasterjobo "zenmasterjobo (2 commits)")[![dotspencer](https://avatars.githubusercontent.com/u/14356561?v=4)](https://github.com/dotspencer "dotspencer (2 commits)")[![Esawyer25](https://avatars.githubusercontent.com/u/25675971?v=4)](https://github.com/Esawyer25 "Esawyer25 (2 commits)")[![gkchestertron](https://avatars.githubusercontent.com/u/5278129?v=4)](https://github.com/gkchestertron "gkchestertron (2 commits)")[![mcurtis-squareup](https://avatars.githubusercontent.com/u/89655685?v=4)](https://github.com/mcurtis-squareup "mcurtis-squareup (2 commits)")[![mihailogajic](https://avatars.githubusercontent.com/u/38126985?v=4)](https://github.com/mihailogajic "mihailogajic (1 commits)")[![jessemartin](https://avatars.githubusercontent.com/u/1626240?v=4)](https://github.com/jessemartin "jessemartin (1 commits)")

---

Tags

sdkapisdksquare

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/square-square/health.svg)

```
[![Health](https://phpackages.com/badges/square-square/health.svg)](https://phpackages.com/packages/square-square)
```

###  Alternatives

[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k22.6M232](/packages/openai-php-client)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

963.1M35](/packages/getbrevo-brevo-php)[mozex/anthropic-php

Anthropic PHP is a supercharged community-maintained PHP API client that allows you to interact with Anthropic API.

46365.1k13](/packages/mozex-anthropic-php)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[deeplcom/deepl-php

Official DeepL API Client Library

2616.2M66](/packages/deeplcom-deepl-php)[swisnl/json-api-client

A PHP package for mapping remote JSON:API resources to Eloquent like models and collections.

211473.2k12](/packages/swisnl-json-api-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)