asaas-kit

v1.8.1

Published

4 months ago

Unofficial Asaas Payment Gateway SDK

0High
0Medium
0Low

asaas asaas sdk asaas-sdk payment gateway sdk asaas gateway asaas-gateway asaas api asaas-api asaas kit asaas-kit payment pagamentos pagamentos gateway

Unofficial Asaas Payment Gateway SDK

A simple sdk made to abstract most of the Asaas payment gateway api requests.

last update: 08/09/2025 Items updated:

Global: Added custom error handler functionality (errorHandler)
Notifications: Added complete notifications API support (update, batch update, get by customer)
Documents: Added complete documents API support (get pending, upload, get file, update file, delete file)
Finance: Added complete finance API support (get balance, payment statistics, split statistics)
Pix: Added Pix API support (static QR code, address key management, transactions)

❗SDK and documentation under development.

Author

Samuel Matos

Reference

Asaas API Manual

Features

[x] Customers (Clientes)
[x] Payments (Cobranças)
[x] Notifications (Notificações)
[x] Installments (Parcelamentos)
[x] Subscriptions (Assinaturas)
[x] Pix (Pix)
[x] Pix Transactions (Transações Pix)
[ ] Payment Links (soon) (Link de pagamentos)
[x] Transfers (Transferências)
[ ] Anticipations (Antecipações)
[ ] Payment Dunnings (Negativações)
[x] Bill (Pagamento de contas)
[ ] Mobile Phone Recharges (Recargas de celular)
[ ] Credit Bureau Report (Consulta Serasa)
[ ] Financial Transactions (Extrato)
[x] Finance (Informações financeiras)
[x] My Account (Informações e personalização da conta)
[x] Invoices (Notas fiscais)
[ ] Fiscal Info (Informações fiscais)
[x] Webhooks (Configurações de Webhooks)
[x] Accounts (Subcontas Asaas)
[x] Documents (Envio de documentos White Label)

Next Steps

We are working on the next features to be included soon in asaas-kit:

[ ] Payment Links: payment link generation
[ ] Anticipations: anticipation requests
[ ] Payment Dunnings: dunning management
[ ] Mobile Phone Recharges: mobile recharge directly via API
[ ] Credit Bureau Report: Serasa credit checks
[ ] Financial Transactions: detailed financial statement
[ ] Fiscal Info: municipal fiscal information

✨ The currently developed feature is: Pix & Pix Transactions.

SDK Documentation

Get Start

Import the package and instantitate a new Client:

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY);

Authentication

Every request to the Asaas API needs an API Key, which must be passed as the first parameter in the constructor. To obtain your API Key, access the Integration Tab in the Account Settings area.

Optionally you can set base url, enable sandbox mode and set sandbox mode base url.

import { AsaasClient } from 'asaas-kit';

//Instantiate a new client
const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  //baseUrl?: string (default: https://api.asaas.com/v3);
  //sandbox?: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //printError?: boolean (default: true); // Determines whether errors will be automatically logged to the console
  //errorHandler?: (action: Action, error: AxiosError) => void; // Custom error handler function
});

Sandbox Mode

To enable Sandbox Mode, pass to the client's constructor, as the second parameter, an object with sandbox information as true. The default sandbox URL is https://sandbox.asaas.com/api/v3

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  sandbox: true;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

Error Logging

By default, the library automatically logs errors to the console when request failures occur. You can disable this behavior by setting the printError option to false:

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  printError: false // Disables automatic error logging to the console
});

Custom Error Handler

You can provide a custom error handler function to handle errors in your own way. The error handler receives the action that failed and the Axios error object:

import { AsaasClient } from 'asaas-kit';
import { Action } from 'asaas-kit';
import { AxiosError } from 'axios';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  errorHandler: (action: Action, error: AxiosError) => {
    // Custom error handling logic
    console.log(`Action ${action} failed:`, error.message);
    
    // You can send errors to external services, log to files, etc.
    // Example: sendToErrorTrackingService(action, error);
  }
});

