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

# PHP

> SDK oficial para PHP — aceite pagamentos em segundos com uma integração simples

<Card title="Alpa PHP SDK" icon="php" href="https://github.com/anthonymengottii/alpa-php-sdk">
  SDK oficial da Alpa para PHP. Compatível com PHP 8.1+.
</Card>

## Instalação

<Note>
  Este SDK ainda não está publicado no Packagist. Instale diretamente pelo GitHub:
</Note>

```bash theme={null}
composer config repositories.alpa vcs https://github.com/anthonymengottii/alpa-php-sdk
composer require alpa/alpa-php:dev-main
```

## Uso Rápido

```php theme={null}
<?php
require 'vendor/autoload.php';

use Alpa\AlpaClient;

$alpa = new AlpaClient($_ENV['ALPA_API_KEY']);
```

## Criar Link de Pagamento

```php theme={null}
$link = $alpa->paymentLinks->create([
    'title'       => 'Produto Premium',
    'amountCents' => 9900,
    'description' => 'Acesso vitalício',
]);
```

## Resposta

```php theme={null}
[
    'id'          => 'lnk_abc123',
    'title'       => 'Produto Premium',
    'description' => 'Acesso vitalício',
    'amount'      => 9900,
    'currency'    => 'BRL',
    'status'      => 'ACTIVE',
    'slug'        => 'abc123',
    'createdAt'   => '2026-04-08T00:00:00.000Z',
    'updatedAt'   => '2026-04-08T00:00:00.000Z',
]
```

A URL do checkout é montada a partir do `slug`:

```php theme={null}
$checkoutUrl = $alpa->paymentLinks->getCheckoutUrl($link['slug']);
// https://checkout.usealpa.com/pay/abc123
```

## Criar Transação PIX

```php theme={null}
$tx = $alpa->transactions->create([
    'product'        => 'Curso PHP',
    'paymentMethod'  => 'PIX',
    'amountCents'    => 19900,
    'clientName'     => 'João Silva',
    'clientEmail'    => 'joao@example.com',
    'clientDocument' => '12345678900',
]);

echo $tx['pixCopiaECola'];
```

## Validar Cupom

```php theme={null}
$result = $alpa->coupons->validate('DESCONTO10', 19900);

// $result['valid'], $result['discountCents'], $result['finalAmountCents']
```

## Validação de Webhooks

```php theme={null}
<?php
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!$alpa->verifyWebhookSignature($payload, $signature, $_ENV['ALPA_WEBHOOK_SECRET'])) {
    http_response_code(401);
    exit(json_encode(['error' => 'Assinatura inválida']));
}

$event = json_decode($payload, true);
echo json_encode(['received' => true]);
```

## Tratamento de Erros

```php theme={null}
<?php
use Alpa\Exceptions\AlpaValidationException;
use Alpa\Exceptions\AlpaException;

try {
    $tx = $alpa->transactions->create([...]);
} catch (AlpaValidationException $e) {
    echo 'Dados inválidos: ' . $e->getMessage();
} catch (AlpaException $e) {
    echo 'Erro ' . $e->getStatusCode() . ': ' . $e->getMessage();
}
```