carecapay
Login

SDK PHP

SDK oficial para PHP 8.1+: cobranças, saldo e verificação de webhooks. Sem dependências além de ext-curl/ext-json.

Instalação

Composer
composer require carecapay/sdk-php

Beta: enquanto o pacote não está no Packagist, aponte um repositório path/vcs do Composer para carecapay-sdk-php.

A chave secreta é obrigatória

O construtor exige a sua chave secreta (ccp_secret_...), do painel em Chaves de API — chaves vazias ou de outro formato são rejeitadas na hora. O ambiente vem da chave: sandbox ou live.

PHP
use CarecaPay\CarecaPay;

$carecapay = new CarecaPay($_ENV['CARECAPAY_SECRET_KEY']);

Criar e acompanhar cobranças

PHP
$charge = $carecapay->charges->create([
    'amount_cents' => 1990,             // obrigatório, em centavos
    'description' => 'Assinatura',      // opcional
    'method' => 'pix',                  // opcional — hoje é o único disponível (padrão)
    'currency' => 'BRL',                // opcional — hoje é a única disponível (padrão)
    'external_reference' => 'order_42', // opcional — seu id do pedido, só guardamos e devolvemos
]);
echo $charge['qr_code'];             // copia e cola do Pix
echo $charge['qr_code_base64'];      // PNG já renderizado (base64), pronto pra exibir

$carecapay->charges->get($charge['id']);
$carecapay->charges->list(['status' => 'paid', 'limit' => 10]);
$carecapay->balance->get();

// só no sandbox: baixa fake (dispara o webhook também)
$carecapay->charges->simulatePayment($charge['id']);

Verificando webhooks

PHP
use CarecaPay\Webhooks;
use CarecaPay\CarecaPayWebhookException;

try {
    $event = Webhooks::constructEvent(
        payload: file_get_contents('php://input'),   // corpo CRU!
        header: $_SERVER['HTTP_X_CARECAPAY_SIGNATURE'] ?? '',
        secret: $_ENV['CARECAPAY_WEBHOOK_SECRET'],   // ccp_whsec_...
    );
} catch (CarecaPayWebhookException) {
    http_response_code(400);
    exit;
}

if ($event['type'] === 'charge.paid') {
    liberarPedido($event['data']['id']); // deduplique pelo $event['id']
}

Sem o SDK, dá pra comparar o header X-CarecaPay-Token com o segredo diretamente — mais simples, mas sem detecção de corpo adulterado. Veja em Webhooks.

Erros tipados

PHP
use CarecaPay\CarecaPayException;

try {
    $carecapay->charges->create(['amount_cents' => 0]);
} catch (CarecaPayException $err) {
    $err->code;   // "invalid_amount" (estável)
    $err->status; // 400 (0 em falha de rede, code "network_error")
}

Os arrays devolvidos têm exatamente os shapes da API REST (snake_case). Também oficiais: SDK Node.js e SDK Python.