The custom error handler will be called for every API error, allowing you to implement your own error handling strategy while still maintaining the default behavior of throwing the error.

Customers

Return all customers

Returns customers. Filters can be applied, passing an object with the items allowed in the official documentation.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

//It lists all registered customers and makes a filter by email.
await asaas.customers.list({
  email: "[email protected]"
});

Return customer by ID

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

//It returns a customer by ID.
await asaas.customers.getById("cus_123abcde456");

| Parameter | Type | Description | | :---------- | :--------- | :------------------------------------------ | | id | string | Required. Customer ID |

Notifications

Update notification

Updates an existing notification configuration.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Update a notification
await asaas.notifications.update("not_123abcde456", {
  enabled: true,
  emailEnabledForProvider: true,
  smsEnabledForProvider: false,
  emailEnabledForCustomer: true,
  smsEnabledForCustomer: true,
  phoneCallEnabledForCustomer: false,
  whatsappEnabledForCustomer: false,
  scheduleOffset: 5
});

Update notifications in batch

Updates multiple notifications for a customer in batch.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Update notifications in batch
await asaas.notifications.updateBatch({
  customer: "cus_123abcde456",
  notifications: [
    {
      enabled: true,
      emailEnabledForProvider: true,
      smsEnabledForProvider: false,
      emailEnabledForCustomer: true,
      smsEnabledForCustomer: true,
      phoneCallEnabledForCustomer: false,
      whatsappEnabledForCustomer: false,
      scheduleOffset: 5
    },
    {
      enabled: true,
      emailEnabledForProvider: true,
      smsEnabledForProvider: true,
      emailEnabledForCustomer: false,
      smsEnabledForCustomer: false,
      phoneCallEnabledForCustomer: true,
      whatsappEnabledForCustomer: false,
      scheduleOffset: 1
    }
  ]
});

Get customer notifications

Retrieves all notifications for a specific customer.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get customer notifications
await asaas.notifications.getByCustomer("cus_123abcde456");

Documents

Get pending documents

Retrieves all pending documents that need to be uploaded.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get pending documents
const documents = await asaas.documents.getPending();
console.log('Pending documents:', documents.data);
console.log('Reject reasons:', documents.rejectReasons);

Upload document

Uploads a document for a specific document group.

import { AsaasClient, DocumentType } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Upload a document
const file = new File(['content'], 'document.pdf', { type: 'application/pdf' });
const uploadedDocument = await asaas.documents.upload('doc_group_123', {
  documentFile: file,
  type: DocumentType.IDENTIFICATION
});
console.log('Document uploaded:', uploadedDocument);

Get document file

Retrieves information about an uploaded document.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get document file info
const documentFile = await asaas.documents.getFile('doc_file_123');
console.log('Document file:', documentFile);

| Parameter | Type | Description | | :---------- | :--------- | :------------------------------------------ | | id | string | Required. Document file ID |

Update document file

Updates an uploaded document with a new file.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Update document file
const newFile = new File(['new content'], 'updated_document.pdf', { type: 'application/pdf' });
const updatedDocument = await asaas.documents.updateFile('doc_file_123', {
  documentFile: newFile
});
console.log('Document updated:', updatedDocument);

Delete document file

Removes an uploaded document.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Delete document file
const deleteResult = await asaas.documents.deleteFile('doc_file_123');
console.log('Document deleted:', deleteResult.deleted);

| Parameter | Type | Description | | :---------- | :--------- | :------------------------------------------ | | id | string | Required. Document file ID |

Finance

Get account balance

Retrieves the current account balance.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get account balance
const balance = await asaas.finance.getBalance();
console.log('Account balance:', balance.balance);

Get payment statistics

Retrieves payment statistics with optional filters.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get payment statistics with filters
const statistics = await asaas.finance.getPaymentStatistics({
  customer: 'cus_123abcde456',
  billingType: 'PIX',
  status: 'CONFIRMED',
  anticipated: false,
  'dateCreated[ge]': '2024-01-01',
  'dateCreated[le]': '2024-12-31'
});
console.log('Payment statistics:', statistics);

