PHPackages                             eduwinner/asaas-sdk - 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. [API Development](/categories/api)
4. /
5. eduwinner/asaas-sdk

ActiveLibrary[API Development](/categories/api)

eduwinner/asaas-sdk
===================

SDK PHP para integração com o Asaas (incluindo White Label/BaaS)

00PHPCI passing

Since Jun 19Pushed todayCompare

[ Source](https://github.com/eduwinner/asaas-sdk)[ Packagist](https://packagist.org/packages/eduwinner/asaas-sdk)[ RSS](/packages/eduwinner-asaas-sdk/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Asaas SDK PHP (com White Label/BaaS)
====================================

[](#asaas-sdk-php-com-white-labelbaas)

SDK não-oficial para integração com o [Asaas](https://www.asaas.com) em PHP, incluindo suporte completo ao modelo **White Label / Banking as a Service (BaaS)**.

- Cliente PSR-18 para chamadas HTTP (traga seu próprio cliente)
- Tipagem forte (PHP 8.1+)
- Subcontas (White Label)
- Clientes, cobranças, assinaturas, Pix, notas fiscais
- Webhook handler
- Tratamento de erros padronizado

---

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

[](#instalação)

```
composer require eduwinner/asaas-sdk
```

Este SDK não inclui um cliente HTTP concreto — você precisa instalar um compatível com PSR-18. Recomendado:

```
composer require guzzlehttp/guzzle nyholm/psr7
```

---

Configuração
------------

[](#configuração)

```
use AsaasSDK\AsaasClient;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;

$httpClient     = new GuzzleClient();
$requestFactory = new HttpFactory();
$streamFactory  = new HttpFactory();

$asaas = new AsaasClient(
    apiKey: '$aact_SUA_CHAVE_AQUI',
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    sandbox: true, // false em produção
);
```

---

Clientes
--------

[](#clientes)

```
// Criar cliente
$cliente = $asaas->createCustomer([
    'name'     => 'João Silva',
    'cpfCnpj'  => '12345678909',
    'email'    => 'joao@exemplo.com',
    'phone'    => '11999990000',
]);

// Buscar cliente
$cliente = $asaas->getCustomer('cus_000012345678');
```

---

Cobranças
---------

[](#cobranças)

```
// Criar cobrança (boleto, Pix ou cartão)
$cobranca = $asaas->createPayment([
    'customer'    => 'cus_000012345678',
    'billingType' => 'BOLETO', // PIX | CREDIT_CARD | BOLETO
    'value'       => 150.00,
    'dueDate'     => '2025-12-31',
    'description' => 'Plano mensal',
]);

// Buscar cobrança
$cobranca = $asaas->getPayment('pay_000012345678');

// Cancelar cobrança
$asaas->deletePayment('pay_000012345678');
```

---

Pix
---

[](#pix)

```
$qrCode = $asaas->createPixQrCode([
    'addressKey'     => 'sua@chave.pix',
    'description'    => 'Pagamento referente ao pedido #42',
    'value'          => 99.90,
]);
```

---

Assinaturas
-----------

[](#assinaturas)

```
$assinatura = $asaas->createSubscription([
    'customer'    => 'cus_000012345678',
    'billingType' => 'BOLETO',
    'value'       => 49.90,
    'nextDueDate' => '2025-12-01',
    'cycle'       => 'MONTHLY', // WEEKLY | MONTHLY | YEARLY
]);
```

---

Transferências entre Contas
---------------------------

[](#transferências-entre-contas)

```
// Transferir para outra conta Asaas via Wallet ID
$asaas->transfer([
    'value'    => 50.00,
    'walletId' => 'a9b388c9-c16c-409d-900c-e6451c4a17fc',
]);

// Transferir via PIX (chave externa)
$asaas->transfer([
    'value'            => 50.00,
    'pixAddressKey'    => 'destino@email.com',
    'pixAddressKeyType'=> 'EMAIL',
    'description'      => 'Repasse parceiro',
]);

// Listar transferências
$lista = $asaas->listTransfers();

// Com filtros
$lista = $asaas->listTransfers(['dateCreated[ge]' => '2025-01-01']);
```

---

Split de Pagamento
------------------

[](#split-de-pagamento)

Repasse automático no momento da cobrança — basta incluir `split` no payload de `createPayment`:

```
$asaas->createPayment([
    'customer'    => 'cus_000012345678',
    'billingType' => 'PIX',
    'value'       => 100.00,
    'dueDate'     => '2025-12-31',
    'split'       => [
        [
            'walletId'        => 'a9b388c9-c16c-409d-900c-e6451c4a17fc',
            'fixedValue'      => 10.00, // valor fixo, ou:
            // 'percentualValue' => 10, // 10%
        ],
    ],
]);
```

---

Notas Fiscais
-------------

[](#notas-fiscais)

```
$nota = $asaas->createInvoice([
    'payment'        => 'pay_000012345678',
    'serviceDescription' => 'Desenvolvimento de software',
    'observations'   => 'ISS retido na fonte',
]);
```

---

White Label / BaaS — Subcontas
------------------------------

[](#white-label--baas--subcontas)

Use `createSubAccount` para criar uma subconta e `withApiKey` para operar em nome dela:

```
// Criar subconta
$subconta = $asaas->createSubAccount([
    'name'       => 'Empresa Parceira LTDA',
    'cpfCnpj'   => '12345678000195',
    'email'      => 'financeiro@parceira.com',
    'mobilePhone'=> '11999990000',
    'address'    => 'Rua Exemplo, 100',
    'province'   => 'Centro',
    'postalCode' => '01310100',
]);

// Operar com a chave da subconta
$clienteSubconta = $asaas->withApiKey($subconta['apiKey']);

$clienteSubconta->createCustomer([...]);
$clienteSubconta->createPayment([...]);
```

---

Webhooks
--------

[](#webhooks)

Crie um endpoint PHP e use `WebhookHandler` para processar os eventos:

```
use AsaasSDK\WebhookHandler;

$handler = new WebhookHandler();

$handler->handle(function (array $evento) {
    match ($evento['event']) {
        'PAYMENT_RECEIVED'  => processarPagamento($evento['payment']),
        'PAYMENT_OVERDUE'   => notificarAtraso($evento['payment']),
        default             => null,
    };
});
```

> Os payloads recebidos são gravados em `asaas_webhook.log` no diretório raiz da requisição.

---

Tratamento de Erros
-------------------

[](#tratamento-de-erros)

```
use AsaasSDK\Exceptions\AsaasException;
use AsaasSDK\Exceptions\HttpException;

try {
    $cobranca = $asaas->createPayment([...]);
} catch (HttpException $e) {
    // Erro da API (4xx / 5xx)
    echo $e->statusCode;  // ex: 400
    echo $e->getMessage(); // descrição retornada pelo Asaas
} catch (AsaasException $e) {
    // Falha de conexão / rede
    echo $e->getMessage();
}
```

---

Ambientes
---------

[](#ambientes)

AmbienteURL baseSandbox`https://sandbox.asaas.com/api/v3`Produção`https://www.asaas.com/api/v3`Passe `sandbox: true` no construtor para usar o ambiente de testes. Crie sua conta sandbox em [sandbox.asaas.com](https://sandbox.asaas.com).

---

Licença
-------

[](#licença)

MIT

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/56270240?v=4)[eduwinner](/maintainers/eduwinner)[@eduwinner](https://github.com/eduwinner)

---

Top Contributors

[![eduwinner](https://avatars.githubusercontent.com/u/56270240?v=4)](https://github.com/eduwinner "eduwinner (16 commits)")

### Embed Badge

![Health badge](/badges/eduwinner-asaas-sdk/health.svg)

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

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[botman/driver-telegram

Telegram driver for BotMan

93452.6k6](/packages/botman-driver-telegram)[200mph/tnt-express-connect

TNT ExpressConnect (API) client

2228.2k](/packages/200mph-tnt-express-connect)

PHPackages © 2026

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