Asaas payment platform integration via API v3. Manage payments (Pix, boleto, credit card), customers, subscriptions, transfers, balance, and marketplace subaccounts. Use when users ask about payment collection, billing automation, Pix, boleto, subscriptions, or financial transfers via Asaas. Integração Asaas: cobranças, clientes, assinaturas, Pix, boleto.
Integration with Asaas billing platform via REST API v3.
Requires environment variables:
export ASAAS_API_KEY="your_api_key_here"
export ASAAS_SANDBOX="true" # set to "false" for production
$aact_ in productionAuth header used in all requests:
access_token: ${ASAAS_API_KEY}
| 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).
| Value | Description |
|---|---|
BOLETO | Bank slip |
CREDIT_CARD | Credit card |
PIX | Pix instant payment |
UNDEFINED | Any method (customer chooses) |
| 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 |
WEEKLY | BIWEEKLY | MONTHLY | QUARTERLY | SEMIANNUALLY | YEARLY
ACTIVE | INACTIVE | EXPIRED
CPF | CNPJ | EMAIL | PHONE | EVP
MEI | LIMITED | INDIVIDUAL | ASSOCIATION
| 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 |
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 |
curl -s -X GET \
"${BASE_URL}/payments/pay_000000000001" \
-H "access_token: ${ASAAS_API_KEY}"
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 |
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).
curl -s -X GET \
"${BASE_URL}/payments/pay_000000000001/identificationField" \
-H "access_token: ${ASAAS_API_KEY}"
Returns identificationField (digitable line) and barcode.
curl -s -X GET \
"${BASE_URL}/payments/pay_000000000001/installments" \
-H "access_token: ${ASAAS_API_KEY}"
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": "[email protected]",
"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 |
curl -s -X GET \
"${BASE_URL}/customers?name=João&limit=20" \
-H "access_token: ${ASAAS_API_KEY}"
Query params: name, cpfCnpj, limit
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 |
curl -s -X GET \
"${BASE_URL}/subscriptions?customer=cus_000000000001&status=ACTIVE&limit=10" \
-H "access_token: ${ASAAS_API_KEY}"
curl -s -X DELETE \
"${BASE_URL}/subscriptions/sub_000000000001" \
-H "access_token: ${ASAAS_API_KEY}"
curl -s -X GET \
"${BASE_URL}/finance/balance" \
-H "access_token: ${ASAAS_API_KEY}"
curl -s -X POST \
"${BASE_URL}/transfers" \
-H "access_token: ${ASAAS_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"value": 250.00,
"pixAddressKey": "[email protected]",
"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 |
curl -s -X POST \
"${BASE_URL}/accounts" \
-H "access_token: ${ASAAS_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Parceiro Comercial LTDA",
"email": "[email protected]",
"cpfCnpj": "12345678000199",
"companyType": "LIMITED",
"phone": "31999990000",
"postalCode": "30140071",
"address": "Rua das Flores",
"addressNumber": "100",
"province": "Centro"
}'
Required fields: name, email, cpfCnpj
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
access_token (note: lowercase, not Authorization)Bearer prefix$aact_YTU5YTE0M... (production) or similar pattern in sandboxRetry-After header valueworkspace/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 formatsASAAS_SANDBOX=true — sandbox is isolated from production funds