Skip to main content
Cobranças comerciais na Conta Padrão (trilho PADRAO), para contas PF ou PJ verificadas. Use chave wp_live_... com as permissões abaixo.

​
Base URL e autenticação

O trilho PADRAO vem da API key, não do body. Respostas seguem o envelope padrão.

​
Módulos

Cobrança avulsa ≠ assinatura: POST /billings/create gera um pagamento. POST /subscriptions/create cria recorrência com ciclo fixo.

​
Permissões na API key

Ative na criação da chave (dashboard → Integrações): Lista completa: Permissões · Mapa geral: Rotas da API.

​
PIX: receber vs cobrar

​
Fluxo típico — cobrança avulsa

  1. Cadastre o pagador em /customers/* ou envie customer inline no create.
  2. POST /v1/billings/create com method, amount e customer.
  3. Entregue boleto (bankSlipUrl, digitableLine), PIX (pixCopyPaste), link de débito (invoiceUrl com CARD_DEBIT) ou confirme cartão de crédito.
  4. Acompanhe com GET /v1/billings/get/{id} ou webhooks.
  5. Estorne com POST /v1/billings/refund se necessário.

​
Fluxo típico — assinatura

  1. POST /v1/subscriptions/create com method, amount, cycle, nextDueDate e customer.
  2. Consulte com GET /v1/subscriptions/get/{id} ou liste com filtros.
  3. Cancele a recorrência com POST /v1/subscriptions/cancel/{id}.

​
Clientes

Base de pagadores usada em cobranças e assinaturas. As mesmas rotas servem a Loja.

​
Rotas

No billings/create e subscriptions/create, o objeto customer aceita name, taxId (CPF ou CNPJ), email, phone e id opcional (referência interna).

​
Cobranças avulsas

Pagamento único: boleto, cartão ou PIX comercial.

​
Rotas

​
Métodos (method)

​
Cartão

Fluxo recomendado:
  1. Primeira cobrança: POST /billings/create com method: "CARD_CREDIT", creditCard, creditCardHolderInfo e remoteIp (IP do pagador).
  2. Resposta: guarde data.creditCardToken — é o token para reutilizar.
  3. Próximas cobranças: envie cardToken + remoteIp (sem PAN/CVV).
  4. Alternativa: POST /billings/tokenize-card gera o token sem cobrar; depois use cardToken no create.
Campos de cartão: creditCard (dados do cartão), creditCardHolderInfo (titular). O creditCardToken retornado é reutilizado como cardToken nas próximas cobranças.

​
Débito (CARD_DEBIT)

A Asaas não oferece captura transparente de débito. O fluxo é:
  1. POST /v1/billings/create com method: "CARD_DEBIT" — sem campos de cartão.
  2. Redirecione o pagador para data.invoiceUrl.
  3. Na página da fatura, o pagador paga com cartão de débito.
Não envie creditCard, cardToken ou remoteIp em CARD_DEBIT — a API rejeita com 400.
remoteIp deve ser o IP do comprador, não do seu servidor. Nunca armazene número completo do cartão ou CVV após a transação.

​
Status da cobrança

Detalhes dos campos de resposta: Consultar cobrança.

​
Assinaturas

Cobrança recorrente com ciclo fixo.

​
Rotas

​
Ciclos (cycle)

WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMIANNUALLY, YEARLY.

​
Métodos

BOLETO, CARD_CREDIT ou PIX — para cartão use o mesmo fluxo de Cartão (creditCard + titular na primeira vez, ou cardToken depois).

​
Bureau de crédito

Negativação de inadimplentes e consultas de crédito via bureau integrado à WovePay. Exige conta verificada no trilho PADRAO.

​
Negativação (dunnings)

Fluxo típico:
  1. Tenha uma cobrança em atraso (billings) com o devedor cadastrado.
  2. Opcional: Simular com ?payment={id} para verificar elegibilidade.
  3. Solicitar negativação via multipart/form-data (dados do devedor, endereço e documentos).
  4. Acompanhe com Listar ou Consultar.
Taxa de referência para negativação: R$ 12,90 por solicitação. Campos principais no create: payment (ID da cobrança), type=CREDIT_BUREAU, dados do devedor e documents (arquivo).

​
Relatórios de crédito

Consulta de crédito por CPF/CNPJ vinculada a um cliente cadastrado. Envie customer (ID do cliente em POST /customers/create) e cpfCnpj em POST /serasa/reports/create. Taxa de referência: R$ 19,90.

​
Webhooks

Confirme pagamentos sem polling. Eventos relevantes: payment.created, payment.paid, payment.refunded. Veja Webhooks.

​
Próximos passos

Criar cobrança

Boleto, cartão ou PIX (pagamento único).

Listar assinaturas

Paginação e filtros por status.

Criar assinatura

Plano recorrente com ciclo fixo.

Negativar inadimplente

Bureau de crédito.

Consulta de crédito

Relatório de crédito.