> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Square

> Configure Square for online and card-present subscription billing

# Square

The Square gateway supports online subscription billing via the Square Subscriptions API and Square Web Payments SDK.

## Configuration

```php theme={null}
// config/subscribd.php
'gateways' => [
    'square' => [
        'driver'         => \Pixelworxio\Subscribd\Gateways\SquareGateway::class,
        'access_token'   => env('SQUARE_ACCESS_TOKEN'),
        'application_id' => env('SQUARE_APPLICATION_ID'),
        'location_id'    => env('SQUARE_LOCATION_ID'),
        'webhook_secret' => env('SQUARE_WEBHOOK_SIGNATURE_KEY'),
        'webhook_url'    => env('SQUARE_WEBHOOK_URL'),
        'sandbox'        => env('SQUARE_SANDBOX', false),
    ],
],
```

## Environment variables

```env theme={null}
SQUARE_ACCESS_TOKEN=...
SQUARE_APPLICATION_ID=...
SQUARE_LOCATION_ID=...
SQUARE_WEBHOOK_SIGNATURE_KEY=...
SQUARE_WEBHOOK_URL=https://yourapp.com/subscribd/webhook/square
SQUARE_SANDBOX=false
```

Set `SQUARE_SANDBOX=true` to use the Square sandbox environment.

## Webhooks

Configure a webhook subscription in the [Square Developer Dashboard](https://developer.squareup.com/apps). Set the notification URL to `https://yourapp.com/subscribd/webhook/square` and enable:

* `subscription.created`
* `subscription.updated`
* `subscription.canceled`
* `subscription.expired`
* `invoice.payment_made`
* `invoice.payment_failed`
* `payment.completed`
* `payment.failed`

Copy the **Signature Key** and set it as `SQUARE_WEBHOOK_SIGNATURE_KEY`.

## Limitations

* `interval_count` must be `1`. Square does not support billing cycles with `interval_count > 1`. Subscribd throws `SubscriptionException` if you attempt to create a subscription on a plan with `interval_count > 1` using this gateway.
* Trial extension is not supported natively. `ExtendTrial` updates the local `trial_ends_at` only.
* Proration is handled by Subscribd's built-in `ProrationEngine`.
* Pausing is not supported natively. Subscribd updates the local status only.

## Next steps

* **[Custom Gateways](/gateways/custom)** — Build your own gateway driver
* **[Webhooks](/advanced/webhooks)** — Full webhook reference