int-asaas

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:

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

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

---

Enums

billingType

Payment status

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

---

Payments

Create payment

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:

Get payment

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

List payments

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

Query params:

Get Pix QR code

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

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

Returns identificationField (digitable line) and barcode.

Get installments

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

---

Customers

Create customer

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:

List customers

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

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:

List subscriptions

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

Cancel subscription

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

---

Financial

Get balance

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

Create transfer (Pix out / TED)

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:

---

Marketplace (Split Payments)

Create subaccount

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

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