Documentação da API

Comece por aqui

O seu sistema (loja, CRM, ERP ou app) conversa direto com a API do Asaas usando a chave da sua própria conta. A Personal Plug acompanha as mesmas cobranças no painel, com régua, conciliação e relatórios, sem você precisar escolher entre um e outro.

Pegue a chave

Crie uma chave de API no Sandbox para testar.

Faça a primeira cobrança

Cliente, cobrança Pix e QR Code em 3 chamadas.

Receba os webhooks

Dê baixa no seu sistema quando o cliente pagar.

Teste sempre no Sandbox primeiro

Sandbox e produção têm chaves diferentes. Use dados fictícios até a integração estar pronta e só então troque a URL e a chave para produção. Guia de Sandbox

Instituição prestadora: Asaas Gestão Financeira Instituição de Pagamento S.A. - CNPJ 19.540.550/0001-21. A Personal Plug atua exclusivamente como integradora tecnológica e distribuidora da experiência do produto, não sendo instituição financeira ou de pagamento, nem realizando intermediação financeira em nome próprio. O relacionamento financeiro/de pagamentos e a responsabilidade regulatória pelos serviços financeiros são do Asaas, nos termos da regulamentação vigente.

Introdução

Sua chave de API

A chave identifica a sua conta em cada chamada e vai no cabeçalho access_token. Ela é criada na área de integrações da sua conta Asaas, uma para o Sandbox e outra para produção. Como criar e gerenciar chaves

Guarde no servidor

Leia a chave de uma variável de ambiente (ex.: ASAAS_API_KEY). Nunca coloque no site, no app, no Git, em prints ou em logs.

Só para o seu negócio

A chave é da sua conta e serve para cobrar os seus clientes. Não compartilhe nem ofereça a integração a outras empresas.

Precisa de ajuda para liberar a chave ou não encontra a área de integrações? Fale com a equipe.

Introdução

Sandbox e produção

Ambiente	URL base
Sandbox	https://api-sandbox.asaas.com/v3
Produção	https://api.asaas.com/v3

Envie estes cabeçalhos em todas as chamadas:

Content-Type: application/json
User-Agent: nome-do-seu-sistema
access_token: <sua chave de API, lida de variável de ambiente>

O User-Agent é obrigatório para contas criadas a partir de 13/06/2024. Use o nome do seu sistema. Autenticação no Asaas

Guia

Primeira cobrança Pix

Passo 1. Cadastre o cliente uma vez e guarde o id que volta (cus_...).

curl -X POST "https://api-sandbox.asaas.com/v3/customers" \
  -H "Content-Type: application/json" \
  -H "User-Agent: minha-loja" \
  -H "access_token: $ASAAS_API_KEY" \
  -d '{ "name": "Maria Silva", "cpfCnpj": "24971563792", "email": "maria@exemplo.com" }'

Passo 2. Crie a cobrança e busque o QR Code. Use o externalReference com o id do pedido no seu sistema: ele volta em todos os webhooks e facilita a baixa.

# 1. Cria a cobrança Pix
curl -X POST "https://api-sandbox.asaas.com/v3/payments" \
  -H "Content-Type: application/json" \
  -H "User-Agent: minha-loja" \
  -H "access_token: $ASAAS_API_KEY" \
  -d '{ "customer": "cus_000005219613", "billingType": "PIX", "value": 150.00,
        "dueDate": "2026-12-10", "description": "Pedido 1234", "externalReference": "pedido-1234" }'

# 2. Busca o QR Code e o copia e cola
curl "https://api-sandbox.asaas.com/v3/payments/pay_080225913252/pixQrCode" \
  -H "User-Agent: minha-loja" \
  -H "access_token: $ASAAS_API_KEY"

Criar cliente · Criar cobrança · QR Code Pix

Guia

Boleto e cartão

A mesma rota /payments cria boleto e cartão: muda só o billingType. Para cartão, o caminho mais simples é mandar o cliente para a página de pagamento (invoiceUrl): assim o seu sistema nunca recebe nem guarda o número do cartão.

POST https://api-sandbox.asaas.com/v3/payments
{
  "customer": "cus_000005219613",
  "billingType": "BOLETO",
  "value": 890.00,
  "dueDate": "2026-12-05",
  "description": "Aluguel dezembro - Apto 302"
}
// resposta: bankSlipUrl (PDF) e invoiceUrl (página de pagamento)

Vai capturar o cartão no seu próprio checkout? Use a tokenização e siga as regras de segurança do Asaas. Guia de cobranças

Guia

Assinaturas

Para mensalidade, aluguel ou plano recorrente, crie uma assinatura em vez de uma cobrança por mês. O Asaas gera as próximas cobranças sozinho e a régua da Personal Plug cuida dos lembretes.

POST https://api-sandbox.asaas.com/v3/subscriptions
{
  "customer": "cus_000005219613",
  "billingType": "BOLETO",
  "value": 199.90,
  "nextDueDate": "2026-12-10",
  "cycle": "MONTHLY",
  "description": "Plano mensal"
}
// o Asaas gera uma cobrança por ciclo; cada uma chega pelos webhooks

Guia de assinaturas · Criar assinatura

Guia

Webhooks

Webhook é o aviso que o Asaas manda para o seu sistema quando algo muda: cobrança criada, paga, vencida ou estornada. É ele que dá baixa automática, sem ninguém conferir extrato.

Não remova o webhook da Personal Plug

A sua conta já tem um webhook que mantém o painel atualizado. Crie o seu como um webhook a mais; se apagar ou desativar o da Personal Plug, o painel e a régua param de receber os pagamentos.

// app/api/asaas/webhook/route.ts
export async function POST(req: Request) {
  // 1. Confere o token que você definiu ao criar o webhook
  if (req.headers.get("asaas-access-token") !== process.env.ASAAS_WEBHOOK_TOKEN) {
    return new Response("unauthorized", { status: 401 });
  }

  const event = await req.json();

  // 2. Idempotência: o mesmo evento pode chegar mais de uma vez
  if (await jaProcessado(event.id)) return Response.json({ received: true });

  // 3. Dá baixa no seu sistema
  if (event.event === "PAYMENT_RECEIVED" || event.event === "PAYMENT_CONFIRMED") {
    await marcarPedidoComoPago(event.payment.externalReference, event.payment.id);
  }

  await registrarProcessado(event.id);
  return Response.json({ received: true }); // responda 200 rápido
}

Confira o cabeçalho asaas-access-token em toda chamada.
Guarde o id de cada evento e ignore repetidos.
Responda 200 rápido e faça o trabalho pesado depois; erros seguidos pausam a fila.

Guia de webhooks · Criar webhook

Referência

Erros e limites

Código	O que significa
400	Dado inválido. A resposta traz `errors[].description` com o motivo; mostre ao usuário.
401	Chave ausente, errada ou de outro ambiente (chave de Sandbox na URL de produção, por exemplo).
404	O id não existe nesta conta.
429	Muitas chamadas em pouco tempo. Espere e tente de novo, com intervalo crescente.

Códigos HTTP · Limites da API

Referência

Referência completa

A lista completa de rotas, campos e respostas é mantida pelo Asaas e sempre atualizada. Lá você também testa as chamadas no Sandbox direto pelo navegador.

Referência da API

Todas as rotas, com console de teste.

Guia de cobranças

Pix, boleto, cartão e parcelamento.

Split de pagamentos

Divida o valor entre carteiras.

Segurança da chave

IPs autorizados e boas práticas.

Travou em algum passo?

Conte o que o seu sistema precisa fazer e a equipe indica o caminho da integração.

Falar com a equipe Criar minha conta