README

SDK oficial da CarecaPay para PHP: cobranças Pix, saldo e webhooks. Sem dependências além de ext-curl/ext-json (PHP 8.1+).

Instalação

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.

Pré-requisito: a chave privada (obrigatória)

Toda chamada é autenticada pela sua chave secreta (ccp_secret_...), gerada no painel em Chaves de API — ela aparece uma única vez. O construtor exige uma chave privada válida e falha na hora com chave pública, vazia ou de outro formato:

use CarecaPay\CarecaPay;

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

O ambiente vem embutido na chave (ccp_secret_sandbox_... → sandbox, ccp_secret_live_... → produção). Para desenvolvimento local:

$carecapay = new CarecaPay($key, ['base_url' => 'http://localhost:8080']);

Uso

Identificar o pagador é obrigatório — use customer_id (cliente já cadastrado e completo) ou customer inline (cria/completa na hora pelo documento), nunca os dois juntos. Sem nenhum dos dois a API devolve 400 customer_required.

$charge = $carecapay->charges->create([
    'amount_cents' => 1990,             // R$ 19,90 — sempre em centavos, obrigatório
    'description' => 'Assinatura',      // opcional
    'external_reference' => 'order_42', // opcional — seu id do pedido, só guardamos e devolvemos
    'customer' => [
        'name' => 'Fulano de Tal',
        'email' => 'fulano@example.com',
        'phone' => '11999999999',
        'document' => ['type' => 'CPF', 'value' => '111.444.777-35'],
    ],
]);
echo $charge['qr_code'];             // copia e cola do Pix
echo $charge['qr_code_base64'];      // PNG já renderizado (base64), pronto pra exibir

$carecapay->charges->get('txn_...');
$carecapay->charges->list(['status' => 'paid', 'limit' => 10]);
$carecapay->balance->get();          // ['available_cents' => ..., 'pending_cents' => ...]

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

Os arrays devolvidos têm exatamente os shapes da API REST (snake_case).

Clientes

customer na criação da cobrança exige os 4 campos (name, email, phone, document). Pra reaproveitar um cliente já cadastrado (e completo — os 4 campos já preenchidos), use customer_id:

// cliente já cadastrado (precisa já ter name/email/phone salvos)
$carecapay->charges->create(['amount_cents' => 1990, 'customer_id' => 'cust_...']);

// gerenciar clientes diretamente — aqui só o documento é obrigatório
// (o restante pode ser completado depois, ou já na criação da cobrança)
$customer = $carecapay->customers->create([
    'document' => '11144477735',
    'name' => 'Fulano de Tal',
    'email' => 'fulano@example.com',
    'phone' => '11999999999',
]);
$carecapay->customers->get($customer['id']);
$carecapay->customers->list();

Webhooks (recomendado)

Configure sua URL e um segredo no painel (Webhooks). Cada entrega vem com dois mecanismos de verificação.

Com o SDK (recomendado): assinatura verificada em 1 chamada

Webhooks::constructEvent valida o HMAC (rejeita corpo adulterado e entregas antigas) usando o corpo CRU da requisição (php://input):

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']
}
http_response_code(200);

Webhooks::verifySignature($payload, $header, $secret) devolve só o booleano. Entregas com mais de 5 minutos são rejeitadas ($toleranceSeconds ajusta).

Sem SDK / mais simples: comparar o token

Todo POST também traz o segredo cru no header X-CarecaPay-Token. É mais simples, mas não detecta corpo adulterado nem repetição de entrega, então exige HTTPS na sua URL:

if (($_SERVER['HTTP_X_CARECAPAY_TOKEN'] ?? '') !== $_ENV['CARECAPAY_WEBHOOK_SECRET']) {
    http_response_code(401);  // não veio da CarecaPay
    exit;
}

Erros

use CarecaPay\CarecaPayException;

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

Desenvolvimento

composer install && composer test

carecapay / sdk-php

Package info

Security

Statistics