Oferta automática de Pix Automático em assinaturas via API

Assinaturas criadas via API passam a ofertar o Pix Automático ao pagador, sem que você precise alterar a integração de assinaturas que já possui.

📘

Ao concluir este guia, você terá criado uma assinatura apta à oferta automática, identificado a autorização vinculada a ela e configurado o acompanhamento por webhooks.

O objetivo é aumentar a recorrência e a previsibilidade de recebimento das suas assinaturas com Pix, sem criar uma segunda integração.

🚧

Atenção

A oferta automática está disponível para contas elegíveis ao Pix Automático. Assinaturas criadas antes da disponibilização não recebem a oferta. Liberação em produção: 29/10/2026.

Quando utilizar

Utilize esta oferta quando:

  • sua integração cria assinaturas via API com cobrança por Pix, boleto ou "Pergunte ao Cliente";
  • você quer que o pagador possa autorizar o débito automático das próximas cobranças, sem uma nova integração;
  • você quer acompanhar a autorização e os débitos das assinaturas por webhooks.

Antes de começar

Antes de implementar:

  • confirme que a conta está elegível ao Pix Automático: conta aprovada, documentos aprovados, chave Pix cadastrada e recebimentos via Pix ativos;
  • defina se a oferta deve ser feita em todas as assinaturas ou apenas em parte delas, usando o campo pixAutomaticAuthorizationMode;
  • configure os webhooks de eventos para Pix Automático que acompanharão a autorização e as cobranças.

Para entender a diferença entre esta jornada e o Pix Automático com autorização obrigatória, consulte Diferença entre Pix Automático e Assinaturas.

Condições para a assinatura receber a oferta

A oferta é gerada quando todas as condições abaixo são atendidas.

CondiçãoRegra
ContaA conta precisa estar elegível ao Pix Automático. Mudanças de elegibilidade são notificadas pelo evento PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED.
Forma de pagamento (billingType)PIX, BOLETO ou UNDEFINED (exibido como "Pergunte ao Cliente"). Assinaturas com CREDIT_CARD não recebem a oferta.
Periodicidade (cycle)WEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY ou YEARLY. Os ciclos BIWEEKLY e BIMONTHLY não recebem a oferta.
DescontoA assinatura não pode ter desconto (discount) configurado, percentual ou de valor fixo.
Modo de autorizaçãoO campo pixAutomaticAuthorizationMode não pode estar como DISABLED.
Momento da criaçãoApenas assinaturas criadas a partir da disponibilização da funcionalidade.

A oferta é apresentada na cobrança vigente da assinatura. Apenas a cobrança vigente é gerada com QR Code composto: se já existirem outras cobranças criadas, elas mantêm o QR Code avulso. Enquanto a autorização estiver pendente (CREATED), a oferta continua nas próximas cobranças, até a autorização ser ativada ou encerrada pelo evento EXPIRED.

O comportamento da oferta é o mesmo para assinaturas criadas pela interface do Asaas.

Uma assinatura que não atende às condições é criada normalmente, sem autorização de Pix Automático, e suas cobranças seguem como cobranças comuns.

Como funciona

Ao criar uma assinatura apta via API, o Asaas:

  1. cria uma autorização de Pix Automático vinculada à assinatura;
  2. gera a cobrança vigente da assinatura com um QR Code composto, que reúne os dados da cobrança e a location dos dados da recorrência;
  3. depois que o pagador autoriza, envia automaticamente as instruções de pagamento das cobranças seguintes ao banco do pagador.
📘

É a cobrança em aberto da assinatura que carrega a oferta. Na criação, é a primeira cobrança. Se ela for paga sem ativar o Pix Automático ou expirar, a cobrança seguinte passa a ser a vigente e recebe o QR Code composto.

📘

A Jornada 4 é o termo do Regulamento do Pix para o fluxo em que o pagador paga ou agenda uma cobrança com vencimento e, só depois, recebe a oferta de autorizar o Pix Automático. A recorrência do arranjo Pix corresponde, na API do Asaas, à autorização de Pix Automático. Os estados CRIADA, APROVADA, CANCELADA e EXPIRADA correspondem aos status CREATED, ACTIVE, CANCELLED e EXPIRED da autorização.

Oferta e autorização Cobranças seguintes com a autorização ativa
ItemComportamento na sua integração
Request de criação da assinaturaNenhum campo novo é obrigatório. O campo opcional pixAutomaticAuthorizationMode permite desativar a oferta em uma assinatura específica.
QR Code da cobrança vigenteContinua sendo obtido pela fatura ou pelo endpoint de QR Code Pix. Na cobrança vigente, o payload contém a location da recorrência.
AutorizaçãoFica vinculada à assinatura e pode ser consultada pelo filtro subscriptionId na listagem de autorizações.
Cobranças seguintesSe a autorização estiver ativa, são debitadas automaticamente na data de vencimento. Se ela ainda estiver pendente (CREATED), o pagador as paga como cobranças comuns.

