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çãoA 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ção | Regra |
|---|---|
| Conta | A 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. |
| Desconto | A assinatura não pode ter desconto (discount) configurado, percentual ou de valor fixo. |
| Modo de autorização | O campo pixAutomaticAuthorizationMode não pode estar como DISABLED. |
| Momento da criação | Apenas 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:
- cria uma autorização de Pix Automático vinculada à assinatura;
- 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;
- 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,CANCELLEDeEXPIREDda autorização.
| Item | Comportamento na sua integração |
|---|---|
| Request de criação da assinatura | Nenhum campo novo é obrigatório. O campo opcional pixAutomaticAuthorizationMode permite desativar a oferta em uma assinatura específica. |
| QR Code da cobrança vigente | Continua 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ção | Fica vinculada à assinatura e pode ser consultada pelo filtro subscriptionId na listagem de autorizações. |
| Cobranças seguintes | Se 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 oferta | Cobrança vigente, com vencimento, que pode ser paga ou agendada | Pagamento imediato |
| Autorização | Opcional, ofertada depois do pagamento ou agendamento | Obrigatória, concedida junto com o pagamento |
| Como habilitar | Automática em assinaturas aptas | Consulte 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"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pixAutomaticAuthorizationMode | string | Não | Modo 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çãoEnvie
OPTIONALexplicitamente 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ção | Status HTTP | code | description |
|---|---|---|---|
OPTIONAL e periodicidade não permitida | 400 | invalid_object | A frequência da assinatura não é permitida para recorrências do Pix Automático. |
OPTIONAL e assinatura com desconto | 400 | invalid_object | Pix Automático não pode ser usado em assinaturas com desconto configurado. |
OPTIONAL e forma de pagamento não permitida | 400 | invalid_object | Pix 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ático | 400 | invalid_object | Você não possui permissão para utilizar este recurso. Entre em contato com seu gerente de contas. |
Valor diferente de OPTIONAL ou DISABLED | 400 | parse_error | O 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:
- o link da fatura (
invoiceUrlda cobrança); ou - o endpoint Obter QR Code para pagamentos via Pix (
GET /v3/payments/{id}/pixQrCode), em que{id}é o identificador da cobrança.
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çãoNã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 consulta | Tipo | Obrigatório | Descrição |
|---|---|---|---|
subscriptionId | string | Não | Identificador 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"
}
]
}| Campo | Descrição |
|---|---|
id | Identificador da autorização. Use-o para relacionar eventos de webhook e instruções de pagamento à assinatura. |
status | Status atual da autorização. Logo após a criação da assinatura, o status é CREATED. |
subscriptionId | Assinatura que originou a autorização. |
originType | Origem da autorização. O valor PAYMENT_AND_RECURRING_OFFER_QR_CODE identifica autorizações geradas pela oferta automática em assinaturas. |
paymentCreationMode | Como as cobranças da autorização são criadas. Nas autorizações de assinatura, o valor é SUBSCRIPTION. |
retryPolicy | Política de retentativa de débito. Nas autorizações de assinatura, o valor é NOT_ALLOWED. |
RecomendadoGuarde o par
subscriptionId↔authorization.idno seu sistema. Os eventos de instrução de pagamento trazempaymentInstruction.authorization.idepaymentInstruction.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.
ImportanteA entrega dos webhooks é assíncrona e a ordem entre eventos não é garantida. Não dependa da ordem e use
authorization.id,subscriptionIdepaymentIdpara correlacionar os eventos.
Eventos de autorização
| Evento | Quando ocorre nesta jornada |
|---|---|
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED | A autorização é criada para a assinatura apta. |
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED | O 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_REFUSED | Não é emitido na Jornada 4. Ocorre apenas na Jornada 3. |
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED | A 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_EXPIRED | A autorização atingiu a data de encerramento, inclusive quando o pagador nunca a ativou. |
Eventos de instrução de pagamento
| Evento | Quando ocorre |
|---|---|
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED | A instrução de débito de uma cobrança da assinatura é criada. |
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED | A instituição do pagador agendou o débito para o vencimento. |
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED | A instrução foi recusada no agendamento ou no processamento. |
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED | A 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_CONFIRMEDDé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_REFUSEDNa 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_CANCELLEDCobrança alterada com a autorização ativa
(cobrança alterada)
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLEDApenas 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çãoAlterações em campos essenciais da assinatura podem cancelar a autorização. Com a autorização
CREATEDouACTIVE, alterarvalue,cycle,nextDueDate,billingType(exceto deUNDEFINEDparaPIX) ou inativar a assinatura cancela a autorização. Alterar juros, multa ou desconto cancela apenas se a autorização estiverCREATED. 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 statusCREATED; - o evento
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATEDé recebido pelo seu webhook.
Estado final de cada cenário:
| Cenário | Assinatura | Primeira cobrança | Autorização | Cobranças seguintes |
|---|---|---|---|---|
| Pagador paga ou agenda a cobrança vigente e autoriza | Ativa | Paga | ACTIVE | Debitadas automaticamente no vencimento |
| Pagador paga a primeira cobrança sem autorizar | Ativa | Paga | CREATED | Cobranças comuns, pagas pelo pagador. A oferta continua até a autorização ser ativada ou encerrada (EXPIRED) |
| Pagador não paga a primeira cobrança | Ativa | Vencida | CREATED | A cobrança seguinte passa a ser a vigente e recebe o QR Code composto |
| Pagador cancela a autorização | Ativa | Paga | CANCELLED | Cobranças comuns, pagas pelo pagador |
| Você cancela a autorização | Ativa | Paga | CANCELLED | Cobranças comuns, pagas pelo pagador |
| Você altera um campo sensível da assinatura | Ativa | Conforme o pagamento | CANCELLED | Cobranças comuns, pagas pelo pagador |
| Você remove a assinatura | Removida | Conforme o pagamento | CANCELLED | Nã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
DISABLEDou de contas não elegíveis não geram autorização. Confirme pelo campopixAutomaticAuthorizationModeda resposta, pela listagem comsubscriptionIdou pelo eventoPIX_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
iddo 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 APIConsulte os endpoints Criar nova assinatura, Listar autorizações e Cancelar uma autorização na Reference.
Próximos passos
Updated 1 day ago
