---
name: evolution-foundation/int-asaas
source: https://app.decimal.ai/s/evolution-foundation-int-asaas@1/SKILL.md
source_sha256: 9ed2bb742ce7
---

# Asaas Payment Skill

Integration with Asaas billing platform via REST API v3.

## When to use

- Create or query payment charges (Pix, boleto, credit card)
- Manage customers in Asaas
- Create or cancel recurring subscriptions
- Check account balance or initiate Pix transfers
- Generate Pix QR codes or boleto digitable lines
- Create marketplace subaccounts for split payments
- List webhook events for payment confirmations

## Setup

Requires environment variables:

```bash
export ASAAS_API_KEY="your_api_key_here"
export ASAAS_SANDBOX="true"   # set to "false" for production
```

### How to obtain the API key

1. Log in to https://www.asaas.com (or https://sandbox.asaas.com for testing)
2. Go to Account Settings → Integrations → API Key
3. Copy the key — it starts with `$aact_` in production

**Auth header used in all requests:**
```
access_token: ${ASAAS_API_KEY}
```

---

## Base URL

| Environment | URL |
|-------------|-----|
| Production | `https://api.asaas.com/v3` |
| Sandbox | `https://sandbox.asaas.com/api/v3` |

Select based on `ASAAS_SANDBOX` env var. **Default is sandbox (safe).**

---

## Enums

### billingType
| Value | Description |
|-------|-------------|
| `BOLETO` | Bank slip |
| `CREDIT_CARD` | Credit card |
| `PIX` | Pix instant payment |
| `UNDEFINED` | Any method (customer chooses) |

### Payment status
| Value | Description |
|-------|-------------|
| `PENDING` | Awaiting payment |
| `RECEIVED` | Payment received |
| `CONFIRMED` | Payment confirmed |
| `OVERDUE` | Past due date |
| `REFUNDED` | Refunded |
| `RECEIVED_IN_CASH` | Received in cash |
| `REFUND_REQUESTED` | Refund requested |
| `CHARGEBACK_REQUESTED` | Chargeback requested |
| `AWAITING_CHARGEBACK_REVERSAL` | Awaiting chargeback reversal |
| `DUNNING_REQUESTED` | Dunning in progress |
| `DUNNING_RECEIVED` | Dunning received |
| `AWAITING_RISK_ANALYSIS` | Under risk analysis |

### Subscription cycle
`WEEKLY` | `BIWEEKLY` | `MONTHLY` | `QUARTERLY` | `SEMIANNUALLY` | `YEARLY`

### Subscription status
`ACTIVE` | `INACTIVE` | `EXPIRED`

### Pix key type
`CPF` | `CNPJ` | `EMAIL` | `PHONE` | `EVP`

### Company type (subaccounts)
`MEI` | `LIMITED` | `INDIVIDUAL` | `ASSOCIATION`

---

## Format Rules

| Field | Format | Example |
|-------|--------|---------|
| CPF | 11 digits, no dashes | `12345678901` |
| CNPJ | 14 digits, no dashes | `12345678000199` |
| CEP | 8 digits, no dashes | `30140071` |
| Dates | ISO `YYYY-MM-DD` | `2026-04-10` |
| Amounts | BRL float | `99.90` |
| IDs | Prefixed strings | `cus_xxx`, `pay_xxx`, `sub_xxx` |

---

## Payments

### Create payment

```bash
curl -s -X POST \
  "${BASE_URL}/payments" \
  -H "access_token: ${ASAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_000000000001",
    "billingType": "PIX",
    "value": 150.00,
    "dueDate": "2026-04-20",
    "description": "Monthly service fee"
  }'
```

**Body fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customer` | string | yes | Customer ID (`cus_xxx`) |
| `billingType` | string | yes | `BOLETO`, `CREDIT_CARD`, `PIX`, `UNDEFINED` |
| `value` | number | yes | Amount in BRL (must be > 0) |
| `dueDate` | string | yes | Due date `YYYY-MM-DD` |
| `description` | string | no | Payment description |

### Get payment

```bash
curl -s -X GET \
  "${BASE_URL}/payments/pay_000000000001" \
  -H "access_token: ${ASAAS_API_KEY}"
```

### List payments

```bash
curl -s -X GET \
  "${BASE_URL}/payments?customer=cus_000000000001&status=PENDING&limit=10&offset=0" \
  -H "access_token: ${ASAAS_API_KEY}"
```

**Query params:**
| Param | Type | Description |
|-------|------|-------------|
| `customer` | string | Filter by customer ID |
| `status` | string | Filter by payment status |
| `limit` | number | Results per page (default 10) |
| `offset` | number | Pagination offset |

### Get Pix QR code

```bash
curl -s -X GET \
  "${BASE_URL}/payments/pay_000000000001/pixQrCode" \
  -H "access_token: ${ASAAS_API_KEY}"
```

Returns `payload` (copy-paste Pix string) and `encodedImage` (base64 PNG).

### Get boleto

```bash
curl -s -X GET \
  "${BASE_URL}/payments/pay_000000000001/identificationField" \
  -H "access_token: ${ASAAS_API_KEY}"