Diferença para o Pix Automático com autorização obrigatória

Oferta automática em assinaturas (Jornada 4)Autorização obrigatória (Jornada 3)
Cobrança que carrega a ofertaCobrança vigente, com vencimento, que pode ser paga ou agendadaPagamento imediato
AutorizaçãoOpcional, ofertada depois do pagamento ou agendamentoObrigatória, concedida junto com o pagamento
Como habilitarAutomática em assinaturas aptasConsulte o guia de Implementação do Pix Automático

1. Crie a assinatura

Utilize o mesmo endpoint de Criar nova assinatura: POST /v3/subscriptions. Para receber a oferta, não é preciso enviar nenhum campo novo.

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 89.90,
  "nextDueDate": "2026-12-10",
  "cycle": "MONTHLY",
  "description": "Plano mensal",
  "externalReference": "assinatura-123"
}

Para desativar a oferta nesta assinatura, envie o campo com o valor DISABLED:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 89.90,
  "nextDueDate": "2026-12-10",
  "cycle": "MONTHLY",
  "pixAutomaticAuthorizationMode": "DISABLED"
}
CampoTipoObrigatórioDescrição
pixAutomaticAuthorizationModestringNãoModo de oferta do Pix Automático na assinatura. Valores aceitos: OPTIONAL (padrão) e DISABLED.

Os demais parâmetros seguem a referência de Criar nova assinatura.

A resposta da criação traz o campo pixAutomaticAuthorizationMode com o modo efetivo da assinatura. OPTIONAL indica que a oferta foi gerada; DISABLED indica que não foi, seja por envio explícito ou porque a assinatura é inapta.

Resposta com o campo omitido e assinatura apta:

{
  "object": "subscription",
  "id": "sub_vsqwcqmdykq5tm2l",
  "dateCreated": "2026-11-06",
  "customer": "cus_000009547456",
  "paymentLink": null,
  "value": 10.00,
  "nextDueDate": "2026-12-11",
  "cycle": "WEEKLY",
  "description": null,
  "billingType": "UNDEFINED",
  "deleted": false,
  "status": "ACTIVE",
  "externalReference": null,
  "checkoutSession": null,
  "sendPaymentByPostalService": false,
  "fine": { "value": 0.00, "type": "FIXED" },
  "interest": { "value": 0.00, "type": "PERCENTAGE" },
  "split": null,
  "pixAutomaticAuthorizationMode": "OPTIONAL"
}

O campo vale a partir da criação da assinatura: se for enviado na atualização da assinatura, é ignorado.

🚧

Atenção

Envie OPTIONAL explicitamente apenas quando a oferta de Pix Automático for indispensável para o seu fluxo. Se a sua integração cria assinaturas de configurações variadas, deixe o campo sem informar: assinaturas inaptas são criadas sem erro.

Validações

SituaçãoStatus HTTPcodedescription
OPTIONAL e periodicidade não permitida400invalid_objectA frequência da assinatura não é permitida para recorrências do Pix Automático.
OPTIONAL e assinatura com desconto400invalid_objectPix Automático não pode ser usado em assinaturas com desconto configurado.
OPTIONAL e forma de pagamento não permitida400invalid_objectPix Automático só está disponível para assinaturas com cobrança via Pix ou Pergunte ao Cliente.
OPTIONAL e conta não elegível ao Pix Automático400invalid_objectVocê não possui permissão para utilizar este recurso. Entre em contato com seu gerente de contas.
Valor diferente de OPTIONAL ou DISABLED400parse_errorO campo 'pixAutomaticAuthorizationMode' informado é inválido.

Em todos os casos a assinatura não é criada. Formato da resposta de erro:

{
  "errors": [
    {
      "code": "invalid_object",
      "description": "Pix Automático não pode ser usado em assinaturas com desconto configurado."
    }
  ]
}

2. Disponibilize a cobrança vigente ao pagador

As cobranças da assinatura são obtidas como em qualquer assinatura, por Listar cobranças de uma assinatura (GET /v3/subscriptions/{id}/payments), em que {id} é o identificador da assinatura retornado no Passo 1. Na criação, a cobrança vigente é a primeira.

Para apresentar o pagamento ao pagador, use uma das opções que você já utiliza:

