lucenarenato/asaas-php-sdk

ASAAS PHP SDK for Laravel and other PHP applications

v1.0.0 2026-08-11 14:43 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.8
• illuminate/container: ^10.28.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/contracts: ^10.28.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^10.28.0 || ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• captainhook/captainhook: ^5.19
• ciareis/bypass: ^1.1
• friendsofphp/php-cs-fixer: ^3.46
• larastan/larastan: ^2.7
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.9
• orchestra/testbench: ^8.0
• pestphp/pest: ^2.28
• pestphp/pest-plugin-faker: ^2.0
• pestphp/pest-plugin-laravel: ^2.2
• pestphp/pest-plugin-watch: ^2.0
• phpstan/phpstan: ^1.10
• roave/security-advisories: dev-latest

MIT

• Renato Lucena

Published on Packagist.org on 2026-08-11 15:01 UTC

README

Este SDK PHP/Laravel foi criado abstraindo os endpoints do Gateway de Pagamento ASAAS e permite trabalhar com a conta principal e subconta.

🇺🇸 This Laravel Package was created abstracting the Brazilian ASAAS Payment Gateway endpoints. The documentation is available in Portuguese (PT-BR) for ease of use of our targeted developers in Brazil. If you have any questions, please do not hesitate to open an issue or contact the author.

ASAAS API REFERENCE

SYSTEM REQUIREMENTS

• PHP 8.1+ para Laravel 10 e 11
• PHP 8.2+ para Laravel 12
• PHP 8.3+ para Laravel 13
• Composer 2+
• Laravel 10, 11, 12 e 13

Observação: a compatibilidade com cada versão do Laravel segue os requisitos oficiais da própria framework.

OBTENDO A CHAVE DA API ASAAS

Para obter a CHAVE DA API ASAAS, você precisa acessar seu Perfil > Integrações.

INSTALANDO O PACOTE

nota: Se o seu projeto ainda não permite dependências dev, ajuste o composer.json para:

"minimum-stability": "dev",

Agora, você pode instalar a versão estável com o seguinte comando:

composer require lucenarenato/asaas-php-sdk

# ou, se quiser fixar a linha da release atual

composer require lucenarenato/asaas-php-sdk:^1.0

Migração: este pacote substitui o antigo nome lucenarenato/asaas-php.

PUBLICANDO O ARQUIVO DE CONFIGURAÇÃO

Para publicar o arquivo de configuração, basta digitar:

php artisan vendor:publish

# então procure por AsaasPhpServiceProvider e pressione [ENTER]

ALTERANDO O ARQUIVO .ENV

Adicione a constante da CHAVE DA API no seu arquivo .env (com aspas simples):

ASAAS_API_VERSION=v3

ASAAS_SANDBOX_BASE_URL=https://sandbox.asaas.com/api/
ASAAS_SANDBOX_API_KEY='sua-chave-sandbox'
ASAAS_SANDBOX_PIX_KEY=sua-chave-pix-sandbox
ASAAS_SANDBOX_EMAIL_ACCOUNT='seu-email-sandbox'
ASAAS_SANDBOX_WEBHOOK_URL='sua-url-webhook-sandbox'
ASAAS_SANDBOX_WEBHOOK_TOKEN='seu-token-webhook-sandbox-aleatório'

ASAAS_PRODUCTION_BASE_URL=https://api.asaas.com/
ASAAS_PRODUCTION_API_KEY='sua-chave-produção'
ASAAS_PRODUCTION_PIX_KEY=sua-chave-pix-produção
ASAAS_PRODUCTION_EMAIL_ACCOUNT='seu-email-produção'
ASAAS_PRODUCTION_WEBHOOK_URL='sua-url-webhook-produção'
ASAAS_PRODUCTION_WEBHOOK_TOKEN='seu-token-webhook-produção-aleatório'
ASAAS_ALLOW_SUB_ACCOUNTS=false # Quando FALSE, carrega automaticamente a chave da API do .env; do contrário a mesma deverá no código

CONSUMINDO A API ASAAS

NOTA: Todas as respostas estão localizadas no diretório \tests\Fixtures\responses.

CLIENTES - LISTAR

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->list();

dd($response);

CLIENTES - CRIAR

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->create(
    name: 'Teste Usuário',
    cpfCnpj: sanitize("012.345.678-90"),
    email: str("[e-mail]")->lower()->toString(),
    mobilePhone: sanitize("(16) 99222-2222")
);

dd($response);

