# PHP SDK

The [`sumup-php`](https://github.com/sumup/sumup-php) package is the official PHP SDK for SumUp APIs. It provides service clients for common resources, such as:

- managing merchant accounts
- managing checkouts
- managing customers
- managing payouts
- querying transactions
- managing readers

## Installation

Install with `composer require sumup/sumup-php`.

## Configure Authentication

Set the `SUMUP_API_KEY` environment variable or pass the API key directly to the `SumUp\SumUp` constructor. You can also provide an OAuth access token via `access_token`.

```bash
export SUMUP_API_KEY='your-api-key-here'
```

## Examples

### Online Payment Checkout

```php
<?php

use SumUp\SumUp;
use SumUp\Exception\SDKException;

try {
    $sumup = new SumUp();

    $checkout = $sumup->checkouts->create([
        'merchant_code' => getenv('SUMUP_MERCHANT_CODE'),
        'amount' => 25.00,
        'currency' => 'EUR',
        'checkout_reference' => 'ORDER-1001',
        'description' => 'Online payment via card widget',
    ]);

    echo $checkout->id . PHP_EOL;
    // Return $checkout->id to your webpage so the SumUp card widget can complete the payment.
} catch (SDKException $exception) {
    echo 'SumUp SDK error: ' . $exception->getMessage();
}
```

### Cloud API Checkout

```php
<?php

use SumUp\SumUp;
use SumUp\Exception\SDKException;

try {
    $sumup = new SumUp();

    $merchantCode = getenv('SUMUP_MERCHANT_CODE');
    $readers = $sumup->readers->list($merchantCode)->items ?? [];
    $firstSolo = $readers[0] ?? null;

    if (!$firstSolo) {
        throw new RuntimeException('Pair a Solo reader before using the Cloud API.');
    }

    $payload = [
        'total_amount' => [
            'currency' => 'EUR',
            'minor_unit' => 2,
            'value' => 1500,
        ],
        'affiliate' => [
            'app_id' => getenv('SUMUP_APP_ID'),
            'foreign_transaction_id' => 'solo-' . time(),
            'key' => getenv('SUMUP_AFFILIATE_KEY'),
        ],
        'description' => 'Cloud API checkout',
    ];

    $checkoutResponse = $sumup->readers->createCheckout(
        $merchantCode,
        $firstSolo->id,
        $payload
    );

    echo $checkoutResponse->data['client_transaction_id'] . PHP_EOL;
} catch (SDKException | RuntimeException $exception) {
    echo 'Error: ' . $exception->getMessage();
}
```

## SDK Documentation

For more information read the **[documentation](https://github.com/sumup/sumup-php)**.