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

# PHP SDK

> Install Tilta's official PHP SDK via Composer to integrate buyer management, credit facilities, orders, and invoices into any PHP app.

Tilta's official PHP SDK wraps the entire public API surface, so you can integrate buyer onboarding, credit facility management, order creation, and invoice capture into any PHP application without writing raw HTTP calls. The SDK handles authentication, request serialisation, and response mapping for you, letting you focus on your business logic instead.

The package is hosted on [Packagist](https://packagist.org/packages/tilta-io/tilta-php-sdk) and the source is available on [GitHub](https://github.com/tilta-io/tilta-php-sdk).

## Requirements

* PHP 7.4 or later
* [Composer](https://getcomposer.org/) (recommended installer)
* A Tilta account with API credentials – contact [support@tilta.io](mailto:support@tilta.io) to request sandbox access

## Installation

Install the SDK using Composer:

```bash theme={null}
composer require tilta-io/tilta-php-sdk
```

Composer adds the package to your `composer.json` and downloads it into your `vendor/` directory. Make sure you require Composer's autoloader in your application if you have not already done so:

```php theme={null}
require_once __DIR__ . '/vendor/autoload.php';
```

<Note>
  Always pin your dependencies to a specific version range in production to avoid unexpected breaking changes. Run `composer update tilta-io/tilta-php-sdk` to pull in the latest compatible release.
</Note>

## Configuration

Before making any API calls, initialise the SDK client with your API key and target environment:

```php theme={null}
<?php

require_once __DIR__ . '/vendor/autoload.php';

use Tilta\Sdk\HttpClient\TiltaClient;

$isSandbox = true; // set to false for production

$client = TiltaClient::create('YOUR_API_KEY', $isSandbox);
```

<Warning>
  Never hard-code your API key in source files. Store it in an environment variable and read it with `getenv('TILTA_API_KEY')` or your framework's configuration system.
</Warning>

## Creating a buyer

The example below shows how to create a new buyer – the first step in most Tilta integrations. A buyer is a business that will receive a credit facility and place orders on your platform.

```php theme={null}
<?php

require_once __DIR__ . '/vendor/autoload.php';

use Tilta\Sdk\HttpClient\TiltaClient;
use Tilta\Sdk\Model\Request\Buyer\CreateBuyerRequestModel;
use Tilta\Sdk\Service\Request\Buyer\CreateBuyerRequest;

$client = TiltaClient::create(getenv('TILTA_API_KEY'), true); // true = sandbox

$requestModel = (new CreateBuyerRequestModel())
    ->setExternalId('buyer_001')
    ->setLegalName('Acme GmbH')
    ->setRegisteredAt('DE');

$service = new CreateBuyerRequest($client);
$buyer   = $service->execute($requestModel);

echo 'Buyer created: ' . $buyer->getId() . PHP_EOL;
```

The `execute` method returns a typed response model. You can call getter methods on the returned object to access fields such as `getId()`, `getStatus()`, and `getLegalName()`.

## Common operations

<AccordionGroup>
  <Accordion title="Requesting a credit facility">
    After a buyer is onboarded, request a credit facility to open their credit line. Tilta's underwriting engine evaluates the request automatically.

    ```php theme={null}
    use Tilta\Sdk\Model\Request\CreditFacility\CreateCreditFacilityRequestModel;
    use Tilta\Sdk\Service\Request\CreditFacility\CreateCreditFacilityRequest;

    $requestModel = (new CreateCreditFacilityRequestModel())
        ->setBuyerExternalId('buyer_001');

    $service  = new CreateCreditFacilityRequest($client);
    $facility = $service->execute($requestModel);

    echo 'Credit limit: ' . $facility->getTotalAmount() . PHP_EOL;
    ```
  </Accordion>

  <Accordion title="Creating an order">
    Create an order when a buyer is ready to make a purchase. The order records the purchase intent and must be authorised before an invoice can be captured.

    ```php theme={null}
    use Tilta\Sdk\Model\Request\Order\CreateOrderRequestModel;
    use Tilta\Sdk\Service\Request\Order\CreateOrderRequest;
    use Tilta\Sdk\Enum\PaymentTermEnum;

    $requestModel = (new CreateOrderRequestModel())
        ->setExternalId('order_001')
        ->setBuyerExternalId('buyer_001')
        ->setAmount(50000)       // amount in cents
        ->setCurrency('EUR')
        ->setPaymentTerm(PaymentTermEnum::DEFER_30D);

    $service = new CreateOrderRequest($client);
    $order   = $service->execute($requestModel);

    echo 'Order status: ' . $order->getStatus() . PHP_EOL;
    ```
  </Accordion>

  <Accordion title="Capturing an invoice">
    Capture an invoice once goods or services have been delivered. This is the legally effective financing step – it triggers merchant payout and starts the buyer's repayment clock.

    ```php theme={null}
    use Tilta\Sdk\Model\Request\Invoice\CreateInvoiceRequestModel;
    use Tilta\Sdk\Service\Request\Invoice\CreateInvoiceRequest;

    $requestModel = (new CreateInvoiceRequestModel())
        ->setExternalId('invoice_001')
        ->setOrderExternalId('order_001')
        ->setAmount(50000)
        ->setCurrency('EUR');

    $service = new CreateInvoiceRequest($client);
    $invoice = $service->execute($requestModel);

    echo 'Invoice captured: ' . $invoice->getId() . PHP_EOL;
    ```
  </Accordion>
</AccordionGroup>

## Error handling

The SDK throws typed exceptions for API errors. Wrap your calls in a try-catch block and handle exceptions according to your application's needs:

```php theme={null}
use Tilta\Sdk\Exception\TiltaException;
use Tilta\Sdk\Exception\Api\ClientException;
use Tilta\Sdk\Exception\Api\ServerException;

try {
    $buyer = $service->execute($requestModel);
} catch (ClientException $e) {
    // 4xx error – check your request data
    echo 'Client error: ' . $e->getErrorCode() . ' – ' . $e->getMessage();
} catch (ServerException $e) {
    // 5xx error – retry with back-off
    echo 'Server error: ' . $e->getMessage();
} catch (TiltaException $e) {
    // Catch-all for other SDK errors
    echo 'Unexpected error: ' . $e->getMessage();
}
```

## Further resources

<CardGroup cols={2}>
  <Card title="GitHub repository" icon="folder-git-2" href="https://github.com/tilta-io/tilta-php-sdk">
    Browse the full source code, open issues, and read the repository README for advanced configuration options and changelog details.
  </Card>

  <Card title="Packagist package" icon="box" href="https://packagist.org/packages/tilta-io/tilta-php-sdk">
    View all published versions, download statistics, and dependency information on Packagist.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference">
    Explore the full REST API documentation that underpins the PHP SDK.
  </Card>

  <Card title="Integration guides" icon="map" href="/docs/introduction">
    Step-by-step guides for buyer onboarding, credit facility setup, and the order-to-invoice flow.
  </Card>
</CardGroup>