Para mais campos disponíveis, consulte: https://docs.asaas.com/reference/criar-novo-cliente

CLIENTES - OBTER

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->get(id: 'cus_000005500564');

dd($response);

CLIENTES - ENCONTRAR

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->findByDocument(document: '01234567890');

dd($response);

CLIENTES - ATUALIZAR

Aqui um exemplo de atualização de telefone móvel usando o asaas-php:

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->update(id: 'cus_000005824295', mobilePhone: sanitize("(11) 91111-1111"));

dd($response);

Para mais campos disponíveis, consulte: https://docs.asaas.com/reference/atualizar-cliente-existente

CLIENTE - DELETAR

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->delete(id: 'cus_000005824295');

dd($response);

CLIENTES - RESTAURAR

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->restore(id: 'cus_000005824295',);

dd($response);

CLIENTES - NOTIFICAÇÕES

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->customer()->notifications( id: 'cus_000005824295',);

dd($response);

COBRANÇAS - PAGAMENTO DIRETO COM BOLETO

$data = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\Billet\DirectBilletDTO(
    customerId: 'cus_000005824295',
    value: 19.25,
);

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->directByBillet(DTO: $data);

dd($response, $resource->getBilletUrl($response));

COBRANÇAS - COBRANÇA COM PIX DINÂMICO

$data = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\Pix\DynamicPixDTO(
    customerId: 'cus_000005824295',
    value: 29.99,
);


$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->pixDynamic(DTO: $data);

dd($response, $resource->getPixPaymentData($response));

COBRANÇAS - COBRANÇA COM PIX ESTÁTICO

$data = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\Pix\StaticPixDTO(
    description: 'Pix Estático - Descrição do Teste',
    value: 19.90,
);


$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->pixStatic(DTO: $data); 

dd($response);

COBRANÇAS - COBRANÇA DIRETA COM CARTÃO DE CRÉDITO

$creditCardDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\CreditCardDTO(
    holderName: 'marcelo h almeida',
    number: '5162306219378829',
    expiryMonth: '05',
    expiryYear: '2024',
    ccv: '318',
);

$creditCardHolderInfoDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\CreditCardHolderInfoDTO(
    name: 'Marcelo Henrique Almeida',
    email: '[e-mail]',
    document: '24971563792',
    postalCode: '89223-005',
    addressNumber: '277',
    phone: '4738010919',
    mobilePhone: '47998781877',
    addressComplement: '',
);

$directCreditCardDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\DirectCreditCardDTO(
    customerId: 'cus_000005824295',
    value: 29.99,
    creditCardDTO: $creditCardDTO,
    creditCardHolderInfoDTO: $creditCardHolderInfoDTO,
);

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->directByCreditCard(DTO: $directCreditCardDTO);

dd($response);

COBRANÇAS - COBRANÇA PARCIAL COM CARTÃO DE CRÉDITO

$creditCardDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\CreditCardDTO(
    holderName: 'marcelo h almeida',
    number: '5162306219378829',
    expiryMonth: '05',
    expiryYear: '2024',
    ccv: '318',
);

$creditCardHolderInfoDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\CreditCardHolderInfoDTO(
    name: 'Marcelo Henrique Almeida',
    email: '[e-mail]',
    document: '24971563792',
    postalCode: '89223-005',
    addressNumber: '277',
    phone: '4738010919',
    mobilePhone: '47998781877',
    addressComplement: '',
);

$partialCreditCardDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\Charges\CreditCard\PartialCreditCardDTO(
    customerId: 'cus_000005824295',
    value: 30.00,
    installments: 2,
    installmentValue: 15.00,
    creditCardDTO: $creditCardDTO,
    creditCardHolderInfoDTO: $creditCardHolderInfoDTO,
);


$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->partialCreditCard(DTO: $partialCreditCardDTO);

dd($response);

COBRANÇAS - LISTAR TODAS AS COBRANÇAS

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->all(limit: 10, offset: 0);

dd($response);

COBRANÇAS - DELETAR COBRANÇA

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->delete( id: 'pay_t7b3b3fvioxuqx4e',);

dd($response);

COBRANÇAS - ATUALIZAR COBRANÇA

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->update(
    id: 'pay_j875qgxq8ycbl42i',
    data: [
        'dueDate' => \Carbon\Carbon::now()->addDay()->format('Y-m-d'),
    ],
);

dd($response);

COBRANÇAS - ENVIAR DOCUMENTO PARA COBRANÇA