Nas assinaturas com oferta, o payload do QR Code da cobrança vigente é um QR Code composto. As demais cobranças criadas mantêm o QR Code avulso. Você não precisa escolher o formato: o Asaas retorna o QR Code composto na cobrança vigente e o avulso nas demais. Nenhum campo novo é retornado. O banco do pagador lê o QR Code, processa o pagamento ou o agendamento e, ao final, apresenta a oferta de Pix Automático.

🚧

Atenção

Não monte o QR Code manualmente e não valide o tamanho ou a estrutura interna do payload. Repasse ao pagador exatamente o conteúdo retornado pelo Asaas.

3. Identifique a autorização vinculada à assinatura

Utilize Listar autorizações com o filtro subscriptionId para localizar a autorização de Pix Automático gerada para a assinatura: GET /v3/pix/automatic/authorizations?subscriptionId={subscriptionId}.

Parâmetro de consultaTipoObrigatórioDescrição
subscriptionIdstringNãoIdentificador da assinatura no Asaas, retornado na criação da assinatura (Passo 1).

Os filtros status e customerId, e a paginação por offset e limit, continuam disponíveis e podem ser combinados com subscriptionId.

Exemplo de resposta da listagem:

{
  "object": "list",
  "hasMore": false,
  "totalCount": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "f491dd86-c552-4468-9d9b-ad0eda4c0aa0",
      "contractId": "1619468",
      "customerId": "cus_000009547456",
      "frequency": "WEEKLY",
      "startDate": "2026-11-06",
      "status": "CREATED",
      "value": 10.00,
      "originType": "PAYMENT_AND_RECURRING_OFFER_QR_CODE",
      "subscriptionId": "sub_vsqwcqmdykq5tm2l",
      "paymentCreationMode": "SUBSCRIPTION",
      "retryPolicy": "NOT_ALLOWED"
    }
  ]
}
CampoDescrição
idIdentificador da autorização. Use-o para relacionar eventos de webhook e instruções de pagamento à assinatura.
statusStatus atual da autorização. Logo após a criação da assinatura, o status é CREATED.
subscriptionIdAssinatura que originou a autorização.
originTypeOrigem da autorização. O valor PAYMENT_AND_RECURRING_OFFER_QR_CODE identifica autorizações geradas pela oferta automática em assinaturas.
paymentCreationModeComo as cobranças da autorização são criadas. Nas autorizações de assinatura, o valor é SUBSCRIPTION.
retryPolicyPolítica de retentativa de débito. Nas autorizações de assinatura, o valor é NOT_ALLOWED.
📘

Recomendado

Guarde o par subscriptionId ↔ authorization.id no seu sistema. Os eventos de instrução de pagamento trazem paymentInstruction.authorization.id e paymentInstruction.paymentId, e é por esses identificadores que você concilia cada débito automático com a assinatura e a cobrança.

4. Acompanhe a autorização e os débitos por webhooks

Habilite os eventos para Pix Automático além dos eventos de cobrança que a sua integração já consome. Não é necessário consultar a listagem de autorizações periodicamente.

📘

Importante

A entrega dos webhooks é assíncrona e a ordem entre eventos não é garantida. Não dependa da ordem e use authorization.id, subscriptionId e paymentId para correlacionar os eventos.

Eventos de autorização

EventoQuando ocorre nesta jornada
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATEDA autorização é criada para a assinatura apta.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATEDO Asaas recebeu a mensagem de confirmação do Pix Automático da instituição do pagador. É independente da liquidação da cobrança.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSEDNão é emitido na Jornada 4. Ocorre apenas na Jornada 3.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLEDA autorização foi cancelada pelo pagador, por você ou em consequência de uma alteração na assinatura. O motivo é informado em authorization.cancellationReason.
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIREDA autorização atingiu a data de encerramento, inclusive quando o pagador nunca a ativou.

Eventos de instrução de pagamento

EventoQuando ocorre
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATEDA instrução de débito de uma cobrança da assinatura é criada.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULEDA instituição do pagador agendou o débito para o vencimento.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSEDA instrução foi recusada no agendamento ou no processamento.
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLEDA instrução foi cancelada.

A confirmação financeira de cada cobrança continua sendo informada pelos eventos de cobrança (PAYMENT_CONFIRMED e PAYMENT_RECEIVED).

Sequências esperadas

Pagador paga a cobrança vigente e autoriza o Pix Automático

PAYMENT_CREATED (cobrança vigente)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_RECEIVED e PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
(sem ordem fixa entre os dois)

Cobranças seguintes com a autorização ativa

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PAYMENT_CONFIRMED

Débito recusado por falta de saldo ou limite do pagador

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

