PHPackages                             carecapay/sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. carecapay/sdk-php

ActiveLibrary

carecapay/sdk-php
=================

SDK oficial PHP da CarecaPay — cobranças Pix, saldo e verificação de webhooks.

v0.1.1(1mo ago)03MITPHPPHP ^8.1CI failing

Since Jul 21Pushed 1mo agoCompare

[ Source](https://github.com/carecapay/carecapay-sdk-php)[ Packagist](https://packagist.org/packages/carecapay/sdk-php)[ Docs](https://carecapay.com)[ RSS](/packages/carecapay-sdk-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

CarecaPay — SDK PHP
===================

[](#carecapay--sdk-php)

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

Instalação
----------

[](#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)
--------------------------------------------

[](#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
---

[](#uso)

```
$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
]);
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).

Webhooks (recomendado)
----------------------

[](#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

[](#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

[](#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
-----

[](#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
---------------

[](#desenvolvimento)

```
composer install && composer test
```

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance92

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

2

Last Release

40d ago

PHP version history (2 changes)v0.1.0PHP >=8.1

v0.1.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/94905ebce6e5df82306a4a1d9d0b0314ddbdc92a6d2a52e3982f4354a024b644?d=identicon)[Alixame](/maintainers/Alixame)

---

Top Contributors

[![Alixame](https://avatars.githubusercontent.com/u/70243265?v=4)](https://github.com/Alixame "Alixame (14 commits)")

---

Tags

sdkgatewaypagamentospixcarecapay

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/carecapay-sdk-php/health.svg)

```
[![Health](https://phpackages.com/badges/carecapay-sdk-php/health.svg)](https://phpackages.com/packages/carecapay-sdk-php)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)