OpenParable
Skip to content
← Back to skills

Int Asaas

Apps & Automation
int-asaas

Int Asaas is an Agent Skill for apps & automation published in the evolution-foundation/evo-nexus repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/evolution-foundation/evo-nexus/blob/HEAD/.claude/skills/int-asaas/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/int-asaas, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

EnvironmentURL
Productionhttps://api.asaas.com/v3
Sandboxhttps://sandbox.asaas.com/api/v3

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


Enums

billingType

ValueDescription
BOLETOBank slip
CREDIT_CARDCredit card
PIXPix instant payment
UNDEFINEDAny method (customer chooses)

Payment status

ValueDescription
PENDINGAwaiting payment
RECEIVEDPayment received
CONFIRMEDPayment confirmed
OVERDUEPast due date
REFUNDEDRefunded
RECEIVED_IN_CASHReceived in cash
REFUND_REQUESTEDRefund requested
CHARGEBACK_REQUESTEDChargeback requested
AWAITING_CHARGEBACK_REVERSALAwaiting chargeback reversal
DUNNING_REQUESTEDDunning in progress
DUNNING_RECEIVEDDunning received
AWAITING_RISK_ANALYSISUnder 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

FieldFormatExample
CPF11 digits, no dashes12345678901
CNPJ14 digits, no dashes12345678000199
CEP8 digits, no dashes30140071
DatesISO YYYY-MM-DD2026-04-10
AmountsBRL float99.90
IDsPrefixed stringscus_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:

FieldTypeRequiredDescription
customerstringyesCustomer ID (cus_xxx)
billingTypestringyesBOLETO, CREDIT_CARD, PIX, UNDEFINED
valuenumberyesAmount in BRL (must be > 0)
dueDatestringyesDue date YYYY-MM-DD
descriptionstringnoPayment 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:

ParamTypeDescription
customerstringFilter by customer ID
statusstringFilter by payment status
limitnumberResults per page (default 10)
offsetnumberPagination 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": "[email protected]",
    "phone": "31999990000"
  }'

Body fields:

FieldTypeRequiredDescription
namestringyesCustomer name
cpfCnpjstringyesCPF (11 digits) or CNPJ (14 digits), numbers only
emailstringnoValid email address
phonestringnoPhone 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:

FieldTypeRequiredDescription
customerstringyesCustomer ID
billingTypestringyesBOLETO, CREDIT_CARD, PIX
valuenumberyesAmount per cycle (must be > 0)
cyclestringyesBilling cycle
nextDueDatestringyesFirst due date YYYY-MM-DD
descriptionstringnoSubscription 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": "[email protected]",
    "pixAddressKeyType": "EMAIL",
    "description": "Supplier payment"
  }'

Body fields:

FieldTypeRequiredDescription
valuenumberyesAmount in BRL (must be > 0)
pixAddressKeystringnoPix key value
pixAddressKeyTypestringnoCPF, CNPJ, EMAIL, PHONE, EVP
descriptionstringnoTransfer 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": "[email protected]",
    "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