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

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

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

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:

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

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:

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

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:

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

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:

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

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