```

Returns `identificationField` (digitable line) and barcode.

### Get installments

```bash
curl -s -X GET \
  "${BASE_URL}/payments/pay_000000000001/installments" \
  -H "access_token: ${ASAAS_API_KEY}"
```

---

## Customers

### Create customer

```bash
curl -s -X POST \
  "${BASE_URL}/customers" \
  -H "access_token: ${ASAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "cpfCnpj": "12345678901",
    "email": "joao@email.com",
    "phone": "31999990000"
  }'
```

**Body fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | Customer name |
| `cpfCnpj` | string | yes | CPF (11 digits) or CNPJ (14 digits), numbers only |
| `email` | string | no | Valid email address |
| `phone` | string | no | Phone number |

### List customers

```bash
curl -s -X GET \
  "${BASE_URL}/customers?name=João&limit=20" \
  -H "access_token: ${ASAAS_API_KEY}"
```

**Query params:** `name`, `cpfCnpj`, `limit`

---

## Subscriptions

### Create subscription

```bash
curl -s -X POST \
  "${BASE_URL}/subscriptions" \
  -H "access_token: ${ASAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_000000000001",
    "billingType": "BOLETO",
    "value": 99.90,
    "cycle": "MONTHLY",
    "nextDueDate": "2026-05-01",
    "description": "Pro plan"
  }'
```

**Body fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customer` | string | yes | Customer ID |
| `billingType` | string | yes | `BOLETO`, `CREDIT_CARD`, `PIX` |
| `value` | number | yes | Amount per cycle (must be > 0) |
| `cycle` | string | yes | Billing cycle |
| `nextDueDate` | string | yes | First due date `YYYY-MM-DD` |
| `description` | string | no | Subscription description |

### List subscriptions

```bash
curl -s -X GET \
  "${BASE_URL}/subscriptions?customer=cus_000000000001&status=ACTIVE&limit=10" \
  -H "access_token: ${ASAAS_API_KEY}"
```

### Cancel subscription

```bash
curl -s -X DELETE \
  "${BASE_URL}/subscriptions/sub_000000000001" \
  -H "access_token: ${ASAAS_API_KEY}"
```

---

## Financial

### Get balance

```bash
curl -s -X GET \
  "${BASE_URL}/finance/balance" \
  -H "access_token: ${ASAAS_API_KEY}"
```

### Create transfer (Pix out / TED)

```bash
curl -s -X POST \
  "${BASE_URL}/transfers" \
  -H "access_token: ${ASAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 250.00,
    "pixAddressKey": "joao@email.com",
    "pixAddressKeyType": "EMAIL",
    "description": "Supplier payment"
  }'
```

**Body fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | number | yes | Amount in BRL (must be > 0) |
| `pixAddressKey` | string | no | Pix key value |
| `pixAddressKeyType` | string | no | `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP` |
| `description` | string | no | Transfer description |

---

## Marketplace (Split Payments)

### Create subaccount

```bash
curl -s -X POST \
  "${BASE_URL}/accounts" \
  -H "access_token: ${ASAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Parceiro Comercial LTDA",
    "email": "parceiro@empresa.com",
    "cpfCnpj": "12345678000199",
    "companyType": "LIMITED",
    "phone": "31999990000",
    "postalCode": "30140071",
    "address": "Rua das Flores",
    "addressNumber": "100",
    "province": "Centro"
  }'
```

**Required fields:** `name`, `email`, `cpfCnpj`

---

## Utilities

### Get webhook events

```bash
curl -s -X GET \
  "${BASE_URL}/webhook/events?event=PAYMENT_CONFIRMED&limit=10&offset=0" \
  -H "access_token: ${ASAAS_API_KEY}"
```

**Common event types:** `PAYMENT_CONFIRMED`, `PAYMENT_RECEIVED`, `PAYMENT_OVERDUE`, `TRANSFER_CREATED`, `SUBSCRIPTION_CREATED`

---

## Auth Model

- **Type:** API Key
- **Header name:** `access_token` (note: lowercase, not `Authorization`)
- **Header value:** raw API key, no `Bearer` prefix
- **Key format:** `$aact_YTU5YTE0M...` (production) or similar pattern in sandbox

## Rate Limits

- Asaas enforces rate limits per API key
- Default limit: ~120 requests/minute (see official docs for current values)
- Back off on HTTP 429; retry after the `Retry-After` header value
- Full rate limit details: https://docs.asaas.com

## Notes

- This skill is based on the MCP implementation at `workspace/projects/mcp-dev-brasil/packages/payments/asaas/src/index.ts` (mcp-dev-brasil project), which includes Zod validation for CPF/CNPJ, email, CEP, and date formats
- **Always start with `ASAAS_SANDBOX=true`** — sandbox is isolated from production funds
- For credit card payments, tokenization requires additional fields not covered here — see https://docs.asaas.com
- Webhook configuration (registering your endpoint URL) must be done in the Asaas dashboard, not via API