@gusnips/asaas

Unofficial TypeScript SDK for the Asaas payment platform API.

Full coverage of the Asaas API v3 with typed interfaces, domain-based architecture, and proper error handling.

Installation

npm install @gusnips/asaas
# or
yarn add @gusnips/asaas
# or
bun add @gusnips/asaas

Quick Start

import { AsaasClient, AsaasBillingType } from "@gusnips/asaas";

const client = new AsaasClient({
  apiKey: "$your_api_key",
  environment: "sandbox", // or 'production'
});

// Create a customer
const customer = await client.customers.create({
  name: "John Doe",
  cpfCnpj: "24971563792",
  email: "[email protected]",
});

// Create a payment
const payment = await client.payments.create({
  customer: customer.id,
  billingType: AsaasBillingType.PIX,
  value: 100.0,
  dueDate: "2025-12-15",
});

// Get PIX QR code
const pixQr = await client.payments.getPixQrCode(payment.id);

Modules

| Module | Access | Description | |--------|--------|-------------| | Customers | client.customers | Customer CRUD, restore, list with filters | | Payments | client.payments | Charges, refunds, status, PIX QR, boleto, credit card | | Subscriptions | client.subscriptions | Recurring billing management | | Installments | client.installments | Installment payments | | Payment Links | client.paymentLinks | Shareable payment links | | Transfers | client.transfers | Bank transfers, PIX, internal | | PIX | client.pix | Address keys, QR codes, transactions | | Finance | client.finance | Balance, extract, statistics | | Invoices | client.invoices | Nota Fiscal (NFS-e) management | | Bills | client.bills | Bill payments (boletos de terceiros) | | Anticipations | client.anticipations | Receivable anticipation | | Webhooks | client.webhooks | Webhook configuration | | Accounts | client.accounts | Sub-accounts (White Label) | | Payment Dunnings | client.paymentDunnings | Debt recovery (Serasa) | | Notifications | client.notifications | Notification settings | | Mobile Recharges | client.mobilePhoneRecharges | Cell phone top-ups |

Usage Examples

Payments

// List payments with filters
const { data: payments, hasMore } = await client.payments.list({
  customer: "cus_xxx",
  status: AsaasPaymentStatus.PENDING,
  "dueDate[ge]": "2025-01-01",
  limit: 50,
});

// Refund a payment (full or partial)
await client.payments.refund("pay_xxx", 50.0, "Partial refund");

// Confirm cash receipt
await client.payments.receiveInCash("pay_xxx", "2025-06-01", 100.0);

Subscriptions

import { AsaasSubscriptionCycle } from "@gusnips/asaas";

const subscription = await client.subscriptions.create({
  customer: "cus_xxx",
  billingType: AsaasBillingType.CREDIT_CARD,
  cycle: AsaasSubscriptionCycle.MONTHLY,
  value: 49.9,
  nextDueDate: "2025-07-01",
});

// List subscription payments
const { data: payments } = await client.subscriptions.listPayments(subscription.id);

Transfers

// Transfer via PIX key
const transfer = await client.transfers.create({
  value: 500.0,
  pixAddressKey: "[email protected]",
  description: "Payment to supplier",
});

// Transfer to bank account
const bankTransfer = await client.transfers.create({
  value: 1000.0,
  operationType: AsaasTransferType.TED,
  bankAccount: {
    bank: { code: "237" },
    ownerName: "Jane Doe",
    cpfCnpj: "12345678901",
    agency: "1234",
    account: "567890",
    accountDigit: "1",
  },
});

Finance

// Get account balance
const { balance } = await client.finance.getBalance();

// Get financial extract
const { data: transactions } = await client.finance.getExtract({
  startDate: "2025-01-01",
  finishDate: "2025-01-31",
});

Webhooks

import { AsaasWebhookSendType } from "@gusnips/asaas";

await client.webhooks.create({
  name: "Payment Events",
  url: "https://myapp.com/webhooks/asaas",
  email: "[email protected]",
  enabled: true,
  interrupted: false,
  apiVersion: 3,
  authToken: "your_auth_token_min_32_chars_long_here",
  sendType: AsaasWebhookSendType.SEQUENTIALLY,
  events: ["PAYMENT_RECEIVED", "PAYMENT_CONFIRMED"],
});

Invoices (Nota Fiscal)

const invoice = await client.invoices.create({
  payment: "pay_xxx",
  serviceDescription: "Software development services",
  observations: "Monthly invoice",
  value: 5000,
  deductions: 0,
  effectiveDate: "2025-06-15",
  municipalServiceName: "Systems analysis and development",
  taxes: {
    retainIss: false,
    iss: 2,
    pis: 0.65,
    cofins: 3,
    csll: 1,
    inss: 0,
    ir: 1.5,
  },
});

// Issue the invoice
await client.invoices.authorize(invoice.id);

Error Handling

The SDK throws AsaasApiError for API errors with structured error information:

import { AsaasApiError } from "@gusnips/asaas";

try {
  await client.payments.create({ /* ... */ });
} catch (error) {
  if (error instanceof AsaasApiError) {
    console.error(`Status: ${error.status}`);
    console.error(`Message: ${error.message}`);
    console.error(`Errors:`, error.errors);
    // error.errors = [{ code: "invalid_customer", description: "..." }]
  }
}

Environments

// Sandbox (for testing)
const sandbox = new AsaasClient({
  apiKey: "$aact_sandbox_key",
  environment: "sandbox",
});

// Production
const production = new AsaasClient({
  apiKey: "$aact_production_key",
  environment: "production",
});

Pagination

All list methods return a paginated response:

interface AsaasApiPaginatedResponse<T> {
  data: T[];
  totalCount: number;
  limit: number;
  offset: number;
  hasMore: boolean;
}

// Iterate through pages
let offset = 0;
let hasMore = true;

while (hasMore) {
  const response = await client.payments.list({ offset, limit: 100 });
  // process response.data
  hasMore = response.hasMore;
  offset += response.data.length;
}

Advanced Usage

Access the underlying Axios instance for custom requests:

const httpClient = client.getHttpClient();
const response = await httpClient.get("/some/custom/endpoint");

Requirements

• TypeScript >= 5.0
• Node.js >= 18 (or Bun/Deno with npm compatibility)

License

MIT