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

# PHP SDK

> Type-safe PHP client for the Macropay API — products, checkout, customers and usage billing, with a one-line sandbox switch.

The PHP SDK is a typed client for the Macropay API, so you can wire payments and
billing into Laravel, Symfony or plain PHP without hand-rolling HTTP requests,
auth headers, or pagination.

Because Macropay is your **Merchant of Record**, those calls do more than move
money: we become the seller of record on your customer's statement, remit sales
tax and VAT worldwide so you don't carry the liability, and keep card data inside
a **PCI DSS Level 1 compliant** vault — your server never touches a raw PAN.

## Install

```bash Terminal theme={null}
composer require macropay/sdk
```

Requires PHP 8.1+ (the SDK uses named arguments and `declare(strict_types=1)`).

## Authenticate and make your first call

Build a client with an access token, then call a resource. Use an
**organization access token (OAT)** for server-side integrations — generate one
in the dashboard and load it from the environment rather than hard-coding it.

```php theme={null}
declare(strict_types=1);

require 'vendor/autoload.php';

use Macropay;

$sdk = Macropay\Macropay::builder()
    ->setSecurity($_ENV['MACROPAY_ACCESS_TOKEN'])
    ->build();

// List the organizations this token can access
$responses = $sdk->organizations->list(
    page: 1,
    limit: 10
);

foreach ($responses as $response) {
    if ($response->statusCode === 200) {
        // Iterate pages and handle results
    }
}
```

The client returns a paginated, iterable response — loop with `foreach` and the
SDK fetches subsequent pages for you.

## Sandbox vs. production

Point the SDK at the [sandbox environment](/integrate/sandbox) to test the full
flow against test cards before going live. Just set the server when you build the
client — everything else stays the same:

```php theme={null}
$sdk = Macropay\Macropay::builder()
    ->setServer('sandbox')
    ->setSecurity($_ENV['MACROPAY_ACCESS_TOKEN'])
    ->build();
```

<Tip>
  Sandbox mirrors production, including webhook delivery, so you can verify
  checkout, fulfillment, and signature verification end-to-end. Use a sandbox token
  here — production tokens won't authenticate against the test server.
</Tip>

## What you can build

The same client surfaces the whole Macropay data model. A few starting points:

<CardGroup cols={2}>
  <Card title="Products & checkout" icon="cart-shopping">
    Sell one-time or subscription products through hosted checkout — Macropay
    handles tax, PCI, and the receipt as your Merchant of Record.
  </Card>

  <Card title="Customers & portal" icon="user">
    Manage customers and let them self-serve through the customer portal:
    subscriptions, invoices, refunds, and payment methods.
  </Card>

  <Card title="Usage & AI billing" icon="bolt">
    Meter ingested events and bill by usage, activity, or outcome — ideal for
    AI products and agents billed on the value they deliver.
  </Card>

  <Card title="Webhooks" icon="webhook">
    React to orders, subscriptions, and payouts with signed, verifiable events.
  </Card>
</CardGroup>

## Need help?

Have a question or hit a snag? [Reach the team](mailto:support@macropay.ai) and
we'll point you in the right direction.