[POST] https://sandbox.asaas.com/api/v3/payments/{id}/documents

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->uploadDocument(
    id: 'pay_j875qgxq8ycbl42i',
    data: [
        'availableAfterPayment' => true,
        'type' => \LucenaRenato\AsaasPhp\Enums\DocumentTypeEnum::DOCUMENT->value,
        attach(filePath: base_path('packages/lucena-renato/asaas-php/examples/files/test-document.pdf'), fieldName: 'file')),
    ],
);

dd($response);

COBRANÇAS - DELETAR DOCUMENTO ENVIADO PARA COBRANÇA

[DELETE] https://sandbox.asaas.com/api/v3/payments/{id}/documents/{documentId}

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->charge()->deleteDocument( id: 'pay_j875qgxq8ycbl42i', document: '4b052313-ec78-42ae-8374-42a1718aab75',);

dd($response);

SUBCONTAS - CRIAR SUBCONTA

nota: Para conta pessoal usando CPF, o campo birthDate é obrigatório.

$subAccountDto = new \LucenaRenato\AsaasPhp\DataTransferObjects\SubAccounts\SubAccountDTO(
    name: 'Aurora Tecnologia Ltda',
    email: '[e-mail]',
    document: '12.345.678/0001-90',
    companyType: \LucenaRenato\AsaasPhp\Enums\CompanyTypeEnum::INDIVIDUAL,
    mobilePhone: '(11) 98888-7777',
    postalCode: '01310-100',
    address: 'Av. Paulista',
    addressNumber: '1000',
    province: 'Bela Vista',
    subAccountWebhooksDTO: new SubAccountWebhooksDTO(),
    complement: 'Sala 1204',
    site: 'https://www.auroratecnologia.com.br',
);

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->create(DTO: $subAccountDto);

dd($response);

SUBCONTAS - LISTAR SUBCONTAS

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->all()

dd($response);

SUBCONTAS - VERIFICAR DOCUMENTOS PENDENTES

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->checkPendingDocuments()

dd($response);

SUBCONTAS - ENVIAR DOCUMENTOS PENDENTES

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->updateDocument(
    documentId: 'b445460f-4bd5-41cc-8493-712b6e0966f2',
    type: \LucenaRenato\AsaasPhp\Enums\FileDocumentTypeEnum::ENTREPRENEUR_REQUIREMENT,
    documentFile: attach(base_path('packages/lucena-renato/asaas-php/examples/files/test-document.pdf'), 'documentFile'),
)

dd($response);

SUBCONTAS - OBTER DOCUMENTOS ENVIADOS

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->getDocument(documentId: '37106b34-21b6-497f-bb12-87d924b34b16');

dd($response);

SUBCONTAS - ATUALIZAR DOCUMENTO ENVIADO

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->updateDocument(
    documentId: '09f4903c-55fe-452e-bd4e-129780143214',
    documentFile: attach(filePath: base_path('packages/lucena-renato/asaas-php/examples/files/test-document.pdf'), fieldName: 'documentFile'),
);

dd($response);

SUBCONTAS - DELETAR DOCUMENTO ENVIADO

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->subAccount()->deleteDocument( documentId: '09f4903c-55fe-452e-bd4e-129780143214',);

dd($response);

SERVIÇOS BANCÁRIOS - EXTRATO BANCÁRIO

Para ver todos os tipos de extrato bancário, consulte: https://docs.asaas.com/reference/recuperar-extrato

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->bank()->getStatement(
    startDate: now()->subMonths(3)->format('Y-m-d'),
    endDate: now()->format('Y-m-d'),
    offset: 0,
    limit: 10,
);

dd($response);

SERVIÇOS BANCÁRIOS - TRANSFERIR PARA OUTRO BANCO OU CHAVE PIX

$bankAccountDTO = new \LucenaRenato\AsaasPhp\DataTransferObjects\BankServices\BankAccountDTO(
    bankCode: '111',
    accountName: 'Conta do Bradesco Teste',
    ownerName: 'Larissa e Helena Advocacia Ltda',
    document: '01234567890',
    agency: '1111',
    accountNumber: '111111',
    accountDigit: '1',
    bankAccountTypeEnum: \LucenaRenato\AsaasPhp\Enums\BankAccountTypeEnum::CONTA_CORRENTE,
);

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->bank()->otherTransfer(
    value: 10.00,
    operationTypeEnum: \LucenaRenato\AsaasPhp\Enums\OperationTypeEnum::TED,
    bankAccountDTO: $bankAccountDTO,
    pixKey: null,
    pixTypeEnum: null,
    descriptionForPix: null,
    scheduleDate: null, // if null, send immediately!
)

