PHPackages                             lumensistemas/asaas-laravel - 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. lumensistemas/asaas-laravel

ActiveLibrary[API Development](/categories/api)

lumensistemas/asaas-laravel
===========================

Laravel client for the Asaas payment API

1.2.1(1mo ago)067↑168.7%MITPHPPHP >=8.4

Since Mar 9Pushed 1mo agoCompare

[ Source](https://github.com/lumensistemas/asaas-laravel)[ Packagist](https://packagist.org/packages/lumensistemas/asaas-laravel)[ RSS](/packages/lumensistemas-asaas-laravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (10)Versions (7)Used By (0)

ASaaS Laravel Client
====================

[](#asaas-laravel-client)

A typed PHP client for the [Asaas](https://www.asaas.com/) payment API (v3), built for Laravel 12.

Requirements
------------

[](#requirements)

- PHP 8.5+
- Laravel 12

Installation
------------

[](#installation)

```
composer require lumensistemas/asaas-laravel
```

The service provider and `Asaas` facade are registered automatically via Laravel's package discovery.

Publish the config file:

```
php artisan vendor:publish --tag=asaas-config
```

Configuration
-------------

[](#configuration)

Set your API key and environment in `.env`:

```
ASAAS_API_KEY=your_api_key_here
ASAAS_ENVIRONMENT=sandbox   # or production
```

VariableDefaultDescription`ASAAS_API_KEY`*(empty)*Default API key`ASAAS_ENVIRONMENT``sandbox``sandbox` or `production``ASAAS_WEBHOOK_TOKEN`*(empty)*Token for incoming webhook verificationUsage
-----

[](#usage)

### Via facade

[](#via-facade)

```
use LumenSistemas\Asaas\Facades\Asaas;

// Customers
$customer = Asaas::customers()->find('cus_000000000001');
$customers = Asaas::customers()->list();

// Payments
$payment = Asaas::payments()->find('pay_000000000001');
$payments = Asaas::payments()->list();

// Webhooks
$webhooks = Asaas::webhooks()->list();
```

### Via dependency injection

[](#via-dependency-injection)

```
use LumenSistemas\Asaas\Asaas;

class MyService
{
    public function __construct(private readonly Asaas $asaas) {}

    public function handle(): void
    {
        $customer = $this->asaas->customers()->find('cus_000000000001');
    }
}
```

### Multi-tenant usage

[](#multi-tenant-usage)

`withApiKey()` returns a new immutable instance scoped to the given key — the singleton in the container is never mutated:

```
$client = Asaas::withApiKey($tenant->asaas_api_key);

$customer = $client->customers()->create($data);
$payment  = $client->payments()->create($data);
```

Resources
---------

[](#resources)

### Customers

[](#customers)

```
use LumenSistemas\Asaas\DTOs\Customer\CreateCustomerData;
use LumenSistemas\Asaas\DTOs\Customer\CustomerListFilters;
use LumenSistemas\Asaas\DTOs\Customer\UpdateCustomerData;
use LumenSistemas\Asaas\Facades\Asaas;

// List
$result = Asaas::customers()->list(new CustomerListFilters(
    name: 'John',
    limit: 20,
));

// Find
$customer = Asaas::customers()->find('cus_000000000001');

// Create
$customer = Asaas::customers()->create(new CreateCustomerData(
    name: 'John Doe',
    cpfCnpj: '24971563792',
    email: 'john@example.com',
    phone: '11999999999',
));

// Update
$customer = Asaas::customers()->update('cus_000000000001', new UpdateCustomerData(
    email: 'newemail@example.com',
));

// Delete / Restore
Asaas::customers()->delete('cus_000000000001');
Asaas::customers()->restore('cus_000000000001');
```

### Payments

[](#payments)

```
use LumenSistemas\Asaas\DTOs\Payment\CreatePaymentData;
use LumenSistemas\Asaas\DTOs\Payment\PaymentDiscount;
use LumenSistemas\Asaas\DTOs\Payment\PaymentFine;
use LumenSistemas\Asaas\DTOs\Payment\PaymentInterest;
use LumenSistemas\Asaas\DTOs\Payment\PaymentListFilters;
use LumenSistemas\Asaas\DTOs\Payment\UpdatePaymentData;
use LumenSistemas\Asaas\Enums\Payment\PaymentBillingType;
use LumenSistemas\Asaas\Enums\Payment\PaymentStatus;
use LumenSistemas\Asaas\Facades\Asaas;

// List with filters
$result = Asaas::payments()->list(new PaymentListFilters(
    customer: 'cus_000000000001',
    status: PaymentStatus::Pending,
    billingType: PaymentBillingType::Pix,
    dueDateGe: '2026-01-01',
    dueDateLe: '2026-12-31',
));

// Find
$payment = Asaas::payments()->find('pay_000000000001');

// Create
$payment = Asaas::payments()->create(new CreatePaymentData(
    customer: 'cus_000000000001',
    billingType: PaymentBillingType::Boleto,
    value: 199.90,
    dueDate: '2026-12-31',
    description: 'Order #1234',
    discount: new PaymentDiscount(value: 10.0, dueDateLimitDays: 5, type: 'PERCENTAGE'),
    fine: new PaymentFine(value: 2.0, type: 'PERCENTAGE'),
    interest: new PaymentInterest(value: 1.0),
));

// Update
$payment = Asaas::payments()->update('pay_000000000001', new UpdatePaymentData(
    value: 249.90,
    description: 'Updated order',
));

// Other actions
Asaas::payments()->delete('pay_000000000001');
Asaas::payments()->restore('pay_000000000001');
Asaas::payments()->refund('pay_000000000001', value: 50.0, description: 'Partial refund');
Asaas::payments()->receiveInCash('pay_000000000001', paymentDate: '2026-03-01');
$status = Asaas::payments()->getStatus('pay_000000000001');
$qr     = Asaas::payments()->getPixQrCode('pay_000000000001');
```

### Webhooks

[](#webhooks)

```
use LumenSistemas\Asaas\DTOs\Webhook\CreateWebhookData;
use LumenSistemas\Asaas\DTOs\Webhook\UpdateWebhookData;
use LumenSistemas\Asaas\Enums\Webhook\WebhookEvent;
use LumenSistemas\Asaas\Enums\Webhook\WebhookSendType;
use LumenSistemas\Asaas\Facades\Asaas;

// List
$result = Asaas::webhooks()->list();

// Find
$webhook = Asaas::webhooks()->find('wbh_000000000001');

// Create
$webhook = Asaas::webhooks()->create(new CreateWebhookData(
    url: 'https://example.com/webhooks/asaas',
    events: [
        WebhookEvent::PaymentReceived,
        WebhookEvent::PaymentConfirmed,
        WebhookEvent::PaymentOverdue,
    ],
    name: 'Payment notifications',
    sendType: WebhookSendType::Sequentially,
    email: 'ops@example.com',
));

// Update
$webhook = Asaas::webhooks()->update('wbh_000000000001', new UpdateWebhookData(
    enabled: false,
));

// Delete
Asaas::webhooks()->delete('wbh_000000000001');

// Clear backoff penalty
Asaas::webhooks()->removeBackoff('wbh_000000000001');
```

Handling incoming webhooks
--------------------------

[](#handling-incoming-webhooks)

### 1. Generate a token

[](#1-generate-a-token)

Use `WebhookSignatureGenerator` to create a secure random token when registering a webhook:

```
use LumenSistemas\Asaas\Webhook\WebhookSignatureGenerator;

$token = (new WebhookSignatureGenerator())->generate(); // 64-char hex string

$webhook = Asaas::webhooks()->create(new CreateWebhookData(
    url: 'https://example.com/webhooks/asaas',
    events: [WebhookEvent::PaymentReceived],
    authToken: $token,
));
```

Store `$token` in your `.env` as `ASAAS_WEBHOOK_TOKEN`.

### 2. Verify incoming requests

[](#2-verify-incoming-requests)

The `asaas.webhook` middleware reads `ASAAS_WEBHOOK_TOKEN` from config and rejects requests whose `asaas-access-token` header doesn't match (HTTP 401):

```
// routes/api.php
Route::post('/webhooks/asaas', WebhookController::class)
    ->middleware('asaas.webhook');
```

Or verify manually:

```
use LumenSistemas\Asaas\Webhook\WebhookSignatureVerifier;

$verifier = new WebhookSignatureVerifier();
if (! $verifier->verify($request->headers->all(), config('asaas.webhook_token'))) {
    abort(401);
}
```

### 3. Handle events

[](#3-handle-events)

```
use LumenSistemas\Asaas\DTOs\Webhook\WebhookEventPayload;
use LumenSistemas\Asaas\Enums\Webhook\WebhookEvent;
use LumenSistemas\Asaas\Webhook\WebhookHandler;

$payload = WebhookEventPayload::fromJson($request->getContent());

$handler = new WebhookHandler();
$handler
    ->on(WebhookEvent::PaymentReceived, function (WebhookEventPayload $p): void {
        // $p->payment is a typed PaymentData instance
    })
    ->on(WebhookEvent::PaymentOverdue, function (WebhookEventPayload $p): void {
        // handle overdue
    })
    ->onAny(function (WebhookEventPayload $p): void {
        // called for every event type
    });

$handler->handle($payload);
```

For payment events (`PAYMENT_*`), `$payload->payment` is a fully typed `PaymentData` instance. For all other event types it is `null`.

Error handling
--------------

[](#error-handling)

API errors (4xx/5xx responses) throw `AsaasApiException`:

```
use LumenSistemas\Asaas\Exceptions\AsaasApiException;

try {
    $customer = Asaas::customers()->find('cus_invalid');
} catch (AsaasApiException $e) {
    $status = $e->status;          // int — HTTP status code
    $errors = $e->errors;          // array — error objects from the API body
}
```

Testing
-------

[](#testing)

```
composer install
./vendor/bin/pest
```

To run integration tests against the real Asaas sandbox API:

```
export ASAAS_TEST_API_KEY="your_sandbox_key"
./vendor/bin/pest --testsuite=Integration
```

### Webhook integration tests

[](#webhook-integration-tests)

Webhook delivery tests require a public URL that Asaas can reach. Use [expose](https://expose.dev) (already in `require-dev`) to tunnel to the local test server.

**Step 1 — Start the webhook server** (in a separate terminal):

```
composer webhook:serve
# or with a custom port:
ASAAS_WEBHOOK_SERVER_PORT=9876 composer webhook:serve
```

**Step 2 — Expose it publicly** (in another terminal):

```
expose share http://localhost:9876
# Note the generated HTTPS URL, e.g. https://abc123.sharedwithexpose.com
```

**Step 3 — Export environment variables and run**:

```
export ASAAS_TEST_API_KEY="your_sandbox_key"
export ASAAS_WEBHOOK_URL="https://abc123.sharedwithexpose.com"
export ASAAS_WEBHOOK_TOKEN="your_secret_token"   # must match the token used when creating the webhook
./vendor/bin/pest --testsuite=Integration --filter=Webhook
```

The server records every incoming `POST` body to a temp directory. Tests poll `GET http://localhost:PORT/events` until the expected event arrives (up to 30 s). Cleanup is automatic via `afterAll`.

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance90

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 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 ~2 days

Total

6

Last Release

52d ago

PHP version history (2 changes)1.0.0PHP >=8.5

1.1.1PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/dfdf6591a8b2d844569545878fba113e9c8de3d9b9d48f5b25637c6f0353ffbd?d=identicon)[lucasvscn](/maintainers/lucasvscn)

---

Top Contributors

[![lucasvscn](https://avatars.githubusercontent.com/u/3482569?v=4)](https://github.com/lucasvscn "lucasvscn (25 commits)")

---

Tags

apilaravelpaymentAsaas

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lumensistemas-asaas-laravel/health.svg)

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

###  Alternatives

[mollie/laravel-mollie

Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite

3624.1M28](/packages/mollie-laravel-mollie)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[dragon-code/laravel-json-response

Automatically always return a response in JSON format

1118.6k1](/packages/dragon-code-laravel-json-response)

PHPackages © 2026

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