leopaulo88/asaas-sdk-laravel

Laravel SDK for Asaas payment gateway integration

v0.1.0-alpha 2025-07-20 01:42 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0||^11.0||^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3||^2.0
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0

MIT

• Leanderson Paulo

• payment
• sdk
• gateway
• laravel
• Asaas

README

A modern, type-safe Laravel SDK for the Asaas payment gateway. This package provides an elegant way to interact with the Asaas API using typed entities, automatic data hydration, and Laravel-style fluent interfaces.

Features

• ✨ Type-safe entities with full IDE support
• 🔄 Automatic data hydration between arrays and objects
• 🎯 Fluent interface for building requests
• 📦 Laravel integration with service providers and facades
• 🧪 Comprehensive test coverage
• 📚 Detailed documentation
• 🛡️ Built-in error handling and validation

Installation

Install the package via Composer:

composer require leopaulo88/asaas-sdk-laravel

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag="asaas-sdk-laravel-config"

This will create a config/asaas.php file:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Asaas API Configuration
    |--------------------------------------------------------------------------
    */

    'api_key' => env('ASAAS_API_KEY'),
    
    'environment' => env('ASAAS_ENVIRONMENT', 'sandbox'), // 'sandbox' or 'production'
    
    'timeout' => env('ASAAS_TIMEOUT', 30),
    
    'retry_attempts' => env('ASAAS_RETRY_ATTEMPTS', 3),
];

Environment Variables

Add the following variables to your .env file:

ASAAS_API_KEY=your_api_key_here
ASAAS_ENVIRONMENT=sandbox

Using Different API Keys

You can use different API keys for specific operations using the withApiKey() method:

use Leopaulo88\Asaas\Facades\Asaas;

// Use default API key from config
$customer = Asaas::customers()->create($data);

// Use a different API key for specific operation
$payment = Asaas::withApiKey('different_api_key_here')
    ->payments()
    ->create($paymentData);

// Use different API key with different environment
$subscription = Asaas::withApiKey('production_api_key', 'production')
    ->subscriptions()
    ->create($subscriptionData);

Multi-Tenant Usage

For multi-tenant applications where each tenant has their own Asaas account:

class TenantPaymentService
{
    public function createPaymentForTenant(int $tenantId, array $paymentData)
    {
        $tenant = Tenant::find($tenantId);
        
        return Asaas::withApiKey($tenant->asaas_api_key, $tenant->asaas_environment)
            ->payments()
            ->create($paymentData);
    }
    
    public function listTenantCustomers(int $tenantId)
    {
        $tenant = Tenant::find($tenantId);
        
        return Asaas::withApiKey($tenant->asaas_api_key)
            ->customers()
            ->list();
    }
}

Quick Start

Using the Facade

use Leopaulo88\Asaas\Facades\Asaas;

// Create a customer
$customer = Asaas::customers()->create([
    'name' => 'John Doe',
    'email' => '[e-mail]',
    'cpfCnpj' => '12345678901'
]);

// Create a payment
$payment = Asaas::payments()->create([
    'customer' => $customer->id,
    'billingType' => 'BOLETO',
    'value' => 100.50,
    'dueDate' => '2025-12-31'
]);

Using Dependency Injection

use Leopaulo88\Asaas\Asaas;

class PaymentService 
{
    public function __construct(
        private Asaas $asaas
    ) {}
    
    public function createPayment(array $data)
    {
        return $this->asaas->payments()->create($data);
    }
}

Available Resources

Resource	Description	Documentation
Customers	Manage customers	Customer Resource
Payments	Handle payments and charges	Payment Resource
Subscriptions	Manage recurring subscriptions	Subscription Resource
Credit Cards	Tokenize credit cards	Credit Card Resource
Accounts	Account management	Account Resource

Entity Usage Patterns

All entities in this SDK support multiple instantiation patterns:

1. Using new Constructor

use Leopaulo88\Asaas\Entities\Customer\CustomerCreateEntity;

$customer = new CustomerCreateEntity(
    name: 'John Doe',
    email: '[e-mail]',
    cpfCnpj: '12345678901'
);

2. Using make() Static Method

$customer = CustomerCreateEntity::make()
    ->name('John Doe')
    ->email('[e-mail]')
    ->cpfCnpj('12345678901');

3. Using fromArray() Static Method

$customer = CustomerCreateEntity::fromArray([
    'name' => 'John Doe',
    'email' => '[e-mail]',
    'cpfCnpj' => '12345678901'
]);

Complete Entity Reference

Customer Entities

• CustomerCreateEntity - For creating customers
• CustomerUpdateEntity - For updating customers
• CustomerResponse - API response entity

Payment Entities

• PaymentCreate - For creating payments
• PaymentUpdate - For updating payments
• PaymentResponse - API response entity
• PaymentCreditCard - For credit card payments
• BillingInfoResponse - Billing information response

Subscription Entities

• SubscriptionCreate - For creating subscriptions
• SubscriptionUpdate - For updating subscriptions
• SubscriptionResponse - API response entity
• SubscriptionUpdateCreditCard - For updating subscription credit cards

Credit Card Entities

• CreditCardTokenCreate - For tokenizing credit cards
• CreditCardTokenResponse - Token response entity

Common Entities

• CreditCard - Credit card information
• CreditCardHolderInfo - Cardholder information
• Discount - Discount configuration
• Fine - Fine configuration
• Interest - Interest configuration
• Split - Payment splitting
• Deleted - Deletion confirmation
• Refund - Refund information

List and Response Entities

• ListResponse - Paginated list responses
• AccountResponse - Account information response

Error Handling

The SDK provides specific exceptions for different error scenarios:

use Leopaulo88\Asaas\Exceptions\{
    AsaasException,
    BadRequestException,
    UnauthorizedException,
    NotFoundException
};

try {
    $payment = Asaas::payments()->create($data);
} catch (BadRequestException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
} catch (UnauthorizedException $e) {
    // Handle authentication errors
} catch (NotFoundException $e) {
    // Handle not found errors
} catch (AsaasException $e) {
    // Handle other API errors
}

Testing

The package includes comprehensive test coverage. Run tests with:

composer test

Documentation

• Customer Management
• Payment Processing
• Subscription Management
• Credit Card Tokenization
• Account Information
• Entity Reference
• Error Handling

Contributing

Please see CONTRIBUTING for details on how to contribute.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Leanderson Paulo
• All Contributors

License

The MIT License (MIT). Please see License File for more information.