dd($response);

SERVIÇOS BANCÁRIOS - TRANSFERIR PARA CONTA ASAAS

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->bank()->transferToAsaas( walletId: 'a45e79db-36ab-48e2-a278-d438cf14329f', value: 49.90,);

dd($response);

SERVIÇOS BANCÁRIOS - OBTER TRANSFERÊNCIA

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->bank()->getTransfer(transferId: 'be0ae5ad-a93e-4f82-8e12-964e5303627a');

dd($response);

SERVIÇOS BANCÁRIOS - OBTER TODAS AS TRANSFERÊNCIAS

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->bank()->getAllTransfers();

dd($response);

NOTIFICAÇÕES - ATUALIZAR NOTIFICAÇÃO

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->notifications()->update(
    notificationId: 'not_3xd6o7qmx475t333',
    DTO: new \LucenaRenato\AsaasPhp\DataTransferObjects\Notifications\UpdateNotificationDTO(
    enabled: false,
    emailEnabledForProvider: false,
    smsEnabledForProvider: false,
    emailEnabledForCustomer: true,
    smsEnabledForCustomer: true,
    phoneCallEnabledForCustomer: false,
    whatsappEnabledForCustomer: true,
    //scheduleOffset: \LucenaRenato\AsaasPhp\Enums\ScheduleOffsetEnum::FIVE, // only valid to PAYMENT_DUEDATE_WARNING
    ),
);

dd($response);

NOTIFICAÇÕES - ATUALIZAÇÃO EM LOTE DE NOTIFICAÇÕES

$notifications = [
    new \LucenaRenato\AsaasPhp\DataTransferObjects\Notifications\UpdateNotificationDTO(
    notificationId: 'not_3xd6o7qmx475t333',
    enabled: false,
    emailEnabledForProvider: false,
    smsEnabledForProvider: false,
    emailEnabledForCustomer: true,
    smsEnabledForCustomer: true,
    phoneCallEnabledForCustomer: false,
    whatsappEnabledForCustomer: true,
    //scheduleOffset: \LucenaRenato\AsaasPhp\Enums\ScheduleOffsetEnum::FIVE, // only valid to PAYMENT_DUEDATE_WARNING
),
    new \LucenaRenato\AsaasPhp\DataTransferObjects\Notifications\UpdateNotificationDTO(
        notificationId: 'not_622b0ypi6ocj6ss4',
        enabled: false,
        emailEnabledForProvider: false,
        smsEnabledForProvider: false,
        emailEnabledForCustomer: true,
        smsEnabledForCustomer: true,
        phoneCallEnabledForCustomer: false,
        whatsappEnabledForCustomer: true,
        //scheduleOffset: \LucenaRenato\AsaasPhp\Enums\ScheduleOffsetEnum::FIVE, // only valid to PAYMENT_DUEDATE_WARNING
    )
];

$response = \LucenaRenato\AsaasPhp\Facades\AsaasPhp::make()->notifications()->batchUpdate(
     customerId: 'cus_000005824295',
     DTO: $notifications
);

dd($response);

TESTES DE COBERTURA

CORE - Asaas Core Class [] verificar método de listagem [] verificar método de criação [] verificar método de obtenção [] verificar método de busca [] verificar método de atualização [] verificar método de exclusão [] verificar método de restauração [] verificar método de notificações [] verificar método de cobrança [] verificar método de upload

CORE - AsaasPhp Facade [x] verificar se a facade retorna a classe core Asaas.php

CLIENTES [x] Criar Cliente [x] Notificação do Cliente [x] Excluir Cliente [x] Encontrar Cliente por Documento [x] Obter Cliente [x] Listar Cliente [x] Restaurar Cliente [x] Atualizar Cliente

COBRANÇAS - BOLETO [x]

WEBHOOKS

Recomendamos fortemente o https://pipedream.com/ (logado com github) para configurar seu ASAAS_SANDBOX_WEBHOOK_URL.

Para ASAAS_PRODUCTION_WEBHOOK_URL,você pode criar uma rota POST em routes/api.php, por exemplo:

Route::post('/webhooks/asaas', function (Request $request) {
    // your business logic here!
    \Illuminate\Support\Facades\Log::info('/webhooks/asaas', $request->all());
});

CONTRIBUTING

Contribuições são bem vindas. Por favor leia nossas diretrizes de contribuição (em inglês).

CREDITS

By Renato Lucena and contributors.