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

# SDK PHP

> Biblioteca oficial PHP para criar pagamentos e verificar webhooks, sem dependências externas.

O [`bob-payments/sdk`](https://github.com/BobPayments/bob-payments-sdk-php) é a forma recomendada de integrar em PHP: zero dependências (usa `ext-curl` e `ext-json`), PHP >= 8.1, analisado com PHPStan level 9.

<Warning>
  Server-side only: a API key `sk_live_`/`sk_test_` é secreta e **nunca** deve ir para o browser.
</Warning>

## Instalação

```bash theme={"system"}
composer require bob-payments/sdk
```

## Cliente

```php theme={"system"}
use BobPayments\BobPaymentsClient;

$bob = new BobPaymentsClient([
    'apiKey' => getenv('BOB_API_KEY'), // sk_live_... ou sk_test_...
    // 'timeoutMs' => 35_000,          // timeout por tentativa
    // 'maxRetries' => 2,              // retries automáticos; 0 desliga
]);

$bob->environment; // 'live' | 'sandbox' — detectado pelo prefixo da chave
```

## Criar uma sessão de checkout (PIX)

Use o checkout hospedado quando quiser que a Bob apresente a tela de pagamento. Hoje o método disponível é PIX; `credit_card` entra quando o cartão for lançado:

```php theme={"system"}
$session = $bob->checkoutSessions->create([
    'amountCents' => 25_000,
    'items' => [['name' => 'Assinatura Pro', 'quantity' => 1, 'unitAmountCents' => 25_000]],
    'paymentMethods' => ['pix'],
    'successUrl' => 'https://loja.example.com/pedido/sucesso',
    'webhookUrl' => 'https://loja.example.com/webhooks/bob',
]);

header('Location: ' . $session['checkoutUrl']);
```

Veja os detalhes dos campos em [Checkout hospedado](/pages/checkout/overview).

## Criar uma cobrança PIX

```php theme={"system"}
$tx = $bob->transactions->create([
    'customer' => [
        'name' => 'João Silva',
        'document' => '12345678901',
        'documentType' => 'CPF',
        'email' => 'joao@example.com',
        'address' => [
            'street' => 'Rua das Flores',
            'streetNumber' => '123',
            'neighborhood' => 'Centro',
            'zipCode' => '01310-100',
            'city' => 'São Paulo',
            'state' => 'SP',
        ],
    ],
    'payment' => ['amountCents' => 10_000, 'product' => 'Assinatura Pro'], // sempre centavos
    'originDomain' => 'loja.example.com',
]);

$tx['pixCode'];        // PIX copia-e-cola (EMV)
$tx['expirationDate']; // quando o PIX expira
$tx['persisted'];      // false = HTTP 202 (reconciliação pendente; PIX válido)
$tx['replayed'];       // true = resposta replayada por idempotência
```

Todo `create` envia um header [`Idempotency-Key`](/pages/idempotency) automaticamente (UUID por chamada, ou o seu via `['idempotencyKey' => "pedido-{$orderId}"]` no segundo argumento), o que torna a chamada segura de repetir — o SDK faz retry com backoff em timeout, falha de rede, 429 e 5xx sem risco de pagamento duplicado.

## Consultas

```php theme={"system"}
$detail = $bob->transactions->get('clx1abc123');

$page = $bob->transactions->list([
    'status' => 'paid',
    'dateFrom' => new DateTimeImmutable('2026-07-01'),
    'limit' => 50,
]); // ['data' => [...], 'meta' => ['total' => ..., 'totalPages' => ...]]

$customers = $bob->customers->list(['email' => 'joao@example.com']);
$customer = $bob->customers->get($customers['data'][0]['id']);
```

## Checkout hospedado

```php theme={"system"}
$session = $bob->checkoutSessions->create([
    'amountCents' => 25_000,
    'successUrl' => 'https://loja.example.com/obrigado',
    'webhookUrl' => 'https://loja.example.com/webhooks/bob', // SDK pede v2 por default
]);

header('Location: ' . $session['checkoutUrl']); // guarde $session['webhookSecret']!

$status = $bob->checkoutSessions->getStatus($session['checkoutToken']);
```

## Webhooks

`Webhooks::constructEvent` verifica a assinatura (v1 e v2, com `hash_equals` e anti-replay) e retorna o evento decodificado:

```php theme={"system"}
use BobPayments\Webhooks;
use BobPayments\Exception\WebhookVerificationException;

$rawBody = file_get_contents('php://input'); // corpo BRUTO — nunca re-serialize
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? null;

try {
    $event = Webhooks::constructEvent($rawBody, $signature, getenv('BOB_WEBHOOK_SECRET'));

    if ($event['event'] === 'transaction.paid') {
        // v2: $event['data']['amountCents'] · v1: $event['data']['amount']
        liberarPedido($event['data']['transactionId']);
    }

    http_response_code(200);
    echo 'ok';
} catch (WebhookVerificationException $e) {
    http_response_code(401);
    echo 'invalid signature';
}
```

Detalhes de payload e assinatura: [Webhooks](/pages/webhooks).

## Tratamento de erros

Toda resposta não-2xx vira `ApiException` com os campos RFC 7807 da API:

```php theme={"system"}
use BobPayments\Exception\ApiException;
use BobPayments\Exception\TimeoutException;

try {
    $bob->transactions->create($params);
} catch (ApiException $e) {
    $e->status;            // 400, 401, 422, 429, 503...
    $e->errorCode;         // 'ERR_INTEGRATION_006', ...
    $e->detail;            // mensagem descritiva
    $e->retryAfterSeconds; // em 429/503 quando a API envia Retry-After
} catch (TimeoutException $e) {
    // excedeu o timeout do cliente
}
```

## Sandbox

Com `sk_test_`, o desfecho no sandbox é controlado pelos centavos do valor — veja [Sandbox](/pages/sandbox):

```php theme={"system"}
$bob->transactions->create([...['payment' => ['amountCents' => 10_001, ...]]]); // expira em ~5s
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="SDK Checkout" icon="credit-card" href="/pages/sdk/checkout">
    Camada de frontend: monte o checkout no seu site com a sessão criada aqui.
  </Card>

  <Card title="Visão geral dos SDKs" icon="cubes" href="/pages/sdk/overview">
    Como as bibliotecas de servidor e o SDK de frontend se encaixam.
  </Card>
</CardGroup>

<Card title="Código-fonte e releases" icon="github" href="https://github.com/BobPayments/bob-payments-sdk-php">
  github.com/BobPayments/bob-payments-sdk-php — CHANGELOG e versões via semantic-release
</Card>