/int-asaas

name: int-asaas
description: "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."

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",
    "descri