Na Jornada 4 não há retentativa automática de débito. As retentativas vêm desativadas por padrão (retryPolicy = NOT_ALLOWED). Após INSTRUCTION_REFUSED, a cobrança continua pendente e pode ser paga de forma avulsa.

Pagador paga a cobrança vigente sem autorizar

PAYMENT_CREATED (cobrança vigente)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_RECEIVED (cobrança vigente)

A autorização permanece CREATED e a oferta continua nas próximas cobranças.

Autorização que nunca é ativada

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
(autorização permanece CREATED enquanto a oferta é renovada nas cobranças vigentes)
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED (na data de encerramento)

Pagador cancela a autorização depois de ativada

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED

Cobrança alterada com a autorização ativa

(cobrança alterada)
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Apenas a instrução daquela cobrança é cancelada. A autorização continua ativa.

Consulte os valores de cancellationReason em Motivos de cancelamento da autorização do Pix Automático.

🚧

Atenção

Alterações em campos essenciais da assinatura podem cancelar a autorização. Com a autorização CREATED ou ACTIVE, alterar value, cycle, nextDueDate, billingType (exceto de UNDEFINED para PIX) ou inativar a assinatura cancela a autorização. Alterar juros, multa ou desconto cancela apenas se a autorização estiver CREATED. Antes de alterar uma assinatura com autorização ativa, verifique o impacto: se a autorização for cancelada, o pagador precisará voltar a pagar as cobranças manualmente.

Confirme o resultado

Após criar uma assinatura apta, confira:

  • a resposta da criação traz pixAutomaticAuthorizationMode = OPTIONAL;
  • a cobrança vigente retorna o QR Code composto e o pagador consegue visualizar a oferta ao pagar ou agendar;
  • a listagem de autorizações, filtrada por subscriptionId, retorna a autorização com status CREATED;
  • o evento PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED é recebido pelo seu webhook.

Estado final de cada cenário:

CenárioAssinaturaPrimeira cobrançaAutorizaçãoCobranças seguintes
Pagador paga ou agenda a cobrança vigente e autorizaAtivaPagaACTIVEDebitadas automaticamente no vencimento
Pagador paga a primeira cobrança sem autorizarAtivaPagaCREATEDCobranças comuns, pagas pelo pagador. A oferta continua até a autorização ser ativada ou encerrada (EXPIRED)
Pagador não paga a primeira cobrançaAtivaVencidaCREATEDA cobrança seguinte passa a ser a vigente e recebe o QR Code composto
Pagador cancela a autorizaçãoAtivaPagaCANCELLEDCobranças comuns, pagas pelo pagador
Você cancela a autorizaçãoAtivaPagaCANCELLEDCobranças comuns, pagas pelo pagador
Você altera um campo sensível da assinaturaAtivaConforme o pagamentoCANCELLEDCobranças comuns, pagas pelo pagador
Você remove a assinaturaRemovidaConforme o pagamentoCANCELLEDNão são geradas

Boas práticas

  • Não condicione a prestação do serviço à autorização. O pagamento da cobrança não pode depender da adesão ao Pix Automático. Um pagador que paga sem autorizar está adimplente.
  • Não assuma que toda assinatura tem autorização. Assinaturas inaptas, com DISABLED ou de contas não elegíveis não geram autorização. Confirme pelo campo pixAutomaticAuthorizationMode da resposta, pela listagem com subscriptionId ou pelo evento PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED.
  • Use o QR Code retornado pelo Asaas. Apenas a cobrança vigente vem com o QR Code composto. Nas demais cobranças, o QR Code é avulso.
  • Acompanhe por webhooks, sem depender da ordem. Use os eventos de autorização para saber quando o débito automático passa a valer e os eventos de cobrança para a confirmação financeira.
  • Implemente idempotência. Os webhooks seguem o modelo de entrega pelo menos uma vez. Persista o id do evento antes de processar. Consulte Como implementar idempotência em Webhooks.
  • Repasse o QR Code sem alterações. O QR Code composto é maior que um QR Code dinâmico comum. Não valide tamanho nem estrutura do payload.
  • Oriente seus pagadores. A oferta aparece no aplicativo do banco do pagador ao final do pagamento ou agendamento da cobrança vigente. Enquanto a autorização não for ativada, ela volta a aparecer nas próximas cobranças vigentes.
  • Teste no Sandbox. Você pode testar a oferta no Sandbox, pagando o QR Code composto de uma conta Asaas para outra conta Asaas, que é a forma mais simples.

Referência da API

📘

Referência da API

Consulte os endpoints Criar nova assinatura, Listar autorizações e Cancelar uma autorização na Reference.

Próximos passos


Did this page help you?