Get split statistics

Retrieves split payment statistics.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

// Get split statistics
const splitStats = await asaas.finance.getSplitStatistics();
console.log('Split statistics:', splitStats);
console.log('Income:', splitStats.income);
console.log('Value to send:', splitStats.value);

Payments

Return all payments

Returns payments. Filters can be applied, passing an object with the items allowed in the official documentation.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY, {
  // sandbox: boolean;
  //sandboxUrl?: string (default: https://sandbox.asaas.com/api/v3);
  //baseUrl?: string (default: https://api.asaas.com/v3);
});

//It lists all registered payments and makes a filter by customer ID.
await asaas.payments.list({
  customer: "cus_123abcde456"
});

Pix

Create static Pix QR Code

Creates a static Pix QR Code for payments.

import { AsaasClient } from 'asaas-kit';

const asaas = new AsaasClient(process.env.ASAAS_API_KEY);

const qrCode = await asaas.pix.newQrCodeStatic({
  addressKey: 'your-pix-key',
  value: 100.00,
  description: 'Payment for order #123',
  expirationDate: '2025-09-30',
  allowsMultiplePayments: false
});
console.log('Pix QR Code:', qrCode);

Delete static Pix QR Code

Deletes a static Pix QR Code by its ID.

const deleted = await asaas.pix.deleteQrCodeStatic('pix_qrcode_id');
console.log('Deleted:', deleted.deleted);

Create Pix Address Key

Creates a new Pix address key (EVP).

const addressKey = await asaas.pix.createAddressKey({ type: 'EVP' });
console.log('Address Key:', addressKey);

List Pix Address Keys

Lists all Pix address keys.

const keys = await asaas.pix.listAddressKeys();
console.log('Pix Address Keys:', keys.data);

Get Pix Address Key by ID

Retrieves a Pix address key by its ID.

const key = await asaas.pix.getAddressKey('pix_key_id');
console.log('Pix Address Key:', key);

Delete Pix Address Key

Deletes a Pix address key by its ID.

const deletedKey = await asaas.pix.deleteAddressKey('pix_key_id');
console.log('Deleted:', deletedKey);

Pix Transactions

Pix transactions are managed via the pixTransactions property of the client. You can list, get, pay, decode, and cancel Pix transactions.

List transactions

const transactions = await asaas.pixTransactions.list();
console.log('Pix Transactions:', transactions.data);

Get transaction by ID

const transaction = await asaas.pixTransactions.getById('pix_transaction_id');
console.log('Pix Transaction:', transaction);

Pay a QRCode

const payment = await asaas.pixTransactions.payQrCode({
  qrCode: {
    payload: 'your-qrcode-payload',
    value: 100.00,
    description: 'Payment for order #123',
    // changeValue, scheduleDate (optional)
  }
});
console.log('Pix Payment:', payment);

Decode a QRCode

const decoded = await asaas.pixTransactions.decodeQrCode({
  payload: 'your-qrcode-payload'
  // changeValue (optional)
});
console.log('Decoded QRCode:', decoded);

Cancel a transaction

const canceled = await asaas.pixTransactions.cancel('pix_transaction_id');
console.log('Canceled:', canceled);

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Unofficial Asaas Payment Gateway SDK

❗SDK and documentation under development.

Author

Reference

Features

Next Steps

SDK Documentation

Get Start

Authentication

Sandbox Mode

Error Logging

Custom Error Handler

Customers

Return all customers

Return customer by ID

Notifications

Update notification

Update notifications in batch

Get customer notifications

Documents

Get pending documents

Upload document

Get document file

Update document file

Delete document file

Finance

Get account balance

Get payment statistics

Get split statistics

Payments

Return all payments

Pix

Create static Pix QR Code

Delete static Pix QR Code

Create Pix Address Key

List Pix Address Keys

Get Pix Address Key by ID

Delete Pix Address Key

